---

name: export-solution description: >- Exports a Dataverse solution containing Power Pages site components as a zip file, ready for deployment to another environment. Use when asked to: "export solution", "download solution", "export managed", "export unmanaged", "package for deployment", "create solution zip", "export site package", or "build deployment artifact". user-invocable: true argument-hint: "Optional: 'managed' or 'unmanaged' (default: asks)" allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch model: opus

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

export-solution

Triggers an async Dataverse solution export, polls until complete, downloads the solution zip, and verifies it. Reads .solution-manifest.json to identify the solution; falls back to asking the user.

Prerequisites

• PAC CLI installed and authenticated
• Azure CLI installed and logged in
• Solution exists in the environment (run setup-solution first if needed)

Phases

Phase 0 — ALM plan gate

plan-alm is the front door. When the user expresses an ALM intent (promote / ship / deploy / set up CI-CD / move to staging / push to prod), the orchestrator (/power-pages:plan-alm) should run first. This Phase 0 enforces that and is meant to fail closed when there's no plan, not to be a one-time check the user can dismiss forever.

Skip rule. If this skill was invoked as part of an active plan-alm orchestration, skip Phase 0 entirely and proceed to Phase 1. The gate helper exposes this via its inExecution block — pass through silently to Phase 1 when:

inExecution.status === "active"

The helper computes this from docs/.alm-plan-data.json — PLAN_STATUS === "In Execution" AND LAST_INVOCATION_AT within the last 60 minutes. check-alm-plan.js refreshes LAST_INVOCATION_AT automatically on every invocation that finds the plan in execution, so each in-chain skill keeps the chain alive for the next one — even multi-hour deploys (deploy-pipeline alone can take 60 min per stage) survive the window without the chain incorrectly de-classifying. Stalled chains (no heartbeat for > 60 min) reclassify as stale-heartbeat and Phase 0 gates fire normally so an abandoned plan doesn't silently bypass user confirmation.

When inExecution.status is anything other than "active" ("not-running", "stale-heartbeat", "no-plan"), run the Phase 0 gate flow below. Branch on the remaining helper fields:

Step 1 — Run the gate helper.

node "${PLUGIN_ROOT}/scripts/lib/check-alm-plan.js" \
  --projectRoot "." \
  --envUrl "{envUrl from .solution-manifest.json or pac env who, if available}" \
  --token "{token, if Phase 1 already acquired one}" \
  --solutionId "{solutionId from .solution-manifest.json, if available}"

The helper returns JSON with { exists, deferred, stale, staleness: { reason, detail }, generatedAt, planStatus, ... }. The freshness check requires env credentials + solutionId; without those the helper does an existence-only check.

Step 2 — Branch on the result.

| Result | Behavior | |---|---| | deferred: true | The user has explicitly deferred ALM for this project (.alm-deferred marker present). Pass through silently to Phase 1 — do not nag. | | exists: false | The user hasn't run plan-alm yet. See Step 3. | | exists: true, stale: false | Plan is current. Pass through silently to Phase 1. | | exists: true, stale: true (reason: solution-modified) | The solution changed after the plan was generated. See Step 4. |

Step 3 — No plan. Tell the user:

"No ALM plan exists for this project. /power-pages:plan-alm builds one — it detects the project state, asks about your promotion strategy (PP Pipelines vs Manual export/import), and orchestrates the right skills (including this one) in the right order. Want me to run plan-alm now?"

<!-- gate: export-solution:0.no-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · export-solution:0.no-plan): Fail-closed entry gate when check-alm-plan.js returns exists:false. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Run /power-pages:plan-alm first? | ALM plan gate | Yes — run /power-pages:plan-alm now (Recommended), Continue without a plan (advanced — I know what I'm doing), Cancel |

• Yes (Recommended) → invoke /power-pages:plan-alm. It builds the plan and returns — plan-alm is a planner and does not deploy. This skill then re-runs the Phase 0 check (now exists:true) and proceeds to Phase 1.
• Continue without a plan → set BYPASSED_PLAN_GATE = true and proceed to Phase 1.
• Cancel → exit cleanly.

Step 4 — Stale plan. Tell the user:

"ALM plan exists from {generatedAt} but the source solution has been modified since (at {solution.modifiedon}). Components may have changed. Re-running plan-alm will refresh the analysis and the rendered HTML."

<!-- gate: export-solution:0.stale-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · export-solution:0.stale-plan): Fail-closed entry gate when check-alm-plan.js returns stale:true. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Refresh the plan first? | ALM plan freshness | Refresh — re-run /power-pages:plan-alm (Recommended), Continue with the existing plan, Cancel |

• Refresh (Recommended) → invoke /power-pages:plan-alm. After completion, re-run the Phase 0 helper once to confirm freshness; if still stale, surface the detail and proceed to Phase 1 anyway (don't infinite-loop).
• Continue → set STALE_PLAN_ACK = true and proceed to Phase 1.
• Cancel → exit cleanly.

Why this gate exists. Direct invocation of export-solution produces a zip without the orchestrator's pre-export completeness check. Users running this skill standalone often miss components that should have been added to the solution (cloud flows, env var values referenced by site settings, sample data references) and ship a zip that imports cleanly into staging but produces a broken site post-deploy. The pre-plan completeness check surfaces those gaps before any zip is built. The gate ensures plan-alm either ran (so completeness was verified and the export was scoped to the right solution lineage) or the user explicitly chose to bypass it.

Phase 1 — Verify Prerequisites

Create all tasks upfront at the start of this phase.

Tasks to create:

1. "Verify prerequisites"
2. "Identify solution"
3. "Configure export"
4. "Trigger async export"
5. "Download solution zip"
6. "Verify export"
7. "Present summary"

Steps:

1. Run verify-alm-prerequisites.js with --require-manifest to confirm PAC CLI auth, acquire a token, verify API access, and validate that .solution-manifest.json exists:

   node "${PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js" --require-manifest
   

   Capture output as JSON; extract .envUrl (store as envUrl) and .token (store as token). If the script exits non-zero, stop and explain what is missing (reference ${PLUGIN_ROOT}/references/dataverse-prerequisites.md).

Phase 1.5 — Ground in current ALM documentation

Reference: ${PLUGIN_ROOT}/references/alm-docs-grounding.md

Cap this step at ~30 seconds. If MCP search / fetch errors out, log a one-line note and continue — this skill must remain runnable offline.

1. Run microsoft_docs_search with the query: Power Pages solution export managed unmanaged ExportSolutionAsync ALM.
2. Fetch https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm (and at most one sister page on managed vs unmanaged or solution layering) in parallel via microsoft_docs_fetch.
3. Extract a one-paragraph summary of what Microsoft Learn currently says about export semantics, managed vs unmanaged implications, and async export polling. Compare against ${PLUGIN_ROOT}/references/solution-api-patterns.md and flag any divergence in ExportSolutionAsync / DownloadSolutionExportData signatures.
4. Use the summary to inform Phase 2+ decisions. Do not silently change skill behavior — surface any divergence to the user as a soft warning before Phase 3.

Phase 2 — Identify Solution

<!-- gate: export-solution:2.identify | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · export-solution:2.identify): No .solution-manifest.json in project root — user must pick or paste a solution unique name before export proceeds. Fires only on the "not found" branch (step 3 below).

Trigger: Phase 2 step 1 didn't find a manifest. Why we ask: Auto-picking the wrong solution exports a managed zip that ships the wrong table/site/flow set to staging. Cancel leaves: Nothing — no ExportSolutionAsync call yet.

1. Look for .solution-manifest.json in project root (use findProjectRoot or glob('**/.solution-manifest.json'))
2. If found: read solution.uniqueName, solution.solutionId, environmentUrl
   • Verify environment URLs match (warn if different — may be cross-environment export)
3. If not found, use AskUserQuestion to pick the solution:
   • Query Dataverse for available unmanaged solutions and present them as options
   • Free-text fallback ("Other") for pasting the unique name directly
4. Confirm solution exists in environment:

   GET {envUrl}/api/data/v9.2/solutions?$filter=uniquename eq '{solutionName}'&$select=solutionid,uniquename,friendlyname,version,ismanaged
   

5. Present solution details and confirm with user.

Phase 2.5 — Pre-export Completeness Check

Before exporting, run the shared site-inventory helper to detect any components that exist on the site but are not in the solution. Catching this here avoids shipping an incomplete package to staging/prod.

node "${PLUGIN_ROOT}/scripts/lib/discover-site-components.js" \
  --envUrl "{envUrl}" --token "{token}" \
  --siteId "{websiteRecordId}" \
  --publisherPrefix "{publisherPrefix from .solution-manifest.json}" \
  --solutionId "{solutionId}" \
  --projectRoot "."

Parse stdout and evaluate missing. Before doing anything else, capture the pre-sync state so a post-sync re-confirmation gate can show what changed:

PRE_SYNC_VERSION = solutionManifest.solution.version   // from .solution-manifest.json read in Phase 2
PRE_SYNC_MISSING = { siteComponents, siteLanguages, cloudFlows, envVarDefinitions, customTables, ... }   // from the discovery stdout above

Then:

• All missing.* arrays empty → report "Solution contents match the site — no gaps detected." Proceed to Phase 3.

• Any non-empty missing.* array → present a concise summary:

  "The solution is missing {N} component(s) that exist on the site:

  • {X} site components (e.g. {first 3 names}, …)
  • {Y} cloud flows
  • {Z} environment variable definitions with your publisher prefix
  • {W} custom tables"

  <!-- gate: export-solution:2.5.completeness | category=progress | cancel-leaves=nothing -->

  🚦 Gate (progress · export-solution:2.5.completeness): Source solution incomplete vs live site. Sync first, export as-is (gap recorded), or abort.

  Then ask via AskUserQuestion:

  "How would you like to proceed?

  1. Run /power-pages:setup-solution in sync mode now — adopts missing components, bumps the solution version, then re-confirms with you before exporting (Recommended)
  2. Export as-is — ship what's currently in the solution; missing components won't travel
  3. Abort — I want to investigate before exporting"

  • Option 1 — Sync first, then re-confirm before export:
    1. Invoke /power-pages:setup-solution (auto-detects the exis