rust-cli

Rust CLI の提供

コマンドラインインターフェイスは、ビジネスロジックを main に直接埋め込むのではなく、安定したユーザープロトコルとして扱います。契約の確認から実装、実際のプロセスによる検証まで、一連のサイクルを完了させてください。

制約の確認

変更を加える前に、要件、既存のヘルプテキスト、スクリプト、README、テスト、リリース設定を確認してください。

• コマンド名、サブコマンド、引数、デフォルト値、相互排他条件、互換性要件
• 人間向け出力と機械向け出力の形式（quiet モード、verbose、JSON、色なし）
• stdin、ファイル、引数からの入力の優先順位、stdout／ファイルの書き込み先
• 成功、使用方法エラー、データエラー、一時的な障害に対応する終了コード
• 対応プラットフォーム、シェル、TTY／パイプ環境、MSRV、依存関係のバージョン
• 環境変数より設定ファイルを優先し、設定ファイルよりコマンドラインオプションを優先すること

重要な契約が欠けている場合は、既存の動作とテストから最小限の互換性のある解決策を推測し、前提を明示してください。フラグ、出力テキスト、終了コードを恣意的に変更しないでください。

ワークフロー

1. 動作のベースラインを確立する

エントリーポイントとビルド境界を確認します。

rustc --version --verbose
cargo metadata --no-deps --format-version 1
cargo test --all-targets
cargo run -- --help

少なくとも1つの成功した呼び出しについて、パラメーター、stdout、stderr、終了コードを記録します。失敗した呼び出しについても、少なくとも1つ記録してください。既存のスナップショットやシェルの呼び出し元は、互換性を保つための制約になります。

2. コマンドの契約を定義する

まず動作マトリクスを作成し、その後で解析ロジックを実装します。次の項目を区別してください。

• 必須の位置引数、任意の引数、繰り返し可能なオプション、サブコマンド
• ユーザー入力エラーと実行時エラー
• 通常のデータ出力と診断出力
• 対話モードと非対話モード
• 安定した機械向け形式と、変更可能な人間向け形式

clap などのパーサーを使用する場合は、リポジトリで固定されているバージョンの公式ドキュメントを参照してください。記憶を頼りに、異なるメジャーバージョンの derive 属性や API を混在させないでください。

3. 解析、実行、表示を分離する

エントリーポイントは薄く保ちます。

Process parameters & environment
    -> Parse into Options/Command
    -> Call testable run(command, io, context)
    -> Map domain results to output and ExitCode

ドメインロジックからは構造化された結果またはエラーを返し、色コード、改行、stderr のメッセージ、終了コードの決定は境界でのみ行います。深い階層の関数で process::exit を直接呼び出したり、グローバルな環境変数を無差別に読み取ったり、無条件に出力したりしないでください。

4. 設定の優先順位に従って I/O を実装する

• テスト可能なパイプ動作を実現するため、BufRead、Write、または明示的なラッパーを使って入出力アダプターを注入します。
• 通常の結果は stdout に書き込み、診断や進行状況のメッセージは stderr に出力します。
• stdout からパイプ入力を読み取るときは、ログ、色、プログレスバーを混在させないでください。
• TTY を検出した後にのみ対話型プロンプトを有効にし、この動作を上書きするオプションも用意します。
• Path／PathBuf を使い、プラットフォーム固有のパスを手作業で連結しないでください。

優先順位を明確に定義します。CLI > 環境変数 > 設定ファイル > デフォルト値。該当する場合は、競合時のテストを作成してください。ファイルを書き込む際は、部分書き込み、アトミックな置換方法、既存ファイルの扱い、権限に関する影響を考慮します。具体的なコマンドマトリクス、標準ストリーム、設定パターンが必要な場合は、コマンドの契約と I/O を参照してください。

5. 運用しやすいエラーを設計する

• 想定される失敗に対して、簡潔で、状況が分かり、対処方法を示すエラーメッセージを提供します。
• デフォルトでは、デバッグ用スタックや機密情報を端末のユーザーに表示しないでください。
• 詳細モードやログ記録のために、完全なエラーチェーンを保持します。
• エラーの種類を安定した終了コードに対応付けます。
• 壊れたパイプを適切に処理します。下流のフィルターが途中で閉じた場合に、余計な出力を発生させないでください。

ユーザー入力、ファイル、ネットワーク操作、設定の失敗に対して unwrap()／expect() を使用しないでください。

6. 実プロセスで検証する

少なくとも以下のシナリオを網羅してください。

1. --help と --version；
2. 正常に実行される経路；
3. 未知のパラメーター、引数の不足、競合するオプション；
4. stdout と stderr のストリームの分離；
5. 正確な終了コード；
6. stdin のパイプまたは一時ファイルの動作；
7. TTY をサポートしない場合の設定の優先順位；
8. スペースを含むパス、非 UTF-8 コンテンツ、またはプラットフォームの違いに関するパスのリスク（該当する場合）。

解析関数だけでなく、コンパイル済みバイナリのテストを優先してください。テストカバレッジとリリース成果物が必要な場合は、CLI Testing & Release を読んでください。一般的なテストの層別化は rust-testing に委任されています。

7. 配布形式を検証する

リポジトリレベルのゲートを適用してください。

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo build --release

クロスプラットフォーム対応または特定のターゲット対応を宣言している場合は、該当する環境または CI マトリックスで検証してください。パッケージング、機能、ワークスペース設定、クロスコンパイル、リリースの詳細は rust-cargo-build が担当します。

8. デーモン、IPC、ターミナルモードに対応する

CLI に永続デーモン、ローカル IPC、PTY、TUI などが含まれる場合は、すべてのコードをバイナリクレートにまとめないでください。解析ロジック、プロトコル DTO、プラットフォームレイヤー、クライアント、サーバー、公開 SDK を適切に分離してください。Daemon & IPC Terminal Toolkit に従って、ハンドシェイクのバージョン、機能ネゴシエーション、フレームサイズ、自動起動中の競合状態、シグナル、アタッチのアップグレード、シャットダウンシーケンス、ツール／境界の選択について、エンドツーエンドテストを作成してください。

完了基準

以下のすべてを満たした場合にのみ、完了を報告してください。

• コマンドの契約と互換性に関する前提が明確に定義されている；
• ビジネスロジックがプロセス境界から分離されている；
• stdout、stderr、終了コード、設定の優先順位を対象とする実プロセステストがある；
• fmt、check、test、Clippy がすべて成功する；
• サポート対象のプラットフォームと配布成果物について、サポートの根拠がある。未検証の項目は明示されている。

引き継ぎの範囲

主な懸念事項	担当先
所有権、パスのセマンティクス、I/O トレイトの定義またはエラー型	rust-stable
テストの層別化、カバレッジ、ファジング、ベンチマーク	rust-testing
Cargo の機能、ワークスペース設定、クロスコンパイル、パッケージング、リリース	rust-cargo-build
Tokio タスク、キャンセル、シグナル、非同期ライフタイム	rust-concurrency
HTTP サービス	rust-web

必要に応じて参照するリソース

• Command Contract & I/O：パラメーター、標準ストリーム、設定、終了コードを設計するときに読んでください。
• CLI Testing & Release：実プロセステストを作成する前、またはリリースの準備をする前に読んでください。
• Daemon & IPC Terminal Toolkit：ローカルデーモン、制御プロトコル、PTY、TUI、またはクロスプラットフォームのターミナルアプリケーションを構築するときに読んでください。
• Example Scenarios：エンドツーエンドのタスクテンプレートが必要な場合に読んでください。
• examples/golden-cli/：オフラインコンパイルを使用して、ゴールデン例の stdout、stderr、終了コードを検証してください。

参考資料

• Rust コマンドラインアプリ
• Rust のコマンドラインアプリケーション
• std::process (https://doc.rust-lang.org/stable/std/process/)
• std::io (https://doc.rust-lang.org/stable/std/io/)
• std::path (https://doc.rust-lang.org/stable/std/path/)