@terreno/admin-backend 0.22.1 → 0.23.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/dist/adminApp.d.ts +9 -1
- package/dist/adminApp.js +73 -15
- package/dist/index.d.ts +2 -0
- package/dist/index.js +3 -1
- package/dist/scriptCli.d.ts +42 -0
- package/dist/scriptCli.js +364 -0
- package/package.json +3 -3
- package/src/adminApp.test.ts +119 -0
- package/src/adminApp.ts +58 -1
- package/src/index.ts +2 -0
- package/src/scriptCli.test.ts +246 -0
- package/src/scriptCli.ts +273 -0
package/src/scriptCli.ts
ADDED
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
import {
|
|
2
|
+
logger,
|
|
3
|
+
parseScriptArgs,
|
|
4
|
+
type ScriptArgDef,
|
|
5
|
+
type ScriptContext,
|
|
6
|
+
type ScriptResult,
|
|
7
|
+
} from "@terreno/api";
|
|
8
|
+
|
|
9
|
+
import type {AdminScriptConfig} from "./adminApp";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Flag names reserved by the script runner itself. They control how a script is
|
|
13
|
+
* invoked (CLI flags and the HTTP `wetRun` query) and are stripped from the
|
|
14
|
+
* arguments handed to the script runner, so script authors should avoid declaring
|
|
15
|
+
* args with these names. Exported so the admin HTTP route can strip the same set
|
|
16
|
+
* and keep `ctx.args` identical across CLI and HTTP invocations.
|
|
17
|
+
*/
|
|
18
|
+
export const RESERVED_SCRIPT_FLAGS = ["help", "h", "list", "json", "wet", "wetRun", "dry"];
|
|
19
|
+
|
|
20
|
+
export interface RunScriptCliOptions {
|
|
21
|
+
/** The same script configs registered on {@link AdminApp}. */
|
|
22
|
+
scripts: AdminScriptConfig[];
|
|
23
|
+
/** Tokens to parse. Defaults to `process.argv.slice(2)`. */
|
|
24
|
+
argv?: string[];
|
|
25
|
+
/** Line writer for human-readable output. Defaults to stdout. */
|
|
26
|
+
write?: (line: string) => void;
|
|
27
|
+
/**
|
|
28
|
+
* When true (default), the process exits with the resulting exit code after the
|
|
29
|
+
* run. Pass false in tests or when embedding the runner in a larger CLI.
|
|
30
|
+
*/
|
|
31
|
+
exit?: boolean;
|
|
32
|
+
/** Program name shown in help text. Defaults to "script". */
|
|
33
|
+
programName?: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export interface RunScriptCliResult {
|
|
37
|
+
exitCode: number;
|
|
38
|
+
script?: string;
|
|
39
|
+
wetRun: boolean;
|
|
40
|
+
success: boolean;
|
|
41
|
+
results: string[];
|
|
42
|
+
errors: string[];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const formatArgUsage = (arg: ScriptArgDef): string => {
|
|
46
|
+
const type = arg.type ?? "string";
|
|
47
|
+
const base = type === "boolean" ? `--${arg.name}` : `--${arg.name} <${type}>`;
|
|
48
|
+
return arg.required ? base : `[${base}]`;
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
const describeArg = (arg: ScriptArgDef): string => {
|
|
52
|
+
const parts = [` --${arg.name}`];
|
|
53
|
+
if (arg.aliases && arg.aliases.length > 0) {
|
|
54
|
+
parts.push(`(-${arg.aliases.join(", -")})`);
|
|
55
|
+
}
|
|
56
|
+
parts.push(`[${arg.type ?? "string"}${arg.required ? ", required" : ""}]`);
|
|
57
|
+
parts.push(`- ${arg.description}`);
|
|
58
|
+
if (arg.default !== undefined) {
|
|
59
|
+
parts.push(`(default: ${String(arg.default)})`);
|
|
60
|
+
}
|
|
61
|
+
if (arg.example !== undefined) {
|
|
62
|
+
parts.push(`(e.g. ${arg.example})`);
|
|
63
|
+
}
|
|
64
|
+
return parts.join(" ");
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
const printGeneralHelp = (
|
|
68
|
+
scripts: AdminScriptConfig[],
|
|
69
|
+
programName: string,
|
|
70
|
+
write: (line: string) => void
|
|
71
|
+
): void => {
|
|
72
|
+
write(`Usage: ${programName} <script> [--wet] [args...]`);
|
|
73
|
+
write("");
|
|
74
|
+
write("Runs a registered admin script. Defaults to a dry run; pass --wet to apply changes.");
|
|
75
|
+
write("");
|
|
76
|
+
write("Options:");
|
|
77
|
+
write(" --wet, --wetRun Run in wet mode (applies changes). Default is a dry run.");
|
|
78
|
+
write(" --dry Force a dry run (overrides --wet).");
|
|
79
|
+
write(" --json Emit the result as a single JSON line.");
|
|
80
|
+
write(" --list List available scripts and exit.");
|
|
81
|
+
write(" --help, -h Show help. Combine with a script name for per-script help.");
|
|
82
|
+
write("");
|
|
83
|
+
if (scripts.length === 0) {
|
|
84
|
+
write("No scripts are registered.");
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
write("Available scripts:");
|
|
88
|
+
for (const script of scripts) {
|
|
89
|
+
write(` ${script.name} - ${script.description}`);
|
|
90
|
+
}
|
|
91
|
+
write("");
|
|
92
|
+
write(`Run "${programName} <script> --help" for a script's arguments.`);
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
const printScriptHelp = (
|
|
96
|
+
script: AdminScriptConfig,
|
|
97
|
+
programName: string,
|
|
98
|
+
write: (line: string) => void
|
|
99
|
+
): void => {
|
|
100
|
+
const args = script.args ?? [];
|
|
101
|
+
const usageArgs = args.map(formatArgUsage).join(" ");
|
|
102
|
+
write(`Usage: ${programName} ${script.name} [--wet] ${usageArgs}`.trimEnd());
|
|
103
|
+
write("");
|
|
104
|
+
write(script.description);
|
|
105
|
+
if (args.length > 0) {
|
|
106
|
+
write("");
|
|
107
|
+
write("Arguments:");
|
|
108
|
+
for (const arg of args) {
|
|
109
|
+
write(describeArg(arg));
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Runs a registered admin script from the command line. Exposes every script
|
|
116
|
+
* configured on {@link AdminApp} as a CLI so they can be invoked directly from the
|
|
117
|
+
* project (e.g. by an AI assistant) using the same definitions and argument
|
|
118
|
+
* handling as the admin HTTP routes.
|
|
119
|
+
*
|
|
120
|
+
* The caller is responsible for any environment setup the scripts need (typically
|
|
121
|
+
* connecting to MongoDB) before calling this, and for tearing it down afterwards.
|
|
122
|
+
*/
|
|
123
|
+
export const runScriptCli = async (options: RunScriptCliOptions): Promise<RunScriptCliResult> => {
|
|
124
|
+
const {scripts} = options;
|
|
125
|
+
const argv = options.argv ?? process.argv.slice(2);
|
|
126
|
+
const write = options.write ?? ((line: string) => process.stdout.write(`${line}\n`));
|
|
127
|
+
const shouldExit = options.exit !== false;
|
|
128
|
+
const programName = options.programName ?? "script";
|
|
129
|
+
|
|
130
|
+
const finish = (result: RunScriptCliResult): RunScriptCliResult => {
|
|
131
|
+
if (shouldExit) {
|
|
132
|
+
process.exit(result.exitCode);
|
|
133
|
+
}
|
|
134
|
+
return result;
|
|
135
|
+
};
|
|
136
|
+
|
|
137
|
+
const wantsHelp = argv.includes("--help") || argv.includes("-h");
|
|
138
|
+
const wantsList = argv.includes("--list");
|
|
139
|
+
const wantsJson = argv.includes("--json");
|
|
140
|
+
const scriptName = argv.find((token) => !token.startsWith("-"));
|
|
141
|
+
|
|
142
|
+
if (wantsList || (!scriptName && !wantsHelp)) {
|
|
143
|
+
printGeneralHelp(scripts, programName, write);
|
|
144
|
+
return finish({errors: [], exitCode: 0, results: [], success: true, wetRun: false});
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
if (!scriptName) {
|
|
148
|
+
printGeneralHelp(scripts, programName, write);
|
|
149
|
+
return finish({errors: [], exitCode: 0, results: [], success: true, wetRun: false});
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
const script = scripts.find((s) => s.name === scriptName);
|
|
153
|
+
if (!script) {
|
|
154
|
+
const available = scripts.map((s) => s.name).join(", ") || "(none)";
|
|
155
|
+
const message = `Unknown script: ${scriptName}. Available scripts: ${available}`;
|
|
156
|
+
write(message);
|
|
157
|
+
return finish({
|
|
158
|
+
errors: [message],
|
|
159
|
+
exitCode: 1,
|
|
160
|
+
results: [],
|
|
161
|
+
script: scriptName,
|
|
162
|
+
success: false,
|
|
163
|
+
wetRun: false,
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
if (wantsHelp) {
|
|
168
|
+
printScriptHelp(script, programName, write);
|
|
169
|
+
return finish({
|
|
170
|
+
errors: [],
|
|
171
|
+
exitCode: 0,
|
|
172
|
+
results: [],
|
|
173
|
+
script: script.name,
|
|
174
|
+
success: true,
|
|
175
|
+
wetRun: false,
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
// Everything after removing the script name is treated as arguments.
|
|
180
|
+
const nameIndex = argv.indexOf(scriptName);
|
|
181
|
+
const argTokens = [...argv.slice(0, nameIndex), ...argv.slice(nameIndex + 1)];
|
|
182
|
+
|
|
183
|
+
const {args, errors} = parseScriptArgs(argTokens, script.args ?? []);
|
|
184
|
+
|
|
185
|
+
// Reserved flags control the CLI; resolve them, then strip from the script's args.
|
|
186
|
+
const dryRequested = args.getBoolean("dry");
|
|
187
|
+
const wetRequested = args.getBoolean("wet") || args.getBoolean("wetRun");
|
|
188
|
+
const wetRun = wetRequested && !dryRequested;
|
|
189
|
+
for (const reserved of RESERVED_SCRIPT_FLAGS) {
|
|
190
|
+
delete args.raw[reserved];
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
if (errors.length > 0) {
|
|
194
|
+
for (const error of errors) {
|
|
195
|
+
write(error);
|
|
196
|
+
}
|
|
197
|
+
write("");
|
|
198
|
+
printScriptHelp(script, programName, write);
|
|
199
|
+
return finish({
|
|
200
|
+
errors,
|
|
201
|
+
exitCode: 1,
|
|
202
|
+
results: [],
|
|
203
|
+
script: script.name,
|
|
204
|
+
success: false,
|
|
205
|
+
wetRun,
|
|
206
|
+
});
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
const ctx: ScriptContext = {
|
|
210
|
+
addLog: async (level, message) => {
|
|
211
|
+
if (!wantsJson) {
|
|
212
|
+
write(`[${level}] ${message}`);
|
|
213
|
+
}
|
|
214
|
+
},
|
|
215
|
+
args,
|
|
216
|
+
checkCancellation: async () => {
|
|
217
|
+
// No background task to cancel against when running from the CLI.
|
|
218
|
+
},
|
|
219
|
+
updateProgress: async (percentage, stage, message) => {
|
|
220
|
+
if (!wantsJson) {
|
|
221
|
+
const suffix = [stage, message].filter(Boolean).join(" - ");
|
|
222
|
+
write(`[progress] ${percentage}%${suffix ? ` ${suffix}` : ""}`);
|
|
223
|
+
}
|
|
224
|
+
},
|
|
225
|
+
};
|
|
226
|
+
|
|
227
|
+
if (!wantsJson) {
|
|
228
|
+
write(`Running "${script.name}" (${wetRun ? "wet run" : "dry run"})...`);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
try {
|
|
232
|
+
const result: ScriptResult = await script.runner(wetRun, ctx);
|
|
233
|
+
if (wantsJson) {
|
|
234
|
+
write(
|
|
235
|
+
JSON.stringify({
|
|
236
|
+
results: result.results,
|
|
237
|
+
script: script.name,
|
|
238
|
+
success: result.success,
|
|
239
|
+
wetRun,
|
|
240
|
+
})
|
|
241
|
+
);
|
|
242
|
+
} else {
|
|
243
|
+
for (const line of result.results) {
|
|
244
|
+
write(line);
|
|
245
|
+
}
|
|
246
|
+
write(result.success ? "Done." : "Script reported failure.");
|
|
247
|
+
}
|
|
248
|
+
return finish({
|
|
249
|
+
errors: [],
|
|
250
|
+
exitCode: result.success ? 0 : 1,
|
|
251
|
+
results: result.results,
|
|
252
|
+
script: script.name,
|
|
253
|
+
success: result.success,
|
|
254
|
+
wetRun,
|
|
255
|
+
});
|
|
256
|
+
} catch (err: unknown) {
|
|
257
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
258
|
+
logger.error(`Script ${script.name} failed: ${message}`);
|
|
259
|
+
if (wantsJson) {
|
|
260
|
+
write(JSON.stringify({error: message, script: script.name, success: false, wetRun}));
|
|
261
|
+
} else {
|
|
262
|
+
write(`Error: ${message}`);
|
|
263
|
+
}
|
|
264
|
+
return finish({
|
|
265
|
+
errors: [message],
|
|
266
|
+
exitCode: 1,
|
|
267
|
+
results: [],
|
|
268
|
+
script: script.name,
|
|
269
|
+
success: false,
|
|
270
|
+
wetRun,
|
|
271
|
+
});
|
|
272
|
+
}
|
|
273
|
+
};
|