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

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

4. **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 <https://aka.ms/PowerPlatformCLI> for full installation instructions including .NET SDK setup.

   3. After installation, verify by running `pac help` again.
   4. 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
   ```

2. **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.

3. **If not authenticated**:

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

   <!-- not-a-gate: free-text env URL fallback when PAC CLI auth is missing — data-gathering, no destructive action -->

   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")

   3. 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.

   4. After the command completes, verify by running `pac auth who` again.
   5. If authentication succeeds, proceed to Phase 3.
   6. 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: deploy-site:3.confirm-env | category=consent | cancel-leaves=nothing -->

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

   | 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 |

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

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

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

      ```bash
      pac org list
      ```

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

      ```bash
      pac org select --environment "<SELECTED_ENV_ID_OR_URL>"
      ```

   5. Verify the switch by running `pac auth who