@terreno/mcp 57.18.0 → 57.20.0

package/src/docs/versioned/57.1.0/explanation/model-router-actions.md

@@ -1,156 +0,0 @@
-# modelRouter actions
-
-`modelRouter` can register **actions** — named operations at collection or instance scope — alongside standard CRUD. Actions reuse the same permission model, error envelope, and OpenAPI pipeline as CRUD routes, without hand-wiring `endpoints`, `asyncHandler`, and doc loading.
-
-## When to use actions
-
-Use actions when an endpoint performs an operation that is not a plain create/read/update/delete on the model document:
-
-- **Collection scope** (`POST /todos/bulkComplete`) — operate on many documents or the collection as a whole.
-- **Instance scope** (`POST /todos/:id/markComplete`) — operate on one loaded document.
-
-Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) when the URL does not fit the `/:id/{actionName}` or `/{actionName}` pattern.
-
-## Example
-
-```typescript
-import {modelRouter, Permissions, z} from "@terreno/api";
-import {Todo} from "../models";
-
-export const todoRouter = modelRouter("/todos", Todo, {
-  permissions: {
-    create: [Permissions.IsAuthenticated],
-    list: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-    delete: [Permissions.IsOwner],
-  },
-  instanceActions: {
-    markComplete: {
-      method: "POST",
-      permissions: [Permissions.IsOwner],
-      handler: async ({doc}) => {
-        doc.completed = true;
-        await doc.save();
-        return doc;
-      },
-      summary: "Mark a todo complete",
-    },
-  },
-  collectionActions: {
-    bulkComplete: {
-      method: "POST",
-      permissions: [Permissions.IsAuthenticated],
-      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
-      response: z.object({matched: z.number(), modified: z.number()}).strict(),
-      handler: async ({body, user}) => {
-        // updateMany using body.ids and user._id
-      },
-      summary: "Mark multiple todos complete",
-    },
-  },
-});
-```
-
-Use `.strict()` on Zod object schemas when you want unknown JSON keys rejected at runtime. Zod’s default object behavior strips unknown keys.
-
-## Handler context
-
-Handlers receive a single context object:
-
-| Field | Instance | Collection |
-|-------|----------|------------|
-| `req`, `res`, `user` | yes | yes |
-| `doc` | loaded document | — |
-| `body` | parsed body (see below) | parsed body |
-| `query` | parsed query | parsed query |
-
-Return a plain value from the handler; the framework responds with `{data: <value>}` and status `200` (or `action.status` if set). If the handler writes the response itself (`res.json`, streaming), return without relying on auto-wrap — the framework skips wrapping when `res.headersSent` is true.
-
-## Permissions
-
-Each action requires a non-empty `permissions` array (same `PermissionMethod` types as CRUD). An empty array disables the action and returns **405**, matching CRUD.
-
-HTTP method and scope map to a CRUD permission check:
-
-| Scope | GET | POST |
-|-------|-----|------|
-| Instance | `read` | `update` |
-| Collection | `list` | `create` |
-
-**405** — denied before a document is loaded (or on any collection action denial).  
-**403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
-**401** — unauthenticated when a permission requires auth (from existing auth middleware).
-
-`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD.
-
-## Validation
-
-Optional `body` and `query` Zod schemas validate input. On failure the API returns **400** with `title: "Validation failed"` and field errors in `meta.fields`.
-
-Parsed values are passed only through `ctx.body` / `ctx.query`. Express 5 does not allow reassigning `req.query`; do not mutate `req.body` in middleware.
-
-When no `body` or `query` schema is configured, the raw `req.body` / `req.query` are passed through (for manual validation in the handler).
-
-## Document loading (instance actions)
-
-Instance actions load the document by `id` before the handler runs. Missing documents return **404**, including soft-delete metadata when applicable.
-
-`queryFilter` is **not** applied to this load (same as CRUD permission middleware). List filters may hide a document that still exists; post-load permission checks are responsible for access control.
-
-`req.obj` is set to the loaded document for parity with CRUD update/delete handlers.
-
-## OpenAPI and SDK codegen
-
-When `openApi` is configured on the router (automatic with `TerrenoApp` and `setupServer`), each action is documented on first route registration. Operations use:
-
-- **Tag** — model collection name by default; override with `action.tag`.
-- **operationId** — `{tag}_{actionName}` (e.g. `todos_markComplete`) for stable RTK Query hook names after SDK regeneration.
-
-Request/response schemas are derived from Zod when `body`, `query`, or `response` are set. Successful responses are documented as `{data: ...}` to match the wire format.
-
-## Collision detection
-
-At router build time, Terreno rejects:
-
-- Empty action names or names that do not match `/^[A-Za-z][A-Za-z0-9_-]+$/`
-- Instance action names that match a Mongoose array field path (which would collide with `POST /:id/:field` array routes)
-
-Actions are registered before user `endpoints` callbacks, so they take precedence if paths overlap.
-
-## Migrating from `endpoints`
-
-Before (hand-rolled):
-
-```typescript
-endpoints: (router) => {
-  router.post("/generate", [authenticateMiddleware()], asyncHandler(async (req, res) => {
-    // manual admin check, validation, OpenAPI omitted
-    return res.json({data: result});
-  }));
-},
-```
-
-After:
-
-```typescript
-collectionActions: {
-  generate: {
-    method: "POST",
-    permissions: [Permissions.IsAuthenticated],
-    handler: async ({body, user}) => { /* ... */ return result; },
-  },
-},
-```
-
-Remove duplicate `asyncHandler`, `authenticateMiddleware`, and manual `{data: ...}` wrapping unless you need a custom response shape.
-
-## Dependencies
-
-`@terreno/api` lists **`zod` as a peer dependency** (^4.3.x). Applications that define action schemas must install `zod` in the backend project. Import `z` from `@terreno/api` (re-exported after OpenAPI extension) so action Zod schemas work with automatic OpenAPI generation.
-
-`@asteasolutions/zod-to-openapi` is bundled with `@terreno/api` for OpenAPI schema generation.
-
-## Concurrency
-
-Action handlers run the same as other Express handlers — no transactions or locking. Use application-level guards (version fields, idempotency keys) if you need to prevent double-submit races.

package/src/docs/versioned/57.1.0/explanation/modular-api-design.md

@@ -1,228 +0,0 @@
-# Modular API Design
-
-**Status**: 🚧 Planned for v2.0.0
-
-## The Problem
-
-As Terreno has grown, the `setupServer()` function has become increasingly difficult to extend and customize. When setting up new backends, several pain points emerge:
-
-1. **Configuration scattered across environment variables and options** — Some settings come from env vars (tokens, secrets), others from the options object, making it unclear what needs to be configured
-
-2. **All-or-nothing middleware** — Built-in middleware (CORS, body parsing, auth) can't be disabled or customized without editing the framework code
-
-3. **Limited extensibility** — Adding features like an admin panel requires touching multiple places in the middleware stack, making installation instructions tedious and error-prone
-
-4. **No lifecycle hooks** — Can't inject custom logic at precise points in server initialization or request handling
-
-5. **Rigid architecture** — Hard to build modular "apps" (like Django apps) that can be installed with a single call
-
-## The Solution: TerrenoApp
-
-The new `TerrenoApp` class addresses these issues with a **fluent builder API** inspired by Django and modern Node.js frameworks:
-
-``````typescript
-const app = TerrenoApp.create({
-  auth: {
-    userModel: User,
-    token: {secret: process.env.TOKEN_SECRET!, issuer: "myapp"},
-  },
-  middleware: {
-    cors: {enabled: true, origin: ["https://myapp.com"]},
-    helmet: {enabled: true},
-    rateLimit: {enabled: true, max: 100},
-  },
-  health: {
-    enabled: true,
-    check: async () => ({healthy: true, uptime: process.uptime()}),
-  },
-})
-  .addModelRouter("/todos", Todo, {list: [IsAuthenticated]})
-  .addRoute("/webhooks", webhookRouter)
-  .enableWebSocket({path: "/ws"})
-  .start();
-``````
-
-### Key Improvements
-
-#### 1. Configuration over Environment Variables
-
-All settings are explicit options, not env vars. This makes configuration:
-- **Discoverable**: TypeScript autocomplete shows all available options
-- **Testable**: Easy to swap configurations between environments
-- **Documented**: JSDoc on each option explains its purpose
-
-Environment variables can still be used, but they're passed in explicitly:
-
-``````typescript
-auth: {
-  token: {
-    secret: process.env.TOKEN_SECRET!,  // Explicit, not implicit
-    issuer: process.env.TOKEN_ISSUER!,
-  },
-}
-``````
-
-#### 2. Toggleable Middleware
-
-Every piece of built-in middleware can be enabled, disabled, or customized:
-
-``````typescript
-middleware: {
-  cors: false,                    // Disable entirely
-  json: {limit: "10mb"},          // Customize
-  helmet: {enabled: true},        // Enable with defaults
-  rateLimit: {                    // Enable with custom config
-    windowMs: 15 * 60 * 1000,
-    max: 100,
-  },
-}
-``````
-
-#### 3. Comprehensive Hooks
-
-Hooks allow custom logic at every stage:
-
-``````typescript
-hooks: {
-  onAppCreated: (app) => {
-    // Just after Express app created
-  },
-  onAuthReady: (app) => {
-    // After auth middleware configured, before routes
-  },
-  onRoutesReady: (app) => {
-    // After all routes added, before error handlers
-  },
-  onReady: (app) => {
-    // App fully configured, before listening
-  },
-  onListening: (server, port) => {
-    // Server started
-  },
-  onRequest: (req, res) => {
-    // On every incoming request
-  },
-  onError: (error, req, res) => {
-    // On every error
-  },
-  onShutdown: async () => {
-    // On graceful shutdown
-  },
-}
-``````
-
-These hooks enable advanced use cases like:
-- Custom admin-only auth checks inserted after built-in auth
-- Request-level metrics and tracing
-- Cleanup tasks on shutdown (close DB connections, flush logs)
-
-#### 4. Fluent API
-
-Instead of a single large options object, configuration happens through chained method calls:
-
-``````typescript
-TerrenoApp.create({auth, middleware})
-  .addModelRouter("/users", User, permissions)
-  .addModelRouter("/posts", Post, permissions)
-  .addRoute("/webhooks", webhookRouter)
-  .addMiddleware(customMiddleware, {path: "/admin"})
-  .enableWebSocket({path: "/ws"})
-  .start();
-``````
-
-This is:
-- **More readable**: Each line is a clear intent
-- **More flexible**: Add routes and middleware in any order
-- **Easier to extend**: New methods can be added without breaking existing code
-
-#### 5. Foundation for Modular Apps
-
-The new architecture enables installable "apps" (like Django's app system):
-
-``````typescript
-import {adminApp} from "@terreno/admin";
-
-TerrenoApp.create({auth})
-  .install(adminApp({
-    models: [User, Post, Todo],
-    permissions: [IsAdmin],
-  }))
-  .start();
-``````
-
-This would be nearly impossible with `setupServer()` because installing an app requires:
-- Adding routes at a specific point in the stack
-- Registering middleware
-- Adding hooks for initialization
-- Merging OpenAPI specs
-
-With TerrenoApp, an "app" is just a function that receives the `TerrenoApp` instance and calls its methods.
-
-## Design Principles
-
-### 1. Explicit over Implicit
-
-Settings are passed in, not read from global state (env vars). This makes dependencies clear and testing easier.
-
-### 2. Composable over Monolithic
-
-Features are added via method calls, not configured via a mega-options object. This allows fine-grained control.
-
-### 3. Progressive Disclosure
-
-Simple cases are simple:
-
-``````typescript
-TerrenoApp.create({auth: {userModel: User, token: {...}}})
-  .addModelRouter("/todos", Todo, {list: [IsAuthenticated]})
-  .start();
-``````
-
-Complex cases are possible:
-
-``````typescript
-TerrenoApp.create({auth, middleware, health, logging, hooks})
-  .addModelRouter("/todos", Todo, {...})
-  .addRoute("/webhooks", webhookRouter, {openapi: {...}})
-  .addMiddleware(customMiddleware, {position: "afterAuth"})
-  .addErrorHandlingMiddleware(sentryErrorHandler)
-  .enableWebSocket({path: "/ws", authenticate, onConnection, onMessage})
-  .start();
-``````
-
-### 4. Backward Compatibility (Initially)
-
-The implementation plan originally aimed for backward compatibility with `setupServer()`, but the final design makes this a **breaking change**. This is intentional:
-
-- Allows cleaner architecture without maintaining two code paths
-- Forces migration to better patterns
-- Provides opportunity to fix long-standing API warts
-
-Migration will be supported with:
-- Detailed migration guide
-- Deprecation warnings in v2.0.0-beta
-- `setupServer()` available but deprecated in v2.0.0
-- Removal in v3.0.0, giving users time to migrate
-
-## Implementation Status
-
-**Current**: Planning phase (implementation plan merged)
-
-**Next steps**:
-1. ✅ Write implementation plan
-2. ✅ Gather community feedback
-3. 🚧 Implement core TerrenoApp class with tests
-4. 🚧 Update example-backend to demonstrate new API
-5. 🚧 Write migration guide with real examples
-6. 🚧 Publish v2.0.0-beta for testing
-7. 🚧 Address feedback and publish v2.0.0
-
-## Learn More
-
-- 📖 [Implementation plan](../implementationPlans/ModularAPI.md) — Full technical specification
-- 💬 [GitHub PR #149](https://github.com/TerrenoLabs/terreno/pull/149) — Discussion and feedback
-
-## Related
-
-- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
-- [Authentication architecture](authentication.md) — How JWT and OAuth work in Terreno

package/src/docs/versioned/57.1.0/explanation/positioning.md

@@ -1,164 +0,0 @@
-# Positioning
-
-This is the single source of truth for how Terreno describes itself. The problem
-this page exists to fix is drift: the README, the docs landing page, `AGENTS.md`,
-and the npm package descriptions have historically said different things, so a
-visitor's impression of Terreno depended on which door they walked through.
-
-The rule is simple: **write the wording once, here, then reuse it verbatim
-everywhere else.** Do not paraphrase per surface.
-
-## Canonical copy blocks
-
-Copy these blocks exactly. They are in fenced code blocks so they can be lifted
-without markdown-rendering surprises.
-
-### `tagline`
-
-Used by: README H1 subtitle, docs site `tagline`, npm `description` prefix.
-
-```
-Terreno is Django/Rails for TypeScript — with universal app support.
-```
-
-### `elevator`
-
-Used by: README intro, docs landing intro, package READMEs.
-
-```
-Terreno is Django/Rails for TypeScript — a batteries-included, full-stack
-framework where the undifferentiated 80% of an app is already written. On the
-backend you get Mongoose models, auto-generated REST APIs, permissions, an admin
-panel, authentication, and an AI service. On the frontend you get one universal
-app — a single React Native codebase that ships to iOS, Android, and web. It is
-built to be driven by AI coding agents from the first prompt to a production
-deploy.
-```
-
-### `pillars`
-
-Used by: README, docs landing, `AGENTS.md`. Keep the order.
-
-```
-- Batteries included — auth, CRUD APIs, admin, permissions, AI, realtime,
-  feature flags, and consent are already built, so your code is business logic.
-- Universal by default — one React Native codebase ships to iOS, Android, and
-  web. Not a web framework with a mobile bolt-on.
-- AI-native — agents are a first-class client of the framework, not an
-  afterthought.
-```
-
-### `aiPillar`
-
-Used wherever the AI-native pillar gets more than a bullet. It must always name
-**both** layers (see language rule 5).
-
-```
-Terreno's AI-native story has two layers. The tool layer is a Model Context
-Protocol (MCP) server that gives coding agents codegen, documentation search,
-and component reference for the framework's conventions. The process layer is the
-`/terreno-*` SDLC pipeline — plan, implement test-first, verify in a fresh
-context, submit with evidence, then own the review loop — which today runs inside
-the Terreno repository while its consumer-installable packaging is finished.
-Django gives you `manage.py startapp`; Terreno is building a reviewed path from a
-request to a mergeable pull request.
-```
-
-> **Portability gate (do not remove until cleared).** The `/terreno-*` pipeline
-> is not yet verified to run in a consumer application — that is
-> [`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5,
-> which is still open. Until it passes, describe the pipeline as in-progress
-> packaging (as the `aiPillar` block above does) and never imply a consumer can
-> install and run it today. When Task 2.5 passes, update the `aiPillar` block to
-> claim the pipeline as consumer-ready.
-
-### `pitch`
-
-Used by: blog post intros, conference abstracts, social. ~150 words.
-
-```
-Every app needs the same foundation: authentication, user management, CRUD APIs,
-an admin panel, permissions, realtime updates, feature flags, and AI. That work
-is weeks of undifferentiated effort, and it is the same in every product.
-
-Terreno is Django/Rails for TypeScript. Define a Mongoose model, register it, and
-you have a permissioned REST API with pagination, filtering, and an OpenAPI spec.
-Add the admin package and you have a working admin panel. Your app is left with
-the part that is actually yours: the business logic.
-
-The difference from Django or Rails is universal apps — one React Native codebase
-ships to iOS, Android, and web — and being AI-native. Agents are a first-class
-client: an MCP server teaches them the conventions, and a reviewed SDLC pipeline
-takes a request to a mergeable pull request. You build with AI from the first
-prompt to production.
-```
-
-## Why the Django/Rails analogy
-
-Django and Rails won by deciding that the generic parts of a web app — the ORM,
-the router, the admin, auth — belong in the framework, not in every project. They
-are opinionated, batteries-included, and productive because of it. Terreno makes
-the same bet for TypeScript: the generic 80% of an app lives in the framework so
-your codebase is the 20% that is unique to your product.
-
-The analogy earns two honest caveats. First, Terreno targets a document store
-(MongoDB via Mongoose), not a relational ORM, and it has no migrations framework.
-Second, it is younger — several Django/Rails staples (background jobs,
-server-side rendering, role-based access control) are not shipped yet. The
-comparison table below is deliberately straight about where the analogy holds and
-where it does not; being honest about the gaps is what makes the analogy credible
-rather than marketing.
-
-The two things Django and Rails do not give you, and Terreno does, are **universal
-apps** (one codebase for iOS, Android, and web) and being **AI-native** by design.
-
-## Comparison table
-
-Every "shipped" row cites where the feature lives in the source. Every "not
-shipped" row links the implementation plan or roadmap item that tracks it.
-
-| Django / Rails concept | Terreno equivalent | Honest caveat |
-|------------------------|--------------------|----------------|
-| Models + ORM | Mongoose schemas + `@terreno/api` plugins (`api/src/plugins.ts`) | Document store, not relational; no migrations framework (see the Migrations row) |
-| `ModelViewSet` / scaffolds | `modelRouter` (`api/src/api.ts`) | REST only; no GraphQL |
-| Django admin | `@terreno/admin-backend` + `@terreno/admin-frontend` / `@terreno/admin-spa` | Younger; the parity gap is tracked in [`admin-ui-v2-django-parity`](../implementationPlans/admin-ui-v2-django-parity.md) |
-| Auth + permissions | Better Auth (`api/src/betterAuthApp.ts`) + `Permissions` (`api/src/permissions.ts`) | Fine-grained RBAC is in progress ([`rbac-permissions`](../implementationPlans/rbac-permissions.md)) |
-| Templates / views | `@terreno/ui` components — one universal codebase for iOS, Android, and web | Server-side rendering for web is not shipped yet ([`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md)) |
-| `manage.py` / generators | MCP server tools — the *tool* layer (`mcp-server/src/tools.ts`) + the `/terreno-*` SDLC pipeline — the *process* layer (`plugins/terreno-planning/skills/`) | Agent-driven rather than CLI-driven; the pipeline is not yet packaged for consumer apps ([`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5) |
-| Celery / ActiveJob (background jobs) | Not shipped | On the [roadmap](../../ROADMAP.md) |
-| Migrations | No migrations framework | Schema evolution is convention plus the `mongoose-schema-safety` skill (`.claude/skills/mongoose-schema-safety/`) |
-
-## Language rules
-
-Every doc, README, landing page, and agent-facing surface follows these rules.
-
-1. **Lead with the analogy.** Say "Django/Rails for TypeScript" within the first
-   two sentences of the README and the docs landing page.
-2. **Say "universal app,"** not "cross-platform" and not "React Native app," when
-   describing the frontend. It is one codebase that ships to iOS, Android, and
-   web.
-3. **Never claim an unshipped feature as available.** If a capability is on the
-   roadmap or tracked by an open IP, say so. Grep the package source before
-   writing that something ships.
-4. **Keep superlatives off reference pages.** "The best framework for X" belongs
-   on the landing page and the pitch, never in reference documentation.
-5. **Never describe one AI layer without the other.** The tool layer (MCP server)
-   and the process layer (`/terreno-*` pipeline) are always named together, and
-   the pipeline is described honestly per the portability gate above.
-
-## Repository metadata (maintainer action)
-
-The GitHub repository description and topics cannot be set from a commit. A
-maintainer must set them in **Settings → General** and the **About** panel.
-
-**Description** (the short tagline variant):
-
-```
-Django/Rails for TypeScript, with universal iOS/Android/web apps.
-```
-
-**Topics:**
-
-```
-typescript, react-native, expo, express, mongoose, framework, mcp, ai, universal-apps, full-stack
-```

package/src/docs/versioned/57.1.0/explanation/repository-settings.md

@@ -1,52 +0,0 @@
-# Repository settings (maintainers)
-
-Some GitHub settings cannot be committed to the repo. Enable these manually in
-the [Terreno repository settings](https://github.com/TerrenoLabs/terreno/settings).
-
-## Discussions
-
-**Path:** Settings → General → Features → Discussions
-
-Enable Discussions and create these categories (see
-[public roadmap IP](../implementationPlans/public-roadmap-github.md) for
-descriptions):
-
-1. Announcements (maintainers only)
-2. Q&A
-3. Ideas
-4. Agents & AI
-5. RFCs
-6. Show and tell
-7. Docs feedback
-
-## Security
-
-**Path:** Settings → Security → Code security and analysis
-
-- Enable **Private vulnerability reporting** (GitHub PVR as the primary channel;
-  `security@terreno.app` is the email fallback — see [SECURITY.md](../../SECURITY.md))
-
-## Branch protection (`master`)
-
-**Path:** Settings → Branches → Branch protection rules → `master`
-
-- Require a pull request before merging
-- Require status checks to pass (include Repository policies, package CI, and
-  Rulesync Check jobs relevant to the change)
-- Require branches to be up to date before merging
-- Do not allow bypassing the above settings
-
-### CircleCI dual-run (in progress)
-
-Package CI / policy / Playwright twins live under `.circleci/` (see
-[how-to/circleci.md](../how-to/circleci.md)). **Keep requiring the existing GitHub
-Actions check names** until a twin is trusted; then add the CircleCI job name and
-remove the GHA workflow. Do not require CircleCI deploy jobs yet (deploys not
-ported).
-
-## Merge settings
-
-**Path:** Settings → General → Pull Requests
-
-- Allow **squash merging** only (disable merge commits and rebase merging)
-- Enable **Automatically delete head branches** after merge