@terreno/mcp 0.31.0 → 56.0.0-beta.0

package/dist/docs/upgrades/0.31.0.md

@@ -1,60 +0,0 @@
-# 0.31.0
-
-Terreno packages move in lockstep. Nothing in this release removes or renames a public
-export, so most apps upgrade by bumping the `@terreno/*` versions and running:
-
-- `bun run compile` and `bun run lint` at the repo root
-- `cd <your frontend> && bun run sdk` after any `@terreno/api` route or model surface change
-
-## Mongoose 9 is now supported (Mongoose 8 still works)
-
-Every published package that talks to Mongoose (`api`, `test`, `admin-backend`, `ai`,
-`feature-flags`) widened its peer dependency to `^8.0.0 || ^9.0.0`. Terreno itself
-develops against Mongoose 9.7.4.
-
-You can stay on Mongoose 8 with no changes. If you upgrade your app to Mongoose 9, the
-changes that mattered inside Terreno will most likely matter in your code too:
-
-```typescript
-// Before (Mongoose 8)
-await Model.findOneAndUpdate(filter, update, {new: true});
-
-// After (Mongoose 9)
-await Model.findOneAndUpdate(filter, update, {returnDocument: "after"});
-```
-
-- Aggregation-pipeline updates must pass `updatePipeline: true` to `updateMany`.
-- Query middleware no longer takes the legacy `next()` callback — use the async form.
-- Array schema paths expose `getEmbeddedSchemaType()`; the private `caster` property is gone.
-- Mongoose 9 ships its own types, so `@types/mongodb` and
-  `@types/passport-local-mongoose` should be removed from your dev dependencies.
-- Pin `bson` to `7.2.0` if your lockfile resolves an older copy alongside Mongoose 9.
-
-Mongoose 9 requires Node >= 20.19.0. Terreno's root `package.json` now declares that
-engine range for local development.
-
-## `@terreno/api` type changes
-
-Both changes widen or relax types; they are source-compatible for normal usage, but
-explicit annotations may need updating:
-
-- `modelRouter` now accepts `Model<T, any, any, any, any, any>` instead of `Model<T>`,
-  so models with custom query helpers, methods, or virtuals no longer need a cast.
-- `findOneOrNoneFor(model, query)` takes `ModelQuery<T>` (a partial record keyed by the
-  document fields) instead of Mongoose's `FilterQuery<T>`. If you were building a
-  `FilterQuery<T>` value to pass in, it still works; if you were annotating the variable
-  as `FilterQuery<T>` and relying on operator typing, switch to `ModelQuery<T>`.
-
-## `@terreno/admin-backend` array field metadata
-
-`GET /admin/config` derives array item metadata (`itemType`, `itemRef`, `itemEnum`) from
-Mongoose's public `getEmbeddedSchemaType()` when available, falling back to the Mongoose 8
-`caster` shape. `itemEnum` is only emitted when the embedded enum is an array, so an enum
-declared as an object map no longer produces a malformed `itemEnum`. Admin clients that
-read `itemEnum` should treat it as optional.
-
-## License changed from Apache-2.0 to MIT
-
-All published `@terreno/*` packages are now MIT licensed and ship a `LICENSE` file in the
-package tarball. No code change is required; update any license inventory or attribution
-list that pinned Terreno as Apache-2.0.

package/dist/docs/versioned/next/explanation/deployment-architecture-gcp.md

@@ -1,65 +0,0 @@
-# GCP deployment architecture
-
-Reference topology for hosting a Terreno full-stack app on Google Cloud Platform.
-
-This page is conceptual — commands live in the [how-to guides](../how-to/deploy-to-gcp.md).
-
-## Topology
-
-```mermaid
-flowchart TD
-  U["User<br/>iOS / Android / Web"]
-  CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
-  CR["Cloud Run<br/>@terreno/api backend"]
-  SM["Secret Manager<br/>auth secrets, MONGO_URI"]
-  AT["MongoDB Atlas<br/>replica set (change streams)"]
-  GCS["GCS bucket<br/>user file uploads"]
-  AR["Artifact Registry<br/>backend image"]
-  U -->|"web"| CDN
-  U -->|"native app"| CR
-  CDN -->|"API calls"| CR
-  CR --> SM
-  CR --> AT
-  CR --> GCS
-  AR --> CR
-```
-
-## Component responsibilities
-
-| Component | Role |
-|-----------|------|
-| **Artifact Registry** | Stores versioned backend container images built from `example-backend/Dockerfile` |
-| **Cloud Run** | Runs the long-lived `@terreno/api` process (HTTP + Socket.io) |
-| **Secret Manager** | Holds `MONGO_URI`, JWT secrets, and other credentials — mounted as env vars |
-| **MongoDB Atlas** | Primary database; must be a replica set for change streams (realtime, feature flags) |
-| **GCS (web bucket)** | Serves static web export; CDN caches at the edge |
-| **GCS (uploads bucket)** | Private object storage for user uploads via `@terreno/api` file plugins |
-
-## Why Cloud Run (not App Engine or GKE)
-
-| Option | Tradeoff |
-|--------|----------|
-| **Cloud Run** | Pay-per-use, minimal ops, supports WebSockets with session affinity — fits Terreno's socket + HTTP model |
-| **App Engine** | Similar serverless model but less flexible for custom containers and long timeouts |
-| **GKE** | Full control but requires cluster management — overkill for a single Terreno backend |
-
-## Why Atlas (not self-hosted Mongo on GCP)
-
-| Option | Tradeoff |
-|--------|----------|
-| **MongoDB Atlas** | Managed replica sets, backups, and change streams out of the box |
-| **Self-hosted on Compute Engine** | You operate replica set elections, backups, and upgrades — documented as out of scope for launch |
-
-## Static web vs server-rendered
-
-| Approach | Tradeoff |
-|----------|----------|
-| **GCS + CDN (static export)** | Cheapest, simplest, works today with Expo `single`/`static` output — no SSR or API routes |
-| **Node/Bun server (SSR)** | Better SEO and API routes — requires Expo SDK ≥ 55; not available in the current `~54` catalog |
-
-Native iOS and Android apps call Cloud Run directly; only the web client uses the CDN origin.
-
-## Related
-
-- [Deployment baseline](deployment-baseline.md) — seven requirements every host must satisfy
-- [Deploy to GCP](../how-to/deploy-to-gcp.md) — step-by-step guides

package/dist/docs/versioned/next/explanation/deployment-baseline.md

@@ -1,78 +0,0 @@
-# Deployment baseline
-
-Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), future Vercel guide) map these to specific platforms; this page names them once.
-
-See also the [environment variables reference](../reference/environment-variables.md).
-
-## Seven baseline requirements
-
-| # | Requirement | Why Terreno needs it | When missing |
-|---|-------------|----------------------|--------------|
-| 1 | **MongoDB replica set** | Change streams power realtime and live feature-flag updates | Startup logs: `FeatureFlag.watch() failed — live updates require MongoDB as a replica set` (`feature-flags/src/featureFlagsApp.ts`) |
-| 2 | **Auth secrets** | JWT signing and sessions (or Better Auth encryption) | Login fails; tokens rejected |
-| 3 | **Long-lived backend process** | Socket.io connections are not request/response | Websockets drop on platforms with short request timeouts or aggressive scale-to-zero |
-| 4 | **Correct origins** | CORS and Better Auth `trustedOrigins` must include your web and native schemes | Browser: blocked by CORS; native: auth redirects fail |
-| 5 | **Build-time client config** | `EXPO_PUBLIC_*` values are inlined into the web bundle at build time | API calls go to `undefined` or localhost after deploy — see [Build for web](../how-to/build-for-web.md) |
-| 6 | **Health endpoint** | Load balancers and orchestrators need readiness probes | Platform marks the service unhealthy and stops routing traffic |
-| 7 | **Durable file storage** | Uploads must not live on ephemeral container disk | Files disappear on restart; use GCS/S3 and credentials |
-
-Requirements **1**, **3**, and **5** are the ones teams miss most often.
-
-### Symptom details
-
-**1 — Standalone MongoDB**
-
-Terreno's feature-flag plugin opens a change stream on startup. Without a replica set, live flag sync is disabled and logs:
-
-```text
-[feature-flags] FeatureFlag.watch() failed — live updates require MongoDB as a replica set (even single-node).
-```
-
-Use [MongoDB Atlas](https://www.mongodb.com/atlas) or a single-node replica set for development.
-
-**3 — Short-lived serverless timeouts**
-
-The RTK/socket client enables reconnection (`reconnection: true`, `reconnectionAttempts: 5` in `rtk/src/socket.ts`). When the backend drops idle connections (for example Cloud Run's default 300s request timeout), clients reconnect but realtime state may lag until the new socket attaches.
-
-**5 — Build-time API URL**
-
-If you set `EXPO_PUBLIC_API_URL` only at runtime on the static host, the bundle still contains whatever was present at `bun run export` time — often `http://localhost:4000`. The browser then fails network requests against localhost.
-
-## Web output modes
-
-Expo Router supports three web output modes. The choice determines hosting options.
-
-| Mode | Output | API routes | SSR | Hosting | Terreno status |
-|------|--------|-----------|-----|---------|----------------|
-| `single` | One `index.html` SPA | No | No | Any static host | **Current default** |
-| `static` | Per-route HTML files | No | No | Any static host | Available; better SEO |
-| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Not yet — repo catalog is Expo `~54.0.29`; see [Web SSR and admin SPA](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md) |
-
-## Multi-environment checklist
-
-Staging and production differ in these values (each environment needs its **own web build** because of `EXPO_PUBLIC_API_URL`):
-
-| Item | Where to configure |
-|------|-------------------|
-| Secret values | Platform secret store / Secret Manager |
-| `MONGO_URI` | Separate cluster or database per environment |
-| `EXPO_PUBLIC_API_URL` | Set before `bun run export` — one build per environment |
-| `corsOrigin` | `setupServer({ corsOrigin })` in backend |
-| Better Auth `trustedOrigins` + `BETTER_AUTH_URL` | Better Auth config / env |
-| Feature-flag defaults | MongoDB documents or seed scripts |
-
-## Containerizing the backend
-
-The canonical Dockerfile is [`example-backend/Dockerfile`](https://github.com/FlourishHealth/terreno/blob/master/example-backend/Dockerfile). It:
-
-1. Installs workspace dependencies and compiles packages in dependency order.
-2. Builds a Bun-compiled binary for production.
-3. Runs as a non-root user and exposes `/health` via `@terreno/api-health`.
-
-Three details consumers get wrong:
-
-- **`PORT`** — Cloud Run and other platforms assign the listen port via `PORT`. Terreno reads `process.env.PORT` in `api/src/terrenoApp.ts` (default `9000` if unset).
-- **Non-root** — Do not run the container as root in production.
-- **Compile order** — Workspace packages (`@terreno/api`, `@terreno/test`, etc.) must compile before the example backend bundles.
-
-CI builds the image on every PR that touches backend paths (`.github/workflows/example-backend-docker.yml`).

package/dist/docs/versioned/next/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/dist/docs/versioned/next/explanation/repository-settings.md

@@ -1,44 +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/FlourishHealth/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
-
-## Merge settings
-
-**Path:** Settings → General → Pull Requests
-
-- Allow **squash merging** only (disable merge commits and rebase merging)
-- Enable **Automatically delete head branches** after merge