@terreno/mcp 57.19.2 → 57.21.0

package/dist/docs/versioned/57.2.0/implementationPlans/migrate-cicd-to-circleci.md

@@ -1,269 +0,0 @@
-# Implementation Plan: Migrate CI/CD to CircleCI
-
-**Status:** In progress — Phase 1–3 CI config landed (deploys deferred per request)  
-**Discussion:** _(none)_  
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
-**Linear:** _(none)_  
-**Priority:** High  
-**Effort:** Large (cross-cutting infra; many workflows)  
-**Owner:** unassigned (CircleCI org/plan: requester)  
-**Created:** 2026-08-17  
-**Branch:** `cursor/migrate-cicd-circleci-2b6d`  
-**Research:** [`migrate-cicd-to-circleci-research.md`](migrate-cicd-to-circleci-research.md)  
-**Depends on:** CircleCI org + paid plan created by requester; GCP project access for OIDC terraform  
-
-## Goal
-
-Move Terreno’s CI/CD from GitHub Actions to CircleCI end-to-end: every pipeline that builds, tests, deploys, publishes, or gates PRs runs on CircleCI. Use a dual-run cutover (GHA stays required until the matching CircleCI workflow is green, then delete the GHA workflow). End state: no `.github/workflows/*.yml` CI/CD jobs remain; GitHub keeps only what CircleCI cannot replace (if any residual is accepted, document it explicitly under Not Included).
-
-## Non-Goals
-
-- Changing what tests assert (only where they run), except for runner-parity fixes.
-- Migrating sibling repos (Flourish, Zapling, etc.).
-- Redesigning product deploy topology (Cloud Run / Netlify / EAS stay; only the orchestrator changes).
-- Shipping Appium **iOS** on CircleCI in **v1** (deferred to a late phase; Android Appium may move earlier if ubuntu parity is easy).
-- Rewriting gh-aw agentic *prompt* content; only re-home or replace the *runner*.
-
-## Decisions
-
-Recorded 2026-08-17 from Blend clarification.
-
-| # | Question | Decision |
-|---|----------|----------|
-| CC1 | Scope | **A — Full cutover.** All CI/CD moves to CircleCI; GHA workflows deleted after dual-run proves green. |
-| CC2 | Cutover style | **A — Dual-run.** Keep GHA required checks until the CircleCI twin is trusted, then remove GHA. |
-| CC3 | v1 must include | **GCP CD + terraform**, **npm publish-on-tag**, **Netlify** (demo / example-frontend / docs), **EAS PR + fingerprint gate**. Not Appium iOS in v1. |
-| CC4 | CircleCI account | Requester creates the CircleCI plan/org and links the GitHub repo. |
-| CC5 | Branch protection | Remapping required checks is in scope; maintainers apply GitHub settings when CircleCI check names are stable. |
-| CC6 | Config shape | **A — Dynamic config** (`setup: true`) + **path-filtering** orb. |
-
-## Architecture
-
-### Target topology
-
-```mermaid
-flowchart TB
-  subgraph gh [GitHub]
-    PUSH[push / PR / tag / schedule]
-    BP[branch protection required checks]
-  end
-
-  subgraph cci [CircleCI]
-    SETUP[setup workflow path-filtering]
-    CONT[continue config]
-    PKG[package CI + policy]
-    E2E[Playwright e2e]
-    NET[Netlify deploys]
-    EAS[EAS + fingerprint]
-    GCP[GCP CD via OIDC]
-    PUB[npm publish on tag]
-    MOB[Appium / Maestro late phase]
-    REP[replacements: CodeQL alt, bots, triage]
-  end
-
-  PUSH --> SETUP --> CONT
-  CONT --> PKG & E2E & NET & EAS & GCP & PUB & MOB & REP
-  PKG & E2E & EAS --> BP
-  GCP --> CR[Cloud Run / Artifact Registry / Infra Manager]
-  NET --> NL[Netlify sites]
-  PUB --> NPM[npmjs @terreno/*]
-  EAS --> EXPO[EAS Cloud]
-```
-
-### Config layout
-
-```
-.circleci/
-  config.yml              # setup: true — path-filtering only
-  continue-config.yml     # all real workflows/jobs
-  src/                    # optional: generated fragments if we split by package
-```
-
-- Use `circleci/path-filtering` to set boolean parameters (`run-api`, `run-ui`, `run-cd`, …) from changed paths (mirror today’s path filters).
-- Use `circleci/node` orb (≥7.2.0) for Bun install + cache (`pkg-manager: bun`).
-- Shared commands: `bun_install`, `start_mongo` (Docker service or `cimg` + mongo service), `compile_workspace_deps`.
-- Prefer a **private org orb** later for reuse; v1 may inline commands in `continue-config.yml` to ship faster, then extract.
-
-### Secrets: CircleCI Contexts
-
-| Context | Contents (from current GHA) |
-|---------|------------------------------|
-| `terreno-npm` | `NPM_TOKEN` |
-| `terreno-netlify` | `NETLIFY_AUTH_TOKEN`, site IDs |
-| `terreno-expo` | `EXPO_TOKEN` |
-| `terreno-gcp` | CircleCI OIDC (no long-lived key for CD); migrate `GCP_SA_KEY` off preview-cleanup onto OIDC |
-| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` |
-| `terreno-release` | `REPO_ADMIN_TOKEN`, `ZOOM_WEBHOOK_URL`, `ZOOM_WEBHOOK_TOKEN` |
-| `terreno-agentic` | `CURSOR_API_KEY` (and replacements for Copilot/gh-aw tokens if re-homed) |
-| `terreno-github-api` | PAT with `pull-requests`, `deployments`, `contents` as needed for comments / Deployments API / roadmap |
-
-Restrict context access by project + environment (e.g. `release` context only on tag workflows).
-
-### GCP identity (blocking infra for Phase GCP)
-
-Today `terraform/modules/github_oidc` trusts **only** `https://token.actions.githubusercontent.com`. CircleCI CD requires:
-
-1. New Workload Identity pool provider for CircleCI’s OIDC issuer.
-2. Attribute condition on org/project/VCS origin.
-3. Bind `roles/iam.workloadIdentityUser` for deployer + terraform SAs.
-4. Dual-trust during dual-run (GitHub + CircleCI providers both valid), then remove GitHub provider when GHA CD is deleted.
-
-Prefer extending the module (`circleci_oidc` or rename to `ci_oidc` with multiple providers) over a one-off in Flourish terraform only — keep consumer docs honest.
-
-### GitHub ↔ CircleCI integration
-
-- CircleCI GitHub App (or OAuth) on `TerrenoLabs/terreno`.
-- Status checks reported to GitHub for branch protection (job names documented in `docs/explanation/repository-settings.md`).
-- PR comments / labels / Deployments API: call GitHub REST via `gh` or `curl` with `terreno-github-api` context (replaces `GITHUB_TOKEN` action privileges).
-- Tag + schedule triggers: CircleCI pipeline triggers (or GitHub → CircleCI API webhook) for cron jobs currently on GHA.
-
-### Dual-run protocol (every phase)
-
-1. Land CircleCI twin; name check `cci/<old-job-name>` or stable CircleCI job name.
-2. Add CircleCI check as **non-required** optional signal; keep GHA required.
-3. Observe green on `master` + representative PRs.
-4. Flip branch protection: require CircleCI; unrequire GHA.
-5. Delete the GHA workflow file in the same PR window as the protection flip (or immediately after).
-6. Never leave tag publish listening on **both** systems.
-
-## Models / APIs / Notifications / UI
-
-None (infra-only). Zoom release notify stays a webhook call from the publish workflow.
-
-## Phases
-
-### Phase 0 — Prerequisites (human + docs)
-
-- Create CircleCI org/plan; link repo; enable dynamic config.
-- Create empty Contexts; document secret migration checklist.
-- Inventory required check names vs today’s GHA job `name:` fields.
-
-### Phase 1 — Foundation
-
-- Add `.circleci/config.yml` + `continue-config.yml` skeleton.
-- Path-filtering parameter map covering all packages + terraform + docs + demo.
-- Shared Bun + cache + Mongo patterns.
-- Smoke workflow on every push that only validates config.
-
-### Phase 2 — Package CI + repo policy (v1)
-
-Port and dual-run:
-
-- `api-ci`, `ai-ci`, `rtk-ci`, `ui-ci`, `ui-demo-ci`, `comms-ci`, `mcp-server-ci`
-- `example-frontend-ci`, `example-backend-ci`, `example-backend-script-runner`, `example-backend-docker`
-- `admin-spa-ci`
-- `repo-policies`, `rulesync-check`, `dco` (DCO via GitHub API + CircleCI)
-
-### Phase 3 — Playwright E2E (v1)
-
-- `e2e-ci`, `admin-spa-integration` (Mongo replica set + secrets context).
-
-### Phase 4 — Netlify deploys (v1)
-
-- `demo-deploy`, `frontend-example-deploy`, `docs-deploy`
-- Recreate preview aliases + optional GitHub Deployments via API.
-- `preview-cleanup` equivalent for Netlify/GCP previews as applicable.
-
-### Phase 5 — EAS + fingerprint (v1)
-
-- Port `eas-pr`, `eas-dev-build`, `fingerprint-gate` scripts under `.circleci/` or keep scripts in `.github/workflows/scripts/` and invoke from CircleCI until relocated to `scripts/ci/`.
-- PR comment + `fingerprint-acknowledged` label via GitHub API.
-
-### Phase 6 — GCP CD + OIDC (v1)
-
-- Terraform: CircleCI OIDC provider + dual-trust.
-- Port `cd.yml` (detect → terraform → backend/mcp deploy).
-- Port `preview-cleanup` onto OIDC (eliminate `GCP_SA_KEY`).
-- Dual-run CD carefully (concurrency: one deployer).
-
-### Phase 7 — npm publish (v1)
-
-- Port `publish-on-tag` + `publish-feature-flags-manual`.
-- **Single-writer rule:** disable GHA tag trigger in the same change that enables CircleCI tag pipeline.
-- Keep Zoom notify + master version bump + docs cut + demo dispatch.
-
-### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
-
-- Maestro (`maestro-e2e`).
-- Appium Android on Linux VM.
-- Appium iOS on CircleCI macOS resource class (image pin parity with `macos-15` intent).
-- Then delete `demo-appium-ci.yml` / `maestro-e2e.yml`.
-
-### Phase 9 — GitHub-native + agentic replacements (full cutover)
-
-| Current GHA | Replacement approach |
-|-------------|----------------------|
-| `codeql-analysis` | CircleCI job uploading SARIF to GitHub Code Scanning API **or** third-party SAST orb; preserve Security tab if possible |
-| `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
-| `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
-| `roadmap-generate` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
-| `architectural-pr-review` | CircleCI job + `CURSOR_API_KEY` (lose `pull_request_target` free fork safety — use least privilege + fork policy) |
-| `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |
-| `docs-audit` | Scheduled CircleCI job |
-
-### Phase 10 — Cleanup + docs
-
-- Delete remaining `.github/workflows/*.yml` (and lock sources if retired).
-- Update `CONTRIBUTING.md`, `docs/explanation/repository-settings.md`, `terraform/README.md`, deploy how-tos, AGENTS.md Cloud CI notes.
-- Archive research; mark IP Complete.
-
-## Feature Flags & Migrations
-
-- No product feature flags.
-- Infra migration: dual OIDC trust window; dual CI check window; **no dual tag-publish**.
-- Secret migration checklist is the migration artifact (Contexts populated before jobs go required).
-
-## Activity Log & User Updates
-
-- Announce in Discord/Slack/Zoom when required checks flip and when tag publish moves.
-- Changelog: under Unreleased chore — “CI/CD runs on CircleCI”.
-
-## Not Included / Future Work
-
-- Private orb publication + versioning pipeline (nice follow-up after Phase 1–2 stabilize).
-- Moving Netlify sites to GCS+CDN (separate deploy architecture IPs).
-- Self-hosted CircleCI runners.
-- Credit-cost optimization beyond path-filtering (test splitting, resource-class tuning).
-
-## Risks & Mitigations
-
-| Risk | Mitigation |
-|------|------------|
-| Double npm publish | Single-writer cutover for tags; disable GHA first or in same commit |
-| GCP deploy from wrong IdP | Dual-trust then remove GitHub provider; dry-run terraform preview on CircleCI first |
-| Branch protection gaps during flip | Document exact check names; flip in a dedicated maintainer window |
-| macOS/Appium flake | Deferred to Phase 8; keep GHA Appium until CircleCI macOS proven |
-| gh-aw feature loss | Phase 9 explicit replace-or-retire decision per lockfile before deleting |
-| Credit burn during dual-run | Path filters; timebox dual-run per phase (target: days, not months) |
-| `mcp-server-ci` still filters `main` | Normalize to `master` while porting |
-
-## Files to Create / Modify
-
-**Create**
-
-- `.circleci/config.yml`
-- `.circleci/continue-config.yml`
-- `docs/how-to/circleci.md` (or `docs/explanation/ci-cd-circleci.md`)
-- `terraform/modules/circleci_oidc/` or extend `github_oidc` → multi-provider `ci_oidc`
-- `scripts/ci/` (relocated EAS/fingerprint helpers)
-
-**Modify**
-
-- `docs/explanation/repository-settings.md`
-- `terraform/README.md`, Flourish/terreno terraform roots that wire OIDC
-- `CONTRIBUTING.md`, root/CI docs references to GitHub Actions
-- Delete `.github/workflows/*` progressively per phase
-
-## Task List
-
-See [`docs/tasks/migrate-cicd-to-circleci.md`](../tasks/migrate-cicd-to-circleci.md).
-
-## Acceptance Criteria
-
-- [ ] All v1 workflows (package CI, policy, Playwright e2e, Netlify, EAS/fingerprint, GCP CD, npm publish) are green on CircleCI and required on `master` where applicable.
-- [ ] Matching GHA workflows for those surfaces are deleted; tag publish has exactly one listener.
-- [ ] CircleCI OIDC can deploy Cloud Run without `GCP_SA_KEY` for CD paths.
-- [ ] Path-filtering skips unrelated package jobs on a docs-only change.
-- [ ] `repository-settings.md` lists CircleCI check names; branch protection matches.
-- [ ] Phase 8–9 either complete (full cutover) or are tracked as blocking follow-ups before calling CC1 done.
-- [ ] CONTRIBUTING / terraform / deploy docs no longer instruct maintainers to use GHA for Terreno CI/CD.

package/dist/docs/versioned/57.2.0/implementationPlans/model-router-mcp.md

@@ -1,187 +0,0 @@
-# Implementation Plan: modelRouter MCP Tools
-
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1092
-*When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
-
-## Overview
-
-Add MCP (Model Context Protocol) tool generation to `@terreno/api`'s `modelRouter`. Each modelRouter can opt-in to exposing its CRUD operations as MCP tools via an `mcp` config option. When models with MCP config are added to `TerrenoApp`, their tools are registered automatically. On server start, if any models have MCP config, a `/mcp` endpoint is auto-mounted — zero extra setup.
-
-This makes every Terreno app instantly AI-native: any model becomes callable by LLMs with the same permission, filtering, and population guarantees as REST.
-
-**Key design decisions:**
-- Safe defaults: `methods` defaults to `['list', 'read']` (read-only), `maxLimit` defaults to 50
-- `excludeFields` allows hiding sensitive/regulated fields from MCP tool schemas and responses
-- MCP config lives on each `modelRouter` call (per-model opt-in)
-- `TerrenoApp` aggregates all MCP-enabled models into a single `/mcp` endpoint
-- `modelRouter` return type is unchanged — MCP registration is a side effect (same pattern as OpenAPI)
-- Auth-agnostic: works with both JWT and Better Auth
-- Tool naming: `{prefix}_list`, `{prefix}_read`, `{prefix}_create`, `{prefix}_update`, `{prefix}_delete`
-- Populate is an option on the read tool, not a separate tool
-- Also exports `getMCPTools()` from `@terreno/ai` returning Vercel `ai` SDK `CoreTool` objects for direct in-process use
-- Custom tools via `registerMCPTool` (example: `users_todo_statuses`)
-
-**Related work:** The `ai-multimodal-tools-mcp` branch has `MCPService` (MCP client) and `AIService` in `@terreno/ai` — that's the consumer of what this plan builds.
-
-## Models
-
-No new Mongoose models or database changes. New TypeScript interfaces added to `@terreno/api`:
-
-### MCPConfig (on ModelRouterOptions)
-
-```typescript
-// api/src/mcp/types.ts
-
-export interface MCPConfig {
-  methods?: Array<'create' | 'list' | 'read' | 'update' | 'delete'>; // Default: ['list', 'read']
-  description?: string;            // Override auto-generated model description
-  toolPrefix?: string;             // Override tool name prefix (default: pluralized model name)
-  excludeFields?: string[];        // Fields to hide from MCP tool schemas and responses
-                                   // e.g. ['internalNote', '__v', 'metadata.secretKey']
-  maxLimit?: number;               // Max items returned by list tool (default: 50)
-  mcpResponseHandler?: (          // MCP-specific serialization (separate from REST responseHandler)
-    value: any,
-    method: 'create' | 'list' | 'read' | 'update' | 'delete',
-    user?: User
-  ) => Promise<JSONValue>;
-}
-
-// Added to existing ModelRouterOptions<T>
-export interface ModelRouterOptions<T> {
-  // ... all existing fields unchanged ...
-  mcp?: MCPConfig;  // NEW — opt-in MCP tool generation
-}
-```
-
-### Internal Registry
-
-```typescript
-// api/src/mcp/registry.ts
-
-interface MCPRegistryEntry {
-  modelName: string;
-  model: Model<any>;
-  config: MCPConfig;
-  options: ModelRouterOptions<any>;  // full router options for permissions, population, etc.
-}
-
-// Global registry — modelRouter() pushes to this when mcp config is present
-// TerrenoApp reads from this on startup
-const mcpRegistry: MCPRegistryEntry[] = [];
-```
-
-## APIs
-
-No new REST endpoints. One MCP protocol endpoint and auto-generated tools.
-
-### MCP Endpoint
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/mcp` | MCP JSON-RPC 2.0 handler via `StreamableHTTPServerTransport` |
-
-Auto-mounted by `TerrenoApp` on startup if any registered models have `mcp` config.
-
-### Auto-generated MCP Tools
-
-For each model with `mcp` config, tools are generated based on `mcp.methods`:
-
-| Tool Name | Generates When | Input Schema | Output |
-|-----------|---------------|--------------|--------|
-| `{prefix}_list` | `'list'` in methods | `{ query?, page?, limit?, sort?, populate? }` | `{ data, total, page, more }` (limit capped at `maxLimit`, default 50) |
-| `{prefix}_read` | `'read'` in methods | `{ id, populate? }` | `{ data }` |
-| `{prefix}_create` | `'create'` in methods | Model fields from Mongoose schema | `{ data }` |
-| `{prefix}_update` | `'update'` in methods | `{ id, ...partial model fields }` | `{ data }` |
-| `{prefix}_delete` | `'delete'` in methods | `{ id }` | `{ success: true }` |
-
-### Auth Flow (per tool call)
-
-1. Extract headers from MCP transport
-2. Call auth provider (JWT or Better Auth) to get user — same logic as `authenticateMiddleware`
-3. Run `checkPermissions()` with the user and method
-4. For read/update/delete: load document, run object-level permission check
-5. Apply `queryFilter` for list operations
-6. Apply `populatePaths` (default) + optional extra `populate` param from tool input
-7. Strip `excludeFields` from response data
-8. Serialize through `mcpResponseHandler` if provided, otherwise default serialization
-
-### Tool Description Auto-generation
-
-Generated from model name, field names/types, and `queryFields`. Example:
-> "List todo items. Filterable by: completed, status, ownerId. Sortable. Paginated (default 50, max controlled by maxLimit)."
-
-`mcp.description` overrides the auto-generated description.
-
-### CoreTool Export
-
-`getMCPTools()` exported from `@terreno/ai` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel `ai` SDK's `streamText()` / `generateText()`.
-
-## Notifications
-
-No notifications required for this feature. This is framework-level infrastructure.
-
-## UI
-
-### RTK Query Hooks (`@terreno/rtk`)
-
-- `useMCPTools()` — returns all available MCP tools from the connected backend via MCP client tool discovery
-- Handles Bearer token injection from auth state (JWT or Better Auth)
-
-### ai SDK React Integration (`@terreno/rtk`)
-
-- `useTerrenoChat({ baseURL, tools? })` — wraps `@ai-sdk/react`'s `useChat()` pre-configured for the Terreno backend's MCP endpoint
-- Streams tool calls and results to the UI
-- Works with React Native (Expo) via existing RTK/Redux store for auth state
-
-### Example App
-
-- Demo chat screen in `example-frontend` showing `useTerrenoChat()` connected to MCP-enabled models
-
-## Phases
-
-### Phase 1: Core MCP Infrastructure (`@terreno/api`)
-- MCP types and config (`MCPConfig`, registry)
-- Tool generation from modelRouter options + Mongoose schema (Zod schemas from model)
-- MCP server setup with `@modelcontextprotocol/sdk` in TerrenoApp
-- Auth-agnostic user extraction from MCP transport headers
-- Permission checking, query filtering, population in tool handlers
-- `getMCPTools()` export for direct CoreTool usage
-- Tests for tool generation, permissions, CRUD operations over MCP
-- **Deliverable:** Any Terreno app can add `mcp` to a modelRouter and get a working `/mcp` endpoint
-
-### Phase 2: Frontend Integration (`@terreno/rtk`)
-- `useTerrenoChat()` hook wrapping `@ai-sdk/react` `useChat()`
-- Auth token injection (JWT + Better Auth)
-- `useMCPTools()` hook for tool discovery
-- **Deliverable:** Frontend can connect to MCP-enabled backend with typed hooks
-
-### Phase 3: Examples & Polish
-- Example backend: add `mcp` config to existing Todo/Food models
-- Example frontend: demo chat screen using `useTerrenoChat()`
-- Auto-generated tool descriptions refinement
-- Documentation in example apps
-- **Deliverable:** Working full-stack demo of AI-native Terreno app
-
-## Feature Flags & Migrations
-
-**Feature flags:** None. MCP is opt-in per model via `mcp` config. No models have it = nothing is mounted. Zero impact on existing apps.
-
-**Data migrations:** None. No schema changes, no new collections.
-
-**Rollout:** Minor version bump of `@terreno/api`. Existing apps upgrade and add `mcp` configs at their own pace. No breaking changes.
-
-## Activity Log & User Updates
-
-No activity logging specific to this feature. MCP tool calls go through the same permission/hook pipeline as REST — any existing `postCreate`/`postUpdate`/`postDelete` hooks fire normally for write operations.
-
-## Not Included / Future Work
-
-- **Rate limiting** — structured for future hooks but not implemented
-- **MCP resources/prompts** — only tools generated from modelRouter plus `registerMCPTool`
-- **Array operation tools** — handled via update, no dedicated push/patch/delete array tools
-- **WebSocket transport** — HTTP/SSE only
-- **Admin dashboard** — use `getMCPTools()` programmatically or MCP client tool listing
-- **Streaming list results** — pagination only
-- **Per-tool rate limiting or cost tracking**
-- **MCP tool versioning**
-- **Auto-generated RTK hooks per model** — codegen from OpenAPI (stretch goal)