@terreno/mcp 57.1.0 → 57.2.0

package/dist/docs/versioned/0.27.0/implementationPlans/admin-script-runner.md

@@ -1,107 +0,0 @@
-# Admin Script Runner — Maintenance Scripts via `AdminApp`
-
-**Status:** Implemented (ships with Admin UI v2 work; documented here as its own IP)  
-**Related:** [`admin-ui-v2-django-parity.md`](./admin-ui-v2-django-parity.md) (home `scriptRunner` widget, background-task patterns)  
-**Primary packages:** `@terreno/api` (`BackgroundTask`, script types), `@terreno/admin-backend`, `@terreno/admin-frontend`, `admin-spa`, `example-backend`
-
-## Goal
-
-Let backends register **named, server-side maintenance scripts** on `AdminApp`. Admins discover them from **`GET /admin/config`** (`scripts[]`: `name` + `description` only — no code). Execution is **`POST {adminBase}/scripts/:name/run?wetRun=true|false`**, which creates a **`BackgroundTask`**, runs the `runner` async, and supports **poll** (`GET …/scripts/tasks/:id`) and **cancel** (`DELETE …/scripts/tasks/:id`). The admin UI exposes **`AdminScriptList`** + **`AdminScriptRunModal`** (dry/wet, logs, polling) and a **`scriptRunner`** home widget that deep-links to the scripts screen.
-
-## Non-Goals
-
-- Uploading or editing script source from the browser.
-- Running scripts without authentication or without **admin** (`user.admin`).
-- Replacing **`POST /admin/background-tasks`** for arbitrary job kinds — scripts are the **curated** list; background-tasks remain the generic enqueue API for config-driven actions.
-
-## Decisions
-
-| Topic | Decision |
-|-------|-----------|
-| Task storage | Reuse **`BackgroundTask`** from `@terreno/api` (`api/src/scriptRunner.ts`); `taskType` = script `name`. |
-| Dry run | Query **`wetRun=false`** → `isDryRun: true` on the task; runners interpret per app conventions (see example-backend scripts). |
-| Config surface | Only **`name`** and **`description`** in `/admin/config` — runners stay server-only. |
-| UI entry | **`AdminShell`**: nav item when `scripts.length > 0`**; **`AdminHome`**: widget id **`scriptRunner`** (often placed in **`home.slots.navGlobal`** per Django-parity layout). |
-| SPA routing | **`admin-spa`**: dedicated `app/scripts.tsx` and dynamic **`/__scripts`** under `app/[model]/index.tsx`. |
-
-## Architecture
-
-```
-Browser
-  │
-  ├─ GET /admin/config          ← includes scripts: [{ name, description }]
-  │
-  ├─ POST /admin/scripts/:name/run?wetRun=…
-  │     → 201 { taskId }        ← creates BackgroundTask, kicks async runner
-  │
-  ├─ GET  /admin/scripts/tasks/:id   ← poll status / logs / result
-  │
-  └─ DELETE /admin/scripts/tasks/:id ← cancel (running → cancelled)
-```
-
-Types: `ScriptRunner`, `ScriptContext`, `ScriptResult` in `api/src/scriptRunner.ts`.
-
-### Phase completion (all shipped)
-
-| Phase | Scope | Evidence |
-|-------|--------|----------|
-| A | Types + `BackgroundTask` | `api/src/scriptRunner.ts` |
-| B | HTTP routes + config metadata | `admin-backend/src/adminApp.ts`; `admin-backend/src/adminApp.test.ts` (run, poll, cancel, wetRun, 403/404); `adminApp.models.test.ts` (`/admin/config` includes `scripts`) |
-| C | Hooks + UI | `admin-frontend/src/useAdminScripts.ts`, `AdminScriptList.tsx`, `AdminScriptRunModal.tsx`, `AdminShell.tsx`, `AdminHome.tsx`; tests + isolated specs |
-| D | SPA + example | `admin-spa/app/scripts.tsx`, `app/[model]/index.tsx` (`__scripts`); `example-backend/src/server.ts` `scripts` |
-
-Script **run** paths are exercised in **`admin-backend` tests**; the aggregated **`openapi.json`** snapshot in **`example-backend`** documents `/admin/config` (including the `scripts` array shape) and may not list every dynamic `POST /admin/scripts/:name/run` path depending on OpenAPI aggregation — runtime behavior is still covered by admin-backend tests.
-
-## APIs (implemented)
-
-| Method | Path | Purpose |
-|--------|------|--------|
-| POST | `{basePath}/scripts/:name/run` | Start script; body empty; **`wetRun`** query boolean. |
-| GET | `{basePath}/scripts/tasks/:taskId` | Poll task document (status, progress, logs, result). |
-| DELETE | `{basePath}/scripts/tasks/:taskId` | Request cancellation. |
-
-All script routes sit behind **`authenticateMiddleware()`**; run/poll/delete require **`user.admin`** (403 otherwise). See `admin-backend/src/adminApp.ts` (`mountScriptRoutes`).
-
-## UI (implemented)
-
-| Piece | Role |
-|-------|------|
-| `useAdminScripts` | RTK-injected endpoints for run / get task / cancel. |
-| `AdminScriptRunModal` | Dry vs wet run, start, poll, show logs/results, cancel. |
-| `AdminScriptList` | Lists scripts from config; opens modal. |
-| `AdminHome` widget `scriptRunner` | Card + “Open scripts” → `__scripts` route. |
-| `AdminShell` | Sidebar “Scripts” when `config.scripts.length > 0`. |
-
-## Consumer wiring (example)
-
-`example-backend/src/server.ts` — `new AdminApp({ … scripts: [{ name, description, runner }, …] })`. Runners may use only `wetRun` or also **`ScriptContext`** (`addLog`, `updateProgress`, `checkCancellation`) for long jobs.
-
-## Files (reference)
-
-| Area | Files |
-|------|--------|
-| Types + model | `api/src/scriptRunner.ts` (`ScriptRunner`, `BackgroundTask`, …) |
-| HTTP + OpenAPI | `admin-backend/src/adminApp.ts` |
-| Tests | `admin-backend/src/adminApp.test.ts`, `admin-backend/src/adminApp.models.test.ts` (ctx script) |
-| Hooks + UI | `admin-frontend/src/useAdminScripts.ts`, `AdminScriptList.tsx`, `AdminScriptRunModal.tsx`, `AdminHome.tsx`, `AdminShell.tsx` |
-| SPA | `admin-spa/app/scripts.tsx`, `admin-spa/app/[model]/index.tsx` (`__scripts`) |
-| Example | `example-backend/src/server.ts` (`scripts` array) |
-
-## Task list
-
-Executable checklist: **`docs/tasks/admin-script-runner.md`**.
-
-## Acceptance Criteria (summary)
-
-- [x] `GET /admin/config` includes `scripts` metadata when scripts are registered; empty array when none.  
-- [x] `POST …/scripts/:name/run` returns **201** + **`taskId`** for admins; **403** non-admin; **404** unknown name.  
-- [x] `GET …/scripts/tasks/:id` exposes task state for polling; `DELETE` cancels where allowed.  
-- [x] Runners receive **`wetRun`** and optional **`ScriptContext`**; failures mark task **failed**; **`TaskCancelledError`** respected.  
-- [x] Frontend: list + modal + polling; dry vs wet surfaced to query string.  
-- [x] `scriptRunner` home widget + shell nav reach the scripts screen without embedding the list inside the wrong slot (covered with Admin Home tests + layout rules in Admin UI v2 IP).
-
-## Future / not in scope
-
-- Per-script RBAC beyond “is admin”.  
-- Streaming log output over WebSockets (polling only today).  
-- Shared quota / concurrency limits across script and background-task queues.

package/dist/docs/versioned/0.27.0/implementationPlans/admin-ui-v2-django-parity.md

@@ -1,204 +0,0 @@
-# Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
-
-**Status:** Implemented (phased tasks complete; acceptance criteria verified in-repo)  
-**Branch:** Landed via `cursor/admin-ui-v2-backend-a736` (PR #782)  
-**Owner:** Josh Gachnang  
-**Created:** 2026-06-15  
-**Source:** Claude Design handoff (`Admin UI v2.html`, `admin/v2/schema.jsx`, design transcripts). Design blend plan approved in-session.
-
-**Companion IP — Admin script runner:** Maintenance scripts (`AdminApp` `scripts[]`, `/admin/scripts/*`, `AdminScriptList` / `scriptRunner` widget) are specified in **`docs/implementationPlans/admin-script-runner.md`** with tasks in **`docs/tasks/admin-script-runner.md`**.
-
-## Goal
-
-Evolve Terreno’s admin stack (`@terreno/admin-backend`, `@terreno/admin-frontend`, `@terreno/admin-spa`) so a **single `/admin/config` payload** can drive a **Django-style admin**: grouped sidebar, declarative **home `slots`** (header strip, above-the-fold band, main column, sidebar — analogous to Django admin template blocks), changelist with typed filters / search / sort allowlists / pagination / bulk actions (sync + background), schema-driven forms with fieldsets and readonly enforcement, permission-gated UI (e.g. delete off), and deep links to plugin screens (document storage, AI explorer). **REST-first:** every persisted entity uses `modelRouter` CRUD; only gated custom routes for bulk jobs and config aggregation.
-
-## Non-Goals
-
-- **Pixel-perfect clone** of the HTML prototype’s inline styles — match **behavior and information architecture**, using `@terreno/ui` theming.
-- **Replacing Font Awesome in the prototype** — Terreno UI uses FA6 names via `iconName`; map icons at integration boundary.
-- **Product-specific Flourish models in core packages** — example models may live in `example-backend`; framework ships **capabilities** and **reference wiring**.
-- **SSR / SEO** for admin.
-- **Cross-tenant URL structure** — tenant scoping remains consumer-owned via permissions and query filters.
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| Config contract | Extend `GET /admin/config` with a **versioned** `schemaVersion` (e.g. `2`) and additive fields; preserve v1 consumers until admin-frontend major. |
-| List filters | Encode as **queryFields-compatible** filters (booleans, enums, text contains, date ranges, ref id); rail vs chips is **UI mode** only. |
-| Bulk sync actions | **`POST {basePath}{routePath}/bulk-patch`** with allowlisted patch keys, **≤ 1000** ids, OpenAPI documented. |
-| Background actions | Reuse **`BackgroundTask`** (`@terreno/api`) via **`POST /admin/background-tasks`** (or equivalent under `adminApp`) returning `taskId`; UI uses existing modal patterns (`AdminScriptRunModal` / `Modal` + progress). |
-| Autocomplete refs | **No custom search RPC** — `GET` list on referenced model with search query + small limit. |
-| Recent actions + audit | **Last phase**: optional **`AdminAuditLog`** model + list endpoint + home widget; **`recentActivity` last within the `sidebar` slot** (see home slots below). |
-| Realtime badge | **UI-only** flag from config (`realtime: true`); transport is app-level (polling/socket) out of scope for v1 framework. |
-| Home layout | **Slot-based `home.slots` (Solution A)** — mirrors Django admin template regions so tools/scripts can sit **above** the model grid without being “just another card”. See **Django layout mapping** below. |
-
-### Django layout mapping (reference)
-
-Stock Django `admin/index.html` splits the page into template **blocks**, not a flat widget list: main **`content`** is the app/model list (`app_list`); **`sidebar`** is “Recent actions” only; **`nav-global`** in `base.html` is an empty hook used for global shortcuts (e.g. scripts, reports) in the header row. Custom index pages inject markup **before** `app_list` by overriding `index_template` / `{% block content %}`. Terreno encodes the same idea in **`GET /admin/config`** as named **slots**, each an ordered list of **widget ids** resolved by a built-in + plugin registry.
-
-### `home.slots` contract (canonical)
-
-```typescript
-// Conceptual shape — exact TypeScript lives in admin-backend / shared types.
-home: {
-  title: string;
-  slots: {
-    navGlobal?: string[];   // Django nav-global analogue: compact header strip (e.g. scriptRunner shortcuts)
-    contentTop?: string[];  // Django “inject before app_list”: full-width row above model cards
-    main?: string[];        // Primary column: modelStats, modelsGrid, plugin widgets, etc.
-    sidebar?: string[];     // Django index sidebar: versionConfig, scriptRunner panel, recentActivity, …
-  };
-};
-```
-
-- **`scriptRunner`** (or any custom widget id) in **`navGlobal`** → horizontal tools, never mixed into the model card grid.
-- Same id in **`contentTop`** → prominent band **above** `main`.
-- **`recentActivity`** belongs in **`sidebar`** when used; it must be **last in `sidebar`** if present (Django keeps recent actions in the sidebar column, below other sidebar content you add).
-- Omitted slots render nothing. **`main`** default for backward compat: treat as `["modelsGrid"]` when `schemaVersion >= 2` and `slots` missing but legacy `widgets[]` exists — implementation detail for migration.
-
-## Architecture
-
-```
-Browser (admin-spa / embedded admin-frontend)
-    │
-    ├─ GET /admin/config          ← aggregated model meta + home + screens + scripts
-    │
-    ├─ CRUD  /admin/{resource}/*  ← modelRouter per registered model (IsAdmin)
-    │
-    ├─ POST /admin/{resource}/bulk-patch
-    │
-    └─ POST /admin/background-tasks  → BackgroundTask queue → progress poll/subscribe (app-defined)
-```
-
-Plugin screens (**Documents**, **AI requests**) remain **routes owned by** `@terreno/document-storage` / `@terreno/ai`; config only exposes **navigation entries** (`customScreens[]`).
-
-## Models
-
-Domain models in the prototype are **illustrative** (FeatureFlag, CompanyOrganization, DotPhrase, ExternalClinician, HealthEvent, InsurancePlan, ReferralMethod, ReferralSource, UserStatus). Implementations in consumer apps register Mongoose models with `AdminApp`. Framework work ensures **metadata** and **routers** support their shapes:
-
-| Model | Key relations | Indexes / notes |
-|-------|----------------|-----------------|
-| FeatureFlag | — | Unique `key`; query fields for list/search; hidden `evaluationCache` optional |
-| CompanyOrganization | — | Name search |
-| ExternalClinician | `organization` → CompanyOrganization | Index `organization` |
-| DotPhrase | — | `delete` permission optional **off** |
-| Others | — | Standard list/query/sort fields per config |
-
-**AdminAuditLog** (Phase last): `verb`, `modelName`, `recordLabel`, `recordId?`, `actorId`, `created`; list for home widget; optional TTL index for retention.
-
-**BackgroundTask**: use existing `@terreno/api` type used by `AdminApp` / scripts — no new model if already sufficient; document enqueue contract in OpenAPI.
-
-## APIs
-
-### CRUD (per registered model)
-
-- `POST /admin/{resource}` — create  
-- `GET /admin/{resource}` — list (pagination, sort, queryFields filters)  
-- `GET /admin/{resource}/:id` — read  
-- `PATCH /admin/{resource}/:id` — update (strip readonly server-side)  
-- `DELETE /admin/{resource}/:id` — delete or **disabled** when permissions say so  
-
-All **`Permissions.IsAdmin`** (or stricter consumer override).
-
-### Custom (Action Decision Gate — approved)
-
-| Endpoint | Purpose |
-|----------|---------|
-| `GET /admin/config` | **Aggregation** of models, fields, UI hints, scripts, screens, **`home.slots`** (widget ids per region) |
-| `POST /admin/{resource}/bulk-patch` | **Command + performance**: multi-row patch, cap ids, single audit hook |
-| `POST /admin/background-tasks` | **Command**: enqueue long-running admin job tied to selection |
-
-### Rejected custom routes
-
-| Idea | Fallback |
-|------|----------|
-| Dedicated ref `/search` RPC | `GET` list + query |
-| WebSocket as “admin action” | App transport; REST remains SoT |
-
-## Notifications
-
-- **In-app only:** `@terreno/ui` **Toast** after save, bulk action, enqueue background task, script completion.  
-- **No email/push** for admin events in this IP.
-
-## UI
-
-- **Shell:** `Box` / `Page`, grouped sidebar (`Text` section headers, `Button` / `IconButton`, `Avatar`), sticky top bar with breadcrumbs (`Heading`, `Link`).  
-- **Home:** Render in order: **`navGlobal` + `contentTop` merged into one horizontal top band** (same flex row, wrapping) → two-column **`main`** + **`sidebar`** (Terreno `Box` / `SplitPage`-style layout). Each slot iterates widget ids from `home.slots`; **`recentActivity` last inside `sidebar`** when present.  
-- **List:** `DataTable`, `Pagination`, `TextField` (debounced search), filter rail (`Card` + fields) or chip mode (`SelectField` / date inputs), row selection, bulk `SelectField` + `Modal` confirms, inline boolean via PATCH.  
-- **Form:** `Accordion` or stacked `Card` for fieldsets; `TextField`, `NumberField`, `BooleanField`, `SelectField`, `DateTimeField`; readonly fields disabled + helper copy; ref picker = debounced list fetch.  
-- **Danger zone:** `Button` destructive + `Modal`; **hidden** when delete permission false.  
-- **Background run:** `Modal` + `Spinner` + log `Text` (reuse `AdminScriptRunModal` patterns).  
-- **testIDs:** `admin-home`, `admin-home-slot-top` (combined `navGlobal` + `contentTop` widgets), `admin-home-slot-main`, `admin-home-slot-sidebar`, `admin-list-{model}`, `admin-form-{model}`, `filter-{field}`, `bulk-action`, `widget-recent-activity` (last in **sidebar** slot).
-
-## Phases
-
-1. **Backend contracts** — extend config response; bulk-patch; background enqueue; OpenAPI + tests.  
-2. **CRUD parity** — ensure each registered model’s `queryFields`, sort, response stripping align with config lists.  
-3. **Frontend shell + list + form** — consume v2 config; `DataTable` list; form fieldsets/readonly/autocomplete.  
-4. **Home widgets** — registry + **`home.slots`** layout + plugin widget IDs + placement (`navGlobal` and `contentTop` render in one top row; `main` vs `sidebar`).  
-5. **admin-spa + example** — runnable demo; link plugin screens.  
-6. **Audit log & recent actions (last)** — `AdminAuditLog` model (if approved for deployment), logging hooks, `GET` list, wire **`recentActivity` as the final id in `home.slots.sidebar`**.
-
-### Phase completion (all shipped)
-
-| # | Scope | Evidence |
-|---|--------|----------|
-| 1 | Config + OpenAPI for `/admin/config` | `admin-backend/src/adminApp.models.test.ts` (`schemaVersion`, `home.slots`, scripts metadata) |
-| 2 | Bulk-patch + background-tasks | Same file + `adminApp.test.ts` |
-| 3 | Example modelRouter alignment | `example-backend/src/server.ts` registrations |
-| 4–6 | Shell, list, form | `admin-frontend` compile + `AdminModelTable.test.tsx`, `AdminModelForm.test.tsx`, `AdminBreadcrumbs.test.tsx` |
-| 7 | Home widgets + slots | `admin-frontend/src/AdminHome.test.tsx` |
-| 8 | admin-spa + example | `admin-spa/app/**`, Playwright `admin-spa/e2e/**` |
-| 9 | Audit + recent activity | `example-backend` `AdminAuditLog` + `onAdminAudit`; `admin-backend` **`AdminApp onAdminAudit`** tests (POST/PATCH/DELETE); `AdminHome.test.tsx` sidebar order |
-
-
-## Feature Flags & Migrations
-
-- **Config `schemaVersion`:** clients switch parsers/layout when `>= 2`.  
-- **No DB migration in framework packages** — consumer apps migrate their own collections.  
-- Optional **feature flag** in consumer: `ADMIN_UI_V2` to toggle layout component root (defer if unnecessary).
-
-## Activity Log & User Updates
-
-- **Deferred to final phase** so list/form/config stabilize first.  
-- On completion: admin mutations optionally write **AdminAuditLog** rows; home **Recent actions** reads latest N.  
-- User-visible copy: past tense verbs (“changed”, “added”, “deleted”) matching prototype semantics.
-
-## Not Included / Future Work
-
-- Full **realtime push** of flag changes to all clients (server fan-out).  
-- **Per-field row inline edit** beyond booleans (e.g. numeric inline).  
-- **Cross-model global search**.  
-- **Export CSV** from changelist.  
-- **Granular admin roles** beyond `IsAdmin`.
-
-## Files to Create / Modify (high level)
-
-| Area | Files (expected) |
-|------|------------------|
-| admin-backend | `src/adminApp.ts` (config shape, bulk route, background enqueue), tests |
-| admin-frontend | `AdminModelTable.tsx`, `AdminModelForm.tsx`, new layout/sidebar modules, `useAdminConfig.tsx`, types |
-| admin-spa | Router screens for home v2, list v2, form v2; SDK regen |
-| api | Only if `BackgroundTask` / OpenAPI helpers need small extensions |
-| docs | This IP + `docs/tasks/admin-ui-v2-django-parity.md` |
-
-## Task List
-
-See **`docs/tasks/admin-ui-v2-django-parity.md`** for the executable, phased checklist (audit log / recent actions **last**).
-
-**Script runner tasks** (same release train): **`docs/tasks/admin-script-runner.md`**.
-
-## Acceptance Criteria (summary)
-
-- [x] `GET /admin/config` returns v2 fields without breaking v1 layout (additive + `schemaVersion`).  
-- [x] `POST .../bulk-patch` rejects >1000 ids and unknown patch keys.  
-- [x] Background enqueue returns task id; admin UI shows progress path consistent with scripts.  
-- [x] List: search debounced; filters typed; sort allowlist enforced server-side.  
-- [x] Form: readonly fields cannot be persisted via PATCH.  
-- [x] Delete UI absent when model `delete` permission disabled.  
-- [x] Home: `home.slots` drives layout; `scriptRunner` (or custom tools) in `navGlobal` or `contentTop` never appears inside the **`main`** model grid unless also listed under `main`.  
-- [x] Home: when `recentActivity` is configured, it is **last in `slots.sidebar`**.  
-- [x] Phase last: audit entries created for configured mutations; recent widget shows data from API.
-
-Verification pointers: `admin-backend/src/adminApp.models.test.ts` (config `schemaVersion`, bulk-patch caps/allowlist, background-tasks, **`AdminApp onAdminAudit`** hooks after POST/PATCH/DELETE), `admin-frontend/src/AdminModelForm.test.tsx` (readonly PATCH body), `admin-frontend/src/AdminHome.test.tsx` (slot/widget placement + sidebar order), `example-backend` admin registration + audit model + OpenAPI snapshot.