mattpocock/wizard

wizard は何をしますか？

Wizardは、人間が手作業で行うには面倒で、AIに毎回説明するのも手間な手動手順を、ステップバイステップで人間を案内するbashスクリプトです。各URLを開き、クリックしてコピーすべき内容を正確に指示し、値を取得して適切な場所（.env、GitHub Secretsなど）に書き込み、各段階で確認を促し、残りのステージ数を表示します。サードパーティサービスの設定、一度きりのマイグレーションの実行、プロジェクトの状態遷移などに使用できます。

優れたUXはtemplate.shによって既に解決されています。ステージごとの進捗表示、確認ゲート、クロスプラットフォームなURLオープン（WSL含む）、隠しシークレット入力、冪等な.envのupsert、gh secret/gh variableの書き込み、終了時のサマリー表示などです。あなたの仕事は手順のスコープを決め、そのステージを作成することだけです。 STAGESマーカーの上のライブラリ部分はすべてのウィザードで同一であり、その一貫性が重要です。決して手動で編集しないでください。

ウィザードはデフォルトで一時的なものです。1回の実行のために作成され、スクラッチディレクトリまたはscripts/パスに保存され、ジョブが完了すると削除されます。ユーザーがリポジトリに残すべき繰り返し可能なセットアップパスを希望する場合にのみコミットしてください。

プロセス

1. 手順のスコープを決める

人間が実行しなければならないすべての手動ステップと、その過程で取得されるすべての値を洗い出します。まずリポジトリを読み、何も聞かずに始めないでください。

• セットアップの場合: .env、.env.example、.env.*、README、docker-compose*、フレームワークの設定、および.github/workflows/*（すべてのsecrets.* / vars.*参照は、ウィザードが生成しなければならない値です）。
• マイグレーションまたは移行の場合: 現在の状態、目標の状態、およびそれらの間の不可逆的なアクション。

次に、ユーザーにステージの順序付きリストと各ステージが生成する値を表示し、確認を取ります。ユーザーはステージの追加、削除、順序変更を行うことができます。

完了条件: すべてのステージが順序付けられて名前が付けられ、取得する各値について、(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を使用し、CIが実際に必要とする値にのみset_secretを使用し、不可逆的なアクションの前にはconfirmを使用します。各stageは画面をクリアして現在のステップのみが表示されるようにします。各ステージは1つのタスクに集中させ、人間が必要とする情報がスクロールアウトしないようにします。マーカーの上のライブラリ部分には触れないでください。

4. 確認と引き渡し

• bash -n <script>で構文チェックを行います。可能であればshellcheckを実行します。
• chmod +x <script>で実行権限を付与します。
• 自分でエンドツーエンドで実行しないでください。ブラウザが開き、人間の入力でブロックされます。代わりに静的にトレースします。ステップ1のすべての値が取得され、ステップ1で指定された場所に格納されていること、およびすべてのset_secret名がCI内のsecrets.*参照と完全に一致していることを確認します。
• ユーザーに実行方法を伝えます。繰り返し可能なセットアップパスの場合は、コミットしてREADMEからリンクし、次回の担当者がAIに尋ねる代わりにスクリプトを実行できるようにします。