migrate-webapi-selectall

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

Power Pages Web API のワイルドカードを移行する

非推奨の Webapi/<table>/fields = * の値をすべて、サイトの実際の Web API の動作から確認できる最小限の明示的な列セットに置き換えます。

ソースの特定、呼び出しチェーンの推論、フィールドの決定、レポートの作成、編集は LLM が担当します。同梱スクリプトは、信頼できる Dataverse テーブルスキーマを取得するためだけに使用してください。コードが必要とする列の判断には使用しないでください。

以下の両方に対応します。

• HTML、JavaScript、Liquid、Web テンプレート、集計 YAML を使用する非 SPA サイト。
• React、Vue、Angular、Astro、TypeScript、ダウンロード済みのデプロイ YAML、またはカスタム JavaScript の混在を使用する SPA サイト。

初回の依頼： $ARGUMENTS

必須ルール

1. 共有ラッパー、動的ビルダー、レスポンスの利用箇所を含め、発見されたすべてのソーステーブル Web API 呼び出しを確認してください。
2. すべての構成スコープとデプロイプロファイルのコピーを確認してください。
3. テーブルスキーマを使って、リクエストの EntitySetName 値を設定の論理名に対応付けてください。単数形化、複数形化、推測はしないでください。
4. 読み取り、書き込み、集計、FetchXML、ファイル、画像では、* をサポート対象外として扱ってください。
5. 編集を始める前に、すべてのワイルドカードについて置き換え案を正確に提示してください。
6. すでに明示的に指定されているすべての fields 設定について、不足している列や不要である可能性のある列も含めて報告してください。
7. ワイルドカードと呼び出し箇所の一覧がすべて確定するまで、不完全な移行計画は適用しないでください。
8. レポートに絶対ローカルパス、トークン、URL、データ値、フィルターのリテラル、リクエスト本文、レスポンス本文、ソースの抜粋を含めないでください。また、レポートは同梱テンプレートを同梱スクリプトでレンダリングしてのみ作成してください。
9. 無関係な YAML の構造と値は保持してください。
10. 記憶した一覧ではなく、新たな探索パスで検証してください。
11. 移行出力ディレクトリには、レンダリング済みのレポートとそのアイコンのみを残してください。
12. ユーザーが環境、Web サイト、サイトの種類、データモデル、デプロイプロファイルを明示的に確認するまでは、サイトのコンテンツをダウンロードまたはアップロードしないでください。どちらの転送も取り消せません。
13. スモークテストは明示的な承認を得てから実行してください。また、デプロイ済みサイトに対して POST、PATCH、PUT、DELETE の Web API 呼び出しを絶対に行わないでください。書き込みのテストは実際のレコードデータを破壊します。

呼び出しの分析前に references/column-analysis.md を読んでください。設定の一覧作成またはレポートの作成前に、references/configuration-and-reporting.md を読んでください。ダウンロードまたはアップロードの前に、references/site-transfer.md を読んでください。

フェーズ 1：準備

目標： プロジェクトを特定し、サイトを確認して、既存の作業を保護します。

1. 進捗管理に記載されている7つのタスクをすべて作成します。
2. $ARGUMENTS または現在のディレクトリから PROJECT_ROOT を特定します。
3. サイトのマーカーを個別に検出します。
   • powerpages.config.json は SPA サイトを示します。
   • ルートの website.yml、ルートの sitesetting.yml、または .powerpages-site/ は、ダウンロード済みの非 SPA アーティファクトを示します。
   • 両方が見つかった場合は、両方のレイアウトをスキャンします。
4. .solution-manifest.json が存在する場合は読み込みます。この移行では既存の 設定を変更します。別のソリューションを作成したり選択したりしないでください。
5. Git の状態を確認します。無関係なユーザー変更を破棄、隠蔽、または含めてはいけません。
6. node --version を実行します。
7. assets/migration-report-template.html と scripts/render-migration-report.js が読み取り可能であることを確認し、どちらかが 見つからない場合は中止します。
8. references/site-transfer.md を読み、環境、Web サイト名と WebSiteId、サイトの種類、データモデル、デプロイプロファイル、ターゲットパスをユーザーに確認します。それぞれを pac auth who、pac env who、pac pages list と照合し、不一致があれば中止します。フォルダー名や有効な既定値から推測してはいけません。

誤ったサイトを分析すると、確信を持って誤った修正を行うことになります。そのため、設定を読み取る前にサイトの識別情報を確定してください。ユーザーが新しいコピーを希望する場合、または PROJECT_ROOT にサイトのコンテンツがない場合にのみダウンロードします。ダウンロードするとローカルファイルが置き換えられ、元に戻せません。

🚦 ゲート（同意 · migrate-webapi-selectall:1.download-site）： 確認済みの環境、Web サイト名と ID、サイトの種類、データモデル、ターゲットパス、正確なコマンドを表示した後にのみ、ダウンロードの承認を求めます。キャンセルした場合、ローカルのコンテンツは変更されず、既存のコピーを使って続行します。

AskUserQuestion を使用します。選択肢は Download the confirmed site または Use the local copy です。 ダウンロード後はステップ 3 を繰り返します。

出力： プロジェクトルート、サイトのレイアウト、ソリューションのコンテキスト、Git の状態、確認済みのサイト識別情報、および承認された場合はダウンロード済みのコピー。

フェーズ 2：完全なインベントリを作成する

目標： 列について検討する前に、すべての設定と、候補となる Web API 呼び出し元を見つけます。

2.1 設定スコープをインベントリ化する

Glob、Grep、Read を使って、次を調査します。

• すべての sitesetting.yml。
• すべての *.sitesetting.yml。
• .powerpages-site/site-settings/。
• デプロイプロファイルおよび環境固有のコピー。

すべての Webapi/<table>/fields および Webapi/<table>/enabled エントリについて、相対ファイルパス、行、スコープ、キーの形式、現在の値を記録します。fields 設定を次のように分類します。

• wildcard。
• explicit。
• 有効なテーブルに対する missing。
• 同一の設定スコープ内に限り duplicate。

異なるデプロイプロファイルにある同一の設定を重複として扱ってはいけません。すべてのプロファイル名と、それぞれが上書きする設定を記録します。default プロファイルが意図したデプロイプロファイルだと決めつけてはいけません。

テーブルごとに一度だけ Dataverse にクエリを実行し、設定ごとに実行してはいけません。

2.2 インベントリーのソース呼び出し

権威のある編集可能なソースファイルのみを分析してください。コンパイル済みコードや生成コードは決して調べないでください。

SPA サイトの場合：

1. 呼び出しを検索する前に、powerpages.config.json、package.json、および使用しているフレームワークやバンドラーの設定を読み取ります。
2. compiledPath と、設定されているすべてのビルド出力ディレクトリを、厳格な除外対象として扱います。
3. .powerpages-site/web-files/、node_modules/、カバレッジおよびキャッシュディレクトリ、ソースマップ、圧縮バンドル、フレームワークの出力ディレクトリ、および <entry-name>-<content-hash>.<extension> に一致するコンテンツハッシュ付きアセットを除外します。
4. .powerpages-site/site-settings/ は設定のインベントリーにのみ使用し、ソース分析には使用しません。
5. 設定されているソースディレクトリやフレームワークのアプリケーションディレクトリなど、編集可能なルートを検索します。

SPA 以外のサイトでは、編集可能な JavaScript、Liquid、ウェブテンプレート、ウェブファイル、その他の作成済みソースを検索します。作成済みの SPA 以外のウェブファイルは、ウェブファイルとしてデプロイされるという理由だけで除外しないでください。

.js、.jsx、.ts、.tsx、.vue、.html、.htm、.liquid、.aspx、.ascx、.cshtml、XML ウェブテンプレートなどのソース拡張子を検索します。呼び出しがコンパイル済み、圧縮済み、生成済み、またはコンテンツハッシュ付きの出力にしか存在しない場合は、missing-source ブロッカーを記録し、移行を中止します。その出力から列を推測しないでください。

以下を検索します。

• /_api/、エンコードされた形式、分割された URL フラグメント、および API ベース定数
• fetch、Axios、XMLHttpRequest、jQuery AJAX、webapi.safeAjax、shell.ajaxSafePost、およびカスタムリクエストラッパー
• エンティティセット定数、クエリビルダー、FetchXML ビルダー、およびボディビルダー
• 他のファイルからインポートされた呼び出し元とコンシューマー

ソース候補ごとに、相対パス、行、メソッド、エンドポイント式、ラッパーチェーンを記録します。コメント、例、またはテーブルにないエンドポイントも、明示的な判定が必要です。除外対象のビルド出力は決して記録しません。

設定インベントリーを docs/webapi-selectall-migration/migration-report.json に書き込み、 references/configuration-and-reporting.md に記載されているとおりにドラフトレポートを生成します。 この時点ではフィールドを提案しないでください。

対象範囲内のソースファイルまたは設定ファイルを読み取れない場合は、中止してください。

🚦 ゲート（計画 · migrate-webapi-selectall:2.confirm-scope）： スキーマ取得の前に、プロジェクト、設定スコープとプロファイル、ワイルドカード数、明示的設定数、ソースインベントリーを確認します。キャンセルしても、読み取り専用のドラフトレポートのみが残ります。

確認またはキャンセルするには AskUserQuestion を使用します。ユーザーが別のソースまたはデプロイ範囲を特定した場合は、インベントリーを拡張し、このフェーズを繰り返します。

フェーズ 3：スキーマを取得し、列を特定する

目標： LLM に実際の使用状況を判断させながら、信頼できる名前を使用します。

3.1 関連するテーブルスキーマのみを取得する

次の内容から、重複のない初期リストを作成します。

• すべての Web API 設定に含まれる論理テーブル名
• 候補となるすべてのテーブル呼び出しに含まれるエンティティセット名
• バインド先または関連テーブル呼び出しに直接含まれるエンティティセット名

ナビゲーションプロパティ名をテーブル識別子として扱わないでください。リレーションシップメタデータによって解決された後に限り、そのターゲットの論理名を正しいものとして扱います。

確認済みのプロジェクトコンテキストまたは pac env who から環境 URL を解決してください。取得できない場合は、情報収集のために URL を尋ねてください。アクセストークンを求めたり、受け入れたりしてはいけません。

すべての重複を除いた識別子を、1 行に 1 つずつ docs/webapi-selectall-migration/table-identifiers.txt に書き込みます。次を実行します。

node "${PLUGIN_ROOT}/skills/migrate-webapi-selectall/scripts/query-table-schema.js" --project-root "<PROJECT_ROOT>" --environment-url "<ENVIRONMENT_URL>" --tables-file "<PROJECT_ROOT>/docs/webapi-selectall-migration/table-identifiers.txt" --output "<PROJECT_ROOT>/docs/webapi-selectall-migration/table-schema.json"

識別子を解決できない場合は、コードをたどるか、正しい契約を入手してください。推測してはいけません。

初期スナップショットの取得後、次の手順を行います。

1. 使用されているすべての $expand ナビゲーションプロパティを、ソーステーブルから返されたリレーションシップメタデータと照合します。
2. 既存のすべてのスナップショットに含まれていないターゲット論理名のみを収集します。
3. その名前を table-identifiers-pass-<N>.txt に書き込み、問い合わせて table-schema.pass-<N>.json に保存します。
4. 使用されているナビゲーションセグメントがすべて解決されるまで、ネストされた展開パスについて繰り返します。

table-schema.json とすべての番号付きスナップショットを、1 つのスキーマパッケージとして扱います。そのパッケージにすでに含まれている論理テーブルを再問い合わせしてはいけません。また、スキーマの問い合わせを並行して実行してはいけません。

識別子リストとスキーマスナップショットは作業ファイルです。検証が終わるまで保持し、フェーズ 7 で削除してください。

3.2 すべての呼び出しと利用箇所を分析する

ソースインベントリの各行について、次の手順を行います。

1. その行を含む関数またはテンプレートブロック全体を読みます。
2. インポートされたラッパー、URL 変数、クエリビルダー、本文ビルダー、レスポンスマッパー、型、コンポーネント、テンプレート、およびすべての呼び出し元をたどります。
3. 条件分岐、スプレッド構文、動的配列、および実行時設定を追跡します。
4. スキーマパッケージを使って、エンティティセットを論理テーブルに対応付けます。
5. references/column-analysis.md にあるすべてのルールを適用します。
6. 要件をリクエストごとではなく、所有する論理テーブルごとに記録します。
7. 行を mapped、non-table、または not-a-call に分類します。
8. 実行時の分岐または利用箇所に不明な点が残っている場合は、行を未解決のままにします。

通常、1 つの論理テーブルは複数の場所から参照されます。そのテーブルのフィールドを提案する前に、すべての呼び出し箇所を収集してください。重複または競合するラッパー、ページごとのスクリプト、異なるクエリ形式、同じファイル内での繰り返し呼び出しを含めます。すでに分析したテーブルに対する後続の呼び出し箇所で列が追加される場合があるため、最初の呼び出しだけで分析を終えてはいけません。

$select を指定しない通常のレコード GET では、すべての利用箇所から出力フィールドを導き出し、最小限の明示的なプロジェクションを追加するソース編集を提案します。フィルター、並べ替え、その他のクエリフィールドは、出力プロジェクションに追加すべきでない場合でも、フィールド設定に含めます。

レスポンスのプロジェクションとフィールド設定の許可リストは、別々の集合として保持します。レスポンスの利用箇所でも読み取られていない限り、フィルター専用、並べ替え専用、グループ化専用、または書き込み専用の列を既存の $select に追加してはいけません。

3.3 ビルド設定の提案

ワイルドカード設定ごとに、次の手順を実行します。

1. 適用対象のサイト動作において、対象の論理テーブルに到達するすべての呼び出し元から、裏付けのある要件を統合します。

2. 提案する各名前をスキーマパッケージに照らして検証します。

3. 提案する各列を、ソースパスと行番号、またはユーザーが確認した外部コントラクトに紐付けます。

4. 正確な置換内容を提示します。

   Webapi/<table>/fields = <column-name-1>,<column-name-2>,<column-name-3>
   

5. 提案が空である場合、または証拠が不完全な場合は、未解決のままにします。

すでに明示的に設定されている各項目については、次の手順を実行します。

• 設定済みの列を、裏付けのある必須列と比較します。
• 「完全一致」「必須列の不足」「過剰な可能性あり」「外部根拠あり」のいずれかに分類します。
• 不足がある場合は、すべてについて正確な修正案を含めます。
• 暗黙のうちに変更してはいけません。

レポートを更新します。続行する前に、すべてのワイルドカード行と呼び出し元行を解決してください。

出力： ワイルドカードの正確な置換内容と、既存の明示的な設定をすべて記載した、証拠がそろったレポート。

フェーズ 4：計画全体をレビューする

目標： 編集前に、公開範囲の縮小計画全体を提示します。

次の内容を提示します。

• 検出されたワイルドカードの問題と、それぞれの正確な置換内容。
• 提案する各列の根拠。
• $select が必要なソース GET。
• 既存の明示的な設定と、不足列または余分な列。
• 棚卸しで見つかった設定の不足または重複。
• 未解決の呼び出し元がゼロであること。

🚦 ゲート（同意 · migrate-webapi-selectall:4.apply-plan）： すべてのワイルドカードの置換、必要なソースの射影、任意の明示的設定の強化、およびローカルでの編集を承認します。キャンセルした場合、レポートのみが保持されます。

次の選択肢を使って AskUserQuestion を実行します。

• Apply all wildcard fixes and approved explicit fixes
• Apply all wildcard fixes only
• Cancel

ワイルドカード修正の一部だけを選択する選択肢は提示しないでください。

フェーズ 5：承認された編集を適用する

目標： ソースの射影とすべてのワイルドカード設定を更新します。

1. Edit を使って、承認された $select の射影を追加します。メソッド、フィルター、並べ替え、展開、ページネーション、エンコード、Liquid 式、エラー処理は維持してください。
2. Edit を使って、すべてのスコープとプロファイルにあるすべてのワイルドカード値を置換します。識別子、キー名、引用符、インデント、コメント、および無関係な値は維持してください。
3. すでに明示的に設定されている項目の変更は、選択された承認に含まれる場合のみ適用してください。
4. 変更した各ブロックを直ちに読み直し、レポートのステータスを更新します。

編集に失敗した場合、またはレビュー後にファイルが変更されていた場合は、作業を停止してください。設定の一部だけを適用した状態で続行したり、ユーザーの作業を広範囲にロールバックしたりしてはいけません。

出力： 承認されたすべてのローカル編集と、更新済みのレポート。

フェーズ 6：独立して検証する

目標： 以前のメモを信頼せずに、移行が正しく行われたことを証明します。

1. フェーズ 2 の検出を最初からやり直します。
2. すべての設定スコープに Webapi/<table>/fields のワイルドカード値が存在しないことを確認します。
3. 移行後の各値を、承認された正確な置換内容と比較します。
4. すべての呼び出し元を再度開き、対象範囲の分析を再実施します。
   • マッピング先のテーブルとメソッドが正しいこと。
   • 必須の設定列が含まれていること。
   • 通常のレコード GET で明示的な $select が使われていること。
   • 展開、ルックアップ、書き込み、FetchXML、ファイル、画像の各列が引き続き対象に含まれていること。
5. SPA サイトでは、既存のプロジェクトビルドを実行します。SPA 以外のサイトでは、編集した JavaScript と Liquid の構文を確認し、既存のサイトテストがあれば実行します。
6. レポートのステータスと各項目のステータスを確定し、既存の migration-report.html を削除して、更新済みのデータファイルから再レンダリングします。

明示的な設定に不足が残っている場合、完全な強化を達成したと主張してはいけません。該当する場合は、レポート作成規約で定義されている部分的なステータスを使ってください。

出力： 最終レポートと、検証済みのローカル移行。

サイト整合性の最終ゲート

承認されたすべてのソース編集、独立した検証、および SPA ビルドが完了したら、次を実行します。

node "${PLUGIN_ROOT}/scripts/validate-site-integrity.js" --projectRoot "<PROJECT_ROOT>"

移行が完了したと主張したり、デプロイを提案したりする前に、ブロッキングエラーをすべて修正してください。双方向および展開後の内容も含めて、レビュー結果を確認し報告してください。その後にソースを変更した場合は、このゲートを再実行してください。

フェーズ 7：デプロイと要約

目標： 検証済みの変更のみを公開します。

アップロードの直前に、references/site-transfer.md に記載されたすべての ID 情報をユーザーと再確認し、正確なコマンドを表示します。ユーザーが確認したデプロイプロファイルを選択し、ユーザーが指定した場合に限り default を使用します。環境、Web サイト、データモデル、またはプロファイルを変更する場合は、その都度個別のデプロイ承認が必要です。

🚦 ゲート（最終 · migrate-webapi-selectall:7.deploy）： 表示された環境、Web サイト、サイトの種類、データモデル、およびデプロイプロファイルで、検証済みの移行を承認してください。キャンセルすると、ローカルの編集内容と最終レポートは保持され、公開サイトは変更されません。

AskUserQuestion を使用します：Deploy now または Keep local only。

• pac auth who と pac env who を再実行し、いずれかに不一致があれば停止します。 pac pages upload-code-site は --environment を受け付けず、アクティブな認証プロファイルが示す対象にアップロードします。
• SPA サイトの場合は、.powerpages-site に承認済みの構成変更が含まれていることを確認し、既存の本番ビルドを実行してから、pac pages upload-code-site --rootPath "<PROJECT_ROOT>" --siteName "<SITE_NAME>" を実行します。
• 非 SPA サイトの場合は、pac pages upload --path "<PROJECT_ROOT>" --environment "<ENVIRONMENT>" --modelVersion "<Standard|Enhanced>" --deploymentProfile "<PROFILE>" を実行します。

一方のアップロードコマンドを、もう一方の代わりに使用してはいけません。それぞれがもう一方のサイトの種類を破損し、損傷を元に戻すことはできません。

デプロイ後、スモークテストで実行する読み取りパスを列挙します：GET 呼び出し、$select の射影、$expand、FetchXML、集計。事前に促されない限り、いずれも実行してはいけません。

🚦 ゲート（進行 · migrate-webapi-selectall:7.smoke-test）： デプロイ済みサイトに対して、列挙した読み取りパスのスモークテストを承認してください。キャンセルするとテストは省略され、デプロイ済みの移行は未検証として報告されます。

AskUserQuestion を使用します：Run the read-path smoke test または Skip verification。

書き込み、ファイル、または画像のリクエストは決して実行しないでください。使い捨てレコードに対して、ユーザー自身がそれらのパスを試すよう依頼してください。

HTTP 403 の応答は調査すべき証拠として扱い、* を決して復元しないでください。以前の承認に基づいて列を追加してはいけません。フェーズ 3 に戻り、正確な計画とレポートを更新し、フェーズ 4 の承認を再度得て、フェーズ 6 で独立して検証し、フェーズ 7 の新たなデプロイ承認を得てください。

移行中に作成した作業ファイルをすべて削除し、docs/webapi-selectall-migration/migration-report.html と、レンダラーがその隣に配置する power-pages-icon.png のみを残します。

• table-identifiers.txt および table-identifiers-pass-<N>.txt；
• table-schema.json および table-schema.pass-<N>.json；
• migration-report.json。

この移行で作成したファイルのみを削除し、ディレクトリにレポートとそのアイコンだけがあることを確認してください。前のフェーズに戻る場合はクリーンアップを省略し、そのパスが完了した後、再生成されたファイルを削除してください。

${PLUGIN_ROOT}/references/skill-tracking-reference.md に従い、--skillName "MigrateWebapiSelectall" を指定して使用状況を記録します。

ワイルドカードの件数、明示的なレビュー、ソースの編集、レポートのパス、検証、デプロイ、および未検証のまま残っているすべてのパスを要約します。

進捗の追跡

フェーズ 1 の前に、次のタスクを作成します。

タスクの件名	進行中の表示	説明
移行プロジェクトの準備	移行プロジェクトを準備中	サイトを確認し、レイアウトと git の状態を解決します
Web API の使用状況を調査	Web API の使用状況を調査中	すべての設定とソース呼び出しを見つけます
実際のカラムを特定	実際のカラムを特定中	スキーマを取得し、すべての利用箇所を追跡します
移行計画をレビュー	移行計画をレビュー中	具体的な修正内容と根拠を提示します
承認済みの移行を適用	承認済みの移行を適用中	プロジェクションと設定を編集します
移行結果を検証	移行結果を検証中	調査とビルドを繰り返し、レポートを完成させます
デプロイして要約	デプロイして要約中	承認後に公開し、結果を報告します

各タスクの開始時に in_progress、完了時に completed とマークします。

---

フェーズ 1：準備から開始します。