activate-site

プラグインの確認：node "${PLUGIN_ROOT}/scripts/check-version.js" を実行します。メッセージが出力された場合は、先にユーザーに表示してから続行してください。

Power Pages サイトを有効化する

Power Platform REST API を使用して、Power Platform 環境に新しい Power Pages Web サイトをプロビジョニングします。

前提条件： このスキルは、/create-site で作成済みの Power Pages SPA サイトがあることを前提としています。サイトがまだ存在しない場合は、先にそのスキルを実行してください。

基本原則

• クラウドを考慮した URL 解決 — API のベース URL やサイト URL のドメインをハードコードしないでください。必ず pac auth who が返す Cloud の値から導き出してください。
• トークンの処理 — エージェントが確認する必要があるのは、ユーザーが Azure CLI にログインしていることだけです。
• 変更前に確認 — websites API に POST する前に、必ず有効化の全パラメーターをユーザーに提示し、明示的な承認を得てください。
• 呼び出し元の環境を維持 — 別のスキルから environmentUrl が渡された場合は、有効化の前に PAC と Azure CLI が引き続きその環境とテナントを対象としていることを確認してください。
• 呼び出し元へのステータス更新 — /create-site から statusPath が渡された場合は、有効化の確認を促す前と後にそのファイルを更新し、開いているテンプレートのステータスページにユーザー入力が必要なタイミングが表示されるようにしてください。

初回リクエスト： $ARGUMENTS

ワークフロー

1. フェーズ 1：前提条件の確認 — PAC CLI 認証、Azure CLI ログイン、有効化ステータスの確認
2. フェーズ 2：パラメーターの収集 — サイト名、サブドメイン、Web サイトレコード ID
3. フェーズ 3：確認 — すべてのパラメーターをユーザーに提示して承認を得る
4. フェーズ 4：有効化とポーリング — 有効化スクリプトを実行（POST とプロビジョニングステータスのポーリング）
5. フェーズ 5：概要の提示 — サイト URL を表示し、次のステップを提案する

---

フェーズ 1：前提条件の確認

目標： PAC CLI がインストールされ、認証済みであることを確認し、ユーザーが Azure CLI にログインしていることを確認します。

実行手順

1.1 PAC CLI の確認

pac help を実行し、PAC CLI がインストールされ、システムの PATH で利用可能か確認します。

pac help

コマンドが失敗した場合（コマンドが見つからない／認識されない）：

1. ユーザーに「PAC CLI がインストールされていません。次のコマンドを実行してインストールできます」と伝えます。

   dotnet tool install --global Microsoft.PowerApps.CLI.Tool
   

2. dotnet も利用できない場合は、完全なインストール手順について https://aka.ms/PowerPlatformCLI を案内します。

3. インストール後、再度 pac help を実行して確認します。

1.2 認証の確認

pac auth who を実行し、現在の認証状態を確認します。

pac auth who

認証済みの場合：出力から次の値を抽出します。

• 環境 ID — Environment ID: の後にある GUID
• 組織 ID — Organization ID: の後にある GUID（Dataverse 組織 ID）
• Cloud — Cloud: の後の値（例：Public、UsGov、UsGovHigh、UsGovDod、China）

未認証の場合：deploy-site と同じ認証フローに従い、ユーザーに環境 URL を尋ねて pac auth create --environment "<URL>" を実行します。

1.3 Azure CLI ログインの確認

ユーザーが Azure CLI にログインしていることを確認します。

az account show

az がインストールされていない、またはログインしていない場合：Azure CLI をインストールし、az login --allow-no-subscriptions を実行するようユーザーに案内します（Azure サブスクリプションの有無にかかわらず、この形式で実行できます。有効化フローで必要なのは AAD トークンのみです）。

1.4 すでに有効化されているか確認する

まず、$ARGUMENTS を調べて、別のスキルからインポートされたサイトの識別情報が明示されているか確認します。

siteName: <name>
websiteRecordId: <guid>
environmentUrl: <url>
statusPath: <path>

両方の値がある場合は、すぐに SITE_IDENTITY_SOURCE = "arguments" を設定し、以下のローカルプロジェクトの有効化状態チェックをスキップします。このチェックでは powerpages.config.json / .powerpages-site から識別情報を解決するため、/create-site でインポート済みのテンプレートサイトを有効化する場合、ファイルが存在しない、または無関係な情報が含まれている可能性があります。明示された識別情報を使ってフェーズ 2 に進みます。

environmentUrl がある場合は、EXPECTED_ENVIRONMENT_URL として保存し、フェーズ 2 の前に現在の CLI コンテキストを確認します。

node "${PLUGIN_ROOT}/scripts/validate-cli-tenant-alignment.js" --envUrl "<EXPECTED_ENVIRONMENT_URL>"

JSON の結果が ok: true の場合にのみ続行します。このチェックでは、アクティブな PAC 環境の URL と呼び出し元の URL を比較し、PAC、Azure アカウント、Dataverse アクセストークンが同じテナントを使用していることを確認します。失敗した場合は停止し、PAC または Azure CLI の認証を切り替えるようユーザーに依頼します。別の環境では、インポートした Website Record ID を有効化しないでください。

source が create-site template path で、statusPath がある場合は、ACTIVATION_STATUS_PATH として保存します。これは /create-site が作成した既存のテンプレートステータスファイルです。別のステータスページは作成しないでください。

SITE_IDENTITY_SOURCE !== "arguments" の場合は、共有の有効化ステータススクリプトを実行して、ローカルプロジェクトのサイトがすでに有効化されているか確認します。

node "${PLUGIN_ROOT}/scripts/check-activation-status.js" --projectRoot "<PROJECT_ROOT>"

<PROJECT_ROOT> は、powerpages.config.json または .powerpages-site フォルダーがあるディレクトリです。 JSON の結果を評価します。

• activated が true の場合：サイトがすでに websiteUrl で有効化されていることをユーザーに伝えます。次の手順（フェーズ 5.3）を提案して停止します。フェーズ 2 には進まないでください。
• activated が false の場合：フェーズ 2 に進みます。
• error がある場合：フェーズ 2 に進みます（有効化のフローを妨げないでください）。

SITE_IDENTITY_SOURCE = "arguments" の場合は、このローカルプロジェクトのステータスチェック全体をスキップし、指定されたサイト識別情報を使ってフェーズ 2 に進みます。

出力

• PAC CLI がインストールされ、認証済みであること
• 環境 ID、組織 ID、クラウドの値が抽出されていること
• Azure CLI のログインが確認されていること
• ローカルプロジェクトの有効化状態を確認済み、または引数ベースのインポート済みサイトでは確認をスキップ済みであること

---

フェーズ 2：パラメーターの収集

**目標：**サイト名を特定し、サブドメインを生成するか受け取り、有効化 API 呼び出しに必要な Web サイトレコード ID を検索します。

操作

2.1 サイト名の読み取り

別のスキルから呼び出され、$ARGUMENTS にインポート済みサイトの識別情報が明示されている場合は、ローカルプロジェクトの検出より先にそれを使用します。

siteName: <name>
websiteRecordId: <guid>

両方の値がある場合：

• 明示された値から siteName を設定します。
• 明示された値から websiteRecordId を設定します。
• SITE_IDENTITY_SOURCE = "arguments" を設定します。
• 呼び出し元がインポート済みの Web サイトレコードをすでに解決しているため、以下の powerpages.config.json の検索と、フェーズ 2.3（pac pages list）をスキップします。

明示された値のいずれかがない場合は、既存のローカルプロジェクト検出フローを続行します。

Glob を使い、現在のディレクトリまたはその 1 階層下のサブディレクトリにある powerpages.config.json を検索します。

**/powerpages.config.json

ファイルを読み取り、siteName フィールドを抽出します。見つからない場合は、AskUserQuestion を使ってユーザーにサイト名を尋ねます。

2.2 サブドメイン候補の生成

重要 — この手順は必須です。続行する前に、必ずサブドメインについてユーザーに確認してください。この手順を省略したり、ユーザーの入力なしにサブドメインを自動選択したりしないでください。

サブドメイン生成スクリプトを実行して、ランダムな候補を作成します。

node "${PLUGIN_ROOT}/skills/activate-site/scripts/generate-subdomain.js"

site-a3f2b1 のような文字列が出力されます。Phase 1.2 で取得した Cloud の値から、正しいサイト URL ドメインを判定します。

Cloud	Site URL Domain
Public	powerappsportals.com
UsGov	powerappsportals.us
UsGovHigh	high.powerappsportals.us
UsGovDod	appsplatform.us
China	powerappsportals.cn

🚦 ゲート（計画 · activate-site:2.2.subdomain）： 生成されたサブドメインを確認するか、変更します。サブドメインは最終的なサイト URL の一部です。キャンセルすると、プロビジョニングの呼び出し前に終了します。

生成されたサブドメインをユーザーに提示し、AskUserQuestion を使って、そのまま使用するか独自のものを入力するか尋ねます。

Question	Header	Options
サイトのサブドメインは <suggestion> になります（完全な URL：https://<suggestion>.<siteUrlDomain>）。このサブドメインを使用しますか、それとも独自のサブドメインを入力しますか？	サブドメイン	<suggestion> を使用（推奨）、カスタムサブドメインを入力

ACTIVATION_STATUS_PATH が設定されている場合は、AskUserQuestion の直前に Write を使用して、ファイルをアトミックに上書きします。

{
  "state": "running",
  "phase": "activation",
  "message": "Waiting for subdomain selection",
  "awaitingInput": true,
  "inputPrompt": "Choose the site subdomain in the agent terminal."
}

ユーザーの応答直後に、トーストが消えるようファイルを再度上書きします。

{
  "state": "running",
  "phase": "activation",
  "message": "Preparing site activation",
  "awaitingInput": false
}

ユーザーがプロンプトをキャンセルした場合は、停止する前に awaitingInput をクリアしてください。サブドメインの競合によってこの手順に戻る場合も、同じステータス更新を適用してください。

カスタムの場合：ユーザーは「その他」の自由入力で独自のサブドメインを指定します。小文字の英数字とハイフンのみで構成され、3～50文字であることを検証してください。

2.3 Web サイトレコード ID の取得

SITE_IDENTITY_SOURCE = "arguments" で、websiteRecordId がすでに設定されている場合は、この手順をスキップします。

pac pages list を実行して、Web サイトレコード ID を取得します。

pac pages list

出力を解析して、サイト名に一致する Web サイトレコードを見つけます。Website Record ID（GUID）を抽出します。pac pages list で結果が返されない場合、またはコマンドを使用できない場合は、websiteRecordId を $null に設定します。API によって新しい Web サイトレコードが作成されます。

出力

• サイト名が確定している（設定ファイルまたはユーザー入力から）
• サブドメインが選択されている（生成またはカスタム）
• Web サイトレコード ID が解決されている（GUID または null）

---

Phase 3：確認

目標： すべての有効化パラメーターをユーザーに提示し、API 呼び出しの前に明示的な承認を得ます。

アクション

🚦 ゲート（最終 · activate-site:3.confirm）： 有効化 API 呼び出し前の最終確認です。すべての有効化パラメーターを再提示します。キャンセルすると、プロビジョニングの前に正常に終了します。スキルを呼び出すたびに、新たに実行されます。 plan-alm が複数段階の有効化（ステージング + 本番環境）をオーケストレーションする場合、activate-site は各段階につき1回呼び出されます。各呼び出しで、このゲートが個別の siteName、subdomain、対象環境を使って新たに実行されます。ステージング環境の有効化への同意は、本番環境には適用されません。各段階のサイト URL は、対象者や時期が異なるため、それぞれ独立した公開判断となります。

AskUserQuestion を使って、すべての有効化パラメーターをユーザーに提示します。

Question	Header	Options
次の設定で Power Pages サイトを有効化する準備ができました。\n\n- サイト名：<siteName>\n- サブドメイン：<subdomain>.powerappsportals.com\n- 環境 ID：<environmentId>\n\n有効化を続行しますか？	有効化	はい、サイトを有効化する（推奨）、いいえ、キャンセル

「いいえ」の場合：スキルを停止し、後で再実行できることをユーザーに伝えます。

「はい」の場合：Phase 4 に進みます。

出力

• ユーザーが有効化パラメーターを明示的に承認している

---

Phase 4：有効化とポーリング

目標： Power Platform の Web サイト API に POST してプロビジョニングを開始し、完了するまでポーリングして、結果を報告します。

アクション

4.1 アクティベーションスクリプトを実行する

フェーズ 1～2 で収集したすべてのパラメーターを渡して、共通のアクティベーションスクリプトを実行します。

node "${PLUGIN_ROOT}/skills/activate-site/scripts/activate-site.js" --siteName "<siteName>" --subdomain "<subdomain>" --organizationId "<organizationId>" --environmentId "<environmentId>" --cloud "<cloud>" --websiteRecordId "<websiteRecordId>"

--websiteRecordId が null または空の場合は省略します。

スクリプトの JSON 結果を、信頼できるアクティベーション結果として扱います。Bash のタイムアウトを 360 秒以上に設定してフォアグラウンドで実行し、終了するまでフェーズ 5 に進まないでください。別途、準備状況のポーリングを開始しないでください。

4.2 結果を処理する

JSON 出力を評価します。

status の値	statusCode / errorCode	アクション
Succeeded	—	プロビジョニングが完了しました。結果には siteUrl が含まれています。フェーズ 5 に進みます。
Failed	400 + SubdomainConflict（またはエラーメッセージにサブドメインへの言及がある）	サブドメインはすでに使用されています。フェーズ 2 のアクション 2.2 に戻って新しいサブドメインを指定し、スクリプトを再実行します。
Failed	401	トークンの有効期限が切れています。ユーザーに az login --allow-no-subscriptions を実行して再試行するよう依頼します。
Failed	403	権限が不足しています。「Power Pages site creator」または「System Administrator」ロールが必要であることをユーザーに伝えます。
Failed	409	Web サイトはすでに存在します。ユーザーにその旨を伝え、代わりに /deploy-site を使用するよう提案します。
Failed	429 または 5xx	スロットリングまたはサーバーエラーです。5 秒待って、スクリプトを 1 回再実行します。
Failed	その他	エラーをユーザーに提示し、トラブルシューティングを支援します。
Running	—	5 分経過後もプロビジョニングが進行中です。最長 15 分かかる場合があることをユーザーに伝え、Power Platform 管理センターを確認するよう提案します。
error フィールド	—	前提条件を満たしていません（引数が不足している、トークンがないなど）。エラーを提示し、トラブルシューティングを支援します。

アクティベーションスクリプトが Succeeded を返した後に、siteUrl に対する 2 回目のバックグラウンドポーリングを開始しないでください。HTTP と DNS の反映はプロビジョニングの完了より遅れることがあるため、コマンドを残して別のアシスタントターンを誘発するのではなく、その注意点をフェーズ 5 で伝えます。誤って追加の到達性ポーリングを開始した場合は、アクティベーションの概要を提示する前に停止してください。

出力

• プロビジョニングの状態が確定していること（siteUrl を伴う Succeeded、エラーの詳細を伴う Failed、またはタイムアウトに関する案内を伴う Running）

---

フェーズ 5：概要を提示する

目標： 最終的なサイト URL をユーザーに示し、次の手順を提案します。

アクション

5.1 結果を表示する

スクリプト出力の siteUrl を使って、アクティベーションの概要を提示します。

Power Pages site activated successfully!

  Site Name:  <siteName>
  Site URL:   <siteUrl>
  Environment: <environmentName> (<environmentId>)
  Status:     Provisioned

スクリプトはクラウドごとに適切なサイト URL ドメインをすでに解決しているため、siteUrl の値をそのまま使用します。

5.1b docs/alm/last-activate.json マーカーを書き込む

レンダリングされた ALM プラン（Manual パスのターゲットごとの Activate ステップなど）の利用者向けに、アクティベーション後の状態を記録する構造化マーカーを書き込みます。最初に docs/alm/ ディレクトリが存在することを確認してください。

node -e "require('fs').mkdirSync('docs/alm',{recursive:true})"
# Determine the stage label this activation was for. The upstream ALM context
# (e.g. the user running this after import-solution) supplies it as "Staging"/
# "Production"; standalone invocations may leave it null — refreshActivateSite
# falls back to env-URL matching against planData.stages[].envUrl.
node -e "require('fs').writeFileSync('docs/alm/last-activate.json', JSON.stringify({
  stageName: <stageNameOrNull>,
  siteName: '<siteName>',
  siteUrl: '<siteUrl>',
  websiteRecordId: '<websiteRecordId>',
  environmentUrl: '<envUrl>',
  environmentId: '<environmentId>',
  activatedAt: new Date().toISOString(),
  status: 'Activated',
  cloud: '<cloud>',
}, null, 2))"

フェーズ 1.4 で「すでにアクティベート済み」と判定された場合も、マーカーを書き込みます。アクティベーションを今回実行したか、以前に完了していたかにかかわらず、レンダリングされたプランには「このステージは https://... で稼働中」と反映される必要があります。status: 'AlreadyActivated' を設定し、フェーズ 1.4 のチェックで確認した既存の siteUrl を使用します。

5.2 スキルの使用状況を記録する

参照：${PLUGIN_ROOT}/references/skill-tracking-reference.md

参照先のスキル追跡手順に従って、このスキルの使用状況を記録します。--skillName "ActivateSite" を使用します。

5.2b ALM プランを更新する（存在する場合）

node "${PLUGIN_ROOT}/scripts/lib/refresh-alm-plan-data.js" \
  --projectRoot "." \
  --phase activate-site \
  --stageName "{stageNameOrEmpty}" \
  --render

{stageNameOrEmpty} は、エージェントが有効化しようとしていた手動パスの対象ステージのラベル（例：Staging、Production）です。ユーザーが指定した値、または対象環境から推定した値を指定します。不明な場合は空文字列を渡してください。refreshActivateSite は docs/alm/last-activate.json の environmentUrl と planData.stages[].envUrl を照合するため、単独で実行した場合も記録されます。

このヘルパーは docs/alm/last-activate.json を読み取り、planData.activations[stageName] に対象ごとのエントリー（siteUrl、status、activatedAt）を書き込みます。また docs/alm-plan.html を再描画し、一致する Activate site in {stageName} チェックリストのステップに、ライブサイトの URL をインライン表示した ACTIVATED バッジを表示します。docs/.alm-plan-data.json が存在しない場合（単独で実行され、ALM プランの一部ではない場合）、このヘルパーはソフトな no-op として ok:false を返します。

次のステップをユーザーに案内する（ユーザー主導の順序制御）。 ヘルパーの標準出力 JSON には nextStep: { name, skill: string | null } | null が含まれます。null でない場合、skill に応じて分岐します。skill が null でない場合は、ユーザーに 「プランを更新しました。プランの次のステップ：{nextStep.name} → 準備ができたら {nextStep.skill} を実行してください。」 と伝えます。skill が null の場合（Finalize など、ユーザーコマンドを必要としない内部ステップ）は、ステップ名だけを伝えます。「プランを更新しました。プランの次のステップ：{nextStep.name}。」 とし、run null は決して表示しないでください。null の場合、またはヘルパーが ok:false を返した場合は、次のステップについて何も伝えません。次のスキルを自動的に呼び出してはいけません。実行するのはユーザーです。

5.3 次のステップを提案する

概要の後に、次の項目を提案します。

• サイトをテストする：/test-site — サイトが正しく読み込まれ、API 呼び出しが機能していることを確認します
• ALM をセットアップする：/power-pages:plan-alm — このサイトをステージングまたは本番環境に昇格させるための ALM をセットアップします（ソリューションを作成し、デプロイパイプラインまたはエクスポート／インポート戦略を構成します）
• データモデルをセットアップする：/setup-datamodel
• サンプルデータを追加する：/add-sample-data
• プロビジョニングされた URL でブラウザーからサイトを表示する（注：DNS の反映には数分かかる場合があります）

出力

• サイト URL を含む有効化の概要を提示
• 次のステップをユーザーに提案

---

重要な注意事項

進捗状況の追跡

各フェーズの進捗を追跡するため、最初に TaskCreate を使用します。

タスク	説明
フェーズ 1	前提条件の確認 — PAC CLI 認証、Cloud の検出、Azure CLI ログイン、有効化ステータスの確認
フェーズ 2	パラメーターの収集 — サイト名、サブドメイン、Web サイトレコード ID
フェーズ 3	確認 — 有効化パラメーターに対するユーザーの承認
フェーズ 4	有効化とポーリング — 有効化スクリプトの実行、結果への対応
フェーズ 5	概要の提示 — サイト URL と次のステップを表示

各フェーズが完了したら、TaskUpdate でタスクを完了としてマークします。

主な判断ポイント

• フェーズ 1.2：認証されていない場合は、先に認証する必要があります。スキップできません。
• フェーズ 1.4：サイトがすでに有効化されている場合は、そこで終了します。フェーズ 2 に進んではいけません。
• フェーズ 2.2：ユーザーは生成されたサブドメインを受け入れるか、カスタム値を指定できます。カスタム入力は検証してください。
• フェーズ 3：有効化にはユーザーの明示的な承認が必要です。承認されなかった場合は、スキル全体を終了します。
• フェーズ 4.2：400（サブドメイン使用済み）の場合は、フェーズ 2 のアクション 2.2 に戻り、スクリプトを再実行します。中止してはいけません。
• フェーズ 4.2：409（サイトがすでに存在）の場合は、ユーザーを /deploy-site に案内します。
• フェーズ 4.2：タイムアウト（5 分経過後も Running）の場合は、失敗として扱ってはいけません。管理センターで確認するようユーザーに案内してください。

フェーズ 1：前提条件の確認から開始してください