diagnose-deployment

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

diagnose-deployment

デプロイエラーを検出し、既知のエラーカタログとパターンマッチングします。特定されたエラーに自動修正が利用可能な場合は、変更を適用する前に、ユーザーに明示的な許可を求めます。確認なしで修正を自動適用することはありません。

前提条件

• powerpages.config.json があるプロジェクトルート
• PAC CLI がインストールされていること（見つからない場合は報告します）

フェーズ

フェーズ 1 — 前提条件の確認とプロジェクトの特定

このフェーズの開始時に、すべてのタスクをあらかじめ作成してください。

作成するタスク：

1. 「前提条件を確認してプロジェクトを特定する」
2. 「デプロイ成果物を収集する」
3. 「アップロードエラーを提示する」
4. 「ソリューションのインポート状態を照会する」
5. 「検出結果を診断して分類する」
6. 「自動修正を提案する」
7. 「検出結果の概要を提示する」

手順：

1. プロジェクトルートを特定します。cwd と親ディレクトリで powerpages.config.json を検索します。
2. PAC CLI を確認します。pac --version を実行し、バージョンまたは「未インストール」を報告します。
3. PAC CLI の認証を確認します。pac env who を実行し、環境 URL または「未認証」を報告します。
4. Azure CLI を確認します。az account show を実行し、サブスクリプションまたは「未ログイン」を報告します。

認証エラーはブロッキング要因ではありません。検出結果として報告し、ほかの成果物の収集を続行します。

フェーズ 1.5 — 最新の ALM ドキュメントに基づく確認

参照：${PLUGIN_ROOT}/references/alm-docs-grounding.md

この手順は約 30 秒以内に完了させます。MCP の検索または取得でエラーが発生した場合は、1 行のメモを記録して続行してください。このスキルはオフラインでも実行可能である必要があります。

1. 次のクエリで microsoft_docs_search を実行します：Power Pages deployment errors solution import troubleshooting。
2. https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm（およびトラブルシューティングまたは既知のインポートエラーに関する関連ページを最大 1 件）を microsoft_docs_fetch で並行して取得します。
3. 一般的なデプロイ失敗とその解決方法について、Microsoft Learn が現在説明している内容を 1 段落にまとめます。${PLUGIN_ROOT}/references/deployment-error-catalog.md と比較し、カタログにまだ記載されていない新しいエラーパターンがあれば報告します。
4. この要約をフェーズ 5 のパターンマッチングに活用します。Learn に記載されていてカタログにはない新しいパターンがあれば、カタログを黙って拡張せず、追加候補としてユーザーに提示します。

フェーズ 2 — デプロイ成果物の収集

利用可能なすべてのコンテキストを収集します。

1. powerpages.config.json を読み取り、siteName、websiteRecordId、compiledPath を抽出します。
2. .powerpages-site/ フォルダーの有無を確認します。
3. マニフェストファイルを glob で検索します：.powerpages-site/*-manifest.yml。見つかったファイルをすべて一覧表示し、それぞれの環境ホスト名を記録します。
4. .solution-manifest.json の有無を確認します（ソリューション関連の診断用）。
5. docs/alm/last-import.json の有無を確認します（最近のインポート失敗用）。
6. ビルド出力を確認します。{compiledPath}/ が存在し、空ではないことを確認します。

報告：「プロジェクト {siteName} が見つかりました。成果物を収集しました。」

フェーズ 3 — アップロードエラーの提示

キャプチャモードで pac pages upload-code-site を再実行し、新しいエラー出力を取得します。

pac pages upload-code-site --rootPath "." 2>&1

注：エラーを取得するため、意図的にアップロードを実行します。アップロードが問題なく成功した場合も、有効な診断結果（「エラーは見つかりませんでした」）です。

stdout と stderr を 1 つの文字列としてキャプチャします。scripts/parse-deployment-errors.js に渡します。

echo "{escaped-output}" | node "${PLUGIN_ROOT}/scripts/parse-deployment-errors.js"

JSON の検出結果配列を解析します。エラーなしでアップロードが成功した場合は、その旨を記録し、検出結果リストを空にしてフェーズ 5 に進みます。

フェーズ 4 — ソリューションのインポート状態の照会

.solution-manifest.json が存在する場合にのみ実行します。

1. 環境 URL 用の Azure CLI トークンを取得します。
2. 最近の非同期操作（過去 24 時間）を確認します。

   GET {envUrl}/api/data/v9.2/asyncoperations?$filter=statecode eq 3 and statuscode eq 31 and createdon gt {yesterday}&$select=asyncoperationid,name,message,friendlymessage,statuscode,completedon&$orderby=completedon desc&$top=5
   

3. 最近のインポートジョブを確認します。

   GET {envUrl}/api/data/v9.2/importjobs?$select=solutionname,completedon,progress&$orderby=completedon desc&$top=3
   

4. 失敗した操作が見つかった場合は、それぞれの message フィールドを parse-deployment-errors.js に渡します。

認証を利用できない場合（フェーズ 1 で認証に失敗した場合）は、問題なくスキップします。

フェーズ 5 — 既知の問題を自動診断する

フェーズ 3 と 4 のすべての所見をまとめます。各所見を次のように分類します。

• Error：デプロイを妨げます
• Warning：問題が発生する可能性があります
• Info：参考情報です

フェーズ 2 で見つかった不足アーティファクトについても所見を追加します。

• websiteRecordId がない → Error（patternId: missing-website-record-id）
• ビルド出力が空 → Error（patternId: empty-build）
• 環境マニフェストが複数ある → Warning（環境の混同を示している可能性があります）

すべての所見を次の表に示します。

#	重大度	種類	問題	自動修正？
1	Error	upload	JavaScript のアップロードがブロックされています	はい
2	Warning	config	複数のマニフェストファイルが見つかりました	いいえ

フェーズ 6 — 自動修正を提案する

autoFixAvailable: true の Error 所見ごとに、順番に実行します。

🚦 ゲート（同意 · diagnose-deployment:6.auto-fix）： 自動修正を適用する前に、所見ごとの同意を得ます。autoFixAvailable: true の Error 所見ごとに 1 回ループし、各所見について個別の「はい / いいえ / すべてスキップ」の AskUserQuestion を提示します。プロンプトにはパターン ID が表示されます。修正をまとめて適用してはいけません。所見が 3 件なら、同意プロンプトも 3 回個別に提示します（最初にユーザーが「すべてスキップ」を選んだ場合は、ループを中断します）。所見 1 への「はい」は所見 2 には適用されません。それぞれの修正で影響する範囲（異なるファイル、異なる設定、異なる可逆性）が異なります。

1. 問題と提案する修正を説明します

2. AskUserQuestion を使って明示的な許可を求めます。

   "問題：{message} 提案する修正：{suggestedFix} この修正を適用しますか？ はい / いいえ / すべての自動修正をスキップ"

3. 許可された場合、修正を実行します。

   stale-manifest：.powerpages-site/ 内の *-manifest.yml ファイルを削除します

   # Ask which manifest to delete if multiple found, then:
   rm ".powerpages-site/{manifestFile}"
   

   blocked-js：blockedattachments 設定を更新します

   # Get current setting first
   pac env list-settings | grep -i blocked
   # Remove .js from the blocked list (preserve other blocked types)
   pac env update-settings --name blockedattachments --value "{updated-value}"
   

   missing-website-record-id：レコード ID を取得して更新します

   pac pages list
   # Parse output, find matching site by name, then update powerpages.config.json
   

   auth-expired：再認証の手順を案内します

   pac auth create --environment "{envUrl}"
   az login
   

   empty-build：ビルドを実行します

   npm run build
   

4. 修正のたびに、関連するチェックを再実行して問題が解決したことを確認します。所見のステータスを「Fixed」または「Manual required」に更新します。

重要な制約：ユーザーの明示的な許可なしに修正を適用してはいけません。修正ごとに個別の確認が必要です。

フェーズ 7 — 所見の概要を提示する

すべての所見をまとめた最終表を表示します。

#	重大度	種類	問題	ステータス
1	Error	upload	JS アップロードがブロックされています	Fixed
2	Error	config	websiteRecordId がありません	Manual required
3	Warning	config	複数のマニフェストファイルがあります	Informational

ステータスの値：

• Fixed：自動修正を適用し、確認しました
• Manual required：自動修正を利用できません。手動での手順を示します
• Skipped：ユーザーが修正を拒否しました
• Informational：Warning/Info で、対応は不要です

すべてのエラーが解決した場合は、/power-pages:deploy-site でデプロイを再試行するよう提案します。

手動での対応が残っている場合は、コマンドまたはリンクを含めて具体的に列挙します。

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

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

参照先に記載されたスキルの使用状況を記録する手順に従ってください。--skillName "DiagnoseDeployment" を使用します。

重要な判断ポイント（ユーザーの応答を待つ）

1. フェーズ 6：自動修正を適用するには、修正ごとに明示的な確認が必要です
2. フェーズ 6：ユーザーが「すべての自動修正をスキップ」と言った場合、修正の提案を停止して概要に進みます

エラー処理

• pac pages upload-code-site が出力を生成しない場合：「現在の状態ではアップロードエラーは検出されませんでした」と報告します
• Azure CLI トークンを利用できない場合：フェーズ 4 をスキップし、その旨を概要に記載します
• parse-deployment-errors.js が所見を返さない場合：「既知のエラーパターンは検出されませんでした」と報告し、手動レビュー用に生の出力を表示します

進捗追跡テーブル

タスクの件名	進行中の形式	説明
前提条件を確認し、プロジェクトを特定する	前提条件を確認しています	PAC CLI と Azure CLI を確認し、プロジェクトのルートと powerpages.config.json を特定します
デプロイ成果物を収集する	デプロイ成果物を収集しています	設定を読み取り、マニフェストを一覧表示し、ビルド出力とソリューションマニフェストを確認します
アップロードエラーを明らかにする	アップロードエラーを明らかにしています	pac pages upload-code-site をキャプチャモードで再実行し、標準出力／標準エラーを解析します
ソリューションのインポート状況を照会する	ソリューションのインポート状況を照会しています	Dataverse で最近の失敗した非同期操作とインポートジョブを確認します
検出結果を診断し、分類する	検出結果を診断しています	すべてのエラーを deployment-error-catalog と照合し、重大度を割り当てます
自動修正を提案する	自動修正を適用しています	修正可能なエラーごとに許可を求め、修正を実行して結果を確認します
検出結果の概要を提示する	概要を提示しています	重大度と修正状況を含むすべての検出結果を表で示し、手動での手順を一覧表示します