fallow-cloud-setup

Fallow Cloud のセットアップ：1 つのコミット SHA で実現するランタイムカバレッジ

Fallow Cloud が本番環境のランタイムカバレッジとコードを結び付けるのは、次の 5 つが同じコミット SHA を指定している場合に限られます。

1. アプリ内のビーコンが commitSha を送信する。
2. CI がその SHA の静的インベントリをアップロードする。
3. ビルドでコードをバンドルする場合、CI がその SHA のソースマップをアップロードする。
4. CI がその SHA のデプロイを登録する。
5. その SHA の最初の本番データが届く。

fallow coverage setup --cloud --json は、5 つすべての手順の計画を書き出します。このスキルでは、その計画を適用します。

使用する場面

• アプリに Fallow ビーコンを追加し、本番環境のカバレッジを Fallow Cloud に送信する場合。
• インベントリとソースマップをアップロードし、デプロイを登録する CI 手順を設定する場合。
• Fallow Cloud にリポジトリのデータが表示されない、または一致する関数が表示されない場合に、不足している手順を特定する場合。

使用しない場面

• ローカルのコード品質ツール、CI 品質ゲート、またはエージェントの連携には使用しないでください。fallow-setup を使用してください。
• すでにセットアップ済みのリポジトリのランタイムデータを読み取る場合には使用しないでください。fallow を使用してください。

ルール

1. API キーの値をファイル、コマンド、メッセージに書き込まないでください。計画に記載された環境変数名（cloud.api_key_env、cloud.browser_key_env）を使用してください。ユーザーは値を CI シークレットおよびサーバーの環境変数として保管します。--api-key フラグは決して使わず、コマンドの前にキーを記述しないでください（FALLOW_API_KEY=... npx ...）。ユーザーがシェルでキーをエクスポートします。
2. ブラウザバンドルに使用できるのは、取り込み専用キー（プレフィックス fallow_pub_k1_）だけです。フルキー（プレフィックス fallow_live_k1_）は CI とサーバーに保管します。
3. すべての手順で同じコミット SHA を使用してください。計画内の $GITHUB_SHA や commitSha 式を別の値に置き換えないでください。
4. フラグは fallow coverage setup --help で確認してください。記憶に頼ってフラグを使用しないでください。
5. CI ワークフローを変更する前に、変更内容をユーザーに提示してください。デプロイワークフローにはシークレットや本番環境へのアクセス権が含まれる場合があります。

手順

1. フラグを確認します。 npx fallow coverage setup --help を実行します。--cloud が表示されない場合は、手順 2〜8 ではなく手動セットアップを使用してください。同じ 5 つの手順があります。

2. プランを取得します。 リポジトリのルートで npx fallow coverage setup --cloud --json を実行します。cloud.project_id が null の場合は、Fallow Cloud のプロジェクト ID（owner/repo）をユーザーに尋ね、--project-id <owner/repo> を付けてコマンドを再実行します。これにより、スニペットに OWNER/REPO のプレースホルダーが残りません。コマンドが 2 で終了し、JSON が出力されない場合は、stderr のエラーを確認してください。プロジェクト ID、--git-sha、--api-endpoint などの入力が無効です。

3. プランを読みます。

   • members[] には、コードを実行する各ワークスペースメンバーのエントリがあります。各エントリには、それぞれ独自の snippets、files_to_edit、dockerfile_snippet、warnings があります。members[] のスニペットのみを適用してください。トップレベルの snippets と files_to_edit は、最初のメンバーの内容を繰り返しています。
   • commands はビーコンをインストールします。
   • cloud.ci.steps には、GitHub Actions の手順が含まれています（cloud.ci.provider は github_actions です）。cloud.ci.workflows_detected には、デプロイ用と思われるワークフローファイルが示されます。
   • cloud.source_maps.dirs には、バンドルされた各メンバーのビルド出力先が示されます。cloud.source_maps.reason には、ソースマップの出力など、ビルドで必要な処理が示されます。
   • warnings には、Node サーバーのカバレッジソースなど、プランでは対応できない内容が示されます。

4. ビーコンをインストールします。 プロジェクトのパッケージマネージャーを使用して、commands のコマンドを実行します。

5. スニペットを追加します。 各メンバーについて、各スニペットを path に指定されたファイルに追加します。スニペットの projectId、commitSha、coverageOrigin、runtimeSurface の値はそのままにします。ファイルが存在する場合は、エントリーモジュールの先頭にスニペットを追加してください。ファイルを置き換えないでください。

6. コミット SHA をランタイムに渡します。

   • ブラウザーバンドル：ビルド手順で VITE_FALLOW_COMMIT_SHA を設定します（CI の手順に記載されています）。
   • コンテナー内のサーバー：dockerfile_snippet の行を Dockerfile に追加し、--build-arg FALLOW_COMMIT_SHA=$GITHUB_SHA を付けてビルドします。
   • プラットフォーム上のサーバー：スニペットは、Vercel、Render、または Railway が設定する SHA を読み取ります。それ以外のプラットフォームでは、ランタイム環境で FALLOW_COMMIT_SHA を設定します。

7. CI の手順を追加します。 cloud.ci.steps を、cloud.ci.workflows_detected にあるワークフロー内の、ビルドとデプロイを行うジョブに追加します。このリストが空の場合、またはプロジェクトで GitHub Actions を使用していない場合は、どのジョブがデプロイを行うかユーザーに尋ね、そのジョブに合わせて手順を調整します。チェックアウトでは fetch-depth: 0 が必要です。アップロード手順はビルド手順の後に追加します。アップロードでデータを送信するには、ビルドでソースマップを出力する必要があります。登録手順はデプロイ手順の後に追加します。cloud.ci.instructions に従ってください。

8. ユーザーが手動で行う作業を伝えます。 ユーザーは Fallow Cloud のダッシュボードでキーを作成し、プランに記載されたシークレットとして保存してから、デプロイします。

9. デプロイ後にセットアップを確認します。 シェルで FALLOW_API_KEY（完全なキー）をエクスポートするようユーザーに依頼します。プランの cloud.wait_command に --json を追加し、$DEPLOYED_SHA にデプロイしたコミット SHA を設定して実行します。このコマンドにはプロジェクト ID が含まれています。その後、終了コードを確認します。

   • 0：すべての手順が完了しています。
   • 1：タイムアウトです。cloud.wait.activation.next を確認してください。今すぐ実行する手順と、存在する場合はコマンドが示されます。読み取りに成功しなかった場合、activation は null になり、next.command も null の場合があります。
   • 2：エラーです。cloud.wait.message を確認するか、標準出力に JSON がない場合は stderr を確認してください。

   activation の本文には、このスキルに記載されていない手順 ID や状態が含まれることがあります。そのままユーザーに伝えてください。

よくある問題

• beacon が problem になる：ビーコンがコミット SHA を送信していません。ステップ 5 を確認してください。
• runtime が waiting のままになる：アプリにまだ本番トラフィックがないか、ビーコンの commitSha が CI で使用した完全な SHA ではありません。
• deployment が waiting になる：古いデプロイに引き続きランタイムデータが届いています。新しいデプロイは、最初のランタイムデータを受け取ると現在のデプロイになります。
• overlap が waiting になる：これまでに実行された関数が少なすぎます。トラフィックを増やしてください。
• バンドルせずにソースファイルを実行するアプリで source_maps が missing になる：ランタイムデータがインベントリに加わると not_needed に変わります。
• overlap が problem になる：ランタイムのパスがインベントリのパスと一致していません。たとえば、コンテナ内でコードを別のルート（/app など）から実行する場合は、upload-inventory に --path-prefix が必要です。バンドルされたアプリにはソースマップが必要です。
• CI で inventory が失敗する：チェックアウトが浅い状態です。fetch-depth: 0 を設定してください。

参考資料

• 手動セットアップ：--cloud を使わず、未使用バージョンで手動で行う 5 つのステップです。