migrate-bootstrap

Guide the user through migrating a traditional / native Power Pages site from Bootstrap 3 to Bootstrap 5. Follow a systematic approach: verify tooling, acquire and back up the site, assess scope, run the pac pages bootstrap-migrate engine, review the change report, apply the residual fixes the engine can only flag, upload (which auto-enables the runtime flag), verify, and validate.

• Traditional sites only: This skill targets traditional Power Pages sites (Liquid web templates, *.webtemplate.source.html, *.html/.aspx/.ascx, *.css, sitesetting.yml). It does NOT apply to code sites (React/Vue/Angular/Astro) — they are never Bootstrap-3-based. If the target is a code site, stop and tell the user this skill doesn't apply.
• The engine does the bulk; you do the residual: pac pages bootstrap-migrate deterministically applies the well-known class renames. The skill's value is assisting with the hierarchy / CSS changes the engine only logs (see references/bootstrap-v5-manual-fixes.md).
• Non-destructive, with a restore point: The engine writes a new <folder>V5 copy and never edits the source in place. Still, snapshot the source folder (git) before doing anything.
• Assist and flag — never silently rewrite: Residual fixes are Liquid-aware and can break layouts. Apply them with per-category consent; when a case is ambiguous (e.g. Liquid conditionals), flag it for the user instead of guessing.
• Verify the runtime flag flip via pac-log.txt: pac pages upload flips the server-side Bootstrap 5 flag automatically, but flip outcomes are logged and swallowed by the CLI. Never trust the upload exit code alone. The authoritative record is the PAC diagnostic log (pac telemetry status → pac-log.txt); grep it for BootstrapV5UploadPostProcessor. The flip requires an active portal — a website record with no provisioned site logs no portal found and skips.
• Use TaskCreate/TaskUpdate: Create the todo list upfront with all 8 phases before starting work.

Initial request: $ARGUMENTS

Goal: Ensure PAC CLI is installed, the user is authenticated, the target environment is confirmed, and the required commands are available.

Actions:

1. Create the todo list with all 8 phases (see Progress Tracking).
2. Run pac help to confirm PAC CLI is installed and on PATH. If missing, point the user to https://aka.ms/PowerPlatformCLI (dotnet tool install --global Microsoft.PowerApps.CLI.Tool) and re-verify.

3. Run pac auth who. If not authenticated, ask for the environment URL via AskUserQuestion, then pac auth create --environment "<URL>" and re-verify. Capture the environment name, URL, and ID.

🚦 Gate (consent · migrate-bootstrap:1.confirm-env): Confirm the target environment before any download, migration, or upload. Running the migration against the wrong environment is destructive, so this confirmation is mandatory.

4. Confirm the target environment with the user (AskUserQuestion: use this environment / choose another via pac org list + pac org select).

5. Probe command availability — both verbs are required:

   Copy

   pac pages help

   Confirm bootstrap-migrate and upload appear in the verb list. If either is missing (feature not enabled in this CLI build / tenant), stop and tell the user the migration can't proceed until those commands are available.

6. Locate the PAC diagnostic log — capture the path now; you will need it in Phase 7 to verify the flag flip:

   Copy

   pac telemetry status

   It prints The diagnostic logs can be found at: <…>\logs\pac-log.txt. This is a rolling log across all pac runs and is the authoritative record of the Bootstrap V5 flag flip. Note: pac pages upload writes no per-folder log — pac-log.txt is the only place its post-processor records the flip result. Set PAC_LOG = <that path>.

Output: PAC CLI verified, authenticated session, confirmed environment, bootstrap-migrate and upload confirmed available, PAC_LOG path captured.

Goal: Get a local copy of the traditional site to migrate, and establish a restore point.

Actions:

Goal: Set expectations by inventorying Bootstrap-3 usage and flagging risk areas before running the engine.

Actions:

1. Scan the site for Bootstrap-3 markers using Grep over *.html, *.aspx, *.ascx, *.css:

   • Component classes: 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.
   • Count affected files and the rough number of occurrences per category.

2. Flag risk areas:

   • Heavy custom CSS (large .css files with non-Bootstrap selectors) — won't be auto-converted.
   • Liquid-entangled markup ({% ... %} around classes, conditional dropdowns) — needs review.

3. Present a concise scope summary and set expectations:

   "This is an assisted migration. The engine will auto-apply the common Bootstrap 3→5 class renames. Some changes (grid hierarchy, navbar structure, panel/page-header/pager styling) can only be flagged — I'll help apply those in Phase 6. Visual parity isn't guaranteed and you'll want to QA the result."

Output: Scope summary presented; user understands this is assisted, not push-button.

Goal: Produce the migrated <folder>V5 copy.

Actions:

🚦 Gate (consent · migrate-bootstrap:4.run-engine): Explicit consent before running pac pages bootstrap-migrate. The engine writes a new <SITE_FOLDER>V5 copy and never edits the source, so canceling leaves nothing changed.

1. Get explicit consent to run the engine (AskUserQuestion: "Run the Bootstrap 5 migration on <SITE_FOLDER>? This creates a new <SITE_FOLDER>V5 copy and does not modify the original.").

2. Run:

   Copy

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

3. Confirm the engine produced <SITE_FOLDER>V5 containing:

   • Rewritten *.html / *.js / *.aspx / *.ascx / *.css files
   • Swapped bootstrap.min.css (Bootstrap 5)
   • Updated sitesetting.yml with a Site/BootstrapV5Enabled record
   • logs.txt and per-file *-diff.json

   See references/migration-engine-reference.md for the full output contract. Set MIGRATED_FOLDER = <SITE_FOLDER>V5.

Output: MIGRATED_FOLDER produced with rewritten files, swapped CSS, logs.txt, and diffs.

Goal: Turn logs.txt into a structured, grouped summary that surfaces the manual work.

Actions:

1. Read <MIGRATED_FOLDER>/logs.txt and categorize per the format documented in the engine reference. The report opens with three file lists — no change, auto-applied (Replacement/Addition/Deletion), and hierarchy changes (logged only) — followed by a per-file detail block (Total Number of Changes:<n> + change lines). Use Grep to count and locate the work:

   • Grep for Need hierarchy change → the manual hierarchy items (often zero).
   • The most reliable residual signal is the V5 output itself: Grep the migrated *.html for surviving Bootstrap-3 markers (page-header, glyphicon, label-(info|danger|primary), panel-(primary|success|info|warning|danger), btn-block, navbar-header). Whatever the engine left behind is exactly the Phase 6 work.

2. Present a summary:

   • Counts per category.
   • The list of files with hierarchy changes and CSS-dependent contextual classes (e.g. panel-primary) — these are the Phase 6 work items.

Output: Grouped change summary; explicit list of residual manual items.

Goal: Apply the structural / CSS fixes the engine flagged but could not safely auto-apply, in the MIGRATED_FOLDER files.

Reference recipes: references/bootstrap-v5-manual-fixes.md

Actions:

1. Group the residual items by category (grid hierarchy, navbar structure, panel/card styling, page-header, pager, btn-block, Liquid edge cases, partial paths).

🚦 Gate (progress · migrate-bootstrap:6.residual-fixes): Per-category consent before applying each residual fix to the MIGRATED_FOLDER files. Changes are local to the V5 copy and committed per category; canceling leaves nothing outward-facing changed.

2. For each category, get per-category consent (AskUserQuestion: "Apply the <category> fixes to <N> file(s)?"). On consent:
   • Apply the recipe from the manual-fixes reference using Edit.
   • Re-check the affected lines against the file's *-diff.json to confirm you didn't disturb auto-applied changes.
   • Commit per category: git -C "<MIGRATED_FOLDER>" add -A && git -C "<MIGRATED_FOLDER>" commit -m "v5 fixes: <category>" (init the V5 folder as a repo first if needed). Use -C "<MIGRATED_FOLDER>" on both add and commit so they run against the V5 copy, not the current working directory.
3. For ambiguous / Liquid-entangled cases, do not rewrite — list them for the user with the file and line and a suggested manual change.

Output: Residual fixes applied (or flagged) per category, each committed; ambiguous items listed.

Goal: Upload the migrated site (which automatically flips the server-side Bootstrap 5 flag) and verify the flag actually took effect.

Actions:

Goal: Confirm the live site works on Bootstrap 5 and record the outcome.

Actions:

1. Runtime smoke test — invoke /test-site against the site URL to crawl key pages, verify they render, and capture console/network errors.
2. Before/after visual check — spot-check the highest-traffic pages (home, navbar, any panels/cards, forms, pagination) for layout regressions introduced by the migration.
3. Record skill usage — follow ${PLUGIN_ROOT}/references/skill-tracking-reference.md, passing --projectRoot "<MIGRATED_FOLDER>" (the folder containing powerpages.config.json) and --skillName "MigrateBootstrap". Tracking only writes when the project is a code site (.powerpages-site/site-settings/ exists); for a traditional/native download the script exits silently as a no-op — that is expected, so call it unconditionally and don't treat the no-op as an error. If tracking files are written, include them in the final commit.
4. Summary — present:
   • Files changed per category (auto-applied vs assisted vs flagged-for-manual).
   • Residual items that still need human attention.
   • Confirmation the Bootstrap 5 runtime flag is enabled.
   • Location of the source snapshot (for rollback) and MIGRATED_FOLDER.
5. Suggest next steps — manual QA pass, /test-site re-runs, and (if promoting across environments) the ALM skills (/plan-alm).

Output: Site validated on Bootstrap 5, usage recorded, summary + residual list presented.