@terreno/api 0.22.2 → 0.23.1

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,284 @@
1
+ import {afterAll, beforeAll, describe, expect, it} from "bun:test";
2
+ import mongoose from "mongoose";
3
+
4
+ import {
5
+ BackgroundTask,
6
+ createScriptArgs,
7
+ parseScriptArgs,
8
+ type ScriptArgDef,
9
+ TaskCancelledError,
10
+ } from "./scriptRunner";
11
+
12
+ describe("parseScriptArgs", () => {
13
+ it("parses --name=value form", () => {
14
+ const {args} = parseScriptArgs(["--model=todos"]);
15
+ expect(args.getString("model")).toBe("todos");
16
+ expect(args.has("model")).toBe(true);
17
+ });
18
+
19
+ it("parses --name value form", () => {
20
+ const {args} = parseScriptArgs(["--model", "todos"]);
21
+ expect(args.getString("model")).toBe("todos");
22
+ });
23
+
24
+ it("treats a lone --flag as boolean true", () => {
25
+ const {args} = parseScriptArgs(["--wet"]);
26
+ expect(args.getBoolean("wet")).toBe(true);
27
+ });
28
+
29
+ it("parses --no-flag as boolean false", () => {
30
+ const {args} = parseScriptArgs(["--no-cache"]);
31
+ expect(args.getBoolean("cache")).toBe(false);
32
+ });
33
+
34
+ it("treats short -x like --x", () => {
35
+ const {args} = parseScriptArgs(["-v"]);
36
+ expect(args.getBoolean("v")).toBe(true);
37
+ });
38
+
39
+ it("collects positional arguments", () => {
40
+ const {args} = parseScriptArgs(["one", "two", "-"]);
41
+ expect(args.positional).toEqual(["one", "two", "-"]);
42
+ });
43
+
44
+ it("collapses repeated flags into an array", () => {
45
+ const {args} = parseScriptArgs(["--tag", "a", "--tag", "b", "--tag=c"]);
46
+ expect(args.getStringArray("tag")).toEqual(["a", "b", "c"]);
47
+ });
48
+
49
+ it("does not consume the next token for declared boolean flags", () => {
50
+ const defs: ScriptArgDef[] = [{description: "verbose", name: "verbose", type: "boolean"}];
51
+ const {args} = parseScriptArgs(["--verbose", "leftover"], defs);
52
+ expect(args.getBoolean("verbose")).toBe(true);
53
+ expect(args.positional).toEqual(["leftover"]);
54
+ });
55
+
56
+ it("resolves aliases to the canonical name", () => {
57
+ const defs: ScriptArgDef[] = [
58
+ {aliases: ["m"], description: "model", name: "model", type: "string"},
59
+ ];
60
+ const {args} = parseScriptArgs(["-m", "users"], defs);
61
+ expect(args.getString("model")).toBe("users");
62
+ });
63
+
64
+ it("treats a trailing flag with no value as boolean true", () => {
65
+ const {args} = parseScriptArgs(["--model", "todos", "--wet"]);
66
+ expect(args.getString("model")).toBe("todos");
67
+ expect(args.getBoolean("wet")).toBe(true);
68
+ });
69
+
70
+ it("errors when a declared string flag is missing its value", () => {
71
+ const defs: ScriptArgDef[] = [{description: "model", name: "model", type: "string"}];
72
+ const {errors} = parseScriptArgs(["--model"], defs);
73
+ expect(errors).toHaveLength(1);
74
+ expect(errors[0]).toInclude("--model expects a string value");
75
+ });
76
+
77
+ it("errors when a declared number flag is followed by another flag", () => {
78
+ const defs: ScriptArgDef[] = [{description: "limit", name: "limit", type: "number"}];
79
+ const {errors} = parseScriptArgs(["--limit", "--wet"], defs);
80
+ expect(errors.some((e) => e.includes("--limit expects a number value"))).toBe(true);
81
+ });
82
+
83
+ it("still treats an undeclared value-less flag as boolean true", () => {
84
+ const {args, errors} = parseScriptArgs(["--unknown"]);
85
+ expect(errors).toHaveLength(0);
86
+ expect(args.getBoolean("unknown")).toBe(true);
87
+ });
88
+ });
89
+
90
+ describe("createScriptArgs", () => {
91
+ it("applies declared defaults when missing", () => {
92
+ const defs: ScriptArgDef[] = [{default: "all", description: "model", name: "model"}];
93
+ const {args, errors} = createScriptArgs({defs, values: {}});
94
+ expect(errors).toHaveLength(0);
95
+ expect(args.getString("model")).toBe("all");
96
+ });
97
+
98
+ it("reports an error for missing required args", () => {
99
+ const defs: ScriptArgDef[] = [{description: "model", name: "model", required: true}];
100
+ const {errors} = createScriptArgs({defs, values: {}});
101
+ expect(errors).toHaveLength(1);
102
+ expect(errors[0]).toInclude("Missing required argument: --model");
103
+ });
104
+
105
+ it("coerces declared number args and reports invalid numbers", () => {
106
+ const defs: ScriptArgDef[] = [{description: "limit", name: "limit", type: "number"}];
107
+ const ok = createScriptArgs({defs, values: {limit: "10"}});
108
+ expect(ok.errors).toHaveLength(0);
109
+ expect(ok.args.getNumber("limit")).toBe(10);
110
+
111
+ const bad = createScriptArgs({defs, values: {limit: "nope"}});
112
+ expect(bad.errors).toHaveLength(1);
113
+ expect(bad.errors[0]).toInclude("expected a number");
114
+ });
115
+
116
+ it("coerces declared boolean args", () => {
117
+ const defs: ScriptArgDef[] = [{description: "force", name: "force", type: "boolean"}];
118
+ expect(createScriptArgs({defs, values: {force: "yes"}}).args.getBoolean("force")).toBe(true);
119
+ expect(createScriptArgs({defs, values: {force: "off"}}).args.getBoolean("force")).toBe(false);
120
+ const bad = createScriptArgs({defs, values: {force: "maybe"}});
121
+ expect(bad.errors[0]).toInclude("expected a boolean");
122
+ });
123
+
124
+ it("coerces booleans and numbers from array values (first element)", () => {
125
+ const defs: ScriptArgDef[] = [
126
+ {description: "force", name: "force", type: "boolean"},
127
+ {description: "limit", name: "limit", type: "number"},
128
+ ];
129
+ const {args} = createScriptArgs({
130
+ defs,
131
+ values: {force: ["true", "false"], limit: ["5", "6"]},
132
+ });
133
+ expect(args.getBoolean("force")).toBe(true);
134
+ expect(args.getNumber("limit")).toBe(5);
135
+ });
136
+
137
+ describe("getters", () => {
138
+ it("getString returns fallback when missing and stringifies non-strings", () => {
139
+ const {args} = createScriptArgs({values: {count: 3, flag: true}});
140
+ expect(args.getString("missing", "fallback")).toBe("fallback");
141
+ expect(args.getString("count")).toBe("3");
142
+ expect(args.getString("flag")).toBe("true");
143
+ });
144
+
145
+ it("getNumber handles native numbers, strings, NaN, and missing", () => {
146
+ const {args} = createScriptArgs({values: {a: 7, b: "8", c: "x"}});
147
+ expect(args.getNumber("a")).toBe(7);
148
+ expect(args.getNumber("b")).toBe(8);
149
+ expect(args.getNumber("c", 1)).toBe(1);
150
+ expect(args.getNumber("missing", 99)).toBe(99);
151
+ expect(args.getNumber("missing")).toBeUndefined();
152
+ });
153
+
154
+ it("getBoolean honors native booleans, string truthiness, and fallback", () => {
155
+ const {args} = createScriptArgs({values: {a: true, b: "on", c: "nope"}});
156
+ expect(args.getBoolean("a")).toBe(true);
157
+ expect(args.getBoolean("b")).toBe(true);
158
+ expect(args.getBoolean("c")).toBe(false);
159
+ expect(args.getBoolean("missing")).toBe(false);
160
+ expect(args.getBoolean("missing", true)).toBe(true);
161
+ });
162
+
163
+ it("reads undeclared array values via getString/getNumber (first element)", () => {
164
+ const {args} = createScriptArgs({values: {nums: ["3", "4"], tags: ["x", "y"]}});
165
+ expect(args.getString("tags")).toBe("x");
166
+ expect(args.getNumber("nums")).toBe(3);
167
+ });
168
+
169
+ it("getStringArray normalizes single values and missing keys", () => {
170
+ const {args} = createScriptArgs({values: {many: ["a", "b"], one: "x"}});
171
+ expect(args.getStringArray("one")).toEqual(["x"]);
172
+ expect(args.getStringArray("many")).toEqual(["a", "b"]);
173
+ expect(args.getStringArray("missing")).toEqual([]);
174
+ });
175
+
176
+ it("exposes raw values and positional list", () => {
177
+ const {args} = createScriptArgs({positional: ["p"], values: {x: "1"}});
178
+ expect(args.raw.x).toBe("1");
179
+ expect(args.positional).toEqual(["p"]);
180
+ });
181
+ });
182
+ });
183
+
184
+ describe("TaskCancelledError", () => {
185
+ it("sets the message and name", () => {
186
+ const err = new TaskCancelledError("task-123");
187
+ expect(err.message).toBe("Task task-123 was cancelled");
188
+ expect(err.name).toBe("TaskCancelledError");
189
+ });
190
+
191
+ it("is an instance of Error", () => {
192
+ const err = new TaskCancelledError("abc");
193
+ expect(err).toBeInstanceOf(Error);
194
+ });
195
+ });
196
+
197
+ describe("BackgroundTask model", () => {
198
+ beforeAll(async () => {
199
+ if (mongoose.connection.readyState !== 1) {
200
+ await mongoose.connect(process.env.MONGO_URL ?? "mongodb://127.0.0.1/terreno-test");
201
+ }
202
+ await BackgroundTask.deleteMany({});
203
+ });
204
+
205
+ afterAll(async () => {
206
+ await BackgroundTask.deleteMany({});
207
+ });
208
+
209
+ it("creates a task with required fields", async () => {
210
+ const task = await BackgroundTask.create({taskType: "test-task"});
211
+ expect(task.taskType).toBe("test-task");
212
+ expect(task.status).toBe("pending");
213
+ expect(task.isDryRun).toBe(false);
214
+ expect(task.logs).toEqual([]);
215
+ });
216
+
217
+ describe("addLog", () => {
218
+ it("appends a log entry and saves", async () => {
219
+ const task = await BackgroundTask.create({taskType: "log-test"});
220
+ await task.addLog("info", "step completed");
221
+
222
+ const reloaded = await BackgroundTask.findById(task._id);
223
+ expect(reloaded?.logs).toHaveLength(1);
224
+ expect(reloaded?.logs[0].level).toBe("info");
225
+ expect(reloaded?.logs[0].message).toBe("step completed");
226
+ expect(reloaded?.logs[0].timestamp).toBeDefined();
227
+ });
228
+
229
+ it("appends multiple log entries", async () => {
230
+ const task = await BackgroundTask.create({taskType: "multi-log"});
231
+ await task.addLog("info", "first");
232
+ await task.addLog("warn", "second");
233
+ await task.addLog("error", "third");
234
+
235
+ const reloaded = await BackgroundTask.findById(task._id);
236
+ expect(reloaded?.logs).toHaveLength(3);
237
+ expect(reloaded?.logs[0].level).toBe("info");
238
+ expect(reloaded?.logs[1].level).toBe("warn");
239
+ expect(reloaded?.logs[2].level).toBe("error");
240
+ });
241
+ });
242
+
243
+ describe("updateProgress", () => {
244
+ it("sets progress percentage and stage", async () => {
245
+ const task = await BackgroundTask.create({taskType: "progress-test"});
246
+ await task.updateProgress(50, "processing", "halfway done");
247
+
248
+ const reloaded = await BackgroundTask.findById(task._id);
249
+ expect(reloaded?.progress?.percentage).toBe(50);
250
+ expect(reloaded?.progress?.stage).toBe("processing");
251
+ expect(reloaded?.progress?.message).toBe("halfway done");
252
+ });
253
+
254
+ it("preserves previous stage and message when not provided", async () => {
255
+ const task = await BackgroundTask.create({taskType: "progress-retain"});
256
+ await task.updateProgress(25, "init", "starting");
257
+ await task.updateProgress(75);
258
+
259
+ const reloaded = await BackgroundTask.findById(task._id);
260
+ expect(reloaded?.progress?.percentage).toBe(75);
261
+ expect(reloaded?.progress?.stage).toBe("init");
262
+ expect(reloaded?.progress?.message).toBe("starting");
263
+ });
264
+ });
265
+
266
+ describe("checkCancellation", () => {
267
+ it("does nothing when task is not cancelled", async () => {
268
+ const task = await BackgroundTask.create({status: "running", taskType: "check-cancel"});
269
+ await expect(BackgroundTask.checkCancellation(task._id.toString())).resolves.toBeUndefined();
270
+ });
271
+
272
+ it("throws TaskCancelledError when task is cancelled", async () => {
273
+ const task = await BackgroundTask.create({status: "cancelled", taskType: "check-cancel"});
274
+ await expect(BackgroundTask.checkCancellation(task._id.toString())).rejects.toThrow(
275
+ TaskCancelledError
276
+ );
277
+ });
278
+
279
+ it("does nothing when task does not exist", async () => {
280
+ const fakeId = new mongoose.Types.ObjectId().toString();
281
+ await expect(BackgroundTask.checkCancellation(fakeId)).resolves.toBeUndefined();
282
+ });
283
+ });
284
+ });
@@ -10,6 +10,56 @@ export interface ScriptResult {
10
10
  results: string[];
11
11
  }
12
12
 
13
+ // --- Flexible Script Arguments ---
14
+
15
+ /** A single parsed argument value. Repeated flags collapse into a string array. */
16
+ export type ScriptArgValue = string | number | boolean | string[];
17
+
18
+ /**
19
+ * Optional declaration for a single script argument. Declarations are purely
20
+ * advisory: they drive validation, type coercion, default values, and help text
21
+ * but a script can still read any argument the caller supplied. This keeps
22
+ * argument handling flexible — declare the args you care about, ignore the rest.
23
+ */
24
+ export interface ScriptArgDef {
25
+ /** Canonical name (used as `--name` on the CLI and as the key in the args map). */
26
+ name: string;
27
+ /** Human-readable description shown in CLI help and the admin UI. */
28
+ description: string;
29
+ /** Type used for coercion and validation. Defaults to "string". */
30
+ type?: "string" | "number" | "boolean";
31
+ /** When true, parsing fails if the argument is missing. */
32
+ required?: boolean;
33
+ /** Default applied when the argument is not provided. */
34
+ default?: ScriptArgValue;
35
+ /** Alternate names accepted on the CLI (e.g. ["l"] enables `-l`). */
36
+ aliases?: string[];
37
+ /** Example value shown in help text. */
38
+ example?: string;
39
+ }
40
+
41
+ /**
42
+ * Typed, ergonomic accessor over the parsed arguments passed to a script. Scripts
43
+ * read values via the typed getters; `raw` and `positional` expose everything for
44
+ * advanced cases.
45
+ */
46
+ export interface ScriptArgs {
47
+ /** All named values keyed by canonical name. */
48
+ raw: Record<string, ScriptArgValue>;
49
+ /** Positional (non-flag) arguments, in order. */
50
+ positional: string[];
51
+ /** Whether a named argument was supplied (or has a default). */
52
+ has: (name: string) => boolean;
53
+ /** Read a string value (coerces numbers/booleans; first element of arrays). */
54
+ getString: (name: string, fallback?: string) => string | undefined;
55
+ /** Read a numeric value (coerces strings; returns fallback when missing/NaN). */
56
+ getNumber: (name: string, fallback?: number) => number | undefined;
57
+ /** Read a boolean value ("true"/"1"/"yes"/"on" are truthy). */
58
+ getBoolean: (name: string, fallback?: boolean) => boolean;
59
+ /** Read a string array (single values become a one-element array). */
60
+ getStringArray: (name: string) => string[];
61
+ }
62
+
13
63
  export interface ScriptContext {
14
64
  /** Check if the task has been cancelled. Throws TaskCancelledError if so. */
15
65
  checkCancellation: () => Promise<void>;
@@ -17,10 +67,209 @@ export interface ScriptContext {
17
67
  addLog: (level: "info" | "warn" | "error", message: string) => Promise<void>;
18
68
  /** Update progress on the task. */
19
69
  updateProgress: (percentage: number, stage?: string, message?: string) => Promise<void>;
70
+ /** Arguments supplied to this run (from the CLI, HTTP body, or admin UI). */
71
+ args: ScriptArgs;
20
72
  }
21
73
 
22
74
  export type ScriptRunner = (wetRun: boolean, ctx?: ScriptContext) => Promise<ScriptResult>;
23
75
 
76
+ const coerceArgValue = (
77
+ value: ScriptArgValue,
78
+ type: ScriptArgDef["type"]
79
+ ): {value: ScriptArgValue; error?: string} => {
80
+ if (type === "number") {
81
+ const num = typeof value === "number" ? value : Number(Array.isArray(value) ? value[0] : value);
82
+ if (Number.isNaN(num)) {
83
+ return {error: `expected a number but received "${String(value)}"`, value};
84
+ }
85
+ return {value: num};
86
+ }
87
+ if (type === "boolean") {
88
+ if (typeof value === "boolean") {
89
+ return {value};
90
+ }
91
+ const normalized = String(Array.isArray(value) ? value[0] : value).toLowerCase();
92
+ if (["true", "1", "yes", "on"].includes(normalized)) {
93
+ return {value: true};
94
+ }
95
+ if (["false", "0", "no", "off"].includes(normalized)) {
96
+ return {value: false};
97
+ }
98
+ return {error: `expected a boolean but received "${String(value)}"`, value};
99
+ }
100
+ return {value};
101
+ };
102
+
103
+ const toStringValue = (value: ScriptArgValue | undefined): string | undefined => {
104
+ if (value === undefined) {
105
+ return undefined;
106
+ }
107
+ if (Array.isArray(value)) {
108
+ return value[0];
109
+ }
110
+ return String(value);
111
+ };
112
+
113
+ /**
114
+ * Build a {@link ScriptArgs} accessor from a raw values map and optional declarations.
115
+ * Applies declared defaults, coerces declared types, and validates required args.
116
+ * Returns the accessor plus any validation errors (callers decide how to surface them).
117
+ */
118
+ export const createScriptArgs = ({
119
+ values,
120
+ positional = [],
121
+ defs = [],
122
+ }: {
123
+ values: Record<string, ScriptArgValue>;
124
+ positional?: string[];
125
+ defs?: ScriptArgDef[];
126
+ }): {args: ScriptArgs; errors: string[]} => {
127
+ const errors: string[] = [];
128
+ const raw: Record<string, ScriptArgValue> = {...values};
129
+
130
+ for (const def of defs) {
131
+ if (raw[def.name] === undefined) {
132
+ if (def.default !== undefined) {
133
+ raw[def.name] = def.default;
134
+ } else if (def.required) {
135
+ errors.push(`Missing required argument: --${def.name} (${def.description})`);
136
+ }
137
+ continue;
138
+ }
139
+ const coerced = coerceArgValue(raw[def.name], def.type);
140
+ if (coerced.error) {
141
+ errors.push(`Invalid argument --${def.name}: ${coerced.error}`);
142
+ continue;
143
+ }
144
+ raw[def.name] = coerced.value;
145
+ }
146
+
147
+ const args: ScriptArgs = {
148
+ getBoolean: (name, fallback = false) => {
149
+ const value = raw[name];
150
+ if (value === undefined) {
151
+ return fallback;
152
+ }
153
+ if (typeof value === "boolean") {
154
+ return value;
155
+ }
156
+ const normalized = toStringValue(value)?.toLowerCase();
157
+ return normalized !== undefined && ["true", "1", "yes", "on"].includes(normalized);
158
+ },
159
+ getNumber: (name, fallback) => {
160
+ const value = raw[name];
161
+ if (value === undefined) {
162
+ return fallback;
163
+ }
164
+ const num = typeof value === "number" ? value : Number(toStringValue(value));
165
+ return Number.isNaN(num) ? fallback : num;
166
+ },
167
+ getString: (name, fallback) => toStringValue(raw[name]) ?? fallback,
168
+ getStringArray: (name) => {
169
+ const value = raw[name];
170
+ if (value === undefined) {
171
+ return [];
172
+ }
173
+ if (Array.isArray(value)) {
174
+ return value;
175
+ }
176
+ return [String(value)];
177
+ },
178
+ has: (name) => raw[name] !== undefined,
179
+ positional,
180
+ raw,
181
+ };
182
+
183
+ return {args, errors};
184
+ };
185
+
186
+ /**
187
+ * Parse CLI-style tokens into a {@link ScriptArgs} accessor. Supports a flexible set
188
+ * of conventions so callers and scripts do not need to agree on a rigid format:
189
+ *
190
+ * - `--name=value` and `--name value`
191
+ * - `--flag` (boolean true) and `--no-flag` (boolean false)
192
+ * - short aliases `-x` (treated like `--x`)
193
+ * - repeated flags collapse into a string array
194
+ * - bare tokens become positional arguments
195
+ *
196
+ * When {@link ScriptArgDef declarations} are supplied, values are coerced to the
197
+ * declared type, defaults are applied, and required args are validated.
198
+ */
199
+ export const parseScriptArgs = (
200
+ tokens: string[],
201
+ defs: ScriptArgDef[] = []
202
+ ): {args: ScriptArgs; errors: string[]} => {
203
+ const aliasToName = new Map<string, string>();
204
+ const defByName = new Map<string, ScriptArgDef>();
205
+ for (const def of defs) {
206
+ defByName.set(def.name, def);
207
+ for (const alias of def.aliases ?? []) {
208
+ aliasToName.set(alias, def.name);
209
+ }
210
+ }
211
+
212
+ const values: Record<string, ScriptArgValue> = {};
213
+ const positional: string[] = [];
214
+ const missingValueErrors: string[] = [];
215
+
216
+ const assign = (key: string, value: ScriptArgValue): void => {
217
+ const name = aliasToName.get(key) ?? key;
218
+ const existing = values[name];
219
+ if (existing === undefined) {
220
+ values[name] = value;
221
+ return;
222
+ }
223
+ // Repeated flag: collapse into an array of strings.
224
+ const asArray = Array.isArray(existing) ? existing : [String(existing)];
225
+ values[name] = [...asArray, String(value)];
226
+ };
227
+
228
+ for (let i = 0; i < tokens.length; i++) {
229
+ const token = tokens[i];
230
+ if (!token.startsWith("-") || token === "-") {
231
+ positional.push(token);
232
+ continue;
233
+ }
234
+
235
+ const flag = token.replace(/^-+/, "");
236
+ if (flag.startsWith("no-") && !flag.includes("=")) {
237
+ assign(flag.slice(3), false);
238
+ continue;
239
+ }
240
+
241
+ const eqIndex = flag.indexOf("=");
242
+ if (eqIndex !== -1) {
243
+ assign(flag.slice(0, eqIndex), flag.slice(eqIndex + 1));
244
+ continue;
245
+ }
246
+
247
+ const canonical = aliasToName.get(flag) ?? flag;
248
+ const def = defByName.get(canonical);
249
+ const next = tokens[i + 1];
250
+ const nextIsValue = next !== undefined && (next === "-" || !next.startsWith("-"));
251
+ if (def?.type === "boolean") {
252
+ assign(flag, true);
253
+ continue;
254
+ }
255
+ if (!nextIsValue) {
256
+ // A declared string/number flag was given without a value. Record an error
257
+ // instead of silently storing `true` (which would coerce to 1 / "true").
258
+ if (def) {
259
+ missingValueErrors.push(`Argument --${canonical} expects a ${def.type ?? "string"} value`);
260
+ continue;
261
+ }
262
+ assign(flag, true);
263
+ continue;
264
+ }
265
+ assign(flag, next);
266
+ i++;
267
+ }
268
+
269
+ const {args, errors} = createScriptArgs({defs, positional, values});
270
+ return {args, errors: [...missingValueErrors, ...errors]};
271
+ };
272
+
24
273
  export class TaskCancelledError extends Error {
25
274
  constructor(taskId: string) {
26
275
  super(`Task ${taskId} was cancelled`);