@terreno/admin-backend 0.20.1 → 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.
- package/.ai/guidelines/core.md +5 -0
- package/.github/copilot-instructions.md +1 -1
- package/AGENTS.md +5 -1
- package/bunfig.toml +1 -1
- package/dist/adminApp.d.ts +74 -1
- package/dist/adminApp.js +620 -83
- package/dist/adminApp.models.test.js +537 -8
- package/dist/adminApp.test.js +182 -0
- package/dist/adminUiV2.d.ts +96 -0
- package/dist/adminUiV2.js +189 -0
- package/dist/adminUiV2.test.d.ts +1 -0
- package/dist/adminUiV2.test.js +28 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +15 -0
- package/dist/tests/testEnv.d.ts +0 -0
- package/dist/tests/testEnv.js +6 -0
- package/package.json +5 -4
- package/src/adminApp.models.test.ts +284 -2
- package/src/adminApp.test.ts +95 -0
- package/src/adminApp.ts +598 -22
- package/src/adminUiV2.test.ts +28 -0
- package/src/adminUiV2.ts +188 -0
- package/src/index.ts +9 -1
- package/src/tests/testEnv.ts +5 -0
|
@@ -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-
|
|
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-
|
|
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
|
package/dist/adminApp.d.ts
CHANGED
|
@@ -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
|
* });
|