@terreno/admin-backend 57.2.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 (53) hide show
  1. package/.ai/guidelines/core.md +12 -4
  2. package/.claude/CLAUDE.local.md +17 -2
  3. package/.cursor/rules/00-root.mdc +17 -2
  4. package/.github/copilot-instructions.md +17 -2
  5. package/AGENTS.md +17 -2
  6. package/README.md +3 -1
  7. package/bunfig.toml +9 -1
  8. package/dist/adminApp.d.ts +20 -2
  9. package/dist/adminApp.js +480 -474
  10. package/dist/adminConfigIdentity.d.ts +1 -0
  11. package/dist/adminConfigIdentity.js +1 -0
  12. package/dist/adminMigrations.d.ts +10 -0
  13. package/dist/adminMigrations.js +205 -0
  14. package/dist/adminScriptJob.d.ts +32 -0
  15. package/dist/adminScriptJob.js +360 -0
  16. package/dist/adminTextSearch.d.ts +1 -0
  17. package/dist/adminTextSearch.js +1 -0
  18. package/dist/adminUiV2.d.ts +2 -0
  19. package/dist/aggregateAdmin.js +6 -1
  20. package/dist/documentStorageApp.js +1 -4
  21. package/dist/enrichAdminListFilters.d.ts +7 -0
  22. package/dist/enrichAdminListFilters.js +37 -0
  23. package/dist/filterParser.js +139 -12
  24. package/dist/index.d.ts +2 -0
  25. package/dist/index.js +4 -1
  26. package/dist/legacy.js +4 -2
  27. package/dist/resolvedAdminModel.js +2 -1
  28. package/package.json +8 -8
  29. package/src/adminApp.migrations.test.ts +232 -0
  30. package/src/adminApp.models.test.ts +647 -5
  31. package/src/adminApp.syncMeta.test.ts +237 -0
  32. package/src/adminApp.test.ts +92 -0
  33. package/src/adminApp.ts +354 -240
  34. package/src/adminConfigIdentity.ts +1 -0
  35. package/src/adminHttpGoldens.test.ts +337 -0
  36. package/src/adminMigrations.ts +157 -0
  37. package/src/adminScriptJob.test.ts +297 -0
  38. package/src/adminScriptJob.ts +271 -0
  39. package/src/adminSyncMutationAuthMismatch.test.ts +650 -0
  40. package/src/adminTextSearch.test.ts +28 -0
  41. package/src/adminTextSearch.ts +1 -0
  42. package/src/adminUiV2.test.ts +71 -1
  43. package/src/adminUiV2.ts +2 -0
  44. package/src/aggregateAdmin.test.ts +125 -0
  45. package/src/aggregateAdmin.ts +7 -4
  46. package/src/documentStorageApp.ts +1 -3
  47. package/src/enrichAdminListFilters.test.ts +44 -0
  48. package/src/enrichAdminListFilters.ts +29 -0
  49. package/src/filterParser.test.ts +95 -0
  50. package/src/filterParser.ts +156 -10
  51. package/src/index.ts +2 -0
  52. package/src/legacy.ts +5 -1
  53. package/src/resolvedAdminModel.ts +2 -1
@@ -0,0 +1,297 @@
1
+ import {afterEach, beforeEach, describe, expect, it} from "bun:test";
2
+ import {
3
+ addAuthRoutes,
4
+ apiErrorMiddleware,
5
+ apiUnauthorizedMiddleware,
6
+ BackgroundTask,
7
+ createScriptArgs,
8
+ setupAuth,
9
+ type UserModel as UserModelType,
10
+ } from "@terreno/api";
11
+ import {getBaseServer, setupDb, UserModel} from "@terreno/api/testing";
12
+ import {Job, type JobDefinition, JobsApp, unregisterJobsService} from "@terreno/jobs";
13
+
14
+ import {
15
+ ADMIN_SCRIPT_JOB_NAME,
16
+ type AdminScriptJobTarget,
17
+ defineAdminScriptJob,
18
+ runRegisteredScriptTask,
19
+ tryCancelAdminScriptJob,
20
+ tryEnqueueAdminScriptJob,
21
+ } from "./adminScriptJob";
22
+
23
+ const getAdminScriptHandler = (
24
+ getScript: (name: string) => AdminScriptJobTarget | undefined = () => echoScript
25
+ ): JobDefinition["handler"] => {
26
+ let handler: JobDefinition["handler"] | undefined;
27
+ defineAdminScriptJob(
28
+ {
29
+ define: (_name, definition) => {
30
+ handler = definition.handler;
31
+ },
32
+ },
33
+ getScript
34
+ );
35
+ if (!handler) {
36
+ throw new Error("admin/script handler was not registered");
37
+ }
38
+ return handler;
39
+ };
40
+
41
+ const mockJobContext = {
42
+ attempt: 1,
43
+ jobId: "job-test",
44
+ signal: new AbortController().signal,
45
+ };
46
+
47
+ const echoScript = {
48
+ description: "Echo",
49
+ name: "echo",
50
+ runner: async (wetRun: boolean) => ({
51
+ results: [wetRun ? "wet" : "dry"],
52
+ success: true,
53
+ }),
54
+ };
55
+
56
+ describe("admin/script durable job adapter", () => {
57
+ beforeEach(async () => {
58
+ await setupDb();
59
+ await BackgroundTask.deleteMany({});
60
+ await Job.deleteMany({});
61
+ unregisterJobsService();
62
+ });
63
+
64
+ afterEach(async () => {
65
+ unregisterJobsService();
66
+ });
67
+
68
+ it("parses a valid payload and rejects malformed ones", async () => {
69
+ const handler = getAdminScriptHandler();
70
+ const task = await BackgroundTask.create({
71
+ isDryRun: true,
72
+ logs: [],
73
+ status: "pending",
74
+ taskType: "echo",
75
+ });
76
+ await handler(
77
+ {
78
+ args: {model: "todos"},
79
+ createdByName: "Ada",
80
+ scriptName: "echo",
81
+ taskId: String(task._id),
82
+ wetRun: false,
83
+ },
84
+ mockJobContext
85
+ );
86
+ const completed = await BackgroundTask.findById(task._id);
87
+ expect(completed?.status).toBe("completed");
88
+
89
+ await expect(handler(null, mockJobContext)).rejects.toThrow("Invalid admin/script job payload");
90
+
91
+ const omittedArgsTask = await BackgroundTask.create({
92
+ isDryRun: true,
93
+ logs: [],
94
+ status: "pending",
95
+ taskType: "echo",
96
+ });
97
+ await handler(
98
+ {
99
+ scriptName: "echo",
100
+ taskId: String(omittedArgsTask._id),
101
+ wetRun: false,
102
+ },
103
+ mockJobContext
104
+ );
105
+ expect((await BackgroundTask.findById(omittedArgsTask._id))?.status).toBe("completed");
106
+
107
+ await expect(handler({scriptName: "echo"}, mockJobContext)).rejects.toThrow(
108
+ "Invalid admin/script job payload"
109
+ );
110
+ await expect(
111
+ handler(
112
+ {
113
+ args: {bad: {nested: true}},
114
+ scriptName: "echo",
115
+ taskId: "abc",
116
+ wetRun: true,
117
+ },
118
+ mockJobContext
119
+ )
120
+ ).rejects.toThrow("Invalid admin/script job payload");
121
+ });
122
+
123
+ it("does not enqueue when JobsApp is unregistered", async () => {
124
+ const enqueued = await tryEnqueueAdminScriptJob({
125
+ args: {},
126
+ scriptName: "echo",
127
+ taskId: "000000000000000000000001",
128
+ wetRun: false,
129
+ });
130
+ expect(enqueued).toBeUndefined();
131
+ });
132
+
133
+ it("runs a script against a BackgroundTask row", async () => {
134
+ const task = await BackgroundTask.create({
135
+ isDryRun: true,
136
+ logs: [],
137
+ status: "pending",
138
+ taskType: "echo",
139
+ });
140
+ const {args} = createScriptArgs({values: {}});
141
+ await runRegisteredScriptTask({
142
+ args,
143
+ script: echoScript,
144
+ taskId: String(task._id),
145
+ wetRun: false,
146
+ });
147
+ const refreshed = await BackgroundTask.findById(task._id);
148
+ expect(refreshed?.status).toBe("completed");
149
+ expect(refreshed?.result).toContain("dry");
150
+ });
151
+
152
+ it("enqueues admin/script with maxAttempts 1 and completes via executeQueuedJob", async () => {
153
+ const jobsApp = new JobsApp({pollIntervalMs: 25});
154
+ defineAdminScriptJob(jobsApp, (name) => (name === "echo" ? echoScript : undefined));
155
+ const app = getBaseServer();
156
+ setupAuth(app, UserModel as unknown as UserModelType);
157
+ addAuthRoutes(app, UserModel as unknown as UserModelType);
158
+ jobsApp.register(app);
159
+ app.use(apiUnauthorizedMiddleware);
160
+ app.use(apiErrorMiddleware);
161
+
162
+ const task = await BackgroundTask.create({
163
+ isDryRun: true,
164
+ logs: [],
165
+ status: "pending",
166
+ taskType: "echo",
167
+ });
168
+ const enqueued = await tryEnqueueAdminScriptJob({
169
+ args: {},
170
+ scriptName: "echo",
171
+ taskId: String(task._id),
172
+ wetRun: false,
173
+ });
174
+ expect(enqueued).toBeDefined();
175
+ const job = await Job.findById(enqueued?.id);
176
+ expect(job?.name).toBe(ADMIN_SCRIPT_JOB_NAME);
177
+ expect(job?.maxAttempts).toBe(1);
178
+
179
+ const outcome = await jobsApp.executeQueuedJob(String(job?._id));
180
+ expect(outcome.kind).toBe("executed");
181
+ if (outcome.kind === "executed") {
182
+ expect(outcome.job.lastError).toBeUndefined();
183
+ expect(outcome.job.status).toBe("completed");
184
+ }
185
+ const current = await BackgroundTask.findById(task._id);
186
+ expect(current?.status).toBe("completed");
187
+ expect(current?.result).toContain("dry");
188
+ });
189
+
190
+ it("treats omitted args as empty and rejects empty script names", async () => {
191
+ const handler = getAdminScriptHandler();
192
+ const taggedTask = await BackgroundTask.create({
193
+ isDryRun: true,
194
+ logs: [],
195
+ status: "pending",
196
+ taskType: "echo",
197
+ });
198
+ await handler(
199
+ {
200
+ args: {tags: ["a", "b"]},
201
+ scriptName: "echo",
202
+ taskId: String(taggedTask._id),
203
+ wetRun: true,
204
+ },
205
+ mockJobContext
206
+ );
207
+ expect((await BackgroundTask.findById(taggedTask._id))?.result).toContain("wet");
208
+
209
+ await expect(
210
+ handler(
211
+ {
212
+ args: [],
213
+ scriptName: "echo",
214
+ taskId: "abc",
215
+ wetRun: true,
216
+ },
217
+ mockJobContext
218
+ )
219
+ ).rejects.toThrow("Invalid admin/script job payload");
220
+ await expect(
221
+ handler({scriptName: "", taskId: "abc", wetRun: true}, mockJobContext)
222
+ ).rejects.toThrow("Invalid admin/script job payload");
223
+ await expect(
224
+ handler({scriptName: "echo", taskId: "", wetRun: true}, mockJobContext)
225
+ ).rejects.toThrow("Invalid admin/script job payload");
226
+ await expect(
227
+ handler({scriptName: "echo", taskId: "abc", wetRun: "yes"}, mockJobContext)
228
+ ).rejects.toThrow("Invalid admin/script job payload");
229
+ });
230
+
231
+ it("marks the BackgroundTask cancelled when the job signal is aborted", async () => {
232
+ const task = await BackgroundTask.create({
233
+ isDryRun: true,
234
+ logs: [],
235
+ status: "pending",
236
+ taskType: "echo",
237
+ });
238
+ const {args} = createScriptArgs({values: {}});
239
+ const signal = AbortSignal.abort();
240
+ await runRegisteredScriptTask({
241
+ args,
242
+ script: echoScript,
243
+ signal,
244
+ taskId: String(task._id),
245
+ wetRun: false,
246
+ });
247
+ const refreshed = await BackgroundTask.findById(task._id);
248
+ expect(refreshed?.status).toBe("cancelled");
249
+ });
250
+
251
+ it("fails the BackgroundTask when the script name is unknown", async () => {
252
+ const jobsApp = new JobsApp({pollIntervalMs: 50});
253
+ defineAdminScriptJob(jobsApp, () => undefined);
254
+ const app = getBaseServer();
255
+ jobsApp.register(app);
256
+ const task = await BackgroundTask.create({
257
+ isDryRun: true,
258
+ logs: [],
259
+ status: "pending",
260
+ taskType: "missing",
261
+ });
262
+ const enqueued = await tryEnqueueAdminScriptJob({
263
+ args: {model: "todos"},
264
+ scriptName: "missing",
265
+ taskId: String(task._id),
266
+ wetRun: false,
267
+ });
268
+ const outcome = await jobsApp.executeQueuedJob(String(enqueued?.id));
269
+ expect(outcome.kind).toBe("executed");
270
+ const refreshed = await BackgroundTask.findById(task._id);
271
+ expect(refreshed?.status).toBe("failed");
272
+ expect(refreshed?.error).toInclude("Script not found");
273
+ });
274
+
275
+ it("cancels the matching job row for a script task", async () => {
276
+ const jobsApp = new JobsApp({pollIntervalMs: 50});
277
+ defineAdminScriptJob(jobsApp, (name) => (name === "echo" ? echoScript : undefined));
278
+ const app = getBaseServer();
279
+ jobsApp.register(app);
280
+
281
+ const task = await BackgroundTask.create({
282
+ isDryRun: true,
283
+ logs: [],
284
+ status: "pending",
285
+ taskType: "echo",
286
+ });
287
+ const enqueued = await tryEnqueueAdminScriptJob({
288
+ args: {},
289
+ scriptName: "echo",
290
+ taskId: String(task._id),
291
+ wetRun: false,
292
+ });
293
+ await tryCancelAdminScriptJob(String(task._id));
294
+ const job = await Job.findById(enqueued?.id);
295
+ expect(job?.status).toBe("cancelled");
296
+ });
297
+ });
@@ -0,0 +1,271 @@
1
+ import {
2
+ APIError,
3
+ BackgroundTask,
4
+ createScriptArgs,
5
+ logger,
6
+ type ScriptArgDef,
7
+ type ScriptArgs,
8
+ type ScriptArgValue,
9
+ type ScriptContext,
10
+ type ScriptResult,
11
+ type ScriptRunner,
12
+ TaskCancelledError,
13
+ } from "@terreno/api";
14
+ import {Job, type JobDefinition, type JobHandlerContext, tryGetJobsService} from "@terreno/jobs";
15
+ import {DateTime} from "luxon";
16
+
17
+ export interface AdminScriptJobTarget {
18
+ args?: ScriptArgDef[];
19
+ name: string;
20
+ runner: ScriptRunner;
21
+ }
22
+
23
+ /** Durable job name for admin panel script runs. */
24
+ export const ADMIN_SCRIPT_JOB_NAME = "admin/script";
25
+
26
+ export interface AdminScriptJobPayload {
27
+ args: Record<string, ScriptArgValue>;
28
+ createdByName?: string;
29
+ scriptName: string;
30
+ taskId: string;
31
+ wetRun: boolean;
32
+ }
33
+
34
+ export interface JobsDefineHost {
35
+ define: (name: string, definition: JobDefinition) => unknown;
36
+ }
37
+
38
+ const isScriptArgValue = (value: unknown): value is ScriptArgValue => {
39
+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
40
+ return true;
41
+ }
42
+ if (!Array.isArray(value)) {
43
+ return false;
44
+ }
45
+ return value.every((entry) => typeof entry === "string");
46
+ };
47
+
48
+ const parseAdminScriptJobPayload = (payload: unknown): AdminScriptJobPayload | undefined => {
49
+ if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
50
+ return undefined;
51
+ }
52
+ const record = payload as Record<string, unknown>;
53
+ if (typeof record.scriptName !== "string" || record.scriptName.length === 0) {
54
+ return undefined;
55
+ }
56
+ if (typeof record.taskId !== "string" || record.taskId.length === 0) {
57
+ return undefined;
58
+ }
59
+ if (typeof record.wetRun !== "boolean") {
60
+ return undefined;
61
+ }
62
+ const args: Record<string, ScriptArgValue> = {};
63
+ if (record.args !== undefined) {
64
+ if (!record.args || typeof record.args !== "object" || Array.isArray(record.args)) {
65
+ return undefined;
66
+ }
67
+ for (const [key, value] of Object.entries(record.args as Record<string, unknown>)) {
68
+ if (!isScriptArgValue(value)) {
69
+ return undefined;
70
+ }
71
+ args[key] = value;
72
+ }
73
+ }
74
+ const createdByName = typeof record.createdByName === "string" ? record.createdByName : undefined;
75
+ return {
76
+ args,
77
+ createdByName,
78
+ scriptName: record.scriptName,
79
+ taskId: record.taskId,
80
+ wetRun: record.wetRun,
81
+ };
82
+ };
83
+
84
+ const isAbortLike = (error: unknown): boolean => {
85
+ if (error instanceof TaskCancelledError) {
86
+ return true;
87
+ }
88
+ if (!(error instanceof Error)) {
89
+ return false;
90
+ }
91
+ return error.name === "AbortError" || error.name === "TaskCancelledError";
92
+ };
93
+
94
+ export const runRegisteredScriptTask = async ({
95
+ args,
96
+ script,
97
+ signal,
98
+ taskId,
99
+ wetRun,
100
+ }: {
101
+ args: ScriptArgs;
102
+ script: AdminScriptJobTarget;
103
+ signal?: AbortSignal;
104
+ taskId: string;
105
+ wetRun: boolean;
106
+ }): Promise<void> => {
107
+ const now = DateTime.now().toJSDate();
108
+ await BackgroundTask.findOneAndUpdate(
109
+ {_id: taskId, status: {$in: ["pending", "running"]}},
110
+ {
111
+ $set: {
112
+ progress: {message: "Starting...", percentage: 0, stage: "Running"},
113
+ startedAt: now,
114
+ status: "running",
115
+ },
116
+ }
117
+ );
118
+
119
+ const ctx: ScriptContext = {
120
+ addLog: async (level, message) => {
121
+ const current = await BackgroundTask.findById(taskId);
122
+ if (current) {
123
+ await current.addLog(level, message);
124
+ }
125
+ },
126
+ args,
127
+ checkCancellation: async () => {
128
+ if (signal?.aborted) {
129
+ throw new TaskCancelledError(taskId);
130
+ }
131
+ await BackgroundTask.checkCancellation(taskId);
132
+ },
133
+ updateProgress: async (percentage, stage, message) => {
134
+ const current = await BackgroundTask.findById(taskId);
135
+ if (current) {
136
+ await current.updateProgress(percentage, stage, message);
137
+ }
138
+ },
139
+ };
140
+
141
+ try {
142
+ await ctx.checkCancellation();
143
+ const result: ScriptResult = await script.runner(wetRun, ctx);
144
+ await BackgroundTask.findOneAndUpdate(
145
+ {_id: taskId, status: "running"},
146
+ {
147
+ $set: {
148
+ completedAt: DateTime.now().toJSDate(),
149
+ progress: {message: "Done", percentage: 100, stage: "Complete"},
150
+ result: result.results,
151
+ status: result.success ? "completed" : "failed",
152
+ },
153
+ }
154
+ );
155
+ } catch (err: unknown) {
156
+ if (isAbortLike(err)) {
157
+ await BackgroundTask.findOneAndUpdate(
158
+ {_id: taskId, status: {$in: ["pending", "running"]}},
159
+ {
160
+ $set: {
161
+ completedAt: DateTime.now().toJSDate(),
162
+ status: "cancelled",
163
+ },
164
+ }
165
+ );
166
+ return;
167
+ }
168
+ const message = err instanceof Error ? err.message : String(err);
169
+ logger.error(`Script ${script.name} failed: ${message}`);
170
+ await BackgroundTask.findOneAndUpdate(
171
+ {_id: taskId, status: "running"},
172
+ {
173
+ $set: {
174
+ completedAt: DateTime.now().toJSDate(),
175
+ error: message,
176
+ result: [message],
177
+ status: "failed",
178
+ },
179
+ }
180
+ );
181
+ }
182
+ };
183
+
184
+ const createAdminScriptHandler = (
185
+ getScript: (name: string) => AdminScriptJobTarget | undefined
186
+ ): JobDefinition["handler"] => {
187
+ return async (payload: unknown, ctx: JobHandlerContext): Promise<void> => {
188
+ const parsed = parseAdminScriptJobPayload(payload);
189
+ if (!parsed) {
190
+ throw new APIError({status: 400, title: "Invalid admin/script job payload"});
191
+ }
192
+
193
+ const script = getScript(parsed.scriptName);
194
+ if (!script) {
195
+ const message = `Script not found: ${parsed.scriptName}`;
196
+ await BackgroundTask.findOneAndUpdate(
197
+ {_id: parsed.taskId, status: {$in: ["pending", "running"]}},
198
+ {
199
+ $set: {
200
+ completedAt: DateTime.now().toJSDate(),
201
+ error: message,
202
+ result: [message],
203
+ status: "failed",
204
+ },
205
+ }
206
+ );
207
+ throw new APIError({status: 404, title: message});
208
+ }
209
+
210
+ const {args, errors} = createScriptArgs({
211
+ defs: script.args ?? [],
212
+ values: parsed.args,
213
+ });
214
+ if (errors.length > 0) {
215
+ throw new APIError({status: 400, title: errors.join("; ")});
216
+ }
217
+
218
+ await runRegisteredScriptTask({
219
+ args,
220
+ script,
221
+ signal: ctx.signal,
222
+ taskId: parsed.taskId,
223
+ wetRun: parsed.wetRun,
224
+ });
225
+ };
226
+ };
227
+
228
+ /** Register the shared `admin/script` handler (maxAttempts 1 — scripts are not assumed idempotent). */
229
+ export const defineAdminScriptJob = (
230
+ jobs: JobsDefineHost,
231
+ getScript: (name: string) => AdminScriptJobTarget | undefined
232
+ ): void => {
233
+ jobs.define(ADMIN_SCRIPT_JOB_NAME, {
234
+ handler: createAdminScriptHandler(getScript),
235
+ retry: {maxAttempts: 1},
236
+ });
237
+ };
238
+
239
+ export const tryEnqueueAdminScriptJob = async (
240
+ payload: AdminScriptJobPayload
241
+ ): Promise<{id: string} | undefined> => {
242
+ const jobs = tryGetJobsService();
243
+ if (!jobs?.getDefinition(ADMIN_SCRIPT_JOB_NAME)) {
244
+ return undefined;
245
+ }
246
+ const job = await jobs.enqueue({
247
+ idempotencyKey: `admin-script:${payload.taskId}`,
248
+ name: ADMIN_SCRIPT_JOB_NAME,
249
+ payload,
250
+ });
251
+ return {id: String(job._id)};
252
+ };
253
+
254
+ export const tryCancelAdminScriptJob = async (taskId: string): Promise<void> => {
255
+ const jobs = tryGetJobsService();
256
+ if (!jobs) {
257
+ return;
258
+ }
259
+ const job = await Job.findOneOrNone({
260
+ name: ADMIN_SCRIPT_JOB_NAME,
261
+ "payload.taskId": taskId,
262
+ });
263
+ if (!job) {
264
+ return;
265
+ }
266
+ try {
267
+ await jobs.adminCancelJob(String(job._id));
268
+ } catch {
269
+ // Job may already be terminal; BackgroundTask cancel is the operator contract.
270
+ }
271
+ };