integrate-webapi

> **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 a Power Pages site with Dataverse. SPA sites retain the framework-specific client, service, and hook workflow. Non-SPA sites use native Forms, Lists, and Liquid first, adding Web API JavaScript only when the requested client interaction requires it. ## Site Type Routing Before reading or executing the workflow below, perform the existing SPA project lookup first: - Look for `powerpages.config.json` in the current directory or immediate subdirectories using the existing file-search patterns. - If found, continue with the existing SPA workflow below. Do not run any non-SPA site detection or change the SPA phases, prompts, gates, generated files, or deployment behavior. - Only when that existing SPA lookup finds no `powerpages.config.json`, run: ```bash node "${PLUGIN_ROOT}/scripts/lib/detect-project-context.js" ``` - If it returns `siteType: "non-spa"`, read and follow the complete seven-phase workflow in `${PLUGIN_ROOT}/skills/integrate-webapi/references/non-spa-site-workflow.md`. Do not execute any of the SPA workflow below. - Otherwise, continue to Phase 1 and preserve its existing not-found handling. The non-SPA route supports request-focused and discovery invocation as defined in its workflow reference. SPA invocation semantics remain those defined by the existing workflow below. When `$ARGUMENTS` contains `[CALLED-BY-PARENT-SKILL]`, pass that sentinel and its optional `caller=<skill-name>` token into the non-SPA workflow. It suppresses commits and deployment handoffs only; it does not bypass the non-SPA scope approval or security planning. --- ## 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. - **Preserve site integrity**: Before an agent changes mock-backed or data-driven UI, read `${PLUGIN_ROOT}/references/site-modification-integrity.md`; localize every new visible state when a manifest exists and keep the component bidirectional and expansion-safe. > **Prerequisites:** > > - An existing Power Pages SPA 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: ```text **/.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: ```text **/.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 `--read` only for table permissions and omit primary keys / relationship Navigation Properties from `Webapi/<table>/fields`. - No `AskUserQuestion` prompts are issued for Phase 3 or Phase 6.2 — the caller owns those decisions. - **Defer all git commits to the caller.** Skip Phase 4.4 (`git add -A && git commit`) and Phase 6.5 (permissions/settings commit) entirely. The caller is batching changes into one or two commits at orchestrator-defined milestones; an unprompted commit here turns one logical change into three. Print the file lists you would have committed so the caller can reproduce them. - **Suppress the end-of-skill deploy prompt.** Skip Phase 6.1 (deploy-now ask when `.powerpages-site` is missing — the caller has already gated on this), Phase 7.3 (final deploy ask), and Phase 7.4 (post-deploy notes). The caller owns the single end-of-orchestration deploy decision; nesting deploy prompts inside the delegation gives the user 2–3 redundant asks per run. Return the integration summary (Phase 7.2) without trailing deploy/notes. **When the sentinel is absent**: proceed exactly as today (full CRUD, full interactive flow, auto-commit, deploy prompt). This is the regression guard — no human invocation changes behavior. **Output**: Confirmed project root, framework, data model availability, deployment status, and (if sentinel present) parsed AI-read-only contract. --- ## Phase 2: Explore Integration Points **Goal**: Analyze the site code and data model to identify all tables needing Web API integration **Actions**: Use the **Explore agent** (via `Task` tool with `agent_type: "explore"`) to analyze the site code and data model. The Explore agent should answer these questions: ### 2.1 Discover Tables Ask the Explore agent to identify all Dataverse tables that need Web API integration by examining: - `.datamodel-manifest.json` — List of tables and their columns - `src/**/*.{ts,tsx,js,jsx,vue,astro}` — Source code files that reference table data, mock data, or placeholder API calls - Existing `/_api/` fetch patterns in the code - TypeScript interfaces or types that map to Dataverse table schemas - Component files that display or manipulate data from Dataverse tables - Mock data files or hardcoded arrays that should be replaced with API calls - `TODO` or `FIXME` comments mentioning API integration **Prompt for the Explore agent:** > "Analyze this Power Pages SPA site and identify all Dataverse tables that need Web API integration. Check `.datamodel-manifest.json` for the data model, then search the source code for: mock data arrays, hardcoded data, placeholder fetch calls to `/_api/`, TypeScript interfaces matching Dataverse column patterns (publisher prefix like `cr*_`), TODO/FIXME comments about API integration, and components that display table data. For each table found, report: the table logical name, the entity set name (plural), which source files reference it, what operations are needed (read/create/update/delete), and whether an existing API client or service already exists in `src/shared/` or `src/services/`. Also check if `src/shared/powerPagesApi.ts` already exists." **When AI-only read mode is active (Phase 1.6 flag set):** append the following to the prompt above: > "The caller has specified **AI-READ-ONLY** mode for tables `[tables from sentinel]` (primary=`[primary]`, expand-targets=`[expand-targets]`). Operations needed for every table in that list = **read only**. Do NOT report create/update/delete call sites or mock-data replacement candidates. For each `$expand` target, also report the columns the primary's code `$select`s on that expansion (these become the minimal fields list)." ### 2.2 Identify Existing Integration Code The Explore agent should also report: - Whether `src/shared/powerPagesApi.ts` (or equivalent API client) already exists - Which tables already have service files in `src/shared/services/` or `src/services/` - Which tables already have type definitions in `src/types/` - Any framework-specific hooks/composables already created This avoids duplicating work that was already done. ### 2.3 Compile Integration Manifest From the Explore agent's findings, compile a list of tables needing integration: | Table | Logical Name | Entity Set | Operations | Files Referencing | Existing Service | |-------|-------------|-----------|------------|-------------------|-----------------| | Products | `cr4fc_product` | `cr4fc_products` | CRUD | `ProductList.tsx`, `ProductCard.tsx` | None | | Categories | `cr4fc_category` | `cr4fc_categories` | Read | `CategoryFilter.tsx` | None | **Output**: Complete integration manifest listing all tables, their operations, referencing files, and existing service status --- ## Phase 3: Review Integration Plan **Goal**: Present the integration manifest to the user and confirm which tables to integrate **Actions**: ### 3.1 Present Findings Show the user: 1. The tables that were identified for Web API integration 2. For each table: which files reference it, what operations are needed 3. Whether a shared API client already exists or needs to be created 4. Any tables that were skipped (already have services) ### 3.2 Confirm Tables <!-- gate: integrate-webapi:3.2.confirm-tables | category=plan | cancel-leaves=nothing --> > 🚦 **Gate (plan · integrate-webapi:3.2.confirm-tables):** Final say on which tables get Web API integration code (client, types, services, hooks). > > **Trigger:** Explore agent surfaced candidate tables in Phase 3.1. > **Why we ask:** Auto-selecting all tables can generate orphaned TypeScript files for tables the user never intended to expose via Web API. > **Cancel leaves:** Nothing — no service/type/hook files written yet. **When AI-only read mode is active (Phase 1.6 flag set):** skip this step entirely. Use the `tables` list parsed from the sentinel verbatim — the caller has already confirmed the selection with the user. Do not issue an `AskUserQuestion`. Otherwise, use `AskUserQuestion` to confirm: | Question | Options | |----------|---------| | I found the following tables that need Web API integration: **[list tables]**. Which tables should I integrate? | All of them (Recommended), Let me select specific tables, I need to add more tables | If the user selects specific tables or adds more, update the integration manifest accordingly. **Output**: User-confirmed list of tables to integrate (or sentinel-supplied list in AI-only read mode) --- ## Phase 4: Implement Integrations **Goal**: Create Web API integration code for each confirmed table using the `webapi-integration` agent **Actions**: ### 4.1 Invoke Agent Per Table For each table, use the `Task` tool to invoke the `webapi-integration` agent at `${PLUGIN_ROOT}/agents/webapi-integration.md`: **Prompt template for the agent:** > "Integrate Power Pages Web API for the **[Table Display Name]** table. > > - Table logical name: `[logical_name]` > - Entity set name: `[entity_set_name]` > - Operations needed: [read/create/update/delete] > - Framework: [React/Vue/Angular/Astro] > - Project root: [path] > - Source files referencing this table: [list of files] > - Data model manifest path: [path to .datamodel-manifest.json if available] > > Create the TypeScript types, CRUD service layer, and framework-specific hooks/composables. Replace any mock data or placeholder API calls in the referencing source files with the new service." **When AI-only read mode is active (Phase 1.6 flag set):** replace "Operations needed: [read/create/update/delete]" with `Operations needed: read-only` and append to the prompt: > "**AI-only read integration.** Do NOT emit create, update, or delete functions. Scaffold only `list<Table>` (paginated) and `get<Table>ById` in the service layer. Create the framework-specific read hook only (e.g. `use<Table>()` with `items`, `isLoading`, `error`, `refetch`; no mutation hooks). Do not wire mock-data replacements beyond what is needed for the AI summarization caller — the upstream skill will add the summarization service on top. The shared `src/shared/powerPagesApi.ts` client is still created if it does not already exist; the caller relies on it for the AI integration's read path." ### 4.2 Process First Table, Then Parallelize Remaining The **first table** must be processed alone — it creates the shared `powerPagesApi.ts` client that all other tables depend on. After the first table completes and the shared client exists: - **Verify** the shared API client was created at `src/shared/powerPagesApi.ts` - **Then invoke all remaining tables in parallel** using multiple `Task` calls — each table creates independent files (its own types in `src/types/`, service in `src/shared/services/`, and hook/composable), so there are no conflicts If there is only one table, this step is simply sequential. ### 4.3 Verify Each Integration After each agent completes (or after all parallel agents complete), verify the output: - Check that the expected files were created (types, service, hook/composable) - Confirm the shared API client exists after the first table is processed - Note any issues reported by the agent ### 4.4 Git Commit **Skip when AI-only read mode is active** (Phase 1.6 flag set) — the caller batches commits. Print the file list this phase would have staged so the caller can reproduce, then move on. Otherwise, after all integrations are complete, stage and commit: ```bash git add -A git commit -m "Add Web API integration for [table names]" ``` **Output**: Integration code created for all confirmed tables, verified and (in normal mode) committed --- ## Phase 5: Verify Integrations **Goal**: Validate that all expected integration files exist, imports are correct, and the project builds successfully **Actions**: ### 5.1 Verify File Inventory For each integrated table, confirm the following files exist: - **Type definition** in `src/types/` (e.g., `src/types/product.ts`) - **Service file** in `src/shared/services/` or `src/services/` (e.g., `productService.ts`) - **Framework-specific hook/composable** (e.g., `src/shared/hooks/useProducts.ts` for React, `src/composables/useProducts.ts` for Vue) Also verify: - **Shared API client** at `src/shared/powerPagesApi.ts` exists