@terreno/admin-backend 0.20.2 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ ## Admin Panel (backend)
2
+
3
+ The backend uses `@terreno/admin-backend`'s `AdminApp` for auto-generated admin CRUD endpoints.
4
+ All admin routes require `IsAdmin` permission and are mounted at `/admin`.
5
+ Add models to `AdminApp` in `src/server.ts` to expose them in the admin panel.
@@ -9,7 +9,7 @@ A monorepo containing shared packages for building full-stack applications with
9
9
  - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
10
10
  - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
11
11
  - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
12
- - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
12
+ - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp`, bins `terreno-mcp` / `terreno-mcp-local`)
13
13
  - **demo/** - Demo app for showcasing and testing UI components
14
14
  - **example-frontend/** - Example Expo app demonstrating full stack usage
15
15
  - **example-backend/** - Example Express backend using @terreno/api
package/AGENTS.md CHANGED
@@ -9,7 +9,7 @@ A monorepo containing shared packages for building full-stack applications with
9
9
  - **rtk/** - Redux Toolkit Query utilities for API backends (`@terreno/rtk`)
10
10
  - **admin-backend/** - Admin panel backend plugin for @terreno/api (`@terreno/admin-backend`)
11
11
  - **admin-frontend/** - Admin panel frontend screens for @terreno/api backends (`@terreno/admin-frontend`)
12
- - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp-server`)
12
+ - **mcp-server/** - MCP server for AI assistant integration (`@terreno/mcp`, bins `terreno-mcp` / `terreno-mcp-local`)
13
13
  - **demo/** - Demo app for showcasing and testing UI components
14
14
  - **example-frontend/** - Example Expo app demonstrating full stack usage
15
15
  - **example-backend/** - Example Express backend using @terreno/api
@@ -332,6 +332,10 @@ GitHub Actions workflows that use secrets or environment variables must validate
332
332
  fi
333
333
  ```
334
334
 
335
+ ## @terreno/admin-backend — tests
336
+
337
+ `bunfig.toml` preloads [`src/tests/testEnv.ts`](./src/tests/testEnv.ts) (sets `TERRENO_TEST_USE_MEMORY_MONGO`) then [`api/src/tests/bunSetup.ts`](../api/src/tests/bunSetup.ts), which starts **mongodb-memory-server** and connects Mongoose (no local `mongod` required). To use a real MongoDB instead, remove or edit `testEnv.ts`, or set `TERRENO_TEST_MONGODB_URI` before running tests. Set `BUN_TEST_DISABLE_DB=true` to skip DB hooks entirely.
338
+
335
339
  ## Dependency Management
336
340
 
337
341
  Uses [Bun Catalogs](https://bun.sh/docs/install/catalogs) - shared versions defined in root `package.json` under `catalog`. Reference with `catalog:` in workspace packages.
package/bunfig.toml CHANGED
@@ -1,5 +1,5 @@
1
1
  [test]
2
- preload = ["../api/src/tests/bunSetup.ts"]
2
+ preload = ["./src/tests/testEnv.ts", "../api/src/tests/bunSetup.ts"]
3
3
  root = "./src"
4
4
  coveragePathIgnorePatterns = ["**/*.test.ts", "../api/**", "dist/**", "**/node_modules/**"]
5
5
  # Enforced by scripts/check-coverage.ts; Bun parses this key but does not
@@ -1,6 +1,7 @@
1
- import { type ScriptRunner } from "@terreno/api";
1
+ import { type ScriptRunner, type User } from "@terreno/api";
2
2
  import express from "express";
3
3
  import type { Model } from "mongoose";
4
+ import { type AdminActionInput, type AdminFieldsetInput, type AdminHomeInput, type AdminListFilter, type AdminModelPermissionsInput } from "./adminUiV2";
4
5
  /**
5
6
  * Configuration for a single model in the admin panel.
6
7
  */
@@ -25,6 +26,45 @@ export interface AdminModelConfig {
25
26
  fieldOrder?: string[];
26
27
  /** Fields to hide from admin forms/responses (e.g., password hash fields). */
27
28
  hiddenFields?: string[];
29
+ /** Optional sidebar / nav grouping label for schema v2 shells */
30
+ group?: string;
31
+ /** Changelist columns (defaults to listFields) */
32
+ listDisplay?: string[];
33
+ /** Subset of list columns rendered as links to detail */
34
+ listDisplayLinks?: string[];
35
+ /** Fields the changelist may sort by (informational + future enforcement) */
36
+ sortableFields?: string[];
37
+ /** Fields exposed to text / quick search in the admin UI */
38
+ searchFields?: string[];
39
+ /** Typed list filters (queryFields-compatible on the wire) */
40
+ filters?: AdminListFilter[];
41
+ /** Form layout: grouped fields */
42
+ fieldsets?: AdminFieldsetInput[];
43
+ /** Fields shown read-only in forms; stripped from PATCH bodies server-side */
44
+ readonlyFields?: string[];
45
+ /** Declarative row / selection actions */
46
+ actions?: AdminActionInput[];
47
+ /** Fine-grained CRUD toggles for admin UI + route wiring */
48
+ permissions?: AdminModelPermissionsInput;
49
+ /** Suggested page size for the changelist */
50
+ pageSize?: number;
51
+ /** UI-only hint that live updates may be available */
52
+ realtime?: boolean;
53
+ /**
54
+ * Field key used for the edit screen title (browser tab / stack header). When omitted, the
55
+ * admin UI derives a label from common keys (`name`, `title`, …) then the first scalar
56
+ * {@link listFields} column, matching audit label heuristics.
57
+ */
58
+ recordTitleField?: string;
59
+ /** Allowlisted keys for POST .../bulk-patch (defaults from listFields minus system/readonly/hidden) */
60
+ bulkPatchAllowlist?: string[];
61
+ /**
62
+ * Per-model `modelRouter` query filter (list and other query-shaped reads).
63
+ * Same contract as {@link ModelRouterOptions.queryFilter} in `@terreno/api`: merge into the
64
+ * Mongoose query, return the incoming `query` unchanged if allowed, or return `null` to yield
65
+ * an empty list without error.
66
+ */
67
+ queryFilter?: (user?: User, query?: Record<string, unknown>) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
28
68
  }
29
69
  /**
30
70
  * Configuration for a script that can be run from the admin panel.
@@ -37,6 +77,28 @@ export interface AdminScriptConfig {
37
77
  /** The function that executes the script. Must return string[] results. */
38
78
  runner: ScriptRunner;
39
79
  }
80
+ /**
81
+ * Emitted after successful admin modelRouter mutations when {@link AdminOptions.onAdminAudit}
82
+ * is configured.
83
+ */
84
+ export interface AdminAuditEvent {
85
+ /** Terreno user id performing the action, when available */
86
+ actorId?: string;
87
+ /** Mongoose model name (e.g. "Todo") */
88
+ modelName: string;
89
+ /** Target document id when known */
90
+ recordId?: string;
91
+ /** Short human-readable label derived from list fields */
92
+ recordLabel?: string;
93
+ verb: "created" | "deleted" | "updated";
94
+ }
95
+ /** Declares an extra admin UI screen route merged with built-ins (e.g. version-config). */
96
+ export interface AdminCustomScreenConfig {
97
+ displayName: string;
98
+ name: string;
99
+ /** Optional subtitle or help text shown with the screen card in the admin UI */
100
+ description?: string;
101
+ }
40
102
  /**
41
103
  * Configuration options for the AdminApp plugin.
42
104
  */
@@ -47,6 +109,15 @@ export interface AdminOptions {
47
109
  scripts?: AdminScriptConfig[];
48
110
  /** Base path for all admin routes. Defaults to "/admin". */
49
111
  basePath?: string;
112
+ /** Optional home dashboard layout (schema v2 slots) */
113
+ home?: AdminHomeInput;
114
+ /** Extra custom screens merged with built-ins (e.g. version-config) */
115
+ customScreens?: AdminCustomScreenConfig[];
116
+ /**
117
+ * Optional audit sink for admin CRUD after modelRouter succeeds.
118
+ * Consumers typically persist to an `AdminAuditLog` collection.
119
+ */
120
+ onAdminAudit?: (event: AdminAuditEvent, req: express.Request) => void | Promise<void>;
50
121
  }
51
122
  /**
52
123
  * TerrenoPlugin that auto-generates admin CRUD endpoints for Mongoose models.
@@ -74,6 +145,8 @@ export interface AdminOptions {
74
145
  * routePath: "/todos",
75
146
  * displayName: "Todos",
76
147
  * listFields: ["title", "completed", "ownerId"],
148
+ * // Optional: constrain admin list queries (e.g. tenant) — same as modelRouter queryFilter.
149
+ * queryFilter: (_user, query) => ({...query, tenantId: "acme"}),
77
150
  * },
78
151
  * ],
79
152
  * });