@terreno/mcp 58.0.0-beta.2 → 58.0.0-beta.4

package/dist/docs/versioned/57.22.0/tasks/model-router-mcp.md

@@ -0,0 +1,105 @@
+# Tasks: modelRouter MCP Tools
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+---
+
+### Phase 1: Core MCP Infrastructure
+
+- [x] **Task 1.1**: Define MCP types and interfaces
+  - Description: Create `MCPConfig` interface (with `methods` defaulting to `['list', 'read']`, `excludeFields` for hiding sensitive fields, `maxLimit` defaulting to 50), `MCPRegistryEntry`, and add `mcp?: MCPConfig` to `ModelRouterOptions`. Create the `api/src/mcp/` directory structure.
+  - Files: `api/src/mcp/types.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (add mcp to ModelRouterOptions)
+  - Depends on: none
+  - Acceptance: Types compile, existing tests still pass, `mcp` is an optional field on `ModelRouterOptions`
+
+- [x] **Task 1.2**: Build MCP tool registry
+  - Description: Create a global registry that collects MCP tool entries as `modelRouter()` is called. When a modelRouter has `mcp` config, it pushes an entry to the registry. Export `getMCPRegistry()` from `@terreno/api`. Vercel AI SDK wrapping lives in `getMCPTools()` on `@terreno/ai`.
+  - Files: `api/src/mcp/registry.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (register in modelRouter function)
+  - Depends on: Task 1.1
+  - Acceptance: Calling `modelRouter(Todo, { ..., mcp: { methods: ['list', 'read'] } })` adds entries to the registry. `getMCPRegistry()` returns those entries.
+
+- [x] **Task 1.3**: Generate Zod schemas from Mongoose models
+  - Description: Build a utility that converts a Mongoose model's schema into Zod schemas suitable for MCP tool `inputSchema`. Handle common field types (String, Number, Boolean, Date, ObjectId, Array, Mixed). Generate separate schemas for create (required fields), update (all optional + id required), read (id + optional populate), list (queryFields + pagination), and delete (id only). Respect `excludeFields` — omit listed fields from all generated schemas.
+  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Given a Mongoose model, produces valid Zod schemas for each CRUD method. Tests cover all common field types. `excludeFields` removes specified fields from schemas.
+
+- [x] **Task 1.4**: Generate MCP tool definitions from registry entries
+  - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel AI SDK (`ai`) `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
+  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
+  - Depends on: Task 1.2, Task 1.3
+  - Acceptance: Registry entry with `methods: ['list', 'read']` produces exactly `todos_list` and `todos_read` tools with correct schemas and descriptions.
+
+- [x] **Task 1.5**: Implement MCP tool handlers (CRUD execution)
+  - Description: Build the execute functions for each CRUD tool. Each handler: (1) extracts user from auth context, (2) checks permissions via `checkPermissions()`, (3) for read/update/delete: loads document and checks object-level permissions, (4) applies queryFilter and population for list, (5) enforces `maxLimit` cap on list results (default 50), (6) runs pre/post hooks, (7) strips `excludeFields` from response data, (8) serializes via `mcpResponseHandler` or default. Reuse internal logic from REST handlers but decoupled from Express req/res.
+  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/handlers.test.ts`
+  - Depends on: Task 1.4
+  - Acceptance: Each CRUD handler works with correct permission checks, population, filtering. List enforces maxLimit. excludeFields are stripped from responses. Tests cover: successful CRUD, permission denied (403), not found (404), validation errors, owner filtering, population, maxLimit enforcement, excludeFields stripping.
+
+- [x] **Task 1.6**: Auth-agnostic user extraction for MCP
+  - Description: Build middleware/utility that extracts user from MCP transport headers using whichever auth provider is configured (JWT via passport or Better Auth via `auth.api.getSession()`). Should mirror `authenticateMiddleware` behavior but work with raw headers instead of Express req.
+  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Given headers with a valid JWT, returns User. Given headers with a valid Better Auth session token, returns User. Given no/invalid headers with `allowAnonymous: false`, returns null. Works with both auth providers.
+
+- [x] **Task 1.7**: Mount MCP server in TerrenoApp
+  - Description: In `TerrenoApp`'s startup flow, check if the MCP registry has any entries. If so, create an `McpServer` instance from `@modelcontextprotocol/sdk`, register all tools from the registry, set up `StreamableHTTPServerTransport`, and mount on `/mcp`. Wire up `ListToolsRequestSchema` and `CallToolRequestSchema` handlers.
+  - Files: `api/src/mcp/server.ts`, `api/src/expressServer.ts` (or TerrenoApp equivalent — integrate into startup)
+  - Depends on: Task 1.4, Task 1.5, Task 1.6
+  - Acceptance: Starting a TerrenoApp with MCP-configured models auto-mounts `/mcp`. MCP clients can list tools and call them. No MCP config = no `/mcp` endpoint.
+
+- [x] **Task 1.8**: Integration tests
+  - Description: End-to-end tests that spin up a TerrenoApp with MCP-configured models and test the full flow: MCP client connects, lists tools, performs CRUD via tool calls, verifies permissions block unauthorized access, verifies population and query filtering work.
+  - Files: `api/src/mcp/integration.test.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Full CRUD lifecycle works over MCP. Permission denials return appropriate errors. Owner filtering restricts results. Population returns nested data.
+
+- [x] **Task 1.9**: Export public API
+  - Description: Export `MCPConfig` and MCP registry/server helpers from `@terreno/api`. Export `getMCPTools()` from `@terreno/ai` so the Vercel AI SDK (`ai`) stays out of `@terreno/api`.
+  - Files: `api/src/index.ts`, `ai/src/index.ts`, `ai/src/service/getMCPTools.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Consumers can `import { MCPConfig } from "@terreno/api"` and `import { getMCPTools } from "@terreno/ai"`.
+
+---
+
+### Phase 2: Frontend Integration
+
+- [x] **Task 2.1**: `useTerrenoChat` hook
+  - Description: Create a hook wrapping `@ai-sdk/react`'s `useChat()` pre-configured for a Terreno MCP backend. Handles Bearer token injection from auth state (reads from Redux store — JWT token or Better Auth session). Accepts `baseURL` and optional `tools` override.
+  - Files: `rtk/src/useTerrenoChat.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Hook connects to MCP-enabled backend, streams responses with tool calls, injects auth token automatically.
+
+- [x] **Task 2.2**: `useMCPTools` hook
+  - Description: Create a hook that discovers available MCP tools from the backend via JSON-RPC call to /mcp endpoint. Caches result. Returns typed tool list.
+  - Files: `rtk/src/useMCPTools.ts`
+  - Depends on: Task 1.7
+  - Acceptance: Hook returns list of available tools with names, descriptions, and input schemas. Handles connection errors gracefully.
+
+- [x] **Task 2.3**: Export frontend public API
+  - Description: Export `useTerrenoChat` and `useMCPTools` from `@terreno/rtk`. Add `@ai-sdk/react` and `ai` as dependencies.
+  - Files: `rtk/src/index.ts`, `rtk/package.json`
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: Consumers can `import { useTerrenoChat, useMCPTools } from "@terreno/rtk"`.
+
+---
+
+### Phase 3: Examples & Polish
+
+- [x] **Task 3.1**: Add MCP config to example backend models
+  - Description: Add `mcp` config to the existing Todo and User models in `example-backend`. Todos: read-only (`list`, `read`) with excludeFields. Users: read-only (`list`, `read`) with sensitive fields excluded.
+  - Files: `example-backend/src/api/todos.ts`, `example-backend/src/api/users.ts`
+  - Depends on: Task 1.9
+  - Acceptance: Starting example-backend mounts `/mcp` with todo and user tools. MCP client can list and call them.
+
+- [x] **Task 3.2**: Demo chat screen in example frontend
+  - Description: Add a simple chat screen to `example-frontend` that uses `useTerrenoChat()` to connect to the MCP-enabled backend. Show tool calls inline (e.g., "Searching todos..." with results). Navigation from home screen.
+  - Files: `example-frontend/app/chat.tsx`, `example-frontend/app/_layout.tsx` (add nav)
+  - Depends on: Task 2.3, Task 3.1
+  - Acceptance: User can chat with the AI, which calls MCP tools to query/modify data. Tool calls and results visible in the UI.
+
+- [x] **Task 3.3**: Refine auto-generated tool descriptions
+  - Description: Improve description generation quality. Include field types, required vs optional, enum values, ref model names. Test with multiple model shapes to ensure descriptions are helpful for LLMs.
+  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
+  - Depends on: Task 1.4
+  - Acceptance: Descriptions include actionable detail. LLM can understand what each tool does and what inputs are expected without additional context.

package/dist/docs/versioned/57.22.0/testing/e2e/admin-backend.md

@@ -0,0 +1,71 @@
+# @terreno/admin-backend e2e tests
+
+Run the admin-backend smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd admin-backend smoke   # or, from the root: bun run smoke admin-backend
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `/admin/config` metadata, admin CRUD, row scope, text search, list filters, bulk actions, migrations, scripts, sync meta, document storage, and the HTTP goldens through supertest against in-memory Mongo (`src/**/*.test.ts`) | `bun run --cwd admin-backend test` |
+| Smoke | The compiled `AdminApp` mounted in a real `TerrenoApp`, serving real HTTP from a child process | `bun run --cwd admin-backend smoke` |
+| E2E | The admin panel in Chromium (home, tables, forms, search, bulk actions, custom screens) through example-frontend's `admin-*.spec.ts` Playwright suite against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`admin-backend/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-backend/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api` and `@terreno/admin-backend` by package name. The
+child builds a `TerrenoApp` with a passport-local user model, one `Widget` model registered
+through `modelRouter("/widgets", Widget, {admin: {...}})`, `new AdminApp({})`, and an inline
+`/health` plugin. It seeds one admin user and one widget, then listens on a `freePort()` against
+`smokeMongoUri()`. The parent waits for `/health` with `spawnUntilReady`, then checks over real
+HTTP:
+
+1. The seeded admin logs in through `POST /auth/login`.
+2. `GET /admin/config` returns the Widget model, found by its `displayName`.
+3. `GET` on that model's `routePath` (`/admin/widgets`) lists the seeded widget.
+4. A user who signs up through `POST /auth/signup` gets 403 from `GET /admin/config`.
+5. The same user gets 405 from `GET /admin/widgets`, modelRouter's permission-denied status.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The model uses the `modelRouter` `admin:` option rather than the legacy
+`AdminApp.models` list, so the smoke also proves that `AdminApp` discovers models registered on
+the app. The admin is seeded straight into MongoDB because signup never grants admin. Each run
+uses new emails and a new widget name, so reruns against a shared `TERRENO_TEST_MONGODB_URI`
+never collide.
+
+Signup logs a `publicAppUrl is required to send verification mail` error in the server
+output. The smoke app does not configure email, and signup still returns 200.
+
+**Measured time:** 8–24 s against an external replica set (passing runs took 7.6, 20.7 and
+23.6 s), excluding the compile. Most of it is loading the compiled packages in the child, which
+alone takes about 6 s. In a container shared with parallel builds and test suites, three other
+runs missed the 30 s readiness timeout before the child answered `/health`. The in-memory
+replica set added about two minutes on that loaded container and then timed out. Budget: 30 s.
+
+If the in-memory replica set times out waiting for a primary, point the smoke at a running
+replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd admin-backend smoke
+```
+
+## Add an e2e test
+
+- **New config field, route, filter, or permission rule:** add a test in
+  `admin-backend/src/`. The smoke stays one happy path; do not add edge cases to it.
+- **The admin read path changed** (for example, the `/admin/config` response shape, the model
+  `routePath` scheme, or how `AdminApp` discovers `modelRouter` models): update the checks in
+  `admin-backend/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible admin flow:** add a Playwright spec next to the `admin-*.spec.ts` files in
+  `example-frontend/e2e/`, following [Write a Playwright spec](../e2e.md#write-a-playwright-spec),
+  against example-backend, which already registers `AdminApp`.
+
+See [the admin-backend reference](../../reference/admin-backend.md) for the plugin API,
+[Add a model to the admin](../../how-to/admin-add-model.md) for the `admin:` option, and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.22.0/testing/e2e/admin-frontend.md

@@ -0,0 +1,79 @@
+# @terreno/admin-frontend e2e tests
+
+Run the admin-frontend smoke after a compile and the admin-spa web export, with Playwright's
+Chromium installed:
+
+```bash
+bun run compile && bun run --cwd admin-spa build:web && bun run --cwd admin-frontend smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Screens, widgets, hooks, and request helpers with `@testing-library/react-native` (`src/**/*.test.ts(x)`), plus the `*.isolated.tsx` files that each need a fresh module registry | `bun run --cwd admin-frontend test` |
+| Smoke | The compiled screens, bundled into the admin-spa web export, rendering AdminHome for a signed-in admin in Chromium against example-backend | `bun run --cwd admin-frontend smoke` |
+| E2E | Admin flows in example-frontend's Playwright suite against example-backend: the home, tables, search and filters, bulk actions, forms, Todo CRUD, custom screens, and the comms dashboard (`example-frontend/e2e/admin-*.spec.ts`) | `bun run frontend:e2e` |
+| E2E (admin-spa) | The same screens inside the standalone SPA: `test:e2e` (mocked backend) and `test:integration` (real backend). See [the admin-spa page](admin-spa.md) | `bun run --cwd admin-spa test:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`admin-frontend/e2e/smoke.spec.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-frontend/e2e/smoke.spec.ts)
+runs at the `browser` layer. admin-frontend ships screens, not a server or a binary, so the
+smoke drives them where a consumer gets them: the admin-spa web export, which bundles the
+compiled package. The one file has two roles.
+
+Run with Bun (`bun e2e/smoke.spec.ts`), it is the driver:
+
+1. It exits 1 at once when `admin-spa/dist/index.html` is missing and asks for `build:web`.
+   It does not check that the export is newer than `admin-frontend/dist`, so rebuild the
+   export after each compile, as the command above does.
+2. `spawnExampleBackend()` starts example-backend against `smokeMongoUri()` with
+   `ADMIN_SPA_ENABLED=true` and `AUTH_PROVIDER=better-auth`, so one origin serves the export
+   at `/console`, Better Auth, and the admin API. The smoke never imports `@terreno/api`.
+3. It seeds the admin in its own process, the way example-backend's
+   `src/scripts/seed-admin-spa-admin.ts` does. It signs `admin-frontend-smoke@example.com` up
+   through Better Auth, calls `/admin/config` once so the session middleware creates the app's
+   `User`, then sets `admin: true` and the `superadmin` role on that `users` document with
+   `mongoose`. A rerun against a persistent `TERRENO_TEST_MONGODB_URI` signs in instead.
+   Running the seed script as a second process cost about 4.5 s, mostly loading the backend's
+   models a second time; seeding in the driver takes under 0.5 s.
+4. It runs the root-locked Playwright CLI on Node against this same file, passing the backend
+   URL in `ADMIN_FRONTEND_SMOKE_BASE_URL`. There is no Playwright config: admin-frontend has
+   no other Playwright suite, so the default Chromium project runs only this spec. If the package
+   gains a `playwright.config.ts`, give the smoke its own config and pass it with
+   `--config`. Traces and screenshots go to a temp dir that the driver deletes.
+
+Loaded by Playwright, the file defines one test. The admin opens `/console/login`, fills
+`admin-spa-login-email` and `admin-spa-login-password`, and presses `admin-spa-login-submit`.
+The test then waits for AdminHome's `admin-home-widget-modelsGrid`, which renders only after
+`/admin/config` answers 200 for an admin, and checks that
+`admin-home-models-grid-Todo-clickable` is visible.
+
+The driver prints one `✅` line per step and exits 1 on the first failure, after printing
+example-backend's output and Playwright's report.
+
+The smoke needs Chromium (`bunx playwright install chromium`) but no secrets: the backend
+uses fixed dev values from `spawnExampleBackend()`.
+
+**Measured time:** 23–24.5 s in three runs on an idle 4-CPU container with the in-memory
+replica set: Mongo and example-backend's first boot on an empty database 16–18 s, the seed
+0.4 s, Chromium 5–6 s, and teardown 1 s. Before the seed moved in-process and
+`spawnExampleBackend()` stopped waiting 5 s on SIGTERM, the same runs took 27–29.5 s. Under
+load the boot stretches: one run that shared four CPUs with several other suites waited 75 s
+for `/health`, so the driver waits up to 120 s. Budget: 30 s, excluding the compile and the web
+export.
+
+## Add an e2e test
+
+- **A screen, widget, or hook changed:** add a unit test next to it in `admin-frontend/src/`.
+  The smoke stays one happy path; do not add edge cases to it.
+- **AdminHome, the models grid, or the admin sign-in contract changed:** update the `testID`s
+  in `admin-frontend/e2e/smoke.spec.ts` and keep it within 30 s.
+- **A user flow through the admin screens** (tables, forms, CRUD): add a spec to
+  `example-frontend/e2e/admin-*.spec.ts` and list it in an admin shard. Follow
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec).
+- **A flow specific to the standalone SPA:** add it to admin-spa's suites.
+
+See [the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.22.0/testing/e2e/admin-spa.md

@@ -0,0 +1,63 @@
+# @terreno/admin-spa e2e tests
+
+Run the admin-spa smoke after a compile and the web export:
+
+```bash
+bun run compile && bun run --cwd admin-spa build:web && bun run --cwd admin-spa smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `AdminSpaServeApp` routing, index rewriting, the base-path global, app-config merging, the dev proxy, and the SPA's store and components (`src/**/*.test.ts(x)`, `store/`, `components/`) | `bun run --cwd admin-spa test:ci` |
+| Smoke | The compiled serve plugin serving the built SPA from a real server in a child process | `bun run --cwd admin-spa smoke` |
+| E2E | `test:e2e`: Chromium against the built SPA on `e2e/serveTestApp.ts`, a backend-free server with mocked Better Auth and `/admin/config`. It covers the login redirect, an admin signing in to AdminHome, and a wrong password showing an error (`e2e/login.spec.ts`) | `bun run --cwd admin-spa test:e2e` |
+| E2E (integration) | `test:integration`: Chromium against example-backend serving the SPA at `/console` with Better Auth and the admin API. It covers sign-in and admin CRUD (`e2e/integration/*.spec.ts`). It needs a running backend with `ADMIN_SPA_ENABLED=true` and a seeded admin; see `playwright.integration.config.ts` | `bun run --cwd admin-spa test:integration` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+CircleCI runs `test:e2e` in `admin-spa-ci` and `test:integration` in `admin-spa-integration`.
+The smoke runs only in the `smoke` job.
+
+## The smoke
+
+[`admin-spa/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-spa/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/admin-spa` by package name, registers `AdminSpaServeApp` on
+a plain Express app at `/console` with a custom `brandName`, and listens on a `freePort()`. The
+plugin serves the export from its default location (`admin-spa/dist`), the path a published
+package uses. The parent waits for `/console/app-config.json` with `spawnUntilReady`, then
+checks over real HTTP:
+
+1. `GET /console/` returns the HTML index with `window.__ADMIN_SPA_BASE__="/console"` injected.
+2. The entry bundle the index names under `/console/_expo/` returns JavaScript.
+3. `GET /console/app-config.json` returns the custom `brandName` merged over the default
+   providers.
+4. A deep route, `GET /console/User/123`, falls back to the same index.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. Without `admin-spa/dist/index.html` it exits 1 at once and asks for
+`build:web`; otherwise the plugin would serve an empty index.
+
+The smoke needs no browser, MongoDB, or secrets. The browser flows belong to `test:e2e` and
+`test:integration`.
+
+**Measured time:** 4–4.5 s in two root `bun run smoke` runs after the build (the
+[guide's](../e2e.md#package-pages) figure), excluding the compile and the web export. Single runs
+took 6–8 s wall clock. Most of it is loading `@terreno/test` and starting the child;
+the checks take well under a second. Budget: 30 s.
+
+## Add an e2e test
+
+- **New serve-plugin option or branch:** add a unit test in `admin-spa/src/serve.test.ts`. The
+  smoke stays one happy path; do not add edge cases to it.
+- **The serving contract changed** (the base-path global, the app-config route, or the SPA
+  fallback): update the checks in `admin-spa/e2e/smoke.ts` and keep it within 30 s.
+- **A screen or flow that needs no real backend:** add a Playwright spec to `admin-spa/e2e/`
+  and extend the mocks in `e2e/serveTestApp.ts`. Follow
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec) for `testID`s and waits.
+- **A flow that needs the real admin API or Better Auth** (CRUD, permissions): add a spec to
+  `admin-spa/e2e/integration/`.
+
+See [the `@terreno/admin-spa` reference](../../reference/admin-spa.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.22.0/testing/e2e/ai.md

@@ -0,0 +1,63 @@
+# @terreno/ai e2e tests
+
+Run the ai smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd ai smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `AIService`, chat turns, asks, blocks, history, files, MCP, Langfuse, and observability routes through supertest with scripted mock models (`src/**/*.test.ts`, `src/isolated/*.isolated.ts`) | `bun run --cwd ai test` |
+| Smoke | The compiled `AiApp` streaming a chat reply from a deterministic fake provider, served by a real server in a child process | `bun run --cwd ai smoke` |
+| E2E | The chat screen seen by a user, through example-frontend's `e2e/ai-chat.spec.ts` against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`ai/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/ai/e2e/smoke.ts) runs
+at the `http` layer. It re-runs itself with a `serve` argument to start a child process that
+imports the compiled `@terreno/api` and `@terreno/ai` by package name. The child builds a
+`TerrenoApp` with a passport-local user model, an inline `/health` plugin, and
+`AiApp({aiService})`, and listens on a `freePort()` against `smokeMongoUri()`. The
+`AIService` wraps a deterministic fake provider: `MockLanguageModelV3` from `ai/test`, which
+streams one fixed reply and answers the title request with one fixed title. The parent starts
+the child with every provider key unset (`GEMINI_API_KEY`, `OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, the Google and Vertex credentials, and the Langfuse keys), so no real
+provider can answer. It waits for `/health` with `spawnUntilReady`, then checks over real
+HTTP:
+
+1. `POST /auth/signup` returns a token.
+2. `POST /gpt/prompt` with that token streams Server-Sent Events whose `text` events join to
+   the fake provider's reply, with no `error` event. The `done` event carries the new
+   conversation's `historyId` and the fake title.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. Matching the fake reply exactly also proves the request did not fall back to
+the canned demo-mode reply that `/gpt/prompt` sends when no AI service resolves.
+
+**Measured time:** 11–29 s against an external replica set while other smokes ran on the same
+4-CPU container, excluding the compile. With the in-memory replica set under the same load,
+startup alone pushed a run past 2 minutes; the api smoke slowed the same way. Budget: 30 s.
+
+If the in-memory replica set is slow or times out waiting for a primary, point the smoke at a
+running replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd ai smoke
+```
+
+## Add an e2e test
+
+- **New route, option, ask kind, or block:** add a test in `ai/src/`, next to the code, with a
+  scripted mock model. The smoke stays one happy path; do not add edge cases to it.
+- **The chat path changed** (for example, the `/gpt/prompt` body or the SSE event shape):
+  update the checks in `ai/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible chat flow** (for example, asks or blocks in `GPTChat`): add a Playwright
+  spec in `example-frontend/e2e/` (or extend `ai-chat.spec.ts`), following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), against example-backend.
+
+See [the ai reference](../../reference/ai.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.22.0/testing/e2e/announcements.md

@@ -0,0 +1,63 @@
+# @terreno/announcements e2e tests
+
+Run the announcements smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd announcements smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Pending and feed selection, audience and platform rules, acknowledgements, impressions, clicks, release import, the admin overview, and help routes through supertest (`src/tests/*.test.ts`) | `bun run --cwd announcements test` |
+| Smoke | The compiled plugin publishing an announcement and serving it to a signed-in user from a real server in a child process | `bun run --cwd announcements smoke` |
+| E2E | None yet. example-frontend has no Playwright spec for announcements | none |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`announcements/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/announcements/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api` and `@terreno/announcements` by package name. The
+child builds a `TerrenoApp` with a passport-local user model, an inline `/health` plugin, and
+`AnnouncementsApp` with an `uploadToken`, and listens on a `freePort()` against
+`smokeMongoUri()`. The parent waits for `/health` with `spawnUntilReady`, then checks over
+real HTTP:
+
+1. `POST /announcements/import-release` with the upload token and `publish: true` returns one
+   published announcement.
+2. `POST /auth/signup` returns a token for a new, non-admin user.
+3. `GET /announcements/feed` with that token lists the announcement with its title.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The announcement is created through release import, the route release
+pipelines call, because signup never grants admin. Creating it through the admin CRUD routes
+would mean seeding an admin straight into MongoDB. Each run imports under a new release
+version, so reruns against a shared `TERRENO_TEST_MONGODB_URI` never collide.
+
+**Measured time:** 4.5–8 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. Earlier single runs took
+21–24 s on a quiet 4-CPU container against an external replica set, and 40–100 s when parallel builds starved the CPU, excluding the compile. Most of it is loading
+the compiled packages in the child; under load, password hashing on signup alone took 17 s.
+Budget: 30 s.
+
+If the in-memory replica set times out waiting for a primary, point the smoke at a running
+replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd announcements smoke
+```
+
+## Add an e2e test
+
+- **New route, option, or visibility rule:** add a test in `announcements/src/tests/`. The
+  smoke stays one happy path; do not add edge cases to it.
+- **The publish-to-feed path changed** (for example, the import body or the feed response
+  shape): update the checks in `announcements/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, the announcement modal or the changelog feed): add a
+  Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), against example-backend, which
+  already registers the plugin.
+
+See [the announcements reference](../../reference/announcements.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.22.0/testing/e2e/api-health.md

@@ -0,0 +1,54 @@
+# @terreno/api-health e2e tests
+
+Run the api-health smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd api-health smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `HealthApp` options and branches (custom path, `enabled: false`, sync, async, failing, and throwing checks) through supertest (`src/healthApp.test.ts`) | `bun run api-health:test` |
+| Smoke | The compiled plugin answering health checks from a real server in a child process | `bun run --cwd api-health smoke` |
+| E2E | The plugin as example-backend registers it, with a MongoDB check. Client smokes that start example-backend (`spawnExampleBackend`) wait on its `/health`, and example-frontend's Playwright suite runs against that backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`api-health/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/api-health/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api-health` by package name, registers `HealthApp` on a
+plain Express app the way `TerrenoApp.register` does, and listens on a `freePort()`. It
+registers the plugin twice: once with defaults, and once at `/health/down` with a `check` that
+reports a dependency down. The parent waits for `/health` with `spawnUntilReady`, then checks
+over real HTTP:
+
+1. `GET /health` returns 200 with `{healthy: true}`.
+2. `GET /health/down` returns 503 with `healthy: false` and the check's `details`.
+
+The 503 is part of the happy path for this plugin: it is the status load balancers and Cloud
+Run probes act on. It prints one `✅` line per check and exits 1 on the first failure, after
+printing the server's output. A compiled plugin patched to always answer 200 fails check 2. A
+default route that stops answering 2xx shows up as a `spawnUntilReady` timeout, not as check 1.
+
+The smoke uses no `TerrenoApp`, so it needs no user model, MongoDB, or secrets. That also keeps
+it free of dependencies api-health does not already declare.
+
+**Measured time:** 2 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. A single run that also loads
+`@terreno/test` cold took about 8 s on an idle machine and 11–20 s under load. Budget: 30 s.
+
+## Add an e2e test
+
+- **New option or branch:** add a unit test in `api-health/src/healthApp.test.ts`. The smoke
+  stays one happy path; do not add edge cases to it.
+- **The wire contract changed** (the status codes or the `{healthy, details}` body): update the
+  checks in `api-health/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, an app screen that reports service health): add a
+  Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), with the plugin wired into
+  example-backend.
+
+See [the `@terreno/api-health` reference](../../reference/api-health.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.22.0/testing/e2e/api.md

@@ -0,0 +1,48 @@
+# @terreno/api e2e tests
+
+Run the api smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd api smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `modelRouter`, permissions, auth, sync, and plugins through supertest against in-memory Mongo (`src/**/*.test.ts`) | `bun run api:test` (`bun run --cwd api test:coverage` adds the 95% gate) |
+| Smoke | The compiled package serving real HTTP from a child process | `bun run --cwd api smoke` |
+| E2E | api behavior seen by a user, through example-frontend's Playwright suite against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`api/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/api/e2e/smoke.ts) runs
+at the `http` layer. It re-runs itself with a `serve` argument to start a child process that
+imports the compiled `@terreno/api`, builds a `TerrenoApp` with a passport-local user model,
+one owner-scoped `modelRouter` model (`/widgets`), and an inline `/health` plugin, and listens
+on a `freePort()` against `smokeMongoUri()`. The parent waits for `/health` with
+`spawnUntilReady`, then checks over real HTTP:
+
+1. `GET /health` returns `{healthy: true}`.
+2. `POST /auth/signup` returns a token.
+3. `POST /widgets` with that token returns 201 and a widget owned by the new user.
+4. `GET /widgets` lists the widget.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The health route is inline because `@terreno/api-health` depends on
+`@terreno/api`.
+
+**Measured time:** 5–10 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. Single runs took 13 s on an
+idle machine and 16–26 s under load.
+Budget: 30 s.
+
+## Add an e2e test
+
+- **New route or option behavior:** add a unit test in `api/src/`. The smoke stays one happy
+  path; do not add edge cases to it.
+- **The smoke's happy path changed** (for example, signup or the list response shape): update
+  the checks in `api/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow:** add a Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), with the route wired into
+  example-backend.

package/dist/docs/versioned/57.22.0/testing/e2e/blocks.md

@@ -0,0 +1,53 @@
+# @terreno/blocks e2e tests
+
+Run the blocks smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd blocks smoke   # or, from the root: bun run smoke blocks
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Ask and block schemas, parsing (whole and partial), lint, validation and its error codes, the prompt sections, plain text, JSON Schemas, and `runBlocksCli` in-process, against the fixtures in `src/fixtures/` and `src/asks/fixtures/` (`src/**/*.test.ts`) | `bun run blocks:test` |
+| Smoke | The compiled `terreno-blocks` binary validating documents in a real process | `bun run --cwd blocks smoke` |
+| E2E | Rendering blocks and asks in GPTChat belongs to `@terreno/ui` and example-frontend's Playwright suite (`ai-chat.spec.ts`) | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`blocks/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/blocks/e2e/smoke.ts)
+runs at the `process` layer. It resolves `@terreno/blocks` by package name, reads the `bin`
+field of that package's `package.json`, and runs the `terreno-blocks` entry it names
+(`dist/cli.js`) with `runBin`, the way a consumer's package manager links it. It writes two
+YAML documents to a temp dir and checks:
+
+1. `terreno-blocks validate valid.yaml` exits 0 with no output. The document is a `text` block
+   and an `actions` block with a `reply` button.
+2. `terreno-blocks validate invalid.yaml` exits non-zero and prints a line naming
+   `blocks[0].markdown` and `MISSING_REQUIRED`. The document is a `text` block with no
+   `markdown`.
+
+It prints one `✅` line per check and exits 1 on the first failure, with the binary's stdout
+and stderr. A compiled CLI that stops failing on validation errors fails check 2. A `bin` entry
+that points at a missing file fails check 1. The smoke needs no Mongo, network, or server.
+
+**Measured time:** 1–2 s for the two checks and about 5 s for `bun run --cwd blocks smoke` end
+to end, excluding the compile. One root `bun run smoke blocks` run under load from parallel
+builds took 25 s. Budget: 30 s.
+
+## Add an e2e test
+
+- **New block type, field, limit, or error code:** add fixtures under `blocks/src/fixtures/`
+  and unit tests next to the code, as the
+  [block documents reference](../../reference/blocks.md) describes. The smoke stays one valid
+  and one invalid document; do not add edge cases to it.
+- **The CLI's contract changed** (a new subcommand, the output format, or the exit codes):
+  update `runBlocksCli` tests in `blocks/src/cli.test.ts`, then the checks in
+  `blocks/e2e/smoke.ts`.
+- **A user-visible rendering flow:** add a Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec).
+
+See [the `terreno-blocks` CLI reference](../../reference/blocks.md#cli) and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for `runBin`.