局所トレーサビリティ — グループ: CLI

# 局所トレーサビリティビュー グループ: CLI

生成日時: 2026-03-13 23:59:51

### 対象アイテム

8

### REQ

1

### ARCH

1

### SPEC

1

### TST

1

### IMPL

1

### ADR

3

### レビュー済

8/8

### Suspect

0

### グループ

CLI

## トレーサビリティマトリクス

✓=レビュー済 ○=未レビュー ⚠=Suspect（複数同時表示あり。IDクリックで詳細へ）

グループ | REQ | ARCH | SPEC | TST | IMPL | ADR
--- | --- | --- | --- | --- | --- | ---
CLI | REQ011 ✓ コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。 | ARCH011 ✓ ## コンポーネント構成 ```mermaid graph TD A[beautyspot CLI] -->|Command| B[Typer App] ... | SPEC021 ✓ ## インターフェース ```bash beautyspot list [--db DB_PATH] beautyspot gc [--name PROJEC... | TST021 ✓ ## 目的 CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。`CliR... | IMPL021 ✓ ## 実装概要 `Typer` を利用したコマンドラインインターフェースの実装。 `list`, `show`, `stats`, `clear`, `cle... | ADR006 ✓ # Dashboard Interaction Model ## Context and Problem Statement / コンテキスト 現状のダッシ...
CLI | REQ011 ✓ コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。 | ARCH011 ✓ ## コンポーネント構成 ```mermaid graph TD A[beautyspot CLI] -->|Command| B[Typer App] ... | SPEC021 ✓ ## インターフェース ```bash beautyspot list [--db DB_PATH] beautyspot gc [--name PROJEC... | TST021 ✓ ## 目的 CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。`CliR... | IMPL021 ✓ ## 実装概要 `Typer` を利用したコマンドラインインターフェースの実装。 `list`, `show`, `stats`, `clear`, `cle... | ADR027 ✓ # Pragmatic CLI Refactoring Policy ## Context and Problem Statement / コンテキスト `...
CLI | REQ011 ✓ コマンドラインインターフェースからキャッシュの一覧表示、詳細確認、統計表示、削除、GC等の管理操作ができること。 | ARCH011 ✓ ## コンポーネント構成 ```mermaid graph TD A[beautyspot CLI] -->|Command| B[Typer App] ... | SPEC021 ✓ ## インターフェース ```bash beautyspot list [--db DB_PATH] beautyspot gc [--name PROJEC... | TST021 ✓ ## 目的 CLI はユーザーがキャッシュの状況確認・管理を行う主要インターフェースであり、コマンドの不具合はユーザー体験と運用効率に直接影響する。`CliR... | IMPL021 ✓ ## 実装概要 `Typer` を利用したコマンドラインインターフェースの実装。 `list`, `show`, `stats`, `clear`, `cle... | ADR028 ✓ # CLI Scope Definition and Explicit Storage Linkage ## Context and Problem Stat...

## カバレッジ（局所）

リンク方向 | カバー数 | カバー率 | 未カバー
--- | --- | --- | ---
ARCH → REQ | 1 / 1 | 100.0% | —
SPEC → ARCH | 1 / 1 | 100.0% | —
TST → SPEC | 1 / 1 | 100.0% | —
IMPL → SPEC | 1 / 1 | 100.0% | —
ADR → REQ | 1 / 1 | 100.0% | —

## アイテム詳細

### REQ011 REQ {h(g)} ✓ レビュー済

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

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

親: —

子: ADR006, ADR027, ADR028, ARCH011

### ARCH011 ARCH {h(g)} ✓ レビュー済

## コンポーネント構成

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

## コンポーネント責務

コンポーネント | 責務 | インターフェース
--- | --- | ---
Typer App | コマンドライン引数のパースとサブコマンドのディスパッチ | `main()`, `gc()`, `list()`
MaintenanceService | 実際のキャッシュ管理ロジックの実行 | `clean_garbage()`, `clear()`
Rich Console | ターミナルでの視覚的に分かりやすいテーブルやパネルの描画 | `Console`, `Table`
Dashboard App | キャッシュ状態をインタラクティブに閲覧するためのTUI | `dashboard.py`

## データフロー

    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

## 技術選定

技術領域 | 選定 | 理由
--- | --- | ---
フレームワーク | Typer | 型ヒントに基づいた堅牢なコマンドラインインターフェースを迅速に構築
出力装飾 | Rich | プログレスバーやステータス表示により、長時間処理の進捗を可視化
連携 | Factory DI | カレントディレクトリや設定から自動的に `Spot` インスタンスを組み立て

## 非機能要件方針

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

## コンポーネント構成 ```mermaid graph TD A[beautyspot CLI] -->|Command| B[Typer App] B -->|Business Logic| C[MaintenanceService] B -->|Output| D[Rich Console] B -->|Dashboard| E[Dashboard App] ``` ## コンポーネント責務 | コンポーネント | 責務 | インターフェース | |---|---|---| | Typer App | コマンドライン引数のパースとサブコマンドのディスパッチ | `main()`, `gc()`, `list()` | | MaintenanceService | 実際のキャッシュ管理ロジックの実行 | `clean_garbage()`, `clear()` | | Rich Console | ターミナルでの視覚的に分かりやすいテーブルやパネルの描画 | `Console`, `Table` | | Dashboard App | キャッシュ状態をインタラクティブに閲覧するためのTUI | `dashboard.py` | ## データフロー ```mermaid 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 ``` ## 技術選定 | 技術領域 | 選定 | 理由 | |---|---|---| | フレームワーク | Typer | 型ヒントに基づいた堅牢なコマンドラインインターフェースを迅速に構築 | | 出力装飾 | Rich | プログレスバーやステータス表示により、長時間処理の進捗を可視化 | | 連携 | Factory DI | カレントディレクトリや設定から自動的に `Spot` インスタンスを組み立て | ## 非機能要件方針 - **UX**: 破壊的な操作（`clear`等）には対話的な確認プロンプトを表示 - **互換性**: 標準出力のパイプ連携を妨げないよう、色の自動無効化に対応 - **利便性**: 特定のプロジェクトだけでなく、全DBを横断的にスキャンする機能を提供

親: REQ011

子: SPEC021

### SPEC021 SPEC {h(g)} ✓ レビュー済

## インターフェース

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

## 振る舞い

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

## サブコマンド詳細

コマンド | 説明
--- | ---
`list` | 保存されているキャッシュキーと関数名の一覧を表示
`gc` | 期限切れタスクと孤立Blobのクリーンアップを実行
`stats` | キャッシュヒット率やストレージ使用量の統計を表示
`ui` | ターミナルベースのインタラクティブダッシュボードを起動

## エラーハンドリング

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

## エッジケース

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

## インターフェース ```bash beautyspot list [--db DB_PATH] beautyspot gc [--name PROJECT_NAME] [--force] beautyspot stats beautyspot ui ``` ## 振る舞い 1. **コンテキスト解決**: `--db` 指定がない場合、デフォルトの `.beautyspot/` ディレクトリを探索する 2. **コマンド実行**: `MaintenanceService` または `Spot` インスタンスを生成し、対応するメソッドを呼び出す 3. **フォーマット出力**: `Rich` ライブラリを使用して、結果をテーブルやプログレスバーで表示する ## サブコマンド詳細 | コマンド | 説明 | |---|---| | `list` | 保存されているキャッシュキーと関数名の一覧を表示 | | `gc` | 期限切れタスクと孤立Blobのクリーンアップを実行 | | `stats` | キャッシュヒット率やストレージ使用量の統計を表示 | | `ui` | ターミナルベースのインタラクティブダッシュボードを起動 | ## エラーハンドリング - **DB不在**: 指定されたパスにDBがない場合は、エラーメッセージを表示して終了する。 - **権限不足**: ファイル削除権限がない場合は、スキップされた旨を表示する。 ## エッジケース - **非対話環境**: CI等での実行を考慮し、色の無効化や確認プロンプトのスキップ（`--force`）に対応する。

親: ARCH011

子: IMPL021, TST021

### TST021 TST {h(g)} ✓ レビュー済

## 目的

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不在時に非ゼロの終了コードが返ること

## 目的 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不在時に非ゼロの終了コードが返ること

references: tests/integration/cli/test_cli.py

親: SPEC021

子: —

### IMPL021 IMPL {h(g)} ✓ レビュー済

## 実装概要

`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` 等）はワークスペース全体の走査もサポートする

## 実装概要 `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` 等）はワークスペース全体の走査もサポートする

references: src/beautyspot/cli.py

親: SPEC021

子: —

### ADR006 ADR {h(g)} ✓ レビュー済

# 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` でバージョン指定済みのため許容）。

# 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` でバージョン指定済みのため許容）。

親: REQ011

子: —

### ADR027 ADR {h(g)} ✓ レビュー済

# 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:
  - 品質レポート上の警告は残り続ける。
  - 将来的にコマンドがさらに肥大化した場合には、改めて分割を検討する必要がある。

# 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**: * 品質レポート上の警告は残り続ける。 * 将来的にコマンドがさらに肥大化した場合には、改めて分割を検討する必要がある。

親: REQ011

子: —

### ADR028 ADR {h(g)} ✓ レビュー済

# 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` などの恩恵をフルには受けられない場合がある。

# 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` などの恩恵をフルには受けられない場合がある。

親: REQ011

子: —