Activate Site

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

Activate Power Pages Site

Provision a new Power Pages website in a Power Platform environment via the Power Platform REST API.

Prerequisite: This skill expects an existing Power Pages code site created via /create-site. Run that skill first if the site does not exist yet.

Core Principles

• Cloud-aware URL resolution — Never hardcode API base URLs or site URL domains. Always derive them from the Cloud value returned by pac auth who.
• Token handling — The agent only needs to verify the user is logged in to Azure CLI.
• Confirm before mutating — Always present the full activation parameters to the user and get explicit approval before POSTing to the websites API.
• Preserve the caller's environment — When another skill passes environmentUrl, verify PAC and Azure CLI still target that environment and tenant before activation.
• Caller status updates — When /create-site supplies a statusPath, update that file before and after activation prompts so the open template status page shows when user input is required.

Initial request: $ARGUMENTS

Workflow

1. Phase 1: Verify Prerequisites — PAC CLI auth + Azure CLI login + activation status check
2. Phase 2: Gather Parameters — Site name, subdomain, website record ID
3. Phase 3: Confirm — Present all parameters to user for approval
4. Phase 4: Activate & Poll — Run activation script (POST + poll provisioning status)
5. Phase 5: Present Summary — Show site URL, suggest next steps

Phase 1: Verify Prerequisites

Goal: Ensure PAC CLI is installed and authenticated, and verify the user is logged in to Azure CLI.

Actions

1.1 Verify PAC CLI

Run pac help to check if the PAC CLI is installed and available on the system PATH.

pac help

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

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

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

2. If dotnet is also not available, direct the user to https://aka.ms/PowerPlatformCLI for full installation instructions.

3. After installation, verify by running pac help again.

1.2 Check Authentication

Run pac auth who to check current authentication status.

pac auth who

If authenticated: Extract these values from the output:

• Environment ID — the GUID after Environment ID:
• Organization ID — the GUID after Organization ID: (this is the Dataverse org ID)
• Cloud — the value after Cloud: (e.g., Public, UsGov, UsGovHigh, UsGovDod, China)

If not authenticated: Follow the same authentication flow as deploy-site — ask the user for their environment URL and run pac auth create --environment "<URL>".

1.3 Verify Azure CLI Login

Verify the user is logged in to Azure CLI:

az account show

If az is not installed or not logged in: Instruct the user to install Azure CLI and run az login --allow-no-subscriptions (this form works whether or not the user has an Azure subscription — the activation flow only needs an AAD token).

1.4 Check If Already Activated

First inspect $ARGUMENTS for explicit imported-site identity from another skill:

siteName: <name>
websiteRecordId: <guid>
environmentUrl: <url>
statusPath: <path>

When both values are present, set SITE_IDENTITY_SOURCE = "arguments" immediately and skip the local-project activation status check below. That check resolves identity from powerpages.config.json / .powerpages-site, which may be absent or unrelated when /create-site activates an imported template site. Continue to Phase 2 with the explicit identity.

When environmentUrl is present, store it as EXPECTED_ENVIRONMENT_URL and verify the current CLI context before Phase 2:

node "${PLUGIN_ROOT}/scripts/validate-cli-tenant-alignment.js" --envUrl "<EXPECTED_ENVIRONMENT_URL>"

Continue only when the JSON result has ok: true. This check compares the active PAC environment URL with the caller's URL and verifies that PAC, the Azure account, and the Dataverse access token use the same tenant. If it fails, stop and ask the user to switch PAC or Azure CLI authentication. Do not activate the imported Website Record ID in a different environment.

When source is create-site template path and statusPath is present, store it as ACTIVATION_STATUS_PATH. This is the existing template status file created by /create-site; do not create a separate status page.

When SITE_IDENTITY_SOURCE !== "arguments", check whether the local project site is already activated by running the shared activation status script:

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

Where <PROJECT_ROOT> is the directory containing powerpages.config.json or .powerpages-site folder. Evaluate the JSON result:

• If activated is true: Inform the user their site is already activated at websiteUrl. Suggest next steps (Phase 5.3) and stop — do NOT proceed to Phase 2.
• If activated is false: Proceed to Phase 2.
• If error is present: Proceed to Phase 2 (do not block the activation flow).

When SITE_IDENTITY_SOURCE = "arguments", skip this entire local-project status check and continue to Phase 2 with the supplied site identity.

Output

• PAC CLI installed and authenticated
• Environment ID, Organization ID, and Cloud value extracted
• Azure CLI login confirmed
• Activation status checked for a local project, or skipped for an argument-based imported site

Phase 2: Gather Parameters

Goal: Determine the site name, generate or accept a subdomain, and look up the website record ID needed for the activation API call.

Actions

2.1 Read Site Name

If the skill was invoked by another skill with explicit imported-site identity in $ARGUMENTS, use it before local project discovery:

siteName: <name>
websiteRecordId: <guid>

When both values are present:

• Set siteName from the explicit value.
• Set websiteRecordId from the explicit value.
• Set SITE_IDENTITY_SOURCE = "arguments".
• Skip the powerpages.config.json lookup below and skip Phase 2.3 (pac pages list) because the caller already resolved the imported website record.

If either explicit value is missing, continue with the existing local-project discovery flow.

Look for powerpages.config.json in the current directory or one level of subdirectories using Glob:

**/powerpages.config.json

Read the file and extract the siteName field. If not found, ask the user for the site name using AskUserQuestion.

2.2 Generate Subdomain Suggestion

CRITICAL — This step is MANDATORY. You MUST ask the user about the subdomain before proceeding. Do NOT skip this step or auto-select a subdomain without user input.

Run the subdomain generator script to create a random suggestion:

node "${PLUGIN_ROOT}/skills/activate-site/scripts/generate-subdomain.js"

This outputs a string like site-a3f2b1. Resolve the correct site URL domain from the Cloud value obtained in Phase 1.2:

<!-- gate: activate-site:2.2.subdomain | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · activate-site:2.2.subdomain): Confirm or override the generated subdomain. Subdomain is part of the resulting site URL; Cancel exits before any provisioning call.

Present the generated subdomain to the user and ask them to accept or enter their own using AskUserQuestion:

When ACTIVATION_STATUS_PATH is set, use Write to atomically overwrite it immediately before AskUserQuestion:

{
  "state": "running",
  "phase": "activation",
  "message": "Waiting for subdomain selection",
  "awaitingInput": true,
  "inputPrompt": "Choose the site subdomain in the agent terminal."
}

Immediately after the user responds, overwrite the file again so the toast disappears:

{
  "state": "running",
  "phase": "activation",
  "message": "Preparing site activation",
  "awaitingInput": false
}

If the user cancels the prompt, clear awaitingInput before stopping. Apply the same status updates whenever a subdomain conflict loops back to this step.

If custom: The user provides their own subdomain via "Other" free text input. Validate it is lowercase, alphanumeric with hyphens only, and 3-50 characters.

2.3 Get Website Record ID

Skip this step when SITE_IDENTITY_SOURCE = "arguments" and websiteRecordId is already set.

Run pac pages list to get the website record ID:

pac pages list

Parse the output to find the website record that matches the site name. Extract the Website Record ID (GUID). If pac pages list returns no results or the command is not available, set websiteRecordId to $null — the API will create a new website record.

Output

• Site name determined (from config file or user input)
• Subdomain chosen (generated or custom)
• Website record ID resolved (GUID or null)

Phase 3: Confirm

Goal: Present all activation parameters to the user and get explicit approval before making the API call.

Actions

<!-- gate: activate-site:3.confirm | category=final | cancel-leaves=nothing -->

🚦 Gate (final · activate-site:3.confirm): Last-call before the activation API call. All activation parameters echoed back; Cancel exits cleanly before provisioning. Fires fresh on every skill invocation. When plan-alm orchestrates multi-stage activation (Staging + Production), it invokes activate-site once per stage — each invocation hits this gate fresh with its own siteName, subdomain, and target env. The Staging activation consent does NOT cover Production. Each stage's site URL is a separate go-live decision (different audiences, different timing).

Present all activation parameters to the user using AskUserQuestion:

If "No": Stop the skill and inform the user they can re-run it later.

If "Yes": Proceed to Phase 4.

Output

• User has explicitly approved the activation parameters

Phase 4: Activate & Poll

Goal: POST to the Power Platform websites API to start provisioning, poll until completion, and report the result.