add-cloud-flow

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

# Add Cloud Flow

Connect one or more Power Automate cloud flows to a Power Pages code site, or wire already-registered flows into additional pages/components. For new flows this skill:
- Creates the `adx_cloudflowconsumer` metadata YAML in `.powerpages-site/cloud-flow-consumer/`
- Assigns web roles based on the flow's scenario and target audience
- Generates client-side TypeScript/JavaScript service code to trigger the flow with CSRF authentication

For already-registered flows, the skill skips metadata and role creation and goes straight to client-side integration — wiring the existing flow into new UI locations.

## Core Principles

- **Multiple flows in one run**: The user can add several flows at once. All flows are planned together and implemented together before asking for deployment.
- **Ask before acting**: Present a full HTML plan (all flows, roles, reasoning) before creating any files.
- **Web roles drive access**: Every flow must have at least one web role. Anonymous Users role is valid but must be confirmed.
- **Scenario determines roles**: Understand what each flow does and who triggers it before picking roles.
- **Use TaskCreate/TaskUpdate**: Track all phases upfront before starting any work.

> **Prerequisites:**
> - An existing Power Pages code site with `.powerpages-site` deployed
> - PAC CLI authenticated (`pac auth who` must succeed)
> - Azure CLI authenticated (`az login --allow-no-subscriptions` works whether or not your account has an Azure subscription — Dataverse and Power Platform tokens are AAD-scoped)

**Initial request:** $ARGUMENTS

---

## Workflow

1. **Verify Prerequisites** — Locate the project, confirm `.powerpages-site` exists, inventory web roles and existing flows
2. **List Available Flows** — Fetch flows from the Power Automate Flow RP API
3. **Select Flows & Understand Scenarios** — User picks one or more flows; determine scenario and audience for each
4. **Determine Web Roles** — Propose minimum roles per flow with reasoning
5. **Review Plan** — Render HTML plan for all flows; get user approval
6. **Create Metadata** — Write `.cloudflowconsumer.yml` for each flow; create missing web roles first
7. **Client-Side Integration** — Generate typed service code to call each flow from the frontend
8. **Verify & Summarize** — Validate all YAMLs, record skill usage, offer deployment

---

## Phase 1: Verify Prerequisites

**Goal**: Locate the Power Pages project and confirm all prerequisites are met

**Actions**:

1. Create todo list with all 8 phases (see [Progress Tracking](#progress-tracking) table)

### 1.1 Locate Project

Look for `powerpages.config.json` in the current directory or immediate subdirectories.

**If not found**: Tell the user to create a site first with `/create-site`.

### 1.2 Read Config

Read `powerpages.config.json` to get the `siteName` (used for display and plan rendering).

### 1.3 Check `.powerpages-site` Exists

Look for the `.powerpages-site` folder in the project root.

**If not found**:

<!-- gate: add-cloud-flow:1.3.deploy-first | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · add-cloud-flow:1.3.deploy-first):** `.powerpages-site` missing — cloud flow YAML lives inside it. Deploy first or stop.
>
> **Trigger:** Phase 1.3 found no `.powerpages-site` directory.
> **Why we ask:** Cloud flow YAML written to a non-existent path will never deploy.
> **Cancel leaves:** Nothing — no YAML files written.

Use `AskUserQuestion`:

| Question | Options |
|----------|---------|
| `.powerpages-site` is required to add cloud flows. Would you like to deploy the site now? | Yes, deploy now (Required), Cancel |

**If "Yes, deploy now"**: Invoke `/deploy-site` first, then continue to Phase 2.
**If "Cancel"**: Stop.

### 1.4 Read Existing Web Roles

Read all `.webrole.yml` files from `.powerpages-site/web-roles/` to inventory available roles. Note each role's `id`, `name`, `adx_anonymoususersrole`, and `adx_authenticatedusersrole`.

### 1.5 Check Existing Cloud Flows

Check `.powerpages-site/cloud-flow-consumer/` for existing `.cloudflowconsumer.yml` files. For each file, read:
- `processid` — the flow's `workflowEntityId`
- `name` — the flow's display name
- `adx_CloudFlowConsumer_adx_webrole` — assigned web role UUIDs

Store these as the **already-registered flows** list. These flows already have metadata and web roles configured but may need additional frontend integration on other pages or components.

### 1.6 Detect Frontend Framework

Read `package.json` to detect the framework (React, Vue, Angular, Astro). Note the framework and its conventions for Phase 7. See `${PLUGIN_ROOT}/references/framework-conventions.md` for the detection mapping.

**Output**: Project root, site name, framework, available web roles, already-registered flows (with processid, name, and web roles)

---

## Phase 2: List Available Flows

**Goal**: Fetch all Power Automate cloud flows that have a PowerPages trigger

**Actions**:

Run the list-cloud-flows script (reads environment from `pac auth who` internally):

```bash
node "${PLUGIN_ROOT}/skills/add-cloud-flow/scripts/list-cloud-flows.js"
```

This calls the **Power Automate Flow RP API** with the filter `properties/definitionSummary/triggers/any(t: t/kind eq 'powerpages')`. Results include:

| Field | Source | Used for |
|-------|--------|----------|
| `id` | `properties.workflowEntityId` | `processid` in YAML; URL in client-side API call |
| `flowRpName` | `flow.name` | Flow RP identifier |
| `displayName` | `properties.displayName` | Shown to user; written as `name` in YAML |
| `description` | `properties.description` | Shown to user |
| `state` | `properties.state` | Shown to user (Active/Draft) |

**Separate into two lists**:
- **Unregistered flows**: Flows whose `id` does NOT match any `processid` from Phase 1.5 — these need full setup (metadata + roles +