/pcf

name: pcf
version: 1.0.0
description: Builds, tests, diagnoses, upgrades, deploys and verifies Power Apps component framework (PCF) code components for model-driven apps and Power Pages — field and dataset controls, standard and virtual (React) — from Microsoft-maintained templates and recipes pinned to a tested version matrix. Runs quality gates (manifest and host lint, source checks, lint, unit tests, production build), deploys with pac pcf push, verifies registration and form bindings, and guides Power Pages enablement, with guided setup for canvas apps. Use when the user wants to build, fix, upgrade, deploy or check a PCF control or code component, or asks why one fails to build, import, update or render. For a whole page use /model-apps:genpage; for a whole app use /model-apps:app-builder.
author: Microsoft Corporation
argument-hint: "<control description> | doctor | upgrade | verify | inventory"
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, AskUserQuestion, EnterPlanMode, ExitPlanMode, TaskCreate, TaskUpdate, TaskList, read, edit, execute, search, web, todo

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

PCF skill

Build, repair, upgrade, deploy, bind, verify and inventory Power Apps component framework controls. Run the work in the main conversation loop. Do not dispatch interactive authoring, approval, deploy consent, binding choices or browser-verification choices to a subagent.

Critical startup

1. Set `PLUGIN_ROOT` to the installed `plugins/pcf` directory. 2. Resolve interaction once:

   node "${PLUGIN_ROOT}/scripts/resolve-interaction-mode.js"
   # Optional for automation: --non-interactive

3. In unattended mode, do not call `AskUserQuestion`, `EnterPlanMode` or `ExitPlanMode`. Use explicit request details and documented non-destructive defaults only; write `Unattended default: <question> → <answer> (<reason>)` to `workflow-log.md` in the session working directory; halt on ambiguous environment, app/form/control identity or destructive choices. `pcf-intent.json`, `pcf-plan.md` and `workflow-log.md` live in that working directory. `hooks/validate-write-safety.js` detects a pcf session only from `pcf-intent.json` or `pcf-plan.md` at or one level under the cwd; `workflow-log.md` is not a session marker. `--out` must be a new, empty subdirectory. Never write those session files into `--out` before scaffold runs — a non-empty directory is refused. 4. Suppressing a prompt never authorizes an environment write. `pcf-push.js` still requires an explicit `--env` and prior consent recorded by the user or automation.

Routing

| User intent | Route | | --- | --- | | Build, fix, upgrade, deploy, bind, verify, inventory a PCF code component | Stay in `/pcf:pcf`. | | Why a PCF control will not build, import, update or render | Stay in `/pcf:pcf`; start with [../../references/pcf-troubleshooting.md](../../references/pcf-troubleshooting.md) and the doctor output. | | Whole custom page / generative page | Use `/model-apps:genpage`. | | Whole model-driven app with tables/forms/views/pages | Use `/model-apps:app-builder`. | | Use an existing control without code changes | Guide Maker binding and verification; do not scaffold. |

Modes — detect, then confirm

• **new**: no PCF project exists or the user asks to create one. Follow [create-flow.md](create-flow.md).
• **existing project**: one `*.pcfproj` found. Iterate, gates, deploy-only or bind as requested. If several are found, ask which unless unattended supplied a path.
• **verify**: existing control already registered/bound. Run `verify-pcf.js` or `pcf-inventory.js` as appropriate.
• **pages**: user targets Power Pages. This release supports Power Pages only for standard field controls: the form-field journey and the standalone Liquid journey (`{% codecomponent %}`), both guided. Dataset controls on Pages (form sub-grid and list) are not supported in this release. Run the Pages compatibility gate before deploy or acceptance, then guide site configuration after deploy. Follow [pages-flow.md](pages-flow.md).
• **canvas**: user targets canvas apps. Setup is guided only: gate with the model-driven profile (`model` in the intent and `--hosts`, the gates' default; never `canvas`), keep `pages` as well when the control also targets Power Pages, and review canvas API limits by hand with the user. After the normal push flow, guide the environment setting and Studio setup using [../../references/pcf-canvas.md](../../references/pcf-canvas.md). A canvas gate profile, reading the environment setting and automated runtime evidence are not implemented.
• **doctor**: run `pcf-doctor.js` and stop with fixes unless user asked to apply a repair.
• **upgrade**: follow [upgrade-flow.md](upgrade-flow.md).
• **inventory / "is this control still used?"**: run `pcf-inventory.js --env <url> --where-used`; always include the where-used warning from `pcf-testing.md` because dependency results are registered solution dependencies only, not proof of Liquid or arbitrary text references.

Phase 0 — preflight

Run the smallest doctor for the requested work:

node "${PLUGIN_ROOT}/scripts/pcf-doctor.js" [--project <dir>] [--hosts model,pages] [--needs build,push]

When an environment is involved, also run:

node "${PLUGIN_ROOT}/scripts/check-auth.js" --env <envUrl> [--require-pac]

Use `--require-pac` only for push/package paths and any other path that invokes PAC. Verification and inventory use Azure CLI plus Dataverse reads, so they require `az` auth but not PAC. If auth or tools block, report the script's JSON message and stop.

For repair work, read [../../references/pcf-troubleshooting.md](../../references/pcf-troubleshooting.md) before choosing fixes. It maps build/import/update/render symptoms to the checks and scripts that produce actionable evidence.

Ph