wizard

ウィザード

ウィザードとは、手動の手順を人間に案内する Bash スクリプトです。URL を開き、クリックやコピーする場所を説明し、値を取得して所定の保存先に書き込み、進捗を表示します。サードパーティーサービスの設定、単発の移行、プロジェクトの状態の切り替えなどに使えます。

template.sh は、段階ごとの進捗表示、確認ゲート、WSL を含むクロスプラットフォームの URL 起動、非表示のシークレット入力、冪等な .env の更新、gh secret／gh variable への書き込み、終了時の概要表示を提供します。手順の範囲を定め、STAGES マーカーより上にある共通ライブラリを手作業で編集せずに、各ステージを記述してください。

ウィザードは、デフォルトでは一時的なものです。依頼された実行用に、一時パスへ保存してください。ユーザーがリポジトリ内で繰り返し使えるセットアップ手順を希望する場合は、プロジェクトのスクリプト規約に従って保存し、実行方法を文書化してください。繰り返し使えるからといって、コミットが許可されたことにはなりません。コミットするのは、ユーザーがその操作を許可した場合に限ります。

プロセス

1. 手順の範囲を定める

依頼されたセットアップ、移行、状態の切り替えに必要なステップと値を特定します。情報を尋ねる前に、関連するリポジトリのコンテキストを確認してください。

• セットアップの場合：関連する環境設定の例、README の手順、サービスとフレームワークの設定、CI ワークフローを確認します。secrets.*／vars.* の参照を使って、依頼されたセットアップの値を利用する箇所を特定します。無関係な参照によってウィザードの範囲を広げないでください。必要に応じて既存の設定を再利用し、認証情報を再度収集しないようにします。シークレットを含むファイルは必要な場合にのみ確認し、その値を露出させないでください。
• 移行または状態の切り替えの場合：現在の状態、目標の状態、それらの間にある取り消せない操作を特定します。

会話の中ですでに決まっている手順や判断を再利用してください。ステージの概要は進捗報告として提示できます。改めて承認を求める必要はありません。手順、目標、取得する値に大きく影響する未解決の選択肢についてのみ質問し、その選択肢が未決の間も独立したステージの準備を進めてください。完成したスクリプトを実行するのは人間です。影響の大きい操作はスクリプトの confirm ゲートで承認されるため、自分で実行しないでください。

**完了条件：**すべてのステージに順番どおり名前が付いており、取得する値ごとに、（a）人間がその値を取得する場所、（b）書き込み先（.env、GitHub シークレット、両方、またはいずれにも書き込まない。純粋な操作のみのステージもあります）、（c）シークレットか公開情報か（非表示入力にするか）が分かっていること。

2. 各ステージの手順を整理する

各ステージについて、人間がたどる手順を正確に記述します。開く URL、そこで行う操作、値が表示される場所、設定先の変数を明記してください。例：「ダッシュボード → 開発者 → API キー → テストキーを表示 → コピー」。現在の UI や正確なコマンドが分からない場合は、その旨を伝えてユーザーに尋ねるか、ドキュメントを確認してください。存在するか分からない手順を決して作らないでください。

**完了条件：**すべてのステージに、初めて使う人でも実行できる具体的な手順が示されていること。

3. ウィザードを作成する

template.sh を対象パスにコピーします。サンプルのステージを、依存関係の順に各手順につき 1 つの stage に置き換えます。ライブラリのヘルパー（stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm）を使用します。作成したステージの数を TOTAL_STAGES に設定します。

値を尋ねる前に URL を開きます。シークレットには ask_secret を使用し、取得したシークレットをスクリプトに埋め込んだり、表示したりしないでください。各値は、スコープが定められた保存先にのみ保存します。ローカルの環境ファイルには write_env を、該当する GitHub の設定には set_secret/set_var を使用します。ヘルパーが存在するという理由だけで、値を追加の保存先にコピーしないでください。

元に戻せない操作を実行する前に、その対象と結果を示し、confirm が成功してから実行してください。確認が拒否された場合は、その操作をスキップするか、中止してください。バナーの準備完了時の一時停止は、確認の代わりにはなりません。ユーザーがスクリプトの準備を許可している場合も、実行前の確認ゲートは維持してください。

各 stage と finish は Enter キーを待ってから画面をクリアするため、人間がステージの確認事項や警告を読んでから次に進みます。各ステージは、画面内に表示内容がすべて収まるよう、焦点を絞ったタスク 1 つにしてください。マーカーより上のライブラリには手を加えないでください。

4. 検証して引き渡す

• bash -n <script> を実行し、利用可能であれば shellcheck も実行します。
• chmod +x <script> を実行します。
• スクリプトを最初から最後まで自分で実行しないでください。ブラウザーを開き、人間の入力待ちになるためです。代わりに静的に処理を追跡し、必要な値が取得または再利用されること、各書き込みが意図した保存先に届くこと、CI のシークレット名と変数名が該当する利用側と一致すること、確認が拒否された後に元に戻せない操作が実行されないことを確かめます。
• スクリプトと実行手順を提示し、gh による書き込みの対象となるリポジトリを明記します（スクリプトは実行するディレクトリのリポジトリを使用します）。また、人間による確認が必要な、影響の大きいステージを示します。依頼されたスクリプトが人間の実行に向けて準備できた時点で完了とし、セットアップや移行を実行済みであると主張しないでください。