migrate-bootstrap

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

非SPA Power Pages サイトを Bootstrap 3 から Bootstrap 5 に移行する

非SPA／ネイティブの Power Pages サイトを Bootstrap 3 から Bootstrap 5 に移行する手順をユーザーに案内します。体系的に進めます。ツールを確認し、サイトを取得してバックアップを作成し、対象範囲を評価し、pac pages bootstrap-migrate エンジンを実行し、変更レポートを確認し、エンジンが検出のみ可能な残りの修正を適用し、アップロード（ランタイムフラグが自動的に有効になります）し、確認と検証を行います。

基本原則

• 非SPAサイトのみ：このスキルの対象は、非SPAの Power Pages サイトです（Liquid Webテンプレート、*.webtemplate.source.html、*.html/.aspx/.ascx、*.css、sitesetting.yml）。SPAサイト（React/Vue/Angular/Astro）には適用されません。これらが Bootstrap 3 ベースであることはありません。対象がSPAサイトの場合は中止し、このスキルは適用できないことをユーザーに伝えてください。
• 大部分はエンジンが処理し、残りはユーザーが対応：pac pages bootstrap-migrate は、広く知られているクラス名の変更を決定論的に適用します。このスキルの価値は、エンジンがログに記録するだけの階層／CSSの変更を支援することにあります（references/bootstrap-v5-manual-fixes.md を参照）。
• 非破壊的で、復元ポイントを作成：エンジンは新しい <folder>V5 コピーを作成し、ソースを直接編集することはありません。それでも、何かを始める前に、ソースフォルダーのスナップショット（git）を作成してください。
• 支援して問題を指摘し、黙って書き換えない：残りの修正はLiquidを考慮しますが、レイアウトを壊す可能性があります。カテゴリごとに同意を得て適用してください。Liquid条件分岐など、判断が曖昧なケースは推測せず、ユーザーに指摘してください。
• pac-log.txt でランタイムフラグの切り替えを確認：pac pages upload はサーバー側の Bootstrap 5 フラグを自動的に切り替えますが、切り替えの結果はCLIによってログに記録され、握りつぶされます。アップロードの終了コードだけを信頼しないでください。正式な記録はPAC診断ログ（pac telemetry status → pac-log.txt）です。BootstrapV5UploadPostProcessor を検索してください。この切り替えには稼働中のポータルが必要です。プロビジョニング済みのサイトがないWebサイトレコードでは、no portal found がログに記録され、切り替えはスキップされます。
• TaskCreate/TaskUpdateを使用：作業を始める前に、8つのフェーズすべてを含むToDoリストを作成してください。

初回の依頼： $ARGUMENTS

---

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

目標：PAC CLI がインストールされ、ユーザーが認証済みで、対象環境が確認され、必要なコマンドが利用可能であることを確認します。

アクション：

1. 8 つのフェーズすべてを含む TODO リストを作成します（進捗状況の追跡を参照）。

2. pac help を実行して、PAC CLI がインストールされ、PATH 上にあることを確認します。見つからない場合は、ユーザーに https://aka.ms/PowerPlatformCLI（dotnet tool install --global Microsoft.PowerApps.CLI.Tool） を案内し、再確認します。

3. pac auth who を実行します。認証されていない場合は、AskUserQuestion を使って環境 URL を尋ね、 pac auth create --environment "<URL>" を実行して再確認します。環境名、URL、 ID を記録します。

🚦 ゲート（同意 · migrate-bootstrap:1.confirm-env）：ダウンロード、移行、アップロードを行う前に、対象環境を確認します。誤った環境に対して移行を実行すると破壊的な結果になるため、この確認は必須です。

4. ユーザーと対象環境を確認します（AskUserQuestion：この環境を使用する／pac org list と pac org select を使って別の環境を選択する）。

5. コマンドの利用可否を確認 — 両方の動詞が必要です：

   pac pages help
   

   動詞の一覧に bootstrap-migrate と upload が表示されることを確認します。どちらかがない場合（この CLI ビルド／テナントで機能が有効になっていない場合）は、コマンドが利用可能になるまで移行を進められないことをユーザーに伝えて中止します。

6. PAC 診断ログの場所を特定 — ここでパスを記録します。フラグの切り替えを確認するため、フェーズ 7 で必要になります：

   pac telemetry status
   

   The diagnostic logs can be found at: <…>\logs\pac-log.txt と表示されます。これは すべての pac 実行にまたがるローリングログであり、Bootstrap V5 フラグ切り替えの正式な記録です。注意：pac pages upload は フォルダーごとのログを出力しません — pac-log.txt が、後処理によるフラグ切り替え結果の唯一の記録場所です。PAC_LOG = <that path> を設定します。

出力：PAC CLI の確認、認証済みセッション、確認済み環境、bootstrap-migrate と upload が利用可能であることの確認、PAC_LOG パスの記録。

---

フェーズ 2：サイトの取得とバックアップ

目標：移行する非 SPA サイトのローカルコピーを取得し、復元ポイントを作成します。

アクション：

2.1 サイトの場所を特定するか、ダウンロードする

• ユーザーがローカルのサイトフォルダーパスを指定した場合（または $ARGUMENTS にパスが指定されている場合）：そのパスが存在し、ダウンロード済みの非 SPA サイトに見えること（website.yml と sitesetting.yml が含まれていること）を確認します。そのパスを SITE_FOLDER として使用します。

• それ以外の場合：利用可能な Web サイトを一覧表示し、選択したサイトをダウンロードします。

  pac pages list
  

  🚦 ゲート（計画 · migrate-bootstrap:2.1.select-site）：Web サイトが複数ある場合は、ダウンロードするサイトを選択します。キャンセルしても何も変更されません。

  AskUserQuestion を使って Web サイトを提示し、選択されたサイトをダウンロードします：

  pac pages download --path "<SITE_FOLDER>" --webSiteId "<WEBSITE_ID>"
  

  ダウンロードしたディレクトリを SITE_FOLDER として使用します。

これが SPA サイトではなく、非 SPA サイトであることを確認します。SPA プロジェクトには powerpages.config.json とフレームワークの package.json があり、非 SPA サイトには website.yml、sitesetting.yml、 *.webtemplate.source.html ファイルがあります。SPA サイトの場合は、このスキルの対象外であるため中止します。

2.2 サイトが有効化されていることを確認します（ウェブサイトレコードだけではありません）

pac pages list に表示されるのは ウェブサイトレコード（adx_website）です。ウェブサイトレコードが存在していても、その背後にプロビジョニング済み／アクティブな Power Pages サイト（ポータル）が存在するとは限りません。データのインポート／クローンによって作成されたもの、無効化されたもの、孤立したものもあります。Phase 7 のフラグ切り替え（SetPortalBootstrapV5Enabled）の対象はポータルであり、ウェブサイトレコードではありません。そのため、アクティブなポータルが存在しないと、切り替えは何も通知せずにスキップされ、稼働中のサイトは表示されません。今確認しておかないと、アップロード後までこの問題に気付けません。

websitebinding.yml の adx_sitename からサイト URL を特定し、最終的なステータスコードを確認します（-L はリダイレクトをたどるため、サインイン先または正規ホストへのリダイレクト後の実際のコードを確認できます）。

curl -sL -o /dev/null -w "%{http_code}" "https://<adx_sitename>/"

• 2xx または 2xx／3xx に解決されるリダイレクト → アクティブなポータルです。次に進んでください。プライベートまたは保護されたサイトがサインイン先や正規ホストにリダイレクトされるのは正常です。そのため、解決後の 3xx はアクティブであり、失敗ではありません。

• 4xx／5xx → ステータスだけでは判断できません。プライベートサイトは有効化されていても 200 以外を返すことがあるため、ステータスコードだけで「未有効化」と判断しないでください。エラー本文を取得するか、ブラウザーで URL を開き、未有効化を示す兆候がないか確認します。

  curl -sL "https://<adx_sitename>/" | head -c 4000
  

本文に Dataverse 接続の null 参照（Object reference not set …／CrmOnlineOrganizationService.ToOrganizationService）が表示される場合、またはブラウザーで URL を開いてもポータルページが表示されない場合、そのサイトは未有効化である可能性が非常に高いです。Phase 7 のフラグ切り替えで no portal found for website <id> via Power Pages API とログに記録されるのも、同じ状態が原因です。この兆候を伴わない 4xx／5xx は、アクティブなサイトに対する認証の制限や一時的なエラーである可能性が高いため、アクティブとして扱い、ユーザーにその旨を伝えてください。処理は中断しないでください。

サイトがアクティブでないことが確認できた場合は、そこで作業を止め、まずサイトを有効化／プロビジョニングするようユーザーに伝えてください（Power Pages 管理センター、または /power-pages:activate-site スキル）。未有効化のウェブサイトにコンテンツを移行してもアップロードはできますが、ランタイムフラグを切り替えられず、サイトの検証もできません。

2.3 ソースのスナップショットを作成する

移行を始める前に、復元ポイントを作成します。

cd "<SITE_FOLDER>"
git init -q && git add -A && git commit -q -m "Pre-migration snapshot (Bootstrap 3)"

フォルダーがすでに git リポジトリの場合は、移行前の状態を記録するため、保留中の変更をコミットするだけでかまいません。

出力：SITE_FOLDER が解決され、SPA ではないことが確認され、ソースのスナップショットがコミットされています。

---

Phase 3: 移行前の評価

目標：Bootstrap 3 の使用状況を調査し、エンジンの実行前にリスクのある領域を明らかにして、事前に期待値を設定します。

作業：

1. Grep を使って *.html、*.aspx、*.ascx、*.css を検索し、サイト内の Bootstrap 3 の目印を確認します。

   • コンポーネントのクラス：panel、navbar-header、img-responsive、btn-block、pull-left|pull-right、col-(xs|sm|md|lg)-、glyphicon、label-、page-header、pager、data-toggle|data-dismiss。
   • 影響を受けるファイル数と、カテゴリごとのおおよその出現数を数えます。

2. リスクのある領域を特定します。

   • カスタム CSS が多い（Bootstrap 以外のセレクターを含む .css ファイルが大きい）場合は、自動変換されません。
   • Liquid が入り組んだマークアップ（クラスの周囲に {% ... %} がある、条件付きドロップダウンがある）は、確認が必要です。

3. 対象範囲を簡潔にまとめ、次のように期待値を設定します。

   「これは支援付きの移行です。エンジンは、よく使われる Bootstrap 3 から 5 へのクラス名の変更を自動で適用します。グリッドの階層、ナビゲーションバーの構造、パネル／page-header／pager のスタイルなど、一部の変更は指摘することしかできません。Phase 6 で適用をお手伝いします。見た目が完全に一致する保証はなく、結果の QA が必要です。」

出力：対象範囲の概要が提示され、ユーザーはこれがボタンひとつで完了するものではなく、支援付きの移行であることを理解しています。

---

フェーズ 4：移行エンジンの実行

目標：移行後の <folder>V5 コピーを作成します。

アクション：

🚦 ゲート（同意・migrate-bootstrap:4.run-engine）： pac pages bootstrap-migrate を実行する前に、明示的な同意を得ます。エンジンは新しい <SITE_FOLDER>V5 コピーを書き出し、ソースは編集しないため、キャンセルしても変更は残りません。

1. エンジンを実行することについて、明示的な同意を得ます（AskUserQuestion：「<SITE_FOLDER> に対して Bootstrap 5 の移行を実行しますか？新しい <SITE_FOLDER>V5 コピーが作成され、元のファイルは変更されません。」）。

2. 次を実行します：

   pac pages bootstrap-migrate --path "<SITE_FOLDER>"
   

3. エンジンによって、以下を含む <SITE_FOLDER>V5 が作成されたことを確認します：

   • 書き換えられた *.html / *.js / *.aspx / *.ascx / *.css ファイル
   • 差し替えられた bootstrap.min.css（Bootstrap 5）
   • Site/BootstrapV5Enabled レコードが追加された sitesetting.yml
   • logs.txt およびファイルごとの *-diff.json

   出力仕様の詳細は、references/migration-engine-reference.md を参照してください。MIGRATED_FOLDER = <SITE_FOLDER>V5 を設定します。

出力：書き換えられたファイル、差し替えられた CSS、logs.txt、差分を含む MIGRATED_FOLDER。

---

フェーズ 5：変更レポートの確認

目標：logs.txt を、手作業が必要な箇所がわかる、カテゴリ別に整理された概要にまとめます。

アクション：

1. <MIGRATED_FOLDER>/logs.txt を読み込み、エンジンのリファレンスに記載された形式に従って分類します。レポートの冒頭には 3 つのファイルリスト（変更なし、自動適用（置換／追加／削除）、階層の変更（記録のみ））があり、その後にファイルごとの詳細ブロック（Total Number of Changes:<n> と変更行）が続きます。Grep を使用して、作業の件数と箇所を確認します。

   • Grep で Need hierarchy change を検索し、手動での階層変更項目を確認します（多くの場合 ゼロ です）。
   • 残作業を見つける最も確実な手がかりは、V5 の出力そのものです。移行後の *.html に残っている Bootstrap 3 のマーカー（page-header、glyphicon、label-(info|danger|primary)、panel-(primary|success|info|warning|danger)、btn-block、navbar-header）を Grep で検索します。エンジンが残したものが、まさにフェーズ 6 での作業です。

2. 概要を提示します：

   • カテゴリ別の件数。
   • 階層の変更と CSS に依存するコンテキストクラス（例：panel-primary）があるファイルの一覧。これらがフェーズ 6 の作業項目です。

出力：変更のカテゴリ別概要と、残っている手動作業項目の明示的な一覧。

---

フェーズ 6：AI による残作業の修正

目標：エンジンがフラグを立てたものの、安全に自動適用できなかった構造／CSS の修正を、MIGRATED_FOLDER 内のファイルに適用します。

修正手順のリファレンス：references/bootstrap-v5-manual-fixes.md

アクション：

1. 残作業をカテゴリ別にまとめます（グリッド階層、ナビバーの構造、パネル／カードのスタイル、page-header、pager、btn-block、Liquid のエッジケース、部分テンプレートのパス）。

🚦 ゲート（進捗・migrate-bootstrap:6.residual-fixes）： MIGRATED_FOLDER 内のファイルに残作業の修正を適用する前に、カテゴリごとに同意を得ます。変更は V5 コピー内に限定され、カテゴリごとにコミットされます。キャンセルしても外部に影響する変更は残りません。

2. 各カテゴリについて、カテゴリごとの同意を得ます（AskUserQuestion：「<N> 個のファイルに <category> の修正を適用しますか？」）。同意が得られた場合：
   • 手動修正のリファレンスにある手順を使って、Edit で修正します。
   • 該当行をファイルの *-diff.json と照合し、自動適用された変更に影響していないことを再確認します。
   • カテゴリごとにコミットします：git -C "<MIGRATED_FOLDER>" add -A && git -C "<MIGRATED_FOLDER>" commit -m "v5 fixes: <category>" （必要に応じて、先に V5 フォルダーをリポジトリとして初期化します）。add と commit の両方に -C "<MIGRATED_FOLDER>" を指定し、現在の作業ディレクトリではなく V5 コピーを対象に実行します。
3. 判断が難しいケース／Liquid が絡むケースは、書き換えないでください。ファイル名と行番号、推奨する手動修正をユーザーに提示します。

出力：残作業の修正をカテゴリごとに適用（または要確認として提示）し、それぞれコミットします。判断が難しい項目は一覧にします。

フェーズ 7：アップロード、自動ランタイムフラグ有効化、検証

目標：移行したサイトをアップロードし（サーバー側の Bootstrap 5 フラグが自動的に切り替わります）、フラグが実際に反映されたことを検証します。

操作：

7.1 マニフェストの事前確認

自動フラグ切り替えは、MIGRATED_FOLDER 内の 2 つのファイルを条件とします。

• website.yml に有効な adx_websiteid が含まれている必要があります。
• sitesetting.yml に値が true の Site/BootstrapV5Enabled が含まれている必要があります。

両方を確認してください（Grep／Read）。どちらかが欠けていると、フラグの切り替えは何もせずに終了します。アップロード前に修正してください。

7.2 最終同意の確認後、アップロード

🚦 ゲート（最終確認 · migrate-bootstrap:7.2.upload）： 最初の外部向け変更の前に最終承認を得ます。pac pages upload は Bootstrap 5 サイトを公開し、ランタイムフラグを自動的に有効にします。アップロード前にキャンセルすれば、稼働中のサイトは変更されません。

これは最初の外部向け変更です。明示的な同意を得てください（AskUserQuestion：「<MIGRATED_FOLDER> を環境 <ENV_NAME> にアップロードしますか？これにより Bootstrap 5 サイトが公開され、Bootstrap 5 ランタイムが有効になります。」）。同意を得たら：

pac pages upload --path "<MIGRATED_FOLDER>"

SPA ではないサイトでは、--modelVersion はデフォルト（Standard）のままにしてください。pac pages upload はコンテンツをアップロードし、ポストプロセッサーを介してサーバー側の Bootstrap 5 フラグも自動的に切り替えます（Site/BootstrapV5Enabled=true 設定によってトリガーされます）。

pac pages upload を使用してください。upload-code-site は使用しないでください（これは SPA 用のパスであり、SPA ではないサイトを破損させます）。

7.3 フラグの切り替えを検証する（必須）

CLI はフラグ切り替えの結果をログに記録しても握りつぶすため、アップロードの成功だけではランタイムが Bootstrap 5 で動作している証拠になりません。正しい記録は pac-log.txt（フェーズ 1 で取得した PAC_LOG のパス）であり、稼働中のサイトではありません。まずログを確認してください。数秒で確実に判断できる一方、稼働中のサイトの結果は誤解を招く場合があります（未有効化のサイトでは、Bootstrap と無関係な 500 エラーが発生します）。

# grep the PAC diagnostic log for the post-processor's result (most recent run is last)
grep -iE "BootstrapV5UploadPostProcessor|SetPortalBootstrapV5Enabled" "<PAC_LOG>"

結果は次の 3 通りです。

ログ行	意味	対応
Set … BootstrapV5Enabled ／成功（INF）	切り替えが適用済み	✅ 続行します。必要に応じて稼働中のサイトでも確認します。
Skipping SetPortalBootstrapV5Enabled: no portal found for website <id> via Power Pages API（WRN）	アクティブなポータルがない — 切り替えは試行されていません	❌ サイトが有効化されていません。サイトを有効化して（フェーズ 2.2／/power-pages:activate-site を参照）、pac pages upload を再実行してください。
ポストプロセッサーからの ERR／例外	切り替えを試行したが失敗（認証／HTTP）	❌ 7.1 のマニフェストと権限を再確認し、アップロードを再実行してください。

その後、稼働中のサイトでも照合します（ログに適用済みと記録されている場合にのみ意味があります）。既知のページを再レンダリングして Bootstrap 5 のバンドルが配信されることを確認するか、Power Pages 管理画面でポータルの Bootstrap V5 有効状態を再確認してください。稼働中の URL が Dataverse 接続の null 参照（CrmOnlineOrganizationService.ToOrganizationService）を伴う 5xx を返す場合、これは**「サイトが有効化されていない」**ことを示します。一時的な再起動として扱わず、ログの no portal found 行と照合してください。

出力：移行したサイトをアップロードし、pac-log.txt でフラグ切り替えの結果（適用済み／ポータルなしのためスキップ／エラー）を確認します。適用済みの場合は、稼働中のサイトでも確認します。

---

フェーズ 8：検証と要約

目標：稼働中のサイトが Bootstrap 5 で動作することを確認し、結果を記録します。

アクション：

1. 実行時のスモークテスト — サイトの URL に対して /test-site を実行し、主要なページをクロールして、正しく表示されることを確認し、コンソールおよびネットワークのエラーを記録します。
2. 移行前後の表示確認 — アクセス数の多いページ（ホーム、ナビゲーションバー、各種パネル／カード、フォーム、ページネーション）を抜き取りで確認し、移行によるレイアウトのリグレッションがないか調べます。
3. スキルの使用状況を記録 — ${PLUGIN_ROOT}/references/skill-tracking-reference.md に従い、--projectRoot "<MIGRATED_FOLDER>"（powerpages.config.json を含むフォルダー）と --skillName "MigrateBootstrap" を指定して記録します。記録が書き込まれるのは、プロジェクトが SPA サイト（.powerpages-site/site-settings/ が存在する）の場合のみです。非 SPA／ネイティブダウンロードの場合、スクリプトは何も出力せずに処理を終了します。これは想定どおりのため、常に呼び出し、何も行われなかったことをエラーとして扱わないでください。記録ファイルが書き込まれた場合は、最終コミットに含めてください。
4. 要約 — 以下を提示します。
   • カテゴリ別の変更ファイル数（自動適用、支援適用、手動対応として指摘）。
   • 人による対応がまだ必要な残項目。
   • Bootstrap 5 の実行時フラグが有効になっていることの確認。
   • ソーススナップショット（ロールバック用）と MIGRATED_FOLDER の場所。
5. 次のステップを提案 — 手動 QA、/test-site の再実行、（環境間で昇格する場合は）ALM スキル（/plan-alm）を提案します。

出力：Bootstrap 5 でサイトが検証され、使用状況が記録され、要約と残項目一覧が提示されます。

---

重要な注意事項

すべてのフェーズを通じて

• TaskCreate/TaskUpdate を使用して、各フェーズの進捗を追跡します。
• 重要な判断が必要な箇所（以下）では、ユーザーに確認を求めます。
• エラーを明確に提示します — 修正を提案する前に、関連するコマンドの出力を示して説明します。
• アップロード後の自動ロールバックは行いません — フェーズ 2 のソーススナップショットを使用してください。自動的に元に戻すのではなく、失敗を報告して作業を続行するか、対応を検討します。

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

1. フェーズ 1：認証されていない場合は、環境 URL を取得し、対象環境を確認または切り替えます。
2. フェーズ 2：サイトが複数ある場合は、ダウンロードする Web サイトを確認します。また、非 SPA（コードではない）サイトであることを確認します。
3. フェーズ 4：移行エンジンを実行することへの同意。
4. フェーズ 6：残項目を修正する前に、カテゴリごとに同意を得ます。
5. フェーズ 7：アップロード（外部に反映される操作）の前に、最終確認を得ます。

進捗の追跡

フェーズ 1 を開始する前に、すべてのフェーズを含むタスクリストを TaskCreate で作成します。

タスクの件名	activeForm	説明
前提条件を確認	前提条件を確認中	PAC CLI、認証、環境、およびコマンド（bootstrap-migrate、upload）が利用可能か確認
サイトを取得してバックアップ	サイトを取得中	非 SPA サイトをダウンロード／特定し、ソースのスナップショットを作成
移行前の評価	対象範囲を評価中	Bootstrap 3 の使用状況を調査し、カスタム CSS／Liquid のリスクを指摘
移行エンジンを実行	移行を実行中	pac pages bootstrap-migrate → <folder>V5
変更レポートを確認	レポートを確認中	logs.txt を解析し、自動適用と階層構造／手動対応に分類
残項目を修正	修正を適用中	指摘された階層構造／CSS の項目をカテゴリごとに支援付きで修正
アップロードしてフラグを確認	アップロードして確認中	pac pages upload を実行し、Bootstrap 5 の実行時フラグが切り替わったことを確認
検証して要約	検証中	/test-site、表示確認、使用状況の記録、要約

各タスクの開始時に TaskUpdate を使用して in_progress にし、完了時に completed にします。

---

フェーズ 1：前提条件の確認から開始