@terreno/admin-backend 57.3.0 → 57.4.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.
Files changed (44) hide show
  1. package/bunfig.toml +9 -1
  2. package/dist/adminApp.d.ts +20 -2
  3. package/dist/adminApp.js +468 -363
  4. package/dist/adminConfigIdentity.d.ts +1 -0
  5. package/dist/adminConfigIdentity.js +1 -0
  6. package/dist/adminMigrations.d.ts +10 -0
  7. package/dist/adminMigrations.js +205 -0
  8. package/dist/adminScriptJob.d.ts +32 -0
  9. package/dist/adminScriptJob.js +360 -0
  10. package/dist/adminTextSearch.d.ts +1 -0
  11. package/dist/adminTextSearch.js +1 -0
  12. package/dist/adminUiV2.d.ts +2 -0
  13. package/dist/aggregateAdmin.js +2 -0
  14. package/dist/enrichAdminListFilters.d.ts +7 -0
  15. package/dist/enrichAdminListFilters.js +37 -0
  16. package/dist/filterParser.js +139 -12
  17. package/dist/index.d.ts +2 -0
  18. package/dist/index.js +4 -1
  19. package/dist/legacy.js +4 -2
  20. package/dist/resolvedAdminModel.js +2 -1
  21. package/package.json +7 -7
  22. package/src/adminApp.migrations.test.ts +232 -0
  23. package/src/adminApp.models.test.ts +645 -1
  24. package/src/adminApp.syncMeta.test.ts +237 -0
  25. package/src/adminApp.test.ts +92 -0
  26. package/src/adminApp.ts +344 -124
  27. package/src/adminConfigIdentity.ts +1 -0
  28. package/src/adminHttpGoldens.test.ts +337 -0
  29. package/src/adminMigrations.ts +157 -0
  30. package/src/adminScriptJob.test.ts +297 -0
  31. package/src/adminScriptJob.ts +271 -0
  32. package/src/adminSyncMutationAuthMismatch.test.ts +650 -0
  33. package/src/adminTextSearch.test.ts +28 -0
  34. package/src/adminTextSearch.ts +1 -0
  35. package/src/adminUiV2.ts +2 -0
  36. package/src/aggregateAdmin.test.ts +125 -0
  37. package/src/aggregateAdmin.ts +2 -0
  38. package/src/enrichAdminListFilters.test.ts +44 -0
  39. package/src/enrichAdminListFilters.ts +29 -0
  40. package/src/filterParser.test.ts +95 -0
  41. package/src/filterParser.ts +156 -10
  42. package/src/index.ts +2 -0
  43. package/src/legacy.ts +5 -1
  44. package/src/resolvedAdminModel.ts +2 -1
@@ -12,6 +12,7 @@ const SOURCE_RANK: Record<AdminModelSource, number> = {
12
12
  registered: 2,
13
13
  };
14
14
 
15
+ /** @internal */
15
16
  export const slugFromAdminRoutePath = (routePath: string): string => {
16
17
  const trimmed = routePath.replace(/^\/+|\/+$/g, "").replace(/\//g, "-");
17
18
  if (!trimmed) {
@@ -0,0 +1,337 @@
1
+ /**
2
+ * Task 1.5 characterization goldens: pin today's admin REST membership contract
3
+ * (config shape, list query/pagination, search URL, bulk-patch URL/body) for a
4
+ * String `_id` model (Todo-like) and an ObjectId model (User).
5
+ */
6
+ import {afterEach, beforeEach, describe, it} from "bun:test";
7
+ import {
8
+ addAuthRoutes,
9
+ apiErrorMiddleware,
10
+ apiUnauthorizedMiddleware,
11
+ createdUpdatedPlugin,
12
+ setupAuth,
13
+ type UserModel as UserModelType,
14
+ } from "@terreno/api";
15
+ import {authAsUser, getBaseServer, setupDb, UserModel} from "@terreno/api/testing";
16
+ import {assert} from "chai";
17
+ import type express from "express";
18
+ import mongoose from "mongoose";
19
+ import type TestAgent from "supertest/lib/agent";
20
+
21
+ import type {AdminModelConfig} from "./adminApp";
22
+ import {AdminApp} from "./adminApp";
23
+ import {ADMIN_LIST_SEARCH_PARAM} from "./adminTextSearch";
24
+ import {ADMIN_SCHEMA_VERSION, MAX_BULK_PATCH_IDS} from "./adminUiV2";
25
+
26
+ const ADMIN_CONFIG_TOP_KEYS = [
27
+ "capabilities",
28
+ "customScreens",
29
+ "home",
30
+ "migrations",
31
+ "models",
32
+ "platformTools",
33
+ "schemaVersion",
34
+ "scripts",
35
+ "widgetIds",
36
+ ];
37
+
38
+ const ADMIN_CONFIG_CAPABILITY_KEYS = ["actions", "fieldsets", "filters", "realtime"];
39
+
40
+ const ADMIN_MODEL_META_ALLOWED_KEYS = new Set([
41
+ "actions",
42
+ "adminBroadcast",
43
+ "bulkPatchAllowlist",
44
+ "defaultSort",
45
+ "displayName",
46
+ "fieldOrder",
47
+ "fields",
48
+ "fieldsets",
49
+ "filters",
50
+ "group",
51
+ "hiddenFields",
52
+ "listDisplay",
53
+ "listDisplayLinks",
54
+ "listFields",
55
+ "name",
56
+ "organizationScoped",
57
+ "pageSize",
58
+ "permissions",
59
+ "readonlyFields",
60
+ "realtime",
61
+ "recordTitleField",
62
+ "routePath",
63
+ "searchFields",
64
+ "sortableFields",
65
+ "syncCollection",
66
+ ]);
67
+
68
+ const ADMIN_MODEL_META_REQUIRED_KEYS = [
69
+ "actions",
70
+ "adminBroadcast",
71
+ "bulkPatchAllowlist",
72
+ "defaultSort",
73
+ "displayName",
74
+ "fields",
75
+ "filters",
76
+ "hiddenFields",
77
+ "listDisplay",
78
+ "listDisplayLinks",
79
+ "listFields",
80
+ "name",
81
+ "organizationScoped",
82
+ "permissions",
83
+ "readonlyFields",
84
+ "realtime",
85
+ "routePath",
86
+ "searchFields",
87
+ "sortableFields",
88
+ ];
89
+
90
+ const LIST_PAGINATION_KEYS = ["data", "limit", "more", "page", "total"];
91
+
92
+ const SEARCH_ENVELOPE_KEYS = ["data"];
93
+
94
+ const BULK_PATCH_SUCCESS_KEYS = ["updated"];
95
+
96
+ // Todo-like String `_id` only. syncPlugin is out of scope for Task 1.5 REST membership goldens.
97
+ const goldenTodoSchema = new mongoose.Schema({
98
+ _id: {
99
+ default: (): string => new mongoose.Types.ObjectId().toHexString(),
100
+ description: "Client-minted string id",
101
+ type: String,
102
+ },
103
+ completed: {default: false, description: "Whether the todo is done", type: Boolean},
104
+ title: {description: "Todo title", required: true, type: String},
105
+ });
106
+ goldenTodoSchema.plugin(createdUpdatedPlugin);
107
+
108
+ const GoldenTodoModel =
109
+ mongoose.models.AdminHttpGoldenTodo ?? mongoose.model("AdminHttpGoldenTodo", goldenTodoSchema);
110
+
111
+ const todoModelConfig: AdminModelConfig = {
112
+ displayName: "Todos",
113
+ listFields: ["title", "completed"],
114
+ model: GoldenTodoModel,
115
+ pageSize: 2,
116
+ routePath: "/todos",
117
+ };
118
+
119
+ const userModelConfig: AdminModelConfig = {
120
+ displayName: "Users",
121
+ listFields: ["email", "name"],
122
+ model: UserModel,
123
+ routePath: "/users",
124
+ };
125
+
126
+ const sortedKeys = (value: object): string[] => {
127
+ return Object.keys(value).sort();
128
+ };
129
+
130
+ const assertModelMetaShape = (meta: Record<string, unknown>): void => {
131
+ for (const key of Object.keys(meta)) {
132
+ assert.isTrue(
133
+ ADMIN_MODEL_META_ALLOWED_KEYS.has(key),
134
+ `unexpected GET /admin/config models[] key: ${key}`
135
+ );
136
+ }
137
+ for (const key of ADMIN_MODEL_META_REQUIRED_KEYS) {
138
+ assert.property(meta, key);
139
+ }
140
+ };
141
+
142
+ const buildApp = (models: AdminModelConfig[]): express.Application => {
143
+ const app = getBaseServer();
144
+ setupAuth(app, UserModel as unknown as UserModelType);
145
+ addAuthRoutes(app, UserModel as unknown as UserModelType);
146
+ new AdminApp({basePath: "/admin", models}).register(app);
147
+ app.use(apiUnauthorizedMiddleware);
148
+ app.use(apiErrorMiddleware);
149
+ return app;
150
+ };
151
+
152
+ describe("admin HTTP goldens (membership + config)", () => {
153
+ let app: express.Application;
154
+ let adminAgent: TestAgent;
155
+
156
+ beforeEach(async () => {
157
+ await setupDb();
158
+ app = buildApp([todoModelConfig, userModelConfig]);
159
+ adminAgent = await authAsUser(app, "admin");
160
+ });
161
+
162
+ afterEach(async () => {
163
+ await GoldenTodoModel.deleteMany({});
164
+ });
165
+
166
+ it("pins GET /admin/config envelope and model routePaths", async () => {
167
+ const res = await adminAgent.get("/admin/config").expect(200);
168
+ const body = res.body as Record<string, unknown>;
169
+
170
+ assert.deepEqual(sortedKeys(body), [...ADMIN_CONFIG_TOP_KEYS].sort());
171
+ assert.strictEqual(ADMIN_SCHEMA_VERSION, 2);
172
+ assert.strictEqual(body.schemaVersion, 2);
173
+ assert.deepEqual(
174
+ sortedKeys(body.capabilities as object),
175
+ [...ADMIN_CONFIG_CAPABILITY_KEYS].sort()
176
+ );
177
+ assert.deepEqual(body.capabilities, {
178
+ actions: true,
179
+ fieldsets: true,
180
+ filters: true,
181
+ realtime: false,
182
+ });
183
+
184
+ const models = body.models as Record<string, unknown>[];
185
+ assert.lengthOf(models, 2);
186
+ const todoMeta = models.find((model) => model.routePath === "/admin/todos");
187
+ const userMeta = models.find((model) => model.routePath === "/admin/users");
188
+ assert.isDefined(todoMeta);
189
+ assert.isDefined(userMeta);
190
+ assertModelMetaShape(todoMeta as Record<string, unknown>);
191
+ assertModelMetaShape(userMeta as Record<string, unknown>);
192
+
193
+ assert.strictEqual(todoMeta?.name, "AdminHttpGoldenTodo");
194
+ assert.deepEqual(todoMeta?.listFields, ["title", "completed"]);
195
+ assert.strictEqual(todoMeta?.pageSize, 2);
196
+ assert.strictEqual(todoMeta?.defaultSort, "-created");
197
+ assert.include(todoMeta?.searchFields as string[], "title");
198
+ const todoFields = todoMeta?.fields as Record<string, {type: string}>;
199
+ assert.strictEqual(todoFields._id.type, "string");
200
+ assert.strictEqual(todoMeta?.adminBroadcast, false);
201
+ assert.notProperty(todoMeta as object, "syncCollection");
202
+
203
+ assert.strictEqual(userMeta?.name, "User");
204
+ assert.deepEqual(userMeta?.listFields, ["email", "name"]);
205
+ assert.strictEqual(userMeta?.routePath, "/admin/users");
206
+ const userFields = userMeta?.fields as Record<string, {type: string}>;
207
+ assert.strictEqual(userFields._id.type, "objectid");
208
+ });
209
+
210
+ it("pins String-_id list query params and pagination envelope", async () => {
211
+ await GoldenTodoModel.create({_id: "todo-alpha", title: "Alpha task"});
212
+ await GoldenTodoModel.create({_id: "todo-beta", title: "Beta task"});
213
+ await GoldenTodoModel.create({_id: "todo-gamma", title: "Gamma task"});
214
+
215
+ const paged = await adminAgent.get("/admin/todos?page=1&limit=2&sort=-created").expect(200);
216
+ assert.deepEqual(sortedKeys(paged.body), [...LIST_PAGINATION_KEYS].sort());
217
+ assert.strictEqual(paged.body.limit, 2);
218
+ assert.strictEqual(paged.body.more, true);
219
+ assert.strictEqual(paged.body.page, "1");
220
+ assert.strictEqual(paged.body.total, 3);
221
+ assert.lengthOf(paged.body.data, 2);
222
+ assert.strictEqual(typeof paged.body.data[0]._id, "string");
223
+ assert.match(paged.body.data[0]._id, /^todo-/);
224
+
225
+ const searched = await adminAgent.get("/admin/todos?q=Alpha").expect(200);
226
+ assert.strictEqual(ADMIN_LIST_SEARCH_PARAM, "q");
227
+ assert.lengthOf(searched.body.data, 1);
228
+ assert.strictEqual(searched.body.data[0].title, "Alpha task");
229
+ assert.strictEqual(searched.body.data[0]._id, "todo-alpha");
230
+ assert.strictEqual(searched.body.limit, 2);
231
+ assert.strictEqual(searched.body.more, false);
232
+ assert.strictEqual(searched.body.total, 1);
233
+ });
234
+
235
+ it("pins ObjectId User list query params and pagination envelope", async () => {
236
+ const paged = await adminAgent.get("/admin/users?page=1&limit=1&sort=-created").expect(200);
237
+ assert.deepEqual(sortedKeys(paged.body), [...LIST_PAGINATION_KEYS].sort());
238
+ assert.strictEqual(paged.body.limit, 1);
239
+ assert.strictEqual(paged.body.more, true);
240
+ assert.strictEqual(paged.body.page, "1");
241
+ assert.isAtLeast(paged.body.total, 3);
242
+ assert.lengthOf(paged.body.data, 1);
243
+ assert.strictEqual(typeof paged.body.data[0]._id, "string");
244
+ assert.match(paged.body.data[0]._id, /^[a-f0-9]{24}$/);
245
+
246
+ const searched = await adminAgent.get("/admin/users?q=notAdmin").expect(200);
247
+ assert.lengthOf(searched.body.data, 1);
248
+ assert.strictEqual(searched.body.data[0].email, "notAdmin@example.com");
249
+ assert.strictEqual(searched.body.limit, 100);
250
+ assert.strictEqual(searched.body.more, false);
251
+ assert.strictEqual(searched.body.total, 1);
252
+ });
253
+
254
+ it("pins GET .../search URL, q param, and {data} envelope for both id types", async () => {
255
+ await GoldenTodoModel.create({_id: "todo-search", title: "FindMe later"});
256
+
257
+ const todoSearch = await adminAgent.get("/admin/todos/search?q=FindMe").expect(200);
258
+ assert.deepEqual(sortedKeys(todoSearch.body), SEARCH_ENVELOPE_KEYS);
259
+ assert.lengthOf(todoSearch.body.data, 1);
260
+ assert.strictEqual(todoSearch.body.data[0]._id, "todo-search");
261
+
262
+ const emptyQ = await adminAgent.get("/admin/todos/search").expect(200);
263
+ assert.deepEqual(emptyQ.body, {data: []});
264
+
265
+ const userSearch = await adminAgent.get("/admin/users/search?q=notAdmin").expect(200);
266
+ assert.deepEqual(sortedKeys(userSearch.body), SEARCH_ENVELOPE_KEYS);
267
+ assert.lengthOf(userSearch.body.data, 1);
268
+ assert.strictEqual(userSearch.body.data[0].email, "notAdmin@example.com");
269
+ });
270
+
271
+ it("pins POST .../bulk-patch URL and {ids, patch} body for both id types", async () => {
272
+ const a = await GoldenTodoModel.create({
273
+ _id: new mongoose.Types.ObjectId().toHexString(),
274
+ completed: false,
275
+ title: "A",
276
+ });
277
+ const b = await GoldenTodoModel.create({
278
+ _id: new mongoose.Types.ObjectId().toHexString(),
279
+ completed: false,
280
+ title: "B",
281
+ });
282
+
283
+ const todoPatch = await adminAgent
284
+ .post("/admin/todos/bulk-patch")
285
+ .send({
286
+ ids: [String(a._id), String(b._id)],
287
+ patch: {completed: true},
288
+ })
289
+ .expect(200);
290
+ assert.deepEqual(sortedKeys(todoPatch.body), BULK_PATCH_SUCCESS_KEYS);
291
+ assert.strictEqual(todoPatch.body.updated, 2);
292
+ assert.isUndefined(todoPatch.body.failures);
293
+
294
+ const invalidStringId = await adminAgent
295
+ .post("/admin/todos/bulk-patch")
296
+ .send({
297
+ ids: ["todo-not-an-objectid"],
298
+ patch: {completed: true},
299
+ })
300
+ .expect(200);
301
+ assert.deepEqual(invalidStringId.body, {
302
+ failures: [{id: "todo-not-an-objectid", title: "Invalid id"}],
303
+ updated: 0,
304
+ });
305
+
306
+ const emptyIds = await adminAgent
307
+ .post("/admin/todos/bulk-patch")
308
+ .send({ids: [], patch: {completed: true}})
309
+ .expect(400);
310
+ assert.include(emptyIds.body.title, "at least one");
311
+
312
+ const tooMany = await adminAgent
313
+ .post("/admin/todos/bulk-patch")
314
+ .send({
315
+ ids: Array.from({length: MAX_BULK_PATCH_IDS + 1}, (_, index) => `id-${index}`),
316
+ patch: {completed: true},
317
+ })
318
+ .expect(400);
319
+ assert.include(tooMany.body.title, String(MAX_BULK_PATCH_IDS));
320
+
321
+ const [target] = await UserModel.find({email: "notAdmin@example.com"}).limit(1);
322
+ if (!target) {
323
+ throw new Error("Expected notAdmin@example.com fixture");
324
+ }
325
+ const userPatch = await adminAgent
326
+ .post("/admin/users/bulk-patch")
327
+ .send({
328
+ ids: [String(target._id)],
329
+ patch: {name: "Golden User"},
330
+ })
331
+ .expect(200);
332
+ assert.deepEqual(sortedKeys(userPatch.body), BULK_PATCH_SUCCESS_KEYS);
333
+ assert.strictEqual(userPatch.body.updated, 1);
334
+ const after = await UserModel.findById(target._id);
335
+ assert.strictEqual(after?.name, "Golden User");
336
+ });
337
+ });
@@ -0,0 +1,157 @@
1
+ import {
2
+ APIError,
3
+ assertMigrationsAllowed,
4
+ BackgroundTask,
5
+ type BackgroundTaskDocument,
6
+ checkMigrationFiles,
7
+ getMigrationStatus,
8
+ logger,
9
+ modelRouter,
10
+ type OpenApiMiddleware,
11
+ type PermissionMethod,
12
+ runMigrations,
13
+ type User,
14
+ z,
15
+ } from "@terreno/api";
16
+ import type express from "express";
17
+ import {DateTime} from "luxon";
18
+ import mongoose from "mongoose";
19
+
20
+ const DISABLED_CRUD = {
21
+ create: [] as PermissionMethod<unknown>[],
22
+ delete: [] as PermissionMethod<unknown>[],
23
+ list: [] as PermissionMethod<unknown>[],
24
+ read: [] as PermissionMethod<unknown>[],
25
+ update: [] as PermissionMethod<unknown>[],
26
+ };
27
+
28
+ const runQuerySchema = z.object({
29
+ wetRun: z.enum(["true", "false"]).optional(),
30
+ });
31
+
32
+ export const mountAdminMigrationRoutes = ({
33
+ app,
34
+ basePath,
35
+ dir,
36
+ openApi,
37
+ runPermissions,
38
+ statusPermissions,
39
+ }: {
40
+ app: express.Application;
41
+ basePath: string;
42
+ dir: string | undefined;
43
+ openApi?: OpenApiMiddleware;
44
+ runPermissions: PermissionMethod<unknown>[];
45
+ statusPermissions: PermissionMethod<unknown>[];
46
+ }): void => {
47
+ const requireDir = (): string => {
48
+ if (!dir) {
49
+ throw new APIError({status: 404, title: "Migrations are not configured"});
50
+ }
51
+ return dir;
52
+ };
53
+
54
+ app.use(
55
+ `${basePath}/migrations`,
56
+ modelRouter(BackgroundTask, {
57
+ ...(openApi ? {openApi} : {}),
58
+ collectionActions: {
59
+ run: {
60
+ handler: async ({query, user}) => {
61
+ const actor = user as (User & {_id: unknown; name?: string}) | undefined;
62
+ if (!actor) {
63
+ throw new APIError({status: 403, title: "Admin access required"});
64
+ }
65
+ const migrationsDir = requireDir();
66
+ const isWetRun = (query as {wetRun?: string}).wetRun === "true";
67
+ assertMigrationsAllowed({
68
+ allowEnv: process.env.ALLOW_MIGRATIONS === "true",
69
+ dryRun: !isWetRun,
70
+ force: true,
71
+ isProduction: process.env.NODE_ENV === "production",
72
+ });
73
+
74
+ const now = DateTime.now().toJSDate();
75
+ const task = (await BackgroundTask.create({
76
+ createdBy: actor._id as unknown as mongoose.Types.ObjectId,
77
+ isDryRun: !isWetRun,
78
+ logs: [
79
+ {
80
+ level: "info",
81
+ message: `Migrations ${isWetRun ? "apply" : "dry-run"} started by ${actor.name ?? "admin"}`,
82
+ timestamp: now,
83
+ },
84
+ ],
85
+ progress: {message: "Starting...", percentage: 0, stage: "Queued"},
86
+ startedAt: now,
87
+ status: "running",
88
+ taskType: "migrations:up",
89
+ })) as BackgroundTaskDocument;
90
+
91
+ void (async () => {
92
+ try {
93
+ const migrations = await checkMigrationFiles({dir: migrationsDir});
94
+ const result = await runMigrations({
95
+ checkCancellation: async () => {
96
+ await BackgroundTask.checkCancellation(task._id.toString());
97
+ },
98
+ connection: mongoose.connection,
99
+ dryRun: !isWetRun,
100
+ migrations,
101
+ mongoose,
102
+ });
103
+ await BackgroundTask.findOneAndUpdate(
104
+ {_id: task._id, status: "running"},
105
+ {
106
+ $set: {
107
+ completedAt: DateTime.now().toJSDate(),
108
+ progress: {message: "Done", percentage: 100, stage: "Complete"},
109
+ result: result.applied,
110
+ status: "completed",
111
+ },
112
+ }
113
+ );
114
+ } catch (error) {
115
+ const detail = error instanceof Error ? error.message : String(error);
116
+ logger.error(`Admin migrations run failed: ${detail}`);
117
+ await BackgroundTask.findOneAndUpdate(
118
+ {_id: task._id, status: "running"},
119
+ {
120
+ $set: {
121
+ completedAt: DateTime.now().toJSDate(),
122
+ error: detail,
123
+ status: "failed",
124
+ },
125
+ }
126
+ );
127
+ }
128
+ })();
129
+
130
+ return {taskId: task._id.toString()};
131
+ },
132
+ method: "POST",
133
+ permissions: runPermissions,
134
+ query: runQuerySchema,
135
+ status: 201,
136
+ summary: "Dry-run or apply pending MongoDB migrations",
137
+ tag: "adminMigrations",
138
+ },
139
+ status: {
140
+ handler: async () => {
141
+ const migrationsDir = requireDir();
142
+ const migrations = await checkMigrationFiles({dir: migrationsDir});
143
+ return getMigrationStatus({
144
+ connection: mongoose.connection,
145
+ migrations,
146
+ });
147
+ },
148
+ method: "GET",
149
+ permissions: statusPermissions,
150
+ summary: "List applied and pending MongoDB migrations",
151
+ tag: "adminMigrations",
152
+ },
153
+ },
154
+ permissions: DISABLED_CRUD,
155
+ })
156
+ );
157
+ };