@terreno/mcp 57.3.0 → 57.4.0

package/dist/docs/versioned/next/how-to/README.md

@@ -12,14 +12,19 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 ## Contents
 
+- [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
 - [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
 - [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
+- [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
 - [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
 - [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
 - [Rate limiting](rate-limiting.md) — Opt-in HTTP limiter on `TerrenoApp` (memory or Redis)
 - [Receive inbound webhooks](inbound-webhooks.md) — HMAC, Stripe, Twilio, and SendGrid signatures on `WebhooksApp`
+- [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Enable the framework audit log](audit-log.md) — `AuditApp`, per-router `audit`, append-only events
 - [Seed a database](seed-a-database.md) — Idempotent sync, dry runs, and guarded reset-and-reseed
+- [Run MongoDB migrations](run-mongodb-migrations.md) — Versioned `up`/`down` files, `terreno-migrate`, production gate
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
 - [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
@@ -32,7 +37,12 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
 - [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
 - [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid`
+- [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
+- [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
+- [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`
 
 ## Admin
 

package/dist/docs/versioned/next/how-to/add-gpt-chat-mascot.md

@@ -0,0 +1,92 @@
+# Add a GPT chat mascot
+
+Pass a `mascot` node into `GPTChat`. Terreno does not ship a character — the consumer owns the image, Lottie, icon, or copy.
+
+## When it shows
+
+| Chat state | Mascot |
+| --- | --- |
+| `currentMessages` is empty | Rendered, centered in the chat panel above suggested prompts |
+| One or more messages | Hidden |
+
+The empty state fills the message area and centers both axes. GPTChat sizes that hero to the message viewport so a short mascot stays centered, and the same scroller still reaches a large mascot, suggested prompts, or an open keyboard. Streaming feedback stays with the centered hero until the first message arrives. Size the mascot for a hero slot (`Heading size="2xl"`, a large `Image`, or a Lottie view).
+
+Omit `mascot` to keep the default empty chat (prompts only, or a blank panel).
+
+## Steps
+
+### 1. Build the node in your app
+
+Keep the asset in the consumer package. `GPTChat` only mounts whatever you pass.
+
+```tsx
+import {Box, Heading} from "@terreno/ui";
+import {Image} from "react-native";
+import {useState} from "react";
+
+const MASCOTS = [
+  require("../assets/mascot-1.png"),
+  require("../assets/mascot-2.png"),
+  require("../assets/mascot-3.png"),
+  require("../assets/mascot-4.png"),
+];
+
+const ChatScreen: React.FC = (): React.ReactElement => {
+  // Select once per screen mount; ordinary re-renders keep the same character.
+  const [mascot] = useState(() => MASCOTS[Math.floor(Math.random() * MASCOTS.length)]);
+
+  return (
+    <GPTChat
+      currentMessages={currentMessages}
+      histories={histories}
+      mascot={
+        <Box alignItems="center" gap={3}>
+          <Image
+            accessibilityLabel="App mascot"
+            resizeMode="cover"
+            source={mascot}
+            style={{borderRadius: 112, height: 224, width: 224}}
+          />
+          <Heading align="center" size="md">Ask anything.</Heading>
+        </Box>
+      }
+      onCreateHistory={handleCreateHistory}
+      onDeleteHistory={handleDeleteHistory}
+      onSelectHistory={handleSelectHistory}
+      onSubmit={handleSubmit}
+    />
+  );
+};
+```
+
+For a single fixed mascot, pass one asset directly instead of selecting from an array.
+
+### 2. Pass it to `GPTChat`
+
+```tsx
+<GPTChat
+  currentMessages={currentMessages}
+  histories={histories}
+  mascot={ChatMascot}
+  onCreateHistory={handleCreateHistory}
+  onDeleteHistory={handleDeleteHistory}
+  onSelectHistory={handleSelectHistory}
+  onSubmit={handleSubmit}
+  suggestedPrompts={["What can you help with?"]}
+/>
+```
+
+### 3. Confirm empty vs thread
+
+Open a new chat: the mascot is visible. After the first user or assistant message, it is gone.
+
+## Example
+
+The example app bundles four consumer-owned plant robots in
+`example-frontend/assets/gptMascots/` and selects one on each AI screen mount. The
+demo story `GPTChat` → `Mascot` shows the slot without a backend.
+
+## Related
+
+- [`GPTChat` props](../reference/ui.md#gptchat)
+- Demo: `http://localhost:8085/dev/GPTChat?story=Mascot`

package/dist/docs/versioned/next/how-to/add-organizations.md

@@ -0,0 +1,204 @@
+# Add organizations to a Terreno app
+
+Enable organizations only when the app is multi-tenant. Existing single-tenant
+apps can omit every option in this guide.
+
+## 1. Enable organization RBAC
+
+``````typescript
+import {createAccess, terrenoStatements} from "@terreno/api";
+
+export const access = createAccess({
+  connection: mongoose.connection,
+  organizations: true,
+  statements: terrenoStatements,
+  userModel: User,
+});
+
+await access.roles.seedDefaults();
+``````
+
+This adds Membership-based `org-admin` grants and seeds the locked `operator`
+role. It does not change apps that omit `organizations`.
+
+## 2. Mount organization routes
+
+``````typescript
+const app = new TerrenoApp({
+  accessControl: access,
+  organizations: true,
+  userModel: User,
+});
+``````
+
+This mounts `OrgsApp` at `/orgs`. To configure audit handling or a different
+path, pass an options object:
+
+``````typescript
+organizations: {
+  basePath: "/organizations",
+  onOrgAudit: recordOrganizationAudit,
+  settingsSchema: organizationSettingsSchema,
+}
+``````
+
+## 3. Type organization settings
+
+Keep native `Organization` fields unchanged. Put app fields on
+`Organization.settings` with a nested Mongoose schema and a TypeScript
+interface.
+
+1. Declare the settings shape (optional module augmentation):
+
+``````typescript
+// src/types/models/organizationSettingsTypes.ts
+export interface ExampleOrganizationSettings {
+  timezone?: string;
+}
+
+declare module "@terreno/api" {
+  interface OrganizationSettings extends ExampleOrganizationSettings {}
+}
+``````
+
+2. Build the nested schema. Use optional fields or defaults so existing
+organizations still validate:
+
+``````typescript
+// src/models/organizationSettings.ts
+import {createOrganizationSettingsSchema} from "@terreno/api";
+import type {ExampleOrganizationSettings} from "../types/models/organizationSettingsTypes";
+
+export const organizationSettingsSchema = createOrganizationSettingsSchema<ExampleOrganizationSettings>({
+  timezone: {
+    description: "IANA timezone used for organization-local dates",
+    type: String,
+  },
+});
+``````
+
+3. Register before you create or patch organizations (startup and seeds):
+
+``````typescript
+import {registerOrganizationSettings} from "@terreno/api";
+import {organizationSettingsSchema} from "./models/organizationSettings";
+
+registerOrganizationSettings(organizationSettingsSchema);
+``````
+
+Or pass the same schema on `TerrenoApp` / `OrgsApp`:
+
+``````typescript
+new TerrenoApp({
+  accessControl: access,
+  organizations: {settingsSchema: organizationSettingsSchema},
+  userModel: User,
+});
+``````
+
+Read typed settings with `organizationSettingsOf(organization)` or
+`organizationSettingsOf<ExampleOrganizationSettings>(organization)`.
+
+Without a registered schema, `settings` stays Mixed and accepts any object.
+Unknown keys and wrong types fail with **400** `Organization settings are invalid`
+once a schema is registered.
+
+## 4. Scope tenant models
+
+Add `orgScopedPlugin` to models that use ObjectId organization keys. Put
+`orgContextMiddleware({required: true})` before their routes, use
+`OrgQueryFilter` for lists, and overwrite client organization ids during
+create:
+
+``````typescript
+import {
+  authenticateMiddleware,
+  getOrgContext,
+  modelRouter,
+  OrgQueryFilter,
+  orgContextMiddleware,
+  orgScopedPlugin,
+  Permissions,
+  type TerrenoPlugin,
+} from "@terreno/api";
+import type express from "express";
+
+schema.plugin(orgScopedPlugin);
+
+const projectOrgContextPlugin: TerrenoPlugin = {
+  register(expressApp: express.Application): void {
+    expressApp.use(
+      "/projects",
+      authenticateMiddleware(),
+      orgContextMiddleware({required: true})
+    );
+  },
+};
+
+const projectRouter = modelRouter("/projects", Project, {
+  permissions: {
+    create: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    delete: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    update: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+  },
+  preCreate: (body, _req) => ({
+    ...body,
+    organizationId: getOrgContext()?.organization?._id,
+  }),
+  queryFilter: OrgQueryFilter,
+});
+
+app.register(projectOrgContextPlugin).register(projectRouter);
+``````
+
+For admin CRUD, use `new AdminApp({accessControl: access, organizations:
+true})`. Models with an `organizationId` schema path are scoped automatically,
+except `AuditEvent` (the platform audit log lists without a selected org).
+Admin-window `POST /sync/mutate` and socket `sync:mutate` use the same membership
+check as REST for update and delete when `X-Organization-Id` (HTTP) or
+`organizationId` (socket payload) is set. Admin `createSyncDb({organizationIdProvider})`
+sends that id on every mutate.
+
+`orgScopedPlugin` also makes `organizationId` immutable after the document is
+created. Client PATCH bodies, admin writes, sync updates, and direct Mongoose
+saves that change `organizationId` return HTTP 400 with
+`organizationId cannot be changed`.
+
+## 5. Send organization context
+
+Send `X-Organization-Id` on tenant-scoped requests. `org-admin` callers with
+exactly one administered organization may omit it; Terreno infers that org.
+Operators and superadmins must select an org.
+
+Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
+`useAdminApi` adds the selected organization header automatically.
+
+Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
+tenant context. Operators re-enable them from the organization directory UI or
+with `PATCH /orgs/:id` and `disabled: false` (see
+[How organization tenancy works](../explanation/organizations.md#disabled-organizations)).
+
+Creating or renaming an organization to a name that generates an existing slug,
+including a slug still held by a **soft-deleted** organization, returns **409**
+`Organization name already in use`. `OrgSwitcher` hides itself
+when `/orgs/mine` returns **403** for callers without org-admin memberships.
+
+## Example app accounts
+
+After `bun run backend:seed`, all accounts use password `testpassword123`:
+
+| Account | Access |
+| --- | --- |
+| `operator@example.com` | Platform organization directory; may enter either org |
+| `orgadmin-alpha@example.com` | Org admin for Alpha Workspace |
+| `orgadmin-beta@example.com` | Org admin for Beta Workspace |
+| `test@example.com` | Member of Alpha Workspace |
+| `admin@example.com` / `superadmin@example.com` | Existing example superadmin accounts |
+
+The seed creates Alpha Workspace and Beta Workspace plus two projects in Alpha
+Workspace. Membership rows, not fields on User, are the source of tenant access.
+In-process Better Auth seeding sets `disableRateLimit: true` so production
+preview smoke tests can create all six accounts without hitting Better Auth's
+sign-up limiter.

package/dist/docs/versioned/next/how-to/admin-add-model.md

@@ -38,7 +38,15 @@ Common fields:
 - `searchFields`: string fields matched by the list search box (`q`) as a
   case-insensitive partial (`$regex`) query.
 - `sortableFields`: the only columns with sorting enabled.
-- `filters`: typed filter drawer controls.
+- `filters`: typed list filters rendered on `DataTable` column headers (web) or the
+  mobile **Filters** sheet. `text` filters are case-insensitive contains (`$regex`);
+  `choice` filters support multi-select (`$in`); `ref` stays a single ObjectId. The
+  backend accepts only escaped literal regex patterns and rejects extra nested operators.
+  Optional choice fields (Mongoose path not `required`) automatically expose an **Empty**
+  filter option; set `allowEmpty: false` on the filter config to hide it, or
+  `allowEmpty: true` on required fields when you intentionally want unset matching.
+  Empty filters can be combined with toolbar search or concrete choices. The wire
+  sentinel is consumed before Mongo receives the query.
 - `fieldsets`: grouped form sections.
 - `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
 - `adminPermissions`: optional admin-specific permission methods.

package/dist/docs/versioned/next/how-to/admin-import-prebuilt.md

@@ -3,12 +3,15 @@
 Register first-party plugins on the same `TerrenoApp` as `AdminApp`:
 
 ```ts
+import {JobsApp} from "@terreno/jobs";
+
 const app = new TerrenoApp({userModel: User})
   .register(new FeatureFlagsApp())
   .register(new ConsentApp({auditTrail: true}))
   .register(new DocumentStorageApp({bucketName: process.env.GCS_BUCKET ?? ""}))
   .register(new AIAdminApp())
-  .register(new AdminApp({home: {slots: {main: ["modelStats"]}}}));
+  .register(new JobsApp({accessControl})) // optional — needs admin:access + admin:jobs
+  .register(new AdminApp({home: {slots: {main: ["modelStats", "jobs"]}}}));
 ```
 
 `AdminApp` aggregates each plugin's `adminContribution()`:
@@ -17,6 +20,9 @@ const app = new TerrenoApp({userModel: User})
 - `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
 - `DocumentStorageApp`: `documents` custom screen.
 - `AIAdminApp`: `ai-requests` custom screen and explorer API.
+- `JobsApp`: `jobs` custom screen and home widget (`dead` / `running` counts). With
+  `accessControl`, requires **both** `admin:access` and `admin:jobs`; without it, legacy
+  `user.admin`. See [Durable background jobs](background-jobs.md).
 
 Wrap frontend admin routes in `AdminProvider`. First-party widgets are already in the built-in
 registry, so no consumer-side switch statement or custom-screen map is required.

package/dist/docs/versioned/next/how-to/audit-log.md

@@ -0,0 +1,85 @@
+# Enable the framework audit log
+
+Register `AuditApp` and set `audit: true` on routers you want logged. Successful HTTP mutations write append-only `AuditEvent` rows. Default retention is forever.
+
+## Steps
+
+### 1. Register the plugin
+
+```typescript
+import {AuditApp, TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User}).register(new AuditApp()).start();
+```
+
+Importing `@terreno/api` does not register `AuditEvent`. HTTP list/read is admin-only at `GET /audit-events` and `GET /admin/audit-events`. Create/update/delete over HTTP are disabled (405), including the admin remount.
+
+### 2. Opt in per router
+
+```typescript
+modelRouter("/todos", Todo, {
+  audit: true, // or {redact: ["ssn"]}
+  permissions: {
+    /* ... */
+  },
+});
+```
+
+`audit: true` without `AuditApp` still returns 2xx and logs an error once per process.
+
+## Operations
+
+| HTTP | `verb` | `operation` | Diff |
+| --- | --- | --- | --- |
+| POST `/` | `created` | `create` | `after` only |
+| PATCH `/:id` | `updated` | `update` | Changed fields in `before` / `after` |
+| DELETE `/:id` | `deleted` | `delete` | `before` only |
+| POST `/:id/:field` | `updated` | `arrayPush` | Changed fields; `recordId` set |
+| PATCH `/:id/:field/:itemId` | `updated` | `arrayUpdate` | Changed fields; `recordId` set |
+| DELETE `/:id/:field/:itemId` | `updated` | `arrayRemove` | Changed fields; `recordId` set |
+
+`source` is `modelRouter` for these writes. Secrets (`password`, `hash`, `salt`, `token`,
+`secret`, `refreshToken`) are omitted at every object and array depth, including compound
+keys such as `tokenHash`. Extra `redact` names merge with that list as exact field names.
+
+### 3. Admin mutations
+
+When `AuditApp` is registered, AdminApp writes the same `AuditEvent` collection with
+`source: "admin"` after successful admin POST/PATCH/DELETE. You do not need `onAdminAudit` for
+that. `onAdminAudit` remains an extra sink if the app still wants a second destination.
+Admin diffs also omit each model's `hiddenFields` and `excludeFields`.
+
+RBAC mutations fan into the same collection when `createAccess({auditSink: persistRbacAuditToAuditEvent})` is set. `source` is `rbac`.
+
+`organizationId` is copied onto the event when `req.organization` is set (`id` or `_id`), otherwise from the request org AsyncLocalStorage, then `X-Organization-Id`, then the mutated document's `organizationId` string. Socket admin-window mutates attach `organizationId` on the payload so non-tenant models still land in the selected organization's audit log. The field is omitted when none of those exist. Admin list/read for `AuditEvent` is not organization-scoped, so unscoped rows stay visible when no organization is selected.
+
+`actorId` comes from `req.user.id` (or `_id`). Only a 24-hex Mongo ObjectId is stored;
+mongoose's looser `isValidObjectId` (12-character strings) is not used. Any other id
+shape still writes the event with `actorId` omitted and a warning logged.
+
+Update and delete snapshot `before` only when `audit` is on. If that `toJSON` throws, the
+mutation still completes and the event is recorded without a `before` snapshot.
+
+### 4. Fire-and-forget persist
+
+HTTP handlers do not await Mongo. Diffs still run before the response so `before` / `after` are captured. Failures log; the mutation stays 2xx.
+
+To persist completely off the API process, set Cloud Tasks env (`GCP_PROJECT`, `GCP_LOCATION`, `GCP_TASKS_AUDIT_QUEUE`, `AUDIT_TASKS_URL`, `AUDIT_TASKS_SECRET`) and `bun add @google-cloud/tasks`. `AuditApp` then enqueues the write and handles `POST /internal/audit-events` with header `X-Terreno-Audit-Secret`. Or pass `enqueue` yourself:
+
+```typescript
+new AuditApp({
+  enqueue: async (write) => {
+    await myQueue.push(write);
+  },
+  processQueuePath: "/internal/audit-events",
+  processQueueSecret: process.env.AUDIT_TASKS_SECRET,
+});
+```
+
+Authenticated malformed queue payloads are acknowledged without persistence. They cannot
+become valid on retry, and returning a non-2xx response would make Cloud Tasks retry the
+same poison task indefinitely.
+
+### 5. Retention
+
+Omit `retentionDays` or set `0` to keep events forever (no TTL index). `new AuditApp({retentionDays: 90})` creates a Mongo TTL index on `created` with `expireAfterSeconds = 90 * 86400`, replacing the default `{created: 1}` field index so Mongo does not reject a duplicate key pattern. Mongo expires documents in the background; lowering or removing TTL later requires dropping that index yourself (`db.auditevents.dropIndex(...)`) — Mongoose will not remove it.