deploy-site

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

Deploy Power Pages Code Site

Guide the user through deploying an existing Power Pages code site to a Power Pages environment using PAC CLI. Follow a systematic approach: verify tooling, authenticate, confirm the target environment, build and upload the site, and handle any blockers.

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

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](#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:
3. 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 <https://aka.ms/PowerPlatformCLI> 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:
2. Environment name and URL
3. Environment ID — the GUID after Environment ID:
4. 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.
2. Use AskUserQuestion to ask for the environment URL:

| Question | Header | Options | |----------|--------|---------| | You are not authenticated with PAC CLI. Please provide your Power Pages environment URL (e.g., https://org12345.crm.dynamics.com) so I can authenticate you. | Auth | (free text input via "Other") |

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 "<USER_PROVIDED_URL>" ``

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:

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

Use AskUserQuestion with the following structure:

| Question | Header | Options | |----------|--------|---------| | You are currently connected to environment: <ENV_NAME> (<ENV_URL>). Do you want to deploy to this environment? | Environment | Yes, use this environment, No, let me choose a different one |

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 "<SELECTED_ENV_ID_OR_URL>" ``

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

Output: Confirmed target environment for deployment

Phase 4: Deploy the Code 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

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.

Use AskUserQuestion:

| Question | Header | Options | |----------|--------|---------| | This site has been deployed before. Would you like to run a permissions audit to verify table permissions match your current code before deploying? | Audit | Yes, audit permissions (Recommended), Skip — permissions are up to date |

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](#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: ${CLAUDE_PLUGIN_ROOT}/references/skill-tracking-reference.md

Follow the skill tracking instructions in the reference to record this skill's usage. U