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

Deploy Power Pages Site

Route to the correct deployment workflow before running SPA build, attachment, or activation
logic.

Core Principles

• Verify before acting: Always confirm PAC CLI availability, authentication status, and the target environment before attempting any deployment.
• Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
• Never change environment settings without consent: If deployment requires modifying environment configuration (e.g., unblocking JavaScript attachments), always explain the change and get explicit user permission first.

Initial request: $ARGUMENTS

Site-Type Routing

Classify explicit request signals first:

• React, Vue, Angular, Astro, SPA, code site, or powerpages.config.json → SPA site
• non-SPA, classic, traditional, declarative, Enhanced, EDM, Standard data model, .portalconfig,

or website.yml → Non-SPA site

When the request is not explicit, search the current workspace for:

• SPA roots containing powerpages.config.json;
• non-SPA roots containing both .portalconfig/ and website.yml, including a nested

.powerpages-site/.

Exclude dependency, build-output, temporary, generated-output, and version-control directories.
Use request paths and the current directory to resolve one project. Never choose the first result
arbitrarily.

🚦 Gate (plan · deploy-site:0.project-type): Select the exact project when SPA and
non-SPA sites, or multiple valid roots, remain possible.

Trigger: Project type or root is ambiguous after discovery.
Why: The two site types require incompatible PAC upload commands.
Cancel leaves: Nothing; no build or upload has started.

If ambiguous, use AskUserQuestion to select the exact project root and detected type.

• Non-SPA site: Read and follow

${PLUGIN_ROOT}/skills/deploy-site/workflows/non-spa-site.md. Do not continue into the
SPA phases below.

• SPA site: Continue with the existing workflow below.

Non-SPA upload approval

The authoritative markers and prompts live in workflows/non-spa-site.md.
Gate deploy-site:non-spa-4.permissions-audit handles permission-sensitive changes before upload.
Gate deploy-site:non-spa-5.upload approves the exact root, environment, website identity, model, and local change summary immediately before upload.

SPA-Site Deployment Workflow

The following phases retain the existing SPA behavior.

Phase 1: Verify PAC CLI

Goal: Ensure PAC CLI is installed and available on the system PATH

Actions:

1. Create todo list with all 6 phases (see Progress Tracking table)
2. Run pac help to check if the PAC CLI is installed and available on the system PATH.

```bash
pac help
```

1. If the command succeeds: PAC CLI is installed. Proceed to Phase 2.

1. If the command fails (command not found / not recognized):

1. Inform the user that PAC CLI is required but not installed.
2. Fetch installation instructions from https://aka.ms/PowerPlatformCLI using the following approach:

• Tell the user: "PAC CLI is not installed. You can install it by running:"

```bash
dotnet tool install --global Microsoft.PowerApps.CLI.Tool
```

• If dotnet is also not available, direct the user to for full installation instructions including .NET SDK setup.

1. After installation, verify by running pac help again.
2. If it still fails, stop and ask the user to resolve the installation manually.

Output: PAC CLI installed and verified

Phase 2: Verify Authentication

Goal: Ensure the user is authenticated with PAC CLI and has a valid session

Actions:

1. Run pac auth who to check the current authentication status.

```bash
pac auth who
```

1. If authenticated: Extract the following values from the output:

• Environment name and URL
• Environment ID — the GUID after Environment ID:
• Cloud — the value after Cloud: (e.g., Public, UsGov, UsGovHigh, UsGovDod, China)

Proceed to Phase 3.

1. If not authenticated:

1. Inform the user they are not authenticated with PAC CLI.

1. Use AskUserQuestion to ask for the environment URL:

Provide two placeholder options to guide the user:

• "I'll paste the URL" (description: "Select 'Other' below and paste your environment URL")
• "I don't know my URL" (description: "You can find it in the Power Platform admin center under Environments > your environment > Environment URL")

1. Once the user provides the URL, run the authentication command:

```bash
pac auth create --environment "PROVIDEDURL>"
```

This will open a browser window for the user to sign in.

1. After the command completes, verify by running pac auth who again.
2. If authentication succeeds, proceed to Phase 3.
3. If authentication fails, present the error to the user and help them troubleshoot.

Output: Authenticated PAC CLI session with environment name and URL extracted

Phase 3: Confirm Environment

Goal: Ensure the user is deploying to the correct target environment

Actions:

🚦 Gate (consent · deploy-site:3.confirm-env): Echo the current environment and require explicit confirmation before any upload. Covers the follow-up "pick a different env" sub-prompt in the same section — wrong-env deploys are the #1 destructive shared-state failure for this skill, so this gate must fire even when PAC CLI shows a recognizable env.

Trigger: Phase 3 entry; environment resolved from PAC CLI.
Why we ask: Site uploaded to wrong tenant / wrong env — committed to a Dataverse instance the user did not intend; cleanup requires manual deletion or another deploy from a different env.
Cancel leaves: Nothing — no upload fired.

1. Present the current environment information to the user and ask them to confirm.

Use AskUserQuestion with the following structure:

1. If "Yes, use this environment": Proceed to Phase 4.

1. If "No, let me choose a different one":

1. Run pac org list to retrieve all available environments:

```bash
pac org list
```

1. Parse the output to extract environment names and URLs.
2. Use AskUserQuestion to present the available environments as options (pick up to 4 most relevant, or let user specify).
3. Once the user selects an environment, switch to it:

```bash
pac org select --environment "ENVIDORURL>"
```

1. Verify the switch by running pac auth who again.

Output: Confirmed target environment for deployment

Phase 4: Deploy the SPA Site

Goal: Locate the project, build it, and upload to Power Pages

Actions:

4.1 Locate the Project Root

Determine the project root directory. The project root is the directory containing powerpages.config.json. Use Glob to search for it:

**/powerpages.config.json

🚦 Gate (plan · deploy-site:4.1.multi-project): More than one powerpages.config.json candidate found — pick the right project to deploy.

Trigger: Phase 4.1 glob returned multiple matches.
Why we ask: Wrong project uploaded — pollutes the target env with files from a different site.
Cancel leaves: Nothing — no upload fired.

If found in the current working directory or a subdirectory, use that directory as PROJECT_ROOT. If multiple are found, ask the user which one to deploy using AskUserQuestion.

If not found, ask the user to provide the path to the project root.

4.2 Offer Permissions Audit (Redeployments Only)

If .powerpages-site already exists (i.e., this is not the first deployment), table permissions and site settings may have drifted from the code since the last deployment. Offer to audit before deploying.

🚦 Gate (plan · deploy-site:4.2.audit-permissions): Re-deployment detected — offer to run /audit-permissions to catch drift between code and table permissions before push.

Trigger: .powerpages-site exists (not first deployment).
Why we ask: Stale permission YAML deploys, causing 403s for users until next audit run.
Cancel leaves: Nothing — audit is read-only; declining just proceeds to build + upload.

Use AskUserQuestion:

If "Yes": Invoke /audit-permissions to run the audit. After the audit completes, resume with Step 4.3.
If "Skip": Proceed to Step 4.3.

If .powerpages-site does not exist (first deployment), skip this step — there are no existing permissions to audit.

4.3 Build the Site

Before uploading, ensure the site is built:

cd "<PROJECT_ROOT>"
npm run build

If the build fails, stop and help the user fix the build errors before retrying.

4.4 Upload to Power Pages

Run the upload command:

pac pages upload-code-site --rootPath "<PROJECT_ROOT>"

If the upload succeeds: Proceed to Phase 5 to verify the deployment.

If the upload fails: Check the error message:

• If the failure is related to blocked JavaScript (.js) attachments → proceed to Phase 6
• If the failure mentions .html type attachments are currently blocked → this is a misleading error. See Troubleshooting: HTML Blocked Attachment Error below
• For other errors → present the error to the user and help them troubleshoot

Output: Site built and uploaded to Power Pages

Phase 5: Verify Deployment

Goal: Confirm the deployment was successful and handle post-deployment steps

Actions:

5.1 Verify .powerpages-site Folder

Confirm .powerpages-site exists and list its contents (web-roles/, site-settings/, table-permissions/).

5.2 Record Skill Usage

Reference: ${PLUGIN_ROOT}/references/skill-tracking-reference.md

Follow the skill tracking instructions in the reference to record this skill's usage. Use --skillName "DeploySite".

5.3 Confirm Upload Output

Review the output from the pac pages upload-code-site command in Phase 4 (or Phase 6 retry). Verify it reported a successful upload with no errors.

5.4 Commit Changes

Stage and commit deployment artifacts:

git add -A
git commit -m "Deploy site to Power Pages"

5.5 Check Activation Status

Run the activation status check:

node "${PLUGIN_ROOT}/scripts/check-activation-status.js" --projectRoot "<PROJECT_ROOT>"

Evaluate the JSON result:

• If activated is true: Inform the user their site is already activated (show websiteUrl if present). Proceed to step 5.6, then skip to Suggest Next Steps. Do NOT ask about activation.
• If activated is false: Proceed to step 5.5.1.
• If error is present: Fall back to step 5.5.1. Do not block the deployment flow.

5.5.1 Ask About Activation (only if site is NOT already activated)

🚦 Gate (plan · deploy-site:5.5.1.activate): Site deployed but not yet activated — offer to invoke /activate-site to provision the subdomain.

Trigger: Phase 5.5 detected activated:false on a fresh deploy.
Why we ask: Auto-activating writes the wrong subdomain (permanent for the site); auto-skipping leaves the site without a live URL.
Cancel leaves: Nothing — no activation API call fired.

Ask the user if they want to activate the site using AskUserQuestion:

If "Activate now": Invoke the /activate-site skill. After activation completes, proceed to step 5.6 to clear the site cache.
If "Skip for now": Suggest next steps (see Suggest Next Steps).

5.6 Clear Site Cache (Only If Activated)

After confirming the site is activated (either it was already activated in step 5.5, or the user just activated it in step 5.5.1), offer to clear the runtime cache so the deployed changes are immediately visible.

Prerequisites: The site must be activated and the project root must be known (from Phase 4.1).

🚦 Gate (plan · deploy-site:5.6.restart-cache): Restart the deployed site to flush its runtime cache. Brief production downtime (a few seconds) — explicit user consent required even though the action is recoverable.

Trigger: Site confirmed activated (either pre-existing or just activated in 5.5.1).
Why we ask: Production users see stale content for several minutes until cache TTL expires.
Cancel leaves: Nothing — the deploy itself already succeeded; cache will refresh on its own.

Use AskUserQuestion to confirm before proceeding:

If "Skip": Skip to Suggest Next Steps.

If "Yes": Run the cache-clearing script, passing the project root:

node "${PLUGIN_ROOT}/scripts/clear-site-cache.js" --projectRoot "<PROJECT_ROOT>"

The script reads siteName from powerpages.config.json, looks up the website via the Power Platform API, and restarts it to flush the runtime cache.

Evaluate the result:

• If success is true: Inform the user: "Site cache cleared — your latest changes should now be visible at ."
• If success is false: Warn the user that cache clearing failed and show the error, but do not block the deployment flow. The deployment itself succeeded; cache will eventually refresh on its own. Suggest the user can manually clear cache from the Power Pages admin center if needed.

Output: Deployment verified, changes committed, activation offered, cache cleared

Phase 6: Handle Blocked JavaScript

Goal: Resolve blocked JavaScript attachment errors and retry deployment

Actions:

6.1 Explain the Issue

Tell the user:

"The upload failed because JavaScript (.js) file attachments are blocked in your Power Pages environment. This is a security setting that prevents uploading .js files. To deploy a SPA site, this restriction needs to be relaxed for .js files."

6.2 Ask for Permission

🚦 Gate (consent · deploy-site:6.2.unblock-js): Reactive blockedattachments modification — destructive shared-state change (tenant-wide env setting). Same shape as deploy-pipeline:7.6.2.blocked-attachments.

Trigger: Upload failed with the blocked-.js error.
Why we ask: Auto-unblocking modifies a tenant security setting without explicit consent — visible across the entire environment, not just this site.
Cancel leaves: attachment-block-modified is only possible if the user approved and then a downstream step partial-completed. Pure Cancel here leaves nothing — the original blockedattachments value is untouched.

Use AskUserQuestion:

If "No": Stop and inform the user that the deployment cannot proceed without unblocking .js attachments.

If "Yes": Proceed to 6.3.

6.3 Update Blocked Attachments

1. Run pac env list-settings to retrieve the current environment settings:

```bash
pac env list-settings
```

1. Find the blockedattachments property in the output. It will contain a semicolon-separated list of file extensions (e.g., ade;adp;app;asa;ashx;asmx;asp;bas;bat;cdx;cer;chm;class;cmd;com;config;cnt;cpl;crt;csh;der;dll;exe;fxp;hlp;hta;htr;htw;ida;idc;idq;inf;ins;isp;its;js;jse;ksh;lnk;mad;maf;mag;mam;maq;mar;mas;mat;mau;mav;maw;mda;mdb;mde;mdt;mdw;mdz;msc;msh;msh1;msh1xml;msh2;msh2xml;mshxml;msi;msp;mst;ops;pcd;pif;prf;prg;printer;pst;reg;rem;scf;scr;sct;shb;shs;shtm;shtml;soap;stm;tmp;url;vb;vbe;vbs;vsmacros;vss;vst;vsw;ws;wsc;wsf;wsh).

1. Remove js from the list. Parse the semicolon-separated values, filter out js, and rejoin with semicolons.

1. Update the setting:

```bash
pac env update-settings --name blockedattachments --value "LISTWITHOUT_JS>"
```

1. Confirm the update was successful.

6.4 Retry Upload

Run the upload command again:

pac pages upload-code-site --rootPath "<PROJECT_ROOT>"

If it succeeds: Proceed to Phase 5 to verify the deployment.

If it fails again with a different error, present the error to the user and help troubleshoot.

Output: JavaScript unblocked and site deployed successfully

Troubleshooting: HTML Blocked Attachment Error

If the upload fails with an error like:

Error: Unable to upload webfile name 'index.html' with record Id <GUID> as '.html' type attachments are currently blocked on this environment.

This error is misleading. The .html extension is not actually blocked — the real cause is a stale environment manifest file in the .powerpages-site folder. This manifest maps local files to Dataverse record IDs from a previous upload. When the mapping becomes outdated (e.g., after environment changes or record deletions), the upload fails with this confusing error.

Fix

1. Locate the environment-specific manifest file in the .powerpages-site folder. It follows the naming pattern <environment-host>-manifest.yml (e.g., demo1.crm.dynamics.com-manifest.yml). Use your file-search tool (e.g., Glob with pattern <PROJECT_ROOT>/.powerpages-site/*-manifest.yml) to find it.

1. Delete the manifest file at <PROJECT_ROOT>/.powerpages-site/<environment-host>-manifest.yml.

1. Retry the upload:

```bash
pac pages upload-code-site --rootPath ""
```

If the retry succeeds, proceed to Phase 5. If it fails with a different error, present the error to the user and help them troubleshoot.

Important: Do NOT attempt to unblock .html in the environment's blocked attachments list — the error is not caused by the attachment block setting.

Suggest Next Steps

If the user skips activation (or after activation completes), suggest:

• /activate-site — Provision the site with a subdomain and make it live (if not already activated)
• /test-site — Test the deployed site in the browser (verify pages load, check API calls)
• /audit-permissions — Audit table permissions against current code (recommended after redeployments)
• /setup-datamodel — Create Dataverse tables for dynamic content
• /add-seo — Add meta tags, robots.txt, sitemap.xml, favicon

Important Notes

NEVER Use pac pages upload

Always use pac pages upload-code-site — never use pac pages upload. The pac pages upload command is designed for portal-studio-style sites and will corrupt SPA site metadata if used on a SPA site project. This applies to every upload step in this skill (Phase 4.4, Phase 6.4, and troubleshooting retries).

Throughout All Phases

• Use TaskCreate/TaskUpdate to track progress at every phase
• Ask for user confirmation at key decision points (see list below)
• Present errors clearly — when a command fails, show the user the relevant error output and explain what went wrong before suggesting fixes

Key Decision Points (Wait for User)

1. After Phase 2: If not authenticated, get environment URL from user
2. At Phase 3: Confirm or switch the target environment
3. At Phase 4.1: If multiple powerpages.config.json found, ask which project to deploy
4. At Phase 4.2: Audit permissions now or skip (redeployments only)
5. At Phase 5.5: Activate site now or later
6. At Phase 6: Get permission before modifying blocked attachments setting

Progress Tracking

Before starting Phase 1, create a task list with all phases using TaskCreate:

Mark each task in_progress when starting it and completed when done via TaskUpdate. Phase 6 may be marked completed immediately if no JavaScript blocking issue is encountered. This gives the user visibility into progress and keeps the workflow deterministic.

Begin with Phase 1: Verify PAC CLI