CLI & Dashboard Guide
beautyspot は、キャッシュされたデータの閲覧や、ディスク容量を管理するためのコマンドラインツールを提供しています。
Dashboard (UI)
キャッシュされたタスクの実行履歴、結果、依存関係などをブラウザで視覚的に確認できます。
Basic Usage
<path_to_db>: Spotを作成した際に指定したデータベースファイルのパス（デフォルトでは.beautyspot/project_name.dbなど）。
メンテナンスとクリーンアップ
タスクを実行し続けると、キャッシュデータベースやストレージ容量が増加していきます。beautyspot はこれらを管理するために、目的別の3つのコマンドを提供しています。
コマンドの役割分担
| コマンド | アプローチ | 対象 | 目的 | 推奨頻度 |
|---|---|---|---|---|
gc |
宣言的 (Declarative) | 全体 | ポリシー執行（期限切れデータの削除）とゴミ掃除 | 定期実行 (Daily) |
prune |
命令的 (Imperative) | タスク | 手動介入（「30日以上前のデータ」を一括削除） | 必要に応じて |
clean |
修復 (Repair) | ファイル | 整合性回復（DBにない孤立ファイルの削除） | トラブル時のみ |
1. ガベージコレクション (gc)
gc は、日常的なメンテナンスで使用するメインコマンドです。
ワークスペース内の全てのデータベースをスキャンし、事前に定義されたルール（Lifecycle Policy）に従って不要なデータを削除します。
主な機能:
- 期限切れタスクの削除:
@mark(retention="7d")などで設定された期限を過ぎたデータを、全てのデータベースから削除します（デフォルト有効）。 - ゾンビプロジェクトの削除:
.dbファイルが削除され、取り残されたストレージディレクトリを削除します。
使用例:
# 全てのプロジェクトをスキャンし、期限切れデータとゾンビプロジェクトを削除
$ beautyspot gc
# 期限切れタスクの削除は行わず、ゾンビプロジェクトの削除のみ行う
$ beautyspot gc --no-expired
# 実際に削除せず、何が消えるか確認する
$ beautyspot gc --dry-run
推奨: cron 等で定期実行することで、宣言した保持期間（Retention）に従ってディスク容量が自動的に管理されます。
2. 古いタスクの手動削除 (prune)
prune は、ポリシーに関係なく、「古いデータを一括で消したい」 場合に使用します。ディスク容量が逼迫した場合の緊急対応などに適しています。
例: 最終更新から30日以上経過したタスクを無条件で削除する
- 動作: 指定された日数より古いレコードを削除し、関連するBlobファイルも削除します。
関数名フィルタについて
--func などの関数名フィルタは、完全修飾名（module.qualname）を優先してマッチします。
同名関数がある場合は完全修飾名を指定してください。短い関数名も後方互換のため引き続き使えます。
具体例は Usage Patterns の「Function Identity」セクションを参照してください: docs/guides/usage_patterns.md。
3. 孤立ファイルのクリーンアップ (clean)
clean は、ストレージの整合性を修復 するための低レイヤーコマンドです。
通常、gc や prune が自動的に整合性を保つため、頻繁に使う必要はありません。プロセスのクラッシュなどで「DBレコードは消えたが、ファイルだけ残っている」状態が発生した場合に使用します。
例: