@terreno/mcp 0.21.0 → 0.22.1

package/src/docs/versioned/0.21.0/implementationPlans/PLAN_INDEX.md

@@ -0,0 +1,21 @@
+# Implementation plan index
+
+Tracks active and completed implementation plans (IP) for Terreno. File paths are relative to `docs/implementationPlans/`.
+
+## Active
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
+
+## Completed
+
+*(Move rows here from Active when the IP status becomes Complete.)*
+
+## Deferred / Closed
+
+*(Plans parked or superseded.)*
+
+## Backlog
+
+*(Links to ideas not yet promoted to a full IP.)*

package/src/docs/versioned/0.21.0/implementationPlans/README.md

@@ -0,0 +1,42 @@
+# Implementation Plans
+
+Forward-looking implementation plans for significant features and architectural changes to Terreno packages.
+
+## Purpose
+
+This directory contains detailed technical plans for major features **before implementation**. Each plan documents:
+
+- Design goals and rationale
+- Architecture and file structure
+- Configuration interfaces
+- Usage examples
+- Breaking changes and migration paths
+- Implementation tasks and phases
+
+## Current Plans
+
+- **[Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md)** — Config-driven admin shell (sidebar, home widgets, changelist, forms, bulk + background actions); tasks in [`docs/tasks/admin-ui-v2-django-parity.md`](../tasks/admin-ui-v2-django-parity.md)
+- **[Modular API (TerrenoApp)](ModularAPI.md)** — New fluent builder API to replace `setupServer` in `@terreno/api`
+- **[Offline Mode](offline-mode.md)** — Placeholder plan for offline queueing, replay, conflict handling, and UI surfaces
+- **[MCP Boost Parity](mcp-boost-parity.md)** — Docs search tools, local stdio MCP with runtime introspection, browser log capture, per-package guidelines, and upgrade prompts (inspired by laravel/boost)
+- **[Docs Site & Versioning](docs-site-and-versioning.md)** — Docusaurus site, versioned docs per release, UI demo embeds, and docs-maintenance skills
+
+## Status Tracking
+
+| Plan | Status | Target Version | Discussion |
+|------|--------|----------------|------------|
+| Admin UI v2 (Django parity) | ✅ Approved | TBD | — |
+| Modular API | 📝 Planning | 2.0.0 | [#149](https://github.com/FlourishHealth/terreno/pull/149) |
+| Offline Mode | Placeholder | TBD | TBD |
+| MCP Boost Parity | 📝 Planning | TBD | TBD |
+| Docs Site & Versioning | 📝 Planning | TBD | TBD |
+
+## Process
+
+1. **Planning**: Implementation plan merged to master
+2. **Discussion**: Community feedback in linked PR/issue
+3. **Implementation**: Feature developed in feature branch with tests
+4. **Documentation**: How-to guides and migration docs updated
+5. **Release**: Plan moves to `docs/explanation/` as architectural documentation
+
+Plans that are fully implemented should be moved to `docs/explanation/` and updated to reflect the actual implementation.

package/src/docs/versioned/0.21.0/implementationPlans/admin-improvements.md

@@ -0,0 +1,577 @@
+# Implementation Plan: Admin Interface Overhaul (Django-Admin Parity)
+
+## Goal
+
+Bring Terreno's admin from "rendered CRUD" to "Django-admin-class developer experience": admin config co-located on `modelRouter`, pre-built admins composable via the existing `TerrenoPlugin` contract, a richer table (search, filter sidebar, bulk actions, fieldsets, readonlyFields), a declarative customizable home page, a widget registry consumers can extend, and an API surface that's forward-compatible with realtime via Socket.io.
+
+## Non-goals (v1)
+
+- Shipping a Socket.io server (the API surface is realtime-ready; the transport ships in a follow-up).
+- True related-model inlines (Django `TabularInline`/`StackedInline`). Subdoc inlines via `AdminNestedArrayField` continue to work.
+- `date_hierarchy`, `prepopulated_fields`, `list_editable`, `show_facets`. Roadmapped for v1.1+.
+- Replacing the existing AdminApp config (`AdminApp.models`) — kept with deprecation warning for one minor cycle.
+
+## Decisions from adversarial review
+
+Verified findings folded back in. The five most consequential:
+
+1. **TerrenoPlugin signature is extended (not changed).** `register(app, openApi?, terrenoApp?)` — third argument optional, ignored by existing plugins. `TerrenoApp.build()` passes itself as the third arg. This is how `AdminApp` discovers registered routers and plugin contributions, and how `modelRouter` reaches the app to emit events. No new global registry.
+2. **No renames of existing fields.** `listFields`, `defaultSort`, `fieldOverrides`, `fieldOrder`, `hiddenFields` stay as-is. Only *new* options are added (`searchFields`, `sortableFields`, `filters`, `fieldsets`, `readonlyFields`, `excludeFields`, `autocompleteFields`, `actions`, `adminPermissions`, `adminFilter`, `realtime`, `listDisplayLinks`, `pageSize`, `group`, `icon`). The "Alias + warning" migration applies only to the *shape* (passing `AdminModelConfig` to `AdminApp.models` vs. setting `admin:` on the modelRouter).
+3. **Event payloads are scrubbed at emit time.** `admin:model.changed` events are emitted *after* `excludeFields`/`hiddenFields` filtering (not from raw `postCreate`/etc. hooks). The emit step runs `removeHiddenFields` against the merged exclude+hidden set so future socket listeners cannot leak secrets.
+4. **`adminFilter` is async from day one.** Signature: `(req: AuthedRequest) => Promise<FilterQuery<T>> | FilterQuery<T>`. Matches the existing async `queryFilter` contract.
+5. **Action runs use a frozen context, not the live `req`.** Background actions especially: at enqueue time we snapshot `{ userId, userSnapshot, ids, actionName, requestId, startedAt }` into an `AdminActionContext` and pass *that* to `action.run`. Mirrors the existing `ScriptContext` pattern (admin-backend/src/adminApp.ts:622-638).
+
+Also folded (lower severity, see Risks/Files-to-Touch/Tasks for specifics):
+
+- Widget registry locked to `{ fields, home, screens }` three-bucket shape *before* Phase 3 begins. Field-widgets and home-widgets and screen-widgets are semantically different and use the same lookup mechanism.
+- Collision precedence reversed: **registered modelRouter > plugin contribution > legacy `AdminApp.models`**. Most-specific source wins, "legacy" is purely additive. Duplicate `routePath` from two registered modelRouters → throw at build time.
+- Filter parser is per-type strict: each `AdminFilter.type` accepts exactly one value shape; anything else → 400. Test matrix in Task 2.6 covers array-injection, operator-injection (`$ne`, `$gt`, `$where`, `$regex`), prototype-pollution, and shape mismatches.
+- `readonlyFields` enforced on all body-accepting routes including modelRouter's array sub-routes (`POST /:id/:field`, `PATCH /:id/:field/:itemId`, `DELETE /:id/:field/:itemId`). Implementation point: wrap `preUpdate` AND `preCreate` once; enforcement runs unconditionally regardless of route.
+- `excludeFields` / `hiddenFields` recursion through `populatePaths`: each populated document is scrubbed with *its* model's admin config. If the referenced model has no admin config, populated docs are returned as-is (consumer's choice not to admin-register that model).
+- Bulk actions capped at `MAX_ACTION_IDS = 1000` per request. Bulk validation uses one `find({_id: {$in: ids}, ...adminFilter})` round-trip — no N+1.
+- Per-action permission booleans in `/admin/config`: class-level evaluation calls `checkPermissions(action, ..., user, undefined)` and treats any throw as `false`. `IsOwner` returns `false` (no object) — that's correct: admins can't generally "own" all rows pre-fetch.
+- Soft-deleted documents: out of scope for this IP. `AdminConfig.includeDeleted?: boolean` added to the type for v1.1; no implementation now (documented in non-goals).
+- `ConfigurationApp` and the existing `VersionConfig` singleton routes: stay where they are. Singleton models get a separate IP. `VersionConfig` continues to be served by `AdminApp` directly (until then) but no longer appears in the synthetic `customScreens` array — it's surfaced via a built-in `versionConfig` home widget.
+- CSRF + rate-limit: `/actions/:name` inherits whatever auth+rate-limit middleware the app has installed. Documented; no new middleware in this IP. Better Auth cookie sessions are a known risk (out-of-scope until rate-limit IP).
+
+## High-level architecture
+
+```
+@terreno/api
+  modelRouter(...) { ...options, admin?: AdminConfig }     ← new option
+  TerrenoApp.getRegistrations()                            ← new accessor
+  TerrenoPlugin.adminContribution?(): AdminContribution    ← new optional method
+  AdminEventBus (typed emit/on, no transport)              ← new (lays realtime groundwork)
+
+@terreno/admin-backend
+  AdminApp                                                  ← rewritten to aggregate:
+    1. admin configs on registered model routers
+    2. plugin adminContribution() results
+    3. legacy AdminApp({models:[]}) input (deprecated, accepted)
+  Server-side enforcement:
+    - readonlyFields stripped from PATCH bodies
+    - excludeFields removed from forms AND responses
+    - filters/search/ordering parsed from query params
+    - actions executed (sync or background via BackgroundTask)
+
+@terreno/admin-frontend
+  <AdminProvider api baseUrl widgets={...}>                ← new top-level context
+  <AdminScreenRouter>                                       ← new data-driven dispatcher (replaces consumer's switch)
+  <AdminHome>                                               ← rewrite of AdminModelList; widget-driven
+  AdminModelTable (extended)                                ← search box, filter drawer, bulk-select, actions
+  AdminModelForm  (extended)                                ← fieldsets, readonlyFields, autocomplete refs
+  AdminFieldRenderer                                        ← widget map from context
+  widgets/                                                  ← built-in widgets (ModelStats, RecentActivity, ScriptRunner)
+```
+
+## Configuration shapes (canonical)
+
+### `AdminConfig` (on modelRouter)
+
+**Naming note:** existing fields (`listFields`, `defaultSort`, `fieldOverrides`, `fieldOrder`, `hiddenFields`) keep their names. The "alias + warning" migration applies to the *shape* (passing `AdminModelConfig` to `AdminApp.models` vs. setting `admin:` on the modelRouter), not to renaming individual fields.
+
+```typescript
+export interface AdminConfig<T = unknown> {
+  /** Human-readable name for the model in the admin (e.g., "Users"). */
+  displayName: string;
+
+  /** Optional sidebar group label. Models without a group go in "Other". */
+  group?: string;
+
+  /** Optional icon (FontAwesome 6 name) for navigation. */
+  icon?: string;
+
+  // ── List view ───────────────────────────────────────────────────
+  listFields: string[];                         // columns shown in the table (existing name kept)
+  listDisplayLinks?: string[];                  // NEW. columns that click-through to edit (default: [first])
+  searchFields?: string[];                      // NEW. strings → regex search; surfaces search box in UI
+  sortableFields?: string[];                    // NEW. allowlist; default = all in listFields
+  defaultSort?: string | string[];              // existing name kept
+  pageSize?: number;                            // NEW. default rows per page (default: 25)
+
+  filters?: AdminFilter[];                      // NEW. sidebar filters (see below)
+
+  // ── Form view ───────────────────────────────────────────────────
+  fieldsets?: AdminFieldset[];                  // NEW. grouped form layout; mutually exclusive with fieldOrder
+  fieldOrder?: string[];                        // existing
+  readonlyFields?: string[];                    // NEW. display-only; enforced server-side
+  excludeFields?: string[];                     // NEW. stronger than hiddenFields — not in forms OR detail responses
+  hiddenFields?: string[];                      // existing (not in list/form; still in raw detail unless also excluded)
+  autocompleteFields?: string[];                // NEW. ref fields → async search (uses /search)
+  fieldOverrides?: Record<string, AdminFieldOverride>;  // existing
+
+  // ── Permissions & scoping ───────────────────────────────────────
+  adminPermissions?: Partial<{                  // NEW. per-action override (default: IsAdmin for all)
+    list: Permission[];
+    read: Permission[];
+    create: Permission[];
+    update: Permission[];
+    delete: Permission[];
+  }>;
+  /** NEW. Row-level scoping for admins. Async to allow fetching scope info (e.g., user.organizationId → org members). */
+  adminFilter?: (req: AuthedRequest) => Promise<mongoose.FilterQuery<T>> | mongoose.FilterQuery<T>;
+
+  // ── Bulk actions ────────────────────────────────────────────────
+  actions?: AdminAction<T>[];                   // NEW
+
+  // ── Realtime (API surface only in this IP) ──────────────────────
+  realtime?: boolean;                            // NEW. when true, scrubbed emit fires after each mutation
+
+  // ── Forward-compat placeholder (v1.1) ───────────────────────────
+  includeDeleted?: boolean;                     // NEW (type only; behavior in v1.1)
+}
+
+export interface AdminFilter {
+  field: string;                                 // schema field name (must be in queryFields)
+  type: "boolean" | "choice" | "date" | "dateRange" | "ref" | "text";
+  label?: string;                                // display label (default: humanized field name)
+  choices?: { value: string; label: string }[]; // for "choice"; auto-derived from schema enum if absent
+  refModel?: string;                             // for "ref"; auto-derived from schema ref if absent
+}
+
+export interface AdminFieldset {
+  title: string;
+  fields: string[];
+  collapsed?: boolean;
+  description?: string;
+}
+
+export interface AdminFieldOverride {
+  widget?: string;                               // widget key (resolved against the frontend widget registry)
+  label?: string;
+  helpText?: string;
+}
+
+export interface AdminAction<T = unknown> {
+  name: string;                                  // url-safe id
+  label: string;                                 // shown in dropdown
+  description?: string;
+  confirm?: string;                              // confirmation prompt text
+  permissions?: Permission[];                    // defaults to model's adminPermissions.update
+  background?: boolean;                          // route through BackgroundTask + AdminScriptRunModal
+  run: (ctx: AdminActionContext<T>) =>
+    Promise<{ updatedIds?: string[]; message?: string; results?: string[] }>;
+}
+
+/**
+ * Frozen, request-independent context handed to `action.run`. For sync actions, captured immediately
+ * before invocation. For `background: true` actions, captured at enqueue time and persisted on the
+ * BackgroundTask — `req` may be torn down by the time the background runner picks it up.
+ *
+ * Mirrors the `ScriptContext` pattern in admin-backend/src/adminApp.ts:622-638.
+ */
+export interface AdminActionContext<T = unknown> {
+  /** Snapshot of `req.user._id` at enqueue. */
+  userId: string;
+  /** Snapshot of `req.user` (lean, no methods). May be stale for long-running background actions. */
+  user: Pick<UserDocument, "_id" | "email" | "admin" | "name">;
+  /** Validated ids that exist AND pass the model's `adminFilter`. Capped at `MAX_ACTION_IDS`. */
+  ids: string[];
+  /** Echoed back from URL. */
+  actionName: string;
+  /** Stable id for log correlation. */
+  requestId: string;
+  /** ISO timestamp captured at enqueue. */
+  startedAt: string;
+  /** Model the action is acting on (avoids importing model registry from inside run). */
+  model: Model<T>;
+  /** Logger pre-tagged with {actionName, requestId, userId}. */
+  logger: Logger;
+}
+
+/** Server-side cap on `ids[]` accepted in a single action invocation. Documented; enforced; configurable per-app. */
+export const MAX_ACTION_IDS = 1000;
+```
+
+### `AdminContribution` (on plugins)
+
+```typescript
+export interface AdminContribution {
+  /** Model admins this plugin provides. Equivalent to registering a modelRouter with admin set. */
+  models?: AdminModelContribution[];
+
+  /** Standalone screens for things like DocumentStorageBrowser. */
+  customScreens?: AdminCustomScreen[];
+
+  /** Optional contributions to the home page. Host must list the id in home.widgets to surface it. */
+  homeWidgets?: AdminHomeWidgetContribution[];
+
+  /** Server-side admin scripts (one-off jobs). */
+  scripts?: AdminScriptConfig[];
+}
+
+export interface AdminModelContribution<T = unknown> {
+  model: Model<T>;
+  routePath: string;
+  admin: AdminConfig<T>;
+  permissions?: RESTPermissions<T>;              // public-API permissions if the plugin owns the router
+}
+
+export interface AdminCustomScreen {
+  name: string;                                  // url-safe id, used in URL (/admin/{name})
+  displayName: string;
+  icon?: string;
+  group?: string;
+}
+
+export interface AdminHomeWidgetContribution {
+  id: string;                                    // referenced by host from home.widgets
+  displayName: string;
+  icon?: string;
+  /** Optional list of model names whose changes the widget cares about (used by the future realtime layer). */
+  watches?: string[];
+}
+
+export interface TerrenoPlugin {
+  /**
+   * Existing signature is preserved with one BACKWARD-COMPATIBLE extension: a third optional `terrenoApp`
+   * argument carrying the parent `TerrenoApp`. Plugins that ignore it work unchanged.
+   *
+   * `TerrenoApp.build()` always passes `(app, oapi, this)` from terrenoApp.ts:321.
+   */
+  register(app: express.Application, openApi?: unknown, terrenoApp?: TerrenoApp): void;
+
+  /** NEW (optional). Called by `AdminApp` during its own `register()` to collect contributions. */
+  adminContribution?(): AdminContribution;
+}
+```
+
+**Why this signature, not constructor injection or a `terreno.useAdmin(...)` method:** keeps plugin construction order (`new AdminApp({...})`) free of references to `TerrenoApp`, mirrors how `openApi` is already passed, and is a backward-compatible additive change. All existing plugins (`HealthApp`, `BetterAuthApp`, `ConfigurationApp`, `FeatureFlagsApp`, `LangfuseApp`, `DocumentStorageApp`, `ConsentApp`) compile unchanged.
+
+**modelRouter discovery side:** `ModelRouterRegistration._buildWithOpenApi(openApi)` (api/src/api.ts:449) becomes `_buildWithContext({openApi, terrenoApp})`. `TerrenoApp.build()` passes itself in at registration time. The built router closes over the TerrenoApp reference so its lifecycle hooks can call `terrenoApp.emit("admin:model.changed", ...)`. The existing function signature is renamed; this is internal API. No public consumer should be calling `_buildWithOpenApi` directly.
+
+### `AdminApp` options (host-side)
+
+```typescript
+new AdminApp({
+  basePath?: "/admin";                            // existing
+  models?: AdminModelContribution[];              // existing; accepts the legacy shape too (with warning)
+  scripts?: AdminScriptConfig[];                  // existing
+  home?: AdminHomeConfig;                         // NEW
+});
+
+export interface AdminHomeConfig {
+  title?: string;
+  widgets?: (AdminHomeWidgetSpec | string)[];     // strings resolve to plugin-contributed widgets by id
+  layout?: "grid" | "list";
+}
+
+export type AdminHomeWidgetSpec =
+  | { type: "modelStats"; models?: string[] }            // counts for selected models
+  | { type: "recentActivity"; limit?: number; models?: string[] }
+  | { type: "scriptRunner" }
+  | { type: "customScreensList" }
+  | { type: "modelsGrid"; group?: string }               // legacy auto-grid (default if no home given)
+  | string                                                 // plugin-contributed widget id
+  | React.ComponentType;                                   // ad-hoc inline component
+```
+
+## `/admin/config` response (extended)
+
+```typescript
+interface AdminConfigResponse {
+  models: AdminModelMeta[];               // existing, with fields below added
+  scripts: AdminScriptMeta[];             // existing
+  customScreens: AdminCustomScreen[];     // existing, plugin contributions merged in
+  home?: AdminHomeMeta;                   // NEW
+  widgetIds: string[];                    // NEW: plugin-contributed widget ids the frontend should look up
+  capabilities: {                         // NEW: simple feature flags so older frontends fail soft
+    actions: boolean;
+    filters: boolean;
+    fieldsets: boolean;
+    realtime: boolean;
+  };
+}
+
+interface AdminModelMeta {
+  name: string;
+  routePath: string;
+  displayName: string;
+  group?: string;
+  icon?: string;
+
+  listFields: string[];                   // existing name kept; canonical
+  listDisplayLinks: string[];             // defaults to [first of listFields]
+  searchFields: string[];                 // empty array if search not configured
+  sortableFields: string[];               // defaults to listFields
+  defaultSort: string;                    // existing name kept
+  pageSize: number;                       // default 25
+
+  filters: AdminFilterMeta[];
+
+  fieldsets?: AdminFieldset[];            // if absent, frontend falls back to fieldOrder
+  fieldOrder?: string[];                  // existing
+  readonlyFields: string[];
+  excludeFields: string[];
+  hiddenFields: string[];                 // existing; emitted alongside excludeFields for clarity
+  autocompleteFields: string[];
+  fields: Record<string, AdminFieldMeta>; // existing
+  fieldOverrides: Record<string, AdminFieldOverride>;  // emitted so the frontend can resolve widgets
+
+  actions: AdminActionMeta[];             // {name, label, confirm, background, allowed: boolean}
+  permissions: {                          // booleans for the current user (computed server-side per request)
+    list: boolean; read: boolean; create: boolean; update: boolean; delete: boolean;
+  };
+  realtime: boolean;
+}
+```
+
+### Widget registry shape (locked here so Phase 3/4/5 don't reinvent it)
+
+```typescript
+export interface AdminWidgetRegistry {
+  /** Field widgets resolve `fieldOverrides[fieldName].widget` to a form-field component. */
+  fields: Record<string, FieldWidgetComponent>;
+  /** Home widgets resolve `home.widgets` string ids (and plugin-contributed widget ids) to a dashboard component. */
+  home: Record<string, HomeWidgetComponent>;
+  /** Screen widgets resolve `customScreens[].name` to a full-page screen component. Used by AdminScreenRouter. */
+  screens: Record<string, ScreenWidgetComponent>;
+}
+```
+
+Three separate buckets because (a) the lookup happens in three different places, (b) the component props differ (field widgets receive `value`/`onChange`; home widgets receive `config`; screen widgets receive route params), and (c) lets each bucket evolve its prop contract independently. Same string id can exist in two buckets without conflict.
+
+### Realtime emit step (no leakage)
+
+```typescript
+// inside modelRouter postCreate/postUpdate/postDelete, guarded by options.admin?.realtime === true:
+const safeDoc = scrubAdminFields(savedDoc, options.admin); // strips excludeFields + hiddenFields
+terrenoApp.emit("admin:model.changed", {
+  type: "create" | "update" | "delete",
+  modelName: model.modelName,
+  routePath: registration.path,
+  documentId: String(savedDoc._id),
+  document: safeDoc, // already scrubbed
+  user: { id: String(req.user._id) },
+  at: new Date().toISOString(),
+});
+```
+
+`scrubAdminFields` shares the implementation of `removeHiddenFields` (admin-backend/src/adminApp.ts:132). For delete events, `document` is omitted entirely.
+
+The current-user permission booleans are computed **per-request** (`/admin/config` is gated by `IsAdmin`, but per-action permissions may further restrict). This lets the frontend hide "Create" buttons the user can't use.
+
+## URL conventions
+
+Concrete example (Users model with `routePath: "/users"` and an `activate` action):
+
+```
+GET  /admin/config
+GET  /admin/users?page=2&pageSize=25&sort=-created&q=alice&filter[admin]=true&filter[role]=staff
+GET  /admin/users/507f1f77bcf86cd799439011
+POST /admin/users
+PATCH /admin/users/507f1f77bcf86cd799439011
+DELETE /admin/users/507f1f77bcf86cd799439011
+GET  /admin/users/search?q=ali&fields=email,name              ← used by autocompleteFields ref pickers
+POST /admin/users/actions/activate                            ← body: {ids: string[]} (≤ MAX_ACTION_IDS=1000)
+POST /admin/scripts/syncConsents/run                          ← existing
+GET  /admin/scripts/tasks/abc123                              ← existing (also used for background actions)
+GET  /admin/widgets/feature-flags-overrides/data              ← OPTIONAL — plugin widgets may register a data endpoint
+```
+
+### Filter param parsing (strict per-type)
+
+Express+`qs` parses `filter[k]=v`, `filter[k][gte]=v`, and `filter[k][]=v` into different shapes. The filter parser declares one accepted shape per `AdminFilter.type`; everything else returns HTTP 400 with `{title: "Invalid filter", fields: {<filterName>: "..."}}`:
+
+| `type` | Accepted shape | Rejects |
+|--------|----------------|---------|
+| `boolean` | scalar `"true"` \| `"false"` | arrays, nested objects, anything else |
+| `text` | scalar string | arrays, objects |
+| `choice` | scalar string in declared choices | arrays, objects, unknown values |
+| `ref` | scalar string that is a valid ObjectId | arrays, objects, non-ObjectId strings |
+| `date` | scalar ISO date string | arrays, objects |
+| `dateRange` | `{ gte?: ISO, lte?: ISO }` only — both keys optional but no others | arrays, scalars, extra keys |
+
+Mongo operator keys (`$ne`, `$gt`, `$where`, `$regex`, `$in`, …) are NEVER passed through. Prototype-pollution attempts (`__proto__`, `constructor.prototype`, …) are dropped silently and logged at warn level. Only fields declared in `admin.filters[]` are honored at all.
+
+## Server-side enforcement (security-critical)
+
+| Concern | Enforcement |
+|---------|-------------|
+| `readonlyFields` | Stripped from POST + PATCH bodies AND from array sub-routes (`POST /:id/:field`, `PATCH /:id/:field/:itemId`, `DELETE /:id/:field/:itemId`). Single enforcement point: a body-scrubbing middleware installed on every body-accepting admin route, not just `preUpdate`. |
+| `excludeFields` / `hiddenFields` | Stripped from POST + PATCH bodies and from list + detail responses. **Recursively applied through `populatePaths`**: when a populated doc is encountered, scrub it against *its* model's admin config (if any). Models with no admin config are returned as-is — consumer's responsibility not to populate sensitive refs without admin-registering them. |
+| `adminPermissions` | Per-route guard. Class-level evaluation (no object): `checkPermissions(action, perms, user, undefined)`; any throw → `false`. `IsOwner` returns `false` at the class level (no object to own). Per-action endpoints additionally run `action.permissions`. |
+| `adminFilter` | Async signature. Applied as a `$and` to the modelRouter's existing `queryFilter` for all list/read/update/delete on the admin namespace. |
+| `filters` | Per-type strict shape (see "Filter param parsing"). Only fields in `admin.filters[]` honored. Mongo operator keys never pass through. Prototype-pollution attempts dropped. |
+| `actions[].run` | Receives a frozen `AdminActionContext` (snapshot of user+ids+metadata at enqueue) — never the live `req`. Ids are validated via a single `find({_id: {$in: ids}, ...adminFilter})` round-trip; ids that don't pass `adminFilter` are silently excluded from the action's `ctx.ids`. |
+| `MAX_ACTION_IDS` | `ids[]` capped at 1000 per request. Above → 413 Payload Too Large. Configurable per-app via `AdminApp.maxActionIds`. |
+| `sortableFields` | Only allowlisted sort fields accepted. Unknown → 400. |
+| Search | Regex over `searchFields` only; query string escaped (existing pattern). ObjectId fast-path for valid IDs. List endpoint's `?q=` and the `/search` endpoint share a single helper function — no two implementations of the same semantics. |
+| Realtime emit | Emit happens *after* `removeHiddenFields`/`removeExcludeFields` scrub. Listeners (current AND future socket transport) never see hidden/excluded data. Delete events omit `document` entirely. |
+
+## Realtime API surface (no transport in this IP)
+
+Introduce a typed event bus on `TerrenoApp`:
+
+```typescript
+type AdminChangeEvent = {
+  type: "create" | "update" | "delete";
+  modelName: string;
+  routePath: string;
+  documentId: string;
+  document?: unknown;            // omitted for delete
+  user: { id: string };          // who made the change
+  at: string;                    // ISO timestamp
+};
+
+class TerrenoApp {
+  on(event: "admin:model.changed", listener: (e: AdminChangeEvent) => void): void;
+  off(event: "admin:model.changed", listener: (e: AdminChangeEvent) => void): void;
+  // (internal) emit("admin:model.changed", event)
+}
+```
+
+`modelRouter` `postCreate`/`postUpdate`/`postDelete` hooks emit when `admin.realtime === true`. AdminApp registers a no-op listener that logs in debug mode. **No socket server is started.** The follow-up IP wires this to Socket.io. Frontend hooks accept an optional `socket` in `AdminProvider` and behave normally when absent.
+
+## Files to Create / Modify
+
+### `@terreno/api`
+
+| File | Change |
+|------|--------|
+| `api/src/api.ts` | Add `admin?: AdminConfig` to `ModelRouterOptions`. Wrap lifecycle hooks to emit `admin:model.changed` when `admin.realtime` is true. |
+| `api/src/terrenoApp.ts` | Add `getRegistrations()`, `getPlugins()`, `on/off/emit` typed event bus. |
+| `api/src/terrenoPlugin.ts` | Add `adminContribution?(): AdminContribution` to the interface. |
+| `api/src/adminTypes.ts` (NEW) | Export `AdminConfig`, `AdminFilter`, `AdminFieldset`, `AdminAction`, `AdminContribution`, `AdminChangeEvent`. (Live in `api` so plugins can import without depending on `admin-backend`.) |
+| `api/src/index.ts` | Re-export the new types. |
+| `api/src/api.test.ts` | Tests for emit-on-mutation gate, readonlyFields enforcement when admin config present. |
+
+### `@terreno/admin-backend`
+
+| File | Change |
+|------|--------|
+| `admin-backend/src/adminApp.ts` | Rewrite to aggregate from registered model routers, plugin contributions, and legacy `models[]`. Extend `/admin/config` response. Add filter/sort/search parsing. Add `/actions/:name` endpoint. Compute per-action permission booleans. |
+| `admin-backend/src/legacy.ts` (NEW) | Adapt the legacy `AdminModelConfig` shape (`listFields`, etc.) to `AdminModelContribution`. Emit one-time deprecation warning per legacy entry. |
+| `admin-backend/src/filterParser.ts` (NEW) | Convert `filter[k]=v` query params into a safe Mongoose filter using the model's declared `AdminFilter[]`. |
+| `admin-backend/src/actionRunner.ts` (NEW) | Validate selected ids against `adminFilter`, run sync or background, return result. |
+| `admin-backend/src/index.ts` | Export `AdminApp` + types. |
+| `admin-backend/src/adminApp.test.ts` | Extend with tests for filter parsing, action invocation, plugin contribution aggregation, legacy shape acceptance. |
+
+### `@terreno/admin-frontend`
+
+| File | Change |
+|------|--------|
+| `admin-frontend/src/AdminProvider.tsx` (NEW) | React context: `{ api, baseUrl, widgets, socket?, theme? }`. Wraps the admin tree. |
+| `admin-frontend/src/AdminScreenRouter.tsx` (NEW) | Data-driven dispatcher: reads `customScreens` from config, looks up component by name in registry, falls back to `AdminModelTable`. |
+| `admin-frontend/src/AdminHome.tsx` (NEW; replaces AdminModelList semantically) | Renders `home.widgets` from config. Built-in widget components for `modelStats`, `recentActivity`, `scriptRunner`, `customScreensList`, `modelsGrid`. |
+| `admin-frontend/src/AdminModelTable.tsx` | Add: search box (debounced, surfaces `?q=`), filter drawer (right-side, collapsible, mobile sheet), bulk-select column, actions dropdown, `sortableFields` enforcement, `pageSize` honored. |
+| `admin-frontend/src/AdminModelForm.tsx` | Add: fieldsets (collapsible groups), `readonlyFields`, `autocompleteFields` → async ref picker, `excludeFields` honored. |
+| `admin-frontend/src/AdminFieldRenderer.tsx` | Read widget map from `AdminProvider` context instead of hardcoded switch. |
+| `admin-frontend/src/AdminFilterDrawer.tsx` (NEW) | Right-side drawer with one input per `AdminFilter`. Builds `filter[k]=v` query string. |
+| `admin-frontend/src/AdminActionMenu.tsx` (NEW) | Dropdown next to bulk-select count. Confirms, sends POST to `/actions/:name`. For `background` actions, opens existing `AdminScriptRunModal`. |
+| `admin-frontend/src/widgets/ModelStatsWidget.tsx` (NEW) | Renders counts via `useListQuery({page:1,pageSize:1})`. |
+| `admin-frontend/src/widgets/RecentActivityWidget.tsx` (NEW) | Lists latest documents across selected models. |
+| `admin-frontend/src/widgets/ScriptRunnerWidget.tsx` (NEW) | Compact script list (existing AdminScriptList trimmed). |
+| `admin-frontend/src/widgets/ModelsGridWidget.tsx` (NEW) | The legacy "grid of every model" widget — the default home. |
+| `admin-frontend/src/widgets/CustomScreensListWidget.tsx` (NEW) | Lists plugin-contributed custom screens. |
+| `admin-frontend/src/types.ts` | Add: `AdminWidgetComponent`, `AdminWidgetRegistry`, `AdminContextValue`. Mirror the backend `AdminConfigResponse` shape. |
+| `admin-frontend/src/AdminModelList.tsx` | Deprecate — keep as a thin wrapper that renders `<AdminHome widgets={[{type:"modelsGrid"}, {type:"scriptRunner"}, ...]}>` so existing consumers don't break. Mark for removal in v2. |
+| `admin-frontend/src/index.tsx` | Export `AdminProvider`, `AdminHome`, `AdminScreenRouter`, widgets, types. |
+
+### Pre-built admins (light contribution refactors)
+
+| File | Change |
+|------|--------|
+| `feature-flags/src/featureFlagsApp.ts` | Implement `adminContribution()` returning the model admin + a `feature-flags-overrides` home widget. Delete bare `featureFlagAdminConfig` export (deprecate first). |
+| `feature-flags/src/featureFlagAdminWidget.tsx` (NEW, in a frontend-shipping path) | The flag-overrides home widget component. |
+| `api/src/consent/consentApp.ts` (wherever it lives) | Implement `adminContribution()` returning ConsentForm + ConsentResponse admins, plus `widgetComponents` for `locale-content`, `locale-default`, `checkbox-list`. |
+| `admin-backend/src/documentStorageApp.ts` | Convert to a proper plugin contribution: `adminContribution()` returns `customScreens: [{name:"documents", displayName:"Documents", icon:"folder"}]`. Frontend component registered via the widget registry. |
+| `ai/src/aiAdminApp.ts` (NEW or split out of routes) | Implement `adminContribution()` returning a custom screen for AI Requests Explorer. Consumer no longer needs to hand-roll it. |
+
+### Example apps
+
+| File | Change |
+|------|--------|
+| `example-backend/src/server.ts` | Demonstrate new pattern: pass `admin:` on each modelRouter, remove the verbose `AdminApp.models` repetition. Show declarative `home: { widgets }`. Leave one legacy `models[]` entry to demonstrate back-compat. |
+| `example-backend/src/api/users.ts`, `api/todos.ts` | Add `admin:` config to each. |
+| `example-frontend/app/admin/_layout.tsx` | Wrap in `<AdminProvider api={api} baseUrl="/admin" widgets={{...}}>`. |
+| `example-frontend/app/admin/[model]/index.tsx` | Replace string-switch with `<AdminScreenRouter modelName={...}>`. |
+| `example-frontend/app/admin/index.tsx` | Render `<AdminHome />` (was `<AdminModelList ...>`). |
+
+### Documentation
+
+| File | Change |
+|------|--------|
+| `docs/how-to/admin-add-model.md` (NEW) | "Add an admin for your model in three lines." |
+| `docs/how-to/admin-custom-widget.md` (NEW) | "Build and register a custom field widget." |
+| `docs/how-to/admin-custom-home.md` (NEW) | "Customize the admin home page." |
+| `docs/how-to/admin-import-prebuilt.md` (NEW) | "Import the consent / feature-flags admins." |
+| `docs/reference/admin-config.md` (NEW) | Full `AdminConfig` reference, mapped from Django equivalents. |
+| `docs/implementationPlans/admin-improvements.md` | (this file) |
+
+## Backward Compatibility & Migration
+
+- `AdminApp({models: [{model, listFields, ...}]})` — accepted as-is for one minor release. Logged once-per-process as `[admin] AdminApp.models entry for "Users" uses the legacy shape (listFields/fieldOverrides). Migrate to modelRouter({...,admin:{listDisplay,...}}) — see docs/how-to/admin-add-model.md.`
+- `listFields` accepted as an alias for `listDisplay` in the same window. Same one-time warning.
+- `defaultSort` accepted as an alias for `ordering`.
+- `hiddenFields` continues to mean "stripped from responses" (today's behavior). `excludeFields` is the new stronger version (stripped from forms AND responses). When both are set: union.
+- `customScreens` array prop on `AdminModelList` becomes a no-op once the consumer switches to `AdminProvider` + `AdminScreenRouter`. We log a one-time warning if both are used.
+- All existing endpoints (`GET /admin/config`, `GET /admin/{routePath}`, …) continue to work with the same payloads, plus additive fields. Old frontends see `capabilities.{actions,filters,fieldsets} === false` and skip the new UI affordances.
+
+## Phases
+
+### Phase 1 — Core API surface (`@terreno/api`)
+Adds `AdminConfig`, plugin contribution interface, and the event bus. No UI changes; everything stays backward compatible.
+
+### Phase 2 — Admin backend aggregation
+Rewrites `AdminApp` to aggregate from registered routers and plugin contributions. Extends `/admin/config`. Adds filter parsing, action runner, server-side `readonlyFields`/`excludeFields` enforcement.
+
+### Phase 3 — Admin frontend foundations
+`AdminProvider`, `AdminScreenRouter`, widget registry, `AdminHome`, built-in widgets. No new table/form features yet — keep existing screens working through the new context.
+
+### Phase 4 — Admin frontend feature lift
+Search box, filter drawer, bulk-select + actions, fieldsets, `readonlyFields`, autocomplete refs. Each is a small PR.
+
+### Phase 5 — Pre-built admin migrations
+`feature-flags`, `consent`, `documentStorage`, `ai` all adopt `adminContribution()`. Each pre-built admin gets a one-line consumer story.
+
+### Phase 6 — Examples and docs
+`example-backend` and `example-frontend` rewritten to showcase. Four how-to docs and the reference.
+
+### Phase 7 — Deprecations & polish
+Warning messages, telemetry/log lines, codemod note in CHANGELOG.
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| Field-rename churn. | No renames. Only additive new options. Existing `listFields`, `defaultSort`, `fieldOverrides`, `fieldOrder`, `hiddenFields` keep their names. |
+| Plugin discovery — `AdminApp` needs the parent `TerrenoApp`. | Extend `TerrenoPlugin.register(app, openApi?, terrenoApp?)` backward-compat additively. `TerrenoApp.build()` passes itself. Internal `_buildWithContext` on `ModelRouterRegistration` carries the same reference into modelRouter. |
+| **routePath collisions.** Two registered modelRouters with the same `routePath` → fatal at build time (throw). | Plugin contribution and legacy `AdminApp.models` are additive: registered modelRouter wins over plugin wins over legacy. Loudest collision logs are the registered-vs-registered case. |
+| Filter-injection. | Per-type strict shape (see "Filter param parsing"). Mongo operator keys never pass through. Declared-only fields honored. |
+| Action runner footguns (deleting too many rows). | `confirm` text rendered server-side. `MAX_ACTION_IDS=1000`. Single `$in` validation; ids outside `adminFilter` scope silently excluded. Background actions get a frozen context, not the live `req`. |
+| Realtime payload leakage. | Emit fires *after* `excludeFields`/`hiddenFields` scrub. Verified by test that asserts `hash` is absent from the emitted payload for a User-like model. |
+| Widget registry typing. | Three buckets: `{ fields, home, screens }`. Each bucket has a typed component contract. Runtime fallback to a "missing widget" placeholder + one-time `console.warn` if a referenced key is absent. |
+| `realtime: true` emits events with nowhere to go in v1. | Default `false`. Listener is no-op (debug-logged). Documented as forward-compat. |
+| `AdminScreenRouter` rollout breaks consumers' existing string-switch. | Both paths supported during transition; warning emitted if consumer's `customScreens` prop and `AdminProvider` widgets are both set. |
+| Per-user permission booleans in `/admin/config` make it uncacheable. | `Cache-Control: private, no-store` header. Endpoint already gated by `IsAdmin`. Test guards response size stays under 50KB for 30 models. |
+| Background action runner uses stale `req.user`. | Captured snapshot only. Background task records `userId` separately; the snapshot is a hint, not authoritative. Re-resolve user via `userModel.findById(ctx.userId)` inside `action.run` if fresh data is needed. |
+| `EventEmitter` default max listeners (10). | `TerrenoApp` constructor calls `setMaxListeners(50)` on its emitter. Documented. |
+| Bundle size of widget registry. | Widgets are React components passed at provider construction time — consumers control which they import. Lazy-load via React.lazy is the consumer's choice (no built-in lazy support in v1). |
+| Custom-screen pages in `example-frontend/app/admin/consent-forms/` etc. | Phase 6 explicitly audits these directories; behaviors that the generic `AdminScreenRouter` doesn't subsume become contributed screen widgets. |
+
+## Acceptance Criteria (high level — full per-task in the task file)
+
+1. A model with `admin: {...}` on its `modelRouter` appears in `/admin/config` with full metadata, without being passed to `AdminApp.models`.
+2. Registering `new FeatureFlagsApp(...)` causes the `FeatureFlag` admin to appear automatically and `home.widgets: ["feature-flags-overrides"]` renders its widget.
+3. Search box in the table debounces and surfaces hits using the existing `/search` endpoint scoped to `searchFields`.
+4. Filter drawer renders one control per `AdminFilter`; combining filters narrows the list correctly server-side.
+5. Bulk-select + actions: selecting rows and choosing an action POSTs `{ids}` to `/admin/{routePath}/actions/:name`. Sync actions return updated rows; `background: true` actions route through `AdminScriptRunModal` and show progress.
+6. `readonlyFields` are visible in the form but disabled, and a manual PATCH that tries to change them is silently dropped server-side.
+7. `fieldsets` render as collapsible groups in `AdminModelForm`.
+8. `autocompleteFields` ref pickers async-search via `/search` instead of fetching the whole referenced collection.
+9. The admin home page renders the configured widgets in the configured order. Plugin-contributed widgets only appear when listed.
+10. The legacy `AdminApp({models: [{listFields: [...]}]})` shape continues to work and emits exactly one deprecation warning per legacy entry.
+11. No socket server is started; no realtime events fire to clients. `admin.realtime: true` causes `TerrenoApp.emit("admin:model.changed", ...)` to fire (verified in unit test).
+12. `example-backend` boots; `example-frontend` admin renders; all existing example admin flows still work.
+13. All new types are exported from `@terreno/api`, `@terreno/admin-backend`, `@terreno/admin-frontend`.
+14. Test coverage: filter parser, action runner, readonlyFields enforcement, plugin aggregation, legacy shape adapter, widget registry resolution, search debounce.
+
+## Out of scope (explicit)
+
+- Socket.io server / realtime UI updates.
+- MongoDB change-stream emitter.
+- True related-model inlines.
+- `date_hierarchy`, `prepopulated_fields`, `list_editable`, `show_facets`.
+- Theming / brand customization beyond `home.title`.
+- Multi-AdminSite (Django allows several `AdminSite` instances).