/migrate-bootstrap

name: migrate-bootstrap
description: >-
  Migrates a traditional Power Pages site from Bootstrap 3 to Bootstrap 5. Downloads the
  site, runs the pac pages bootstrap-migrate engine, reviews the change report, applies
  AI-assisted fixes for the residual hierarchy/CSS changes the engine only flags, uploads
  the migrated site (which auto-enables the Bootstrap 5 runtime flag), verifies the flag,
  and validates. Use when the user wants to upgrade an older Bootstrap-3 portal to
  Bootstrap 5. NOT for code sites (React/Vue/Angular/Astro) — those are never Bootstrap-3.
user-invocable: true
argument-hint: Optional website name or local site folder path
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Migrate a Traditional Power Pages Site from Bootstrap 3 to Bootstrap 5

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.

Core Principles

• **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](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

---

Phase 1: Verify Prerequisites

**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](#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. <!-- not-a-gate: data-gathering — free-text environment URL when PAC CLI isn't authenticated; the prompt itself writes nothing -->

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: migrate-bootstrap:1.confirm-env | category=consent | cancel-leaves=nothing -->

> 🚦 **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:

   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:

   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.

---

Phase 2: Acquire the Site & Back Up

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

**Actions**:

2.1 Locate or download the site

• **If the user provided a local site folder path** (or `$ARGUMENTS` names one): verify it exists

and looks like a downloaded traditional site (contains `website.yml` and `sitesetting.yml`). Use it as `SITE_FOLDER`.

• **Otherwise**: list available websites and download the chosen one.

  pac pages list