wizard-wx

ウィザード（Wizard）

wizard は、手作業で行うと手間がかかり、毎回 AI に一から説明するのも面倒な手順を、順を追って案内する bash スクリプトです。各 URL を開き、何をクリックして何をコピーするかを説明し、取得した値を適切な場所（.env、GitHub secret）に書き込み、各ステップで確認を取り、残りのステップ数を表示します。サードパーティサービスの設定、一度限りの移行の実行、プロジェクトをある状態から別の状態への切り替えに利用できます。

スムーズな体験は template.sh で実現済みです。段階ごとの進捗表示、確認ゲート、クロスプラットフォームでの URL 起動（WSL を含む）、secret の非表示入力、冪等な .env 更新、gh secret / gh variable への書き込み、そして最後のまとめが用意されています。あなた（エージェント）の仕事は、手順を定めて各 stage を記述することだけです。 STAGES マーカーより上のライブラリ部分は、すべての wizard で同一です。一貫性を保つことが重要なので、手を加えないでください。

wizard は一時的なものが標準です。一度の実行を目的としており、scratch または scripts/ パスに保存して、使い終わったら削除します。ユーザーが再利用可能なセットアップ手順を望み、リポジトリに残しておきたい場合に限り、コミットしてください。

手順

1. 手順の範囲を定める

人が手作業で行う必要のある各ステップと、その過程で取得する必要のある値をすべて整理します。まずリポジトリを確認してください。何も調べずに質問してはいけません。

• 設定関連：.env、.env.example、.env.*、README、docker-compose*、フレームワークの設定、そして .github/workflows/*（secrets.* / vars.* の参照はすべて、wizard が用意する値です）。
• 移行／切り替え関連：現在の状態、目標の状態、そしてその間にある不可逆な操作。

次に、順番に並べた stage の一覧と、各 stage で取得する値をユーザーに提示して確認します。ユーザーは項目の追加、削除、並べ替えができます。

完了条件： 各 stage の順序が決まっていること。取得する値ごとに、(a) 人がどこから取得するのか、(b) どこに書き込むのか（.env、GitHub secret、両方、またはどこにも書き込まない——操作だけの stage もあります）、(c) secret（非表示入力）か公開情報かが分かっていること。

2. 各 stage の手順を明確にする

各 stage について、人がたどる正確な手順を記述します。どの URL を開き、そこで何をし、値がどこに表示され、どの変数に入力するかを説明してください。たとえば「Dashboard → Developers → API keys → Reveal test key → コピー」のように記述します。現在の UI や正確なコマンドが分からない場合は、その旨を正直に伝え、ユーザーに確認するかドキュメントを調べてください。存在しないかもしれない手順を捏造してはいけません。

完了条件： 各 stage に、初めて行う人でも実行できる明確な指示があること。

3. wizard を作成する

template.sh をコピーして、目的のパスに配置します。サンプルの stage を各手順に置き換え、依存関係の順にそれぞれ stage を記述します。ライブラリのヘルパー関数——stage、say / step、open_url、ask / ask_secret、write_env、set_secret / set_var、pause / confirm——を使い、TOTAL_STAGES を記述した stage の数に設定します。

template が定めた基準を守ってください。値を取得する場合は、質問する前に open_url を使います。secret には必ず ask_secret を使います。永続化する値はすべて write_env で書き込みます。set_secret は CI が実際に必要とする値にのみ使います。不可逆な操作の前には必ず confirm を使います。各 stage は画面をクリアするため、画面には現在の手順だけが表示されます。各 stage では焦点を絞った作業を一つだけ行い、必要な情報が画面から流れて見えなくならないようにしてください。STAGES マーカーより上のライブラリ部分には触れないでください。

4. 検証して引き継ぐ

• bash -n <script> を実行します。利用できる場合は shellcheck も実行します。
• chmod +x <script> を実行します。
• エンドツーエンドでは実行しないでください。ブラウザーが開き、人の入力待ちになるためです。代わりに静的に追跡します。第 1 歩で挙げた値がすべて取得され、そこで決めた場所に書き込まれることを確認します。また、各 set_secret の名前が CI の secrets.* 参照と完全に一致していることを確認します。
• 実行方法をユーザーに伝えます。再利用可能なセットアップ手順の場合は、それをコミットして README からリンクし、次の人が AI に尋ねるのではなくスクリプトを実行できるようにします。