cli-review-runner

cli-review-runner

cli-for-agents のエージェントフレンドリー性に関する10項目の監査を自動化します。対象の CLI に対してブラックボックスプローブを実行し、各検出事項をルール ID（例：help-examples-in-help、err-non-zero-exit-codes、safe-dry-run-flag）に対応付けた構造化レポートを出力します。デフォルトモードは読み取り専用です。実際の引数を指定して破壊的な動詞を実行することはありません。

適用する場面

• ユーザーが CLI のエージェントフレンドリー性、自動化への対応状況、または CI での使用についてレビューや監査を依頼した場合
• ユーザーが CLI の開発を終え、出荷前の健全性チェックを希望している場合
• ユーザーが cli-for-agents カタログに照らして、自身またはサードパーティの CLI を評価している場合
• CLI がエージェントをハングさせる、コンテキストを使い果たす、またはパイプラインで連携できない理由をユーザーが尋ねている場合
• CLI の変更に対する PR レビューで、--help、エラー、ドライランフラグのリグレッションテストをすばやく実施する場合

使用方法

このスキルは scripts/review.sh によって実行されます。対象の CLI（絶対パス、または PATH から解決できる名前）を指定し、出力形式を選択してください。

# Default: text table on stdout, exit 0 if all passed, 1 if any failed
bash scripts/review.sh --target /usr/local/bin/mycli

# Machine-readable output
bash scripts/review.sh --target gh --format json
bash scripts/review.sh --target kubectl --format ndjson

# Supply subcommand list when auto-discovery misses them
bash scripts/review.sh --target gh --subcommands pr,issue,repo

# Preview what would run without touching the target CLI
bash scripts/review.sh --target mycli --dry-run

# Include risky probes on destructive verbs (off by default)
bash scripts/review.sh --target mycli --include-destructive

すべてのフラグ一覧については、bash scripts/review.sh --help を参照してください。

ワークフローの概要

--target <cli>
   │
   ▼
[1] Validate target       fail fast if path missing or not executable
   │
   ▼
[2] Load rule catalog     references/rule-catalog.tsv (45 rules)
   │
   ▼
[3] Discover subcommands  parse top-level --help (gh/kubectl/commander shapes)
   │
   ▼
[4] Run probes P1..P10    each probe emits NDJSON findings to a temp file
   │
   ▼
[5] Render report         scripts/render.sh  ->  text | json | ndjson

プローブごとの詳細な内訳、失敗パターン、カタログの拡張方法については、references/workflow.md を参照してください。

プローブの対象範囲

プローブ	テストするルール	対象範囲
P1 非対話型	interact-no-hang-on-stdin、interact-no-input-flag、interact-flags-first、interact-detect-tty、interact-no-timed-prompts、interact-no-arrow-menus、input-no-prompt-fallback	タイムアウトを設定して </dev/null の下で実行し、ヘルプ内の対話型の表現を確認
P2 階層型ヘルプ	help-per-subcommand、help-no-flag-required、help-layered-discovery	トップレベルの行数、サブコマンドごとの --help、引数なしでの呼び出し
P3 ヘルプ内の使用例	help-examples-in-help、help-flag-summary、help-suggest-next-steps	各サブコマンドのヘルプで Examples:、短縮形と長形式のフラグのペア、「See also」を検索
P4 対処可能なエラー	err-actionable-fix、err-include-example-invocation、err-exit-fast-on-missing-required、err-no-stack-traces-by-default	不正なフラグを指定して実行し、stderr から修正方法と使用例を検索。生のスタックトレースがないことを確認
P5 stderr への出力	err-stderr-not-stdout	エラーテキストが fd 2 に出力されること
P6 終了コード	err-non-zero-exit-codes	使用法エラーと実行時エラーで、それぞれ異なるゼロ以外のコードが返されること
P7 stdin との連携	input-accept-stdin-dash、input-flags-over-positional	ヘルプで - を stdin として使う慣例を検索し、位置引数とフラグの数を数える
P8 構造化出力	output-json-flag、output-respect-no-color	--json が JSON を出力し、NO_COLOR=1 で ANSI が抑制されること
P9 破壊的操作の安全性	safe-dry-run-flag、safe-force-bypass-flag、safe-no-prompts-with-no-input	破壊的な動詞の --help で --dry-run／--yes／--force／--no-input を確認
P10 コマンド構造	struct-resource-verb、struct-standard-flag-names、struct-no-hidden-subcommand-catchall、struct-flag-order-independent	一貫した構造、--help／--version の存在、未知のサブコマンドに対するエラー、フラグの位置に依存しないこと

対象範囲： cli-for-agents の45ルールのうち、30ルールはブラックボックステストが可能です。残りの15ルール（冪等性、状態の調整、NDJSON ストリーミング、出力の上限、クラッシュのみからの復旧、環境変数へのフォールバック、シークレットの stdin 入力、名前の入力による確認）は、実際の呼び出しまたはソースコードの確認が必要です。これらはレポートに「手動レビューが必要」として記載されます。

設定

config.json には、動詞の分類リストとデフォルトのタイムアウトが保存されています。このスキルはセットアップなしで動作し、妥当なデフォルト値が設定されています。実行ごとにフラグで上書きするか、プロジェクト全体に適用する場合はファイルを編集してください。

{
  "timeout_seconds": 5,
  "safe_verbs": ["list", "get", "show", "status", "describe", "help", "version", "config", "ls", "inspect"],
  "destructive_verbs": ["delete", "drop", "destroy", "remove", "reset", "purge", "rm", "del"]
}

安全性モデル

すべてのプローブは、デフォルトで読み取り専用です。

• 安全な動詞（list、get、show、...）は、エラー処理をテストするために不正なフラグを指定して実行できます
• 破壊的な動詞（delete、drop、...）は、--help による確認のみ行います。引数を指定して実行することはありません
• すべてのプローブは、</dev/null の下で5秒の実時間タイムアウトを設定して実行されます
• 対象の CLI は独自のプロセス内でサンドボックス化されます。引数にシェルのメタ文字は含まれません

--include-destructive を指定すると、破壊的な動詞も不正なフラグを指定して実行される場合があります。これにより、CLI がフラグを検証する前に破壊的な処理を行う、まれなケースを検出できます。信頼できる CLI、または使い捨てのテスト環境に対してのみ有効にしてください。

セルフテスト

プローブを変更してリリースする前に、セルフテストを実行してください。このテストでは、特定のルールに意図的に違反するモック CLI を生成し、プローブがその違反を検出できることを確認します。

bash scripts/selftest.sh

期待される出力：Results: 8 passed, 0 failed。失敗がある場合は、scripts/lib/probes.sh のリグレッションを示しています。

ファイル

ファイル	目的
scripts/review.sh	メインエントリーポイント。プローブを実行し、レポートを出力します
scripts/render.sh	出力フォーマッター：text / json / ndjson
scripts/selftest.sh	意図的にバグを含めたモック CLI に対する整合性チェック
scripts/lib/common.sh	共通ヘルパー：タイムアウト、動詞分類器、JSON エスケープ、カタログローダー
scripts/lib/probes.sh	プローブ関数 probe_p1..probe_p10
references/rule-catalog.tsv	cli-for-agents の45ルールをプローブに対応付けたもの
references/workflow.md	プローブごとの詳細な方法、失敗モード、拡張ガイド
gotchas.md	使用中に見つかった既知のエッジケース
config.json	動詞分類器のリストとデフォルトのタイムアウト

関連スキル

• cli-for-agents - このスキルが監査する45ルールの設計カタログです。レポートで問題が指摘され、詳しい説明が必要な場合は、該当するルールファイルを参照してください。