コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。

コンポーネント構成

graph TD
  A[beautyspot CLI] -->|Command| B[Typer App]
  B -->|Business Logic| C[MaintenanceService]
  B -->|Output| D[Rich Console]
  B -->|Dashboard| E[Dashboard App]

コンポーネント責務

データフロー

sequenceDiagram
  participant User as ユーザー
  participant CLI as CLI App
  participant Service as MaintenanceService
  participant Output as Rich Console

  User->>CLI: beautyspot gc --name my-project
  CLI->>Service: clean_garbage()
  Service-->>CLI: result (removed count, etc.)
  CLI->>Output: print summary table
  Output-->>User: formatted output

技術選定

非機能要件方針

• UX: 破壊的な操作（clear等）には対話的な確認プロンプトを表示
• 互換性: 標準出力のパイプ連携を妨げないよう、色の自動無効化に対応
• 利便性: 特定のプロジェクトだけでなく、全DBを横断的にスキャンする機能を提供

インターフェース

beautyspot list [--db DB_PATH]
beautyspot gc [--name PROJECT_NAME] [--force]
beautyspot stats
beautyspot ui

振る舞い

1. コンテキスト解決: --db 指定がない場合、デフォルトの .beautyspot/ ディレクトリを探索する
2. コマンド実行: MaintenanceService または Spot インスタンスを生成し、対応するメソッドを呼び出す
3. フォーマット出力: Rich ライブラリを使用して、結果をテーブルやプログレスバーで表示する

サブコマンド詳細

エラーハンドリング

• DB不在: 指定されたパスにDBがない場合は、エラーメッセージを表示して終了する。
• 権限不足: ファイル削除権限がない場合は、スキップされた旨を表示する。

エッジケース

• 非対話環境: CI等での実行を考慮し、色の無効化や確認プロンプトのスキップ（--force）に対応する。

目的

CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。CliRunner によるコマンド実行と出力の正確性を E2E で検証する。

検証観点

• list コマンド: キャッシュ済みタスクの一覧が正しく表示されること。DBが空の場合に適切なメッセージが表示されること
• show コマンド: 指定タスクの詳細情報（func_name, input_key, created_at, result サイズ等）が正しく表示されること
• stats コマンド: キャッシュ統計（総件数、関数別件数、ストレージ使用量等）が正確に表示されること
• clear コマンド: 確認プロンプト後にキャッシュが削除されること。--force フラグでプロンプトがスキップされること
• gc / prune コマンド: 有効期限切れタスクの削除と孤立Blobの清掃が正しく実行されること
• E2E パイプライン: @mark でキャッシュ保存 → beautyspot list で確認 → beautyspot clear で削除、という一連のワークフローが正常に動作すること
• エラー時の終了コード: 不正な引数やDB不在時に非ゼロの終了コードが返ること

実装概要

Typer を利用したコマンドラインインターフェースの実装。 list, show, stats, clear, clean, gc, prune, version 等の コマンドを提供し、rich ライブラリを用いてコンソール出力（テーブル、パネル、 プログレスバー等）をリッチにフォーマットしている。

設計判断

Typer と Rich の組み合わせ

Typer は型ヒントベースでコマンドやオプションを定義でき、コードの記述量と メンテナンスコストを大幅に削減できる。Rich による出力は、単なるテキストではなく 構造化された情報（JSONやMarkdown）の視認性を劇的に向上させ、DXを高める。

安全性を考慮した対話的プロンプト

clear や clean など、データを大規模に削除するコマンドについては、 --force オプションが指定されない限り、rich.prompt.Confirm を用いて ユーザーに明示的な確認を求めることで、誤操作によるデータ喪失を防いでいる。

実装メモ

• コマンドは MaintenanceService などの内部 API を利用して処理を行う
• 各コマンドは特定のプロジェクト (--project / -p) に対して操作を行うが、 一部のコマンド（list 等）はワークスペース全体の走査もサポートする

Dashboard Interaction Model

Context and Problem Statement / コンテキスト

現状のダッシュボード (dashboard.py) では、タスク一覧の表示と詳細データの復元操作が分離しています。 ユーザーは一覧テーブルで対象を確認した後、別途ドロップダウンメニューから対応する cache_key (ハッシュ値) を手動で探し出す必要があり、認知負荷が高い状態です。 プロジェクトの依存関係として streamlit>=1.51.0 が確保されており、インタラクティブなデータフレーム機能が利用可能となっています。

Decision Drivers / 要求

• Lower Cognitive Load: ユーザーがハッシュ値を意識することなく、直感的にデータを操作できること。
• Seamless Navigation: 一覧での選択が即座に詳細ビューに反映されること。
• Modern UI Experience: Streamlit の最新機能を活用し、洗練された操作感を提供すること。

Considered Options / 検討

• Option 1: 現状維持（テーブルと選択用ドロップダウンの分離）。
• Option 2: st.dataframe の on_select 機能を使用し、テーブル行のクリックによって詳細ビュー（Restore Data）のコンテキストを切り替える方式。

Decision Outcome / 決定

Chosen option: Option 2.

st.dataframe の on_select 機能を使用し、テーブル行のクリックによって詳細ビューのコンテキストを切り替える方式を採用します。これにより、ユーザーはテーブル上のレコードを直接クリックするだけで、そのタスクの詳細や保存されたデータを復元できるようになります。

Consequences / 決定

• Positive:
  • ユーザーは直感的にレコードを選択・復元できる。
  • フィルタリングされた結果に対しても、正しい行インデックスで詳細へアクセスできる。
• Negative:
  • Streamlit の古いバージョン（<1.35）との互換性が失われる（ただし pyproject.toml でバージョン指定済みのため許容）。

Pragmatic CLI Refactoring Policy

Context and Problem Statement / コンテキスト

quality_report.md において、src/beautyspot/cli.py 内の複数の関数（show_cmd, prune_cmd, stats_cmd）が循環的複雑度（CC）で Rank C の警告を受けています。一般的にプロジェクトでは CC の低減を推奨していますが、CLI モジュールに関してはその優先度と費用対効果を再検討する必要があります。

Decision Drivers / 要求

• Efficiency: リファクタリングのリソースを、ユーザーに直接影響するコアロジックに優先的に配分すること。
• Readability: CLI コマンドの「上から下への命令的フロー」を維持し、挙動の追いやすさを損なわないこと。
• Architectural Impact: 依存関係の末端にある CLI モジュールの複雑さが、システム全体の安定性に与える影響を考慮すること。

Considered Options / 検討

• Option 1: 厳格なリファクタリング。すべての Rank C 関数を Rank A/B になるまで分解する。
• Option 2: 戦略的許容。表示ロジックに起因する複雑さは許容し、現状の構造を維持する。

Decision Outcome / 決定

Chosen option: Option 2.

CLI モジュールの Rank C スコアについては、以下の理由から「即時の抜本的なリファクタリングは行わず、現状の構造を維持する」ことを決定しました。

• 表示ロジックの特性: cli.py の複雑さは、データ取得後の表示フォーマット分岐（Rich ライブラリによる出力制御）に集中しており、純粋なビジネスロジックの複雑さとは性質が異なります。
• 設計上の影響の小ささ: cli.py は依存関係の末端に位置しており、他モジュールへの波及効果がありません。
• 可読性の維持: CLI コマンドは、過度に抽象化されるよりも命令的に記述されている方が挙動を追いやすい場合があります。

Consequences / 決定

• Positive:
  • コアロジック（cachekey.py など）のリファクタリングにリソースを集中できる。
  • 不要な抽象化による「コードの追いづらさ」を回避できる。
• Negative:
  • 品質レポート上の警告は残り続ける。
  • 将来的にコマンドがさらに肥大化した場合には、改めて分割を検討する必要がある。

CLI Scope Definition and Explicit Storage Linkage

Context and Problem Statement / コンテキスト

beautyspot の clean コマンドやガベージコレクション機能は、DBファイルとBlobストレージディレクトリの対応関係が「自明」であることを前提としています。標準構成（.beautyspot/ 配下）ではこの前提は成立しますが、ユーザーがカスタムパスを設定したり、外部バックエンド（S3等）を使用した場合、CLIツールは安全に依存関係を特定できません。この状態で推測に基づく削除を行うと、誤って無関係なデータを削除するリスクがあります。

Decision Drivers / 要求

• Data Safety: 管理対象外のデータや、他のプロジェクトが使用しているデータを誤って削除しないこと。
• Predictability: CLI ツールがどの範囲までを安全に管理できるかを明確に定義すること。
• Extensibility: 将来的にカスタム構成であっても安全にメンテナンスが行えるような道筋を立てること。

Considered Options / 検討

• Option 1: パス構造や設定から対応関係を推測し、ベストエフォートでクリーンアップを試みる。
• Option 2: CLI の自動クリーンアップ機能を標準構成に限定し、カスタム構成についてはユーザー管理とする。あわせてメタデータによるリンクを将来的に導入する。

Decision Outcome / 決定

Chosen option: Option 2.

1. CLI Scope Limitation (Policy)

CLIが提供する「ストレージの自動クリーニング・削除機能」のサポート範囲を、標準ディレクトリ構成（.beautyspot/ 配下）を使用しているプロジェクト に限定します。カスタム構成を利用している場合は、CLI による自動削除は保証されず、ユーザー自身の責任で管理を行う必要がある旨を明記します。

2. Explicit Storage Linkage (Roadmap)

「対応関係が自明でない」問題を根本解決するため、将来のバージョンで TaskDB内に使用しているStorageの情報をメタデータとして記録する 仕組みを導入します。DB初期化時に storage_uri を保存し、メンテナンス時に「操作対象のDBが参照しているストレージと、今操作しようとしている実体が一致するか」を検証可能にします。

Consequences / 決定

• Positive:
  • 安全性: 推測による誤削除を確実に防ぐことができる。
  • 明確な責任分界点: ツールが面倒を見る範囲と、ユーザーが管理すべき範囲が明確になる。
  • 将来の拡張性: メタデータ記録が実装されれば、カスタム構成でも安全なGCが可能になる。
• Negative:
  • ユーザーの負担: カスタム構成を利用する上級ユーザーは、beautyspot clean などの恩恵をフルには受けられない場合がある。