/integrate-webapi

name: integrate-webapi
description: >-
  Integrates Power Pages Web API into a site's frontend code with proper permissions and
  deployment. Orchestrates the full integration lifecycle: code integration, table permissions
  setup, and deployment for Dataverse CRUD operations. Use when the user wants to add Web API
  calls, connect to Dataverse, or add data fetching to their frontend.
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList
model: opus

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

Integrate Web API

Integrate Power Pages Web API into a code site's frontend. This skill orchestrates the full lifecycle: analyzing where integrations are needed, implementing API client code for each table, configuring permissions and site settings, and deploying the site.

Core Principles

• **First table sequential, then parallel**: The first table must be processed alone because it creates the shared `powerPagesApi.ts` client. Once that exists, remaining tables can be processed in parallel since each creates independent files (types, service, hooks).
• **Parallelize independent agents**: The `table-permissions-architect` and `webapi-settings-architect` agents are independent — invoke them in parallel rather than sequentially.
• **Permissions require deployment**: The `.powerpages-site` folder must exist before table permissions and site settings can be configured. Integration code can be written without it, but permissions cannot.
• **AI-only read mode is opt-in**: When invoked by another skill (e.g. `/add-ai-webapi`) with the `[AI-READ-ONLY]` sentinel in `$ARGUMENTS`, the flow produces read-only code and hardens the settings/permissions for AI summarization reads. See Phase 1.6 for the contract. Human invocations never trigger this mode.
• **Use TaskCreate/TaskUpdate**: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.

> **Prerequisites:** > > - An existing Power Pages code site created via `/create-site` > - A Dataverse data model (tables/columns) already set up via `/setup-datamodel` or created manually > - The site must be deployed at least once (`.powerpages-site` folder must exist) for permissions setup

**Initial request:** $ARGUMENTS

---

Workflow

1. **Verify Site Exists** — Locate the Power Pages project and verify prerequisites 2. **Explore Integration Points** — Analyze site code and data model to identify tables needing Web API integration 3. **Review Integration Plan** — Present findings to the user and confirm which tables to integrate 4. **Implement Integrations** — Use the `webapi-integration` agent for each table 5. **Verify Integrations** — Validate all expected files exist and the project builds successfully 6. **Setup Permissions & Settings** — Choose permissions source (upload diagram or let the architects analyze), then configure table permissions and Web API site settings with case-sensitive validated column names 7. **Review & Deploy** — Ask the user to deploy the site and invoke `/deploy-site` if confirmed

---

Phase 1: Verify Site Exists

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

**Actions**:

1.1 Locate Project

Look for `powerpages.config.json` in the current directory or immediate subdirectories to find the project root. Use your file-search tool (e.g., `Glob` with patterns `powerpages.config.json` and `*/powerpages.config.json`) rather than a shell-specific command.

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

1.2 Read Existing Config

Read `powerpages.config.json` to get the site name.

1.3 Detect Framework

Read `package.json` to determine the framework (React, Vue, Angular, or Astro). See `${PLUGIN_ROOT}/references/framework-conventions.md` for the full framework detection mapping.

1.4 Check for Data Model

Look for `.datamodel-manifest.json` to discover available tables:

**/.datamodel-manifest.json

If found, read it — this is the primary source for table discovery.

1.5 Check Deployment Status

Look for the `.powerpages-site` folder:

**/.powerpages-site

**If not found**: Warn the user that the permissions phase (Phase 6) will require deployment first. The integration code (Phases 2–5) can still proceed.

1.6 Detect AI-only read mode (skill-to-skill invocation)

Inspect `$ARGUMENTS`. If the text begins with the sentinel `[AI-READ-ONLY]`, the caller is another skill (typically `/add-ai-webapi`) that has already analysed the site and decided which tables need Layer 1/2 prerequisites for AI summarization reads. Parse the following structured tokens out of `$ARGUMENTS`:

| Token | Required | Meaning | |-------|----------|---------| | `mode=ai-read-only` | Yes | Confirms the posture; any other value is rejected with an error. | | `primary=<logical_name>` | Yes | The primary table being summarised. Missing → stop and report the contract violation to the caller. | | `tables=<csv>` | Yes | Comma-separated list of all tables in scope (primary + every `$expand` target). | | `expand-targets=<csv>` | No | Sub-list of `tables` that are `$expand` targets; defaults to empty. | | `caller=<skill-name>` | No | Informational — used in commit messages and the final summary. |

**When the sentinel is present:**

• Set an internal flag **AI-only read mode = true** that every downstream phase consults.
• Skip the Phase 3 interactive table confirmation and use the provided `tables` list verbatim (user has already confirmed in the caller).
• The Phase 4.1 `webapi-integration` prompt restricts operations to **read-only** (list + get by id).
• The Phase 6 Path B agent prompts apply the hardened AI-only posture documented in each agent's "AI-only read mode" section.
• The Phase 6 Path A script invocations use