import-solution

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

import-solution

Imports a solution zip into a target Dataverse environment via ImportSolutionAsync. Supports optional staged import via StageSolution to check for missing dependencies before committing.

Prerequisites

• PAC CLI installed and authenticated to the target environment
• Azure CLI installed and logged in
• Solution zip file exists on disk (produced by export-solution)

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 "${CLAUDE_PLUGIN_ROOT}/scripts/lib/check-alm-plan.js" --projectRoot "."

The helper returns JSON with { exists, deferred, stale, staleness: { reason, detail }, generatedAt, planStatus, ... }. Pass --envUrl, --token, --solutionId once Phase 1 has acquired them if you also want a freshness check; otherwise the helper does an existence-only check, which is sufficient for the gate decision below.

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: import-solution:0.no-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · import-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. plan-alm's Phase 7 dispatches back into this skill at the appropriate stage.
• 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: import-solution:0.stale-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · import-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 import-solution deploys a zip into a target environment without the orchestrator's deployment-strategy selection or post-import validation steps. Users running this skill standalone often skip the staged-import dependency check, miss env var override values for the target environment, and have no plan-tracked record of which environment received which artifact version. The gate ensures plan-alm either ran (so the strategy was selected, per-stage values were captured in deployment-settings.json, and the deployment is reproducible) 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. "Locate solution file"
3. "Configure import"
4. "Stage solution (dependency check)"
5. "Import solution"
6. "Verify import"
7. "Detect cloud flows"
8. "Present summary"

Note: If the import fails with an AttachmentBlocked error, a Phase 5b remediation flow runs inline — no additional task is needed (it continues within the "Import solution" task). The "Detect cloud flows" task is skipped automatically if no Workflows/*.json files are present in the solution zip.

Steps:

1. Run pac env who — extract environmentUrl (verify this is the target environment)
2. Run az account get-access-token --resource "{environmentUrl}" --query accessToken -o tsv — capture token
3. Verify API access: GET {environmentUrl}/api/data/v9.2/WhoAmI
4. Present target environment URL and ask user to confirm this is correct before proceeding.

Important: Confirm the target environment with the user — importing to the wrong environment can be disruptive.

If any check fails, stop (reference ${CLAUDE_PLUGIN_ROOT}/references/dataverse-prerequisites.md).

Phase 1.5 — Ground in current ALM documentation

Reference: ${CLAUDE_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 import staging missing dependencies ImportSolutionAsync ALM.
2. Fetch https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm (and at most one sister page on staged imports or dependency handling) in parallel via microsoft_docs_fetch.
3. Extract a one-paragraph summary of what Microsoft Learn currently says about staging vs direct import, dependency resolution, and component-level error handling. Compare against ${CLAUDE_PLUGIN_ROOT}/references/solution-api-patterns.md and flag any divergence in ImportSolutionAsync / StageSolution 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 4 (the actual