@terreno/mcp 57.14.0 → 57.16.1

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

@@ -1,577 +0,0 @@
-# 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).