@orkestrel/scaffold 0.0.133 → 0.0.134

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 (82) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1018 -194
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +95 -108
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +27 -3
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  35. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  36. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  37. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  38. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  42. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  43. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
  45. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
  46. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  47. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  52. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  53. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  54. package/dist/host/claude/agents/orkestrel.md +4 -4
  55. package/dist/host/claude/rules/documentation.md +1 -1
  56. package/dist/host/claude/rules/patterns.md +5 -4
  57. package/dist/host/claude/rules/styles.md +1 -1
  58. package/dist/host/claude/rules/tests.md +3 -3
  59. package/dist/host/claude/rules/workspace.md +47 -35
  60. package/dist/host/configs/helpers.ts +40 -15
  61. package/dist/host/dotfiles/oxlintrc.json +62 -0
  62. package/dist/host/guides/form.md +79 -4
  63. package/dist/host/guides/scaffold.md +93 -65
  64. package/dist/host/guides/table.md +20 -6
  65. package/dist/host/guides/test.md +9 -7
  66. package/dist/host/manifest.json +44 -44
  67. package/dist/host/tests/config.test.ts +201 -11
  68. package/dist/host/tests/policy.test.ts +14 -21
  69. package/dist/host/tests/setupPolicy.ts +43 -36
  70. package/dist/src/core/index.cjs +191 -93
  71. package/dist/src/core/index.cjs.map +1 -1
  72. package/dist/src/core/index.d.cts +27 -13
  73. package/dist/src/core/index.d.ts +27 -13
  74. package/dist/src/core/index.js +189 -93
  75. package/dist/src/core/index.js.map +1 -1
  76. package/dist/src/server/index.cjs +8 -9
  77. package/dist/src/server/index.cjs.map +1 -1
  78. package/dist/src/server/index.d.cts +1 -1
  79. package/dist/src/server/index.d.ts +1 -1
  80. package/dist/src/server/index.js +8 -9
  81. package/dist/src/server/index.js.map +1 -1
  82. package/package.json +2 -2
@@ -1,25 +1,8 @@
1
- // Probe a bench with one bounded round trip and resolve its entry. Run from the checkout root:
2
- // node .agents/skills/orkestrel-dispatch/scripts/bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS]
3
- // node .agents/skills/orkestrel-dispatch/scripts/bench.ts --codex [--model ID] [--sandbox MODE] [--cap SECONDS]
4
- // node .agents/skills/orkestrel-dispatch/scripts/bench.ts --claude [--model ALIAS] [--cap SECONDS]
5
- // --cursor resolves the Cursor CLI entry (the newest versioned install under LOCALAPPDATA on
6
- // Windows, `agent` on PATH elsewhere), reads its version (an entry that cannot answer `--version` is
7
- // dark, with or without --resolve), and runs one bounded prompt through
8
- // launch.ts into tmp/cursor/bench.jsonl; --resolve, which only --cursor takes, stops after printing
9
- // the entry. --codex reads
10
- // `codex --version` and `codex login status`, then runs one bounded exec into tmp/codex/bench.jsonl
11
- // under the sandbox the host allows (danger-full-access on Windows, read-only elsewhere) unless
12
- // --sandbox names read-only, workspace-write, or danger-full-access. --claude
13
- // reads `claude --version` and runs one bounded print-mode prompt into tmp/claude/bench.jsonl. The
14
- // script runs launch.ts and result.ts as child processes beside it and imports neither. The JSON
15
- // summary carries the command, the version, the session id, the answer, and `live`. --cap is a
16
- // number of seconds above 0 and at most 2147483, checked before any probe runs. Name one bench per
17
- // run; the script refuses a flag it does not read, the `--flag=value` form included. Exit 0 when the
18
- // bench answered READY, 3 when it is dark, 64 on usage.
19
1
  import { spawnSync } from 'node:child_process';
20
2
  import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
21
3
  import { dirname, extname, join } from 'node:path';
22
4
  import { fileURLToPath } from 'node:url';
5
+ import { parseArgs } from 'node:util';
23
6
  /** Names the directory this script runs from, which holds the launch and result siblings. */
24
7
  export const SCRIPTS = dirname(fileURLToPath(import.meta.url));
25
8
  /** Names the extension of the running file: the checkout runs `.ts` sources and a built twin runs `.js` siblings. */
@@ -42,55 +25,37 @@ export const SANDBOX_MODES = [
42
25
  'workspace-write',
43
26
  'danger-full-access',
44
27
  ];
45
- /** Lists the flags that each select one bench. */
46
- export const BENCH_FLAGS = ['--cursor', '--codex', '--claude'];
47
- /** Lists the flags that take a value. */
48
- export const VALUE_FLAGS = ['--model', '--cap', '--sandbox'];
49
- /** Lists every flag the script reads, value flags and switches alike. */
50
- export const FLAGS = [...BENCH_FLAGS, '--resolve', ...VALUE_FLAGS];
51
28
  /** Holds the usage line printed when a call names no bench or more than one. */
52
29
  export const USAGE = 'usage: bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS] | --codex [--model ID] [--sandbox MODE] [--cap SECONDS] | --claude [--model ALIAS] [--cap SECONDS]; name one bench';
30
+ /** Declares every flag the script reads, for `parseArgs`. */
31
+ export const OPTIONS = Object.freeze({
32
+ cursor: Object.freeze({ type: 'boolean' }),
33
+ codex: Object.freeze({ type: 'boolean' }),
34
+ claude: Object.freeze({ type: 'boolean' }),
35
+ resolve: Object.freeze({ type: 'boolean' }),
36
+ model: Object.freeze({ type: 'string' }),
37
+ cap: Object.freeze({ type: 'string' }),
38
+ sandbox: Object.freeze({ type: 'string' }),
39
+ });
53
40
  /**
54
- * Reads the value that follows a flag.
55
- *
56
- * @remarks
57
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
58
- * and the `--flag=value` form is not read.
59
- *
60
- * @param argv - The arguments after the script path.
61
- * @param name - The flag, such as `--cap`.
62
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
63
- * another flag.
64
- */
65
- export function readOption(argv, name) {
66
- const index = argv.indexOf(name);
67
- const value = index === -1 ? undefined : argv[index + 1];
68
- return value === undefined || value.startsWith('--') ? undefined : value;
69
- }
70
- /**
71
- * Names the value flags a caller gave with no value.
72
- *
73
- * @param argv - The arguments after the script path.
74
- * @param names - The flags that take a value.
75
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
76
- */
77
- export function readMissingFlags(argv, names) {
78
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
79
- }
80
- /**
81
- * Names the flags a caller gave that the script does not read.
82
- *
83
- * @remarks
84
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
85
- * scan.
41
+ * Parses the arguments in strict mode against `OPTIONS`.
86
42
  *
87
43
  * @param argv - The arguments after the script path.
88
- * @param flags - Every flag the script reads, value flags and switches alike.
89
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
44
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
90
45
  */
91
- export function readUnknownFlags(argv, flags) {
92
- const end = argv.indexOf('--');
93
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
46
+ export function parseArguments(argv) {
47
+ try {
48
+ const { values, positionals } = parseArgs({
49
+ args: [...argv],
50
+ options: OPTIONS,
51
+ strict: true,
52
+ allowPositionals: false,
53
+ });
54
+ return { success: true, value: { values, positionals } };
55
+ }
56
+ catch (error) {
57
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
58
+ }
94
59
  }
95
60
  /**
96
61
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
@@ -184,7 +149,7 @@ export function resolveCursor() {
184
149
  if (local === undefined)
185
150
  return { command: [], version: undefined, error: 'LOCALAPPDATA is not set' };
186
151
  const versions = join(local, 'cursor-agent', 'versions');
187
- if (!existsSync(versions) || !statSync(versions).isDirectory()) {
152
+ if (statSync(versions, { throwIfNoEntry: false })?.isDirectory() !== true) {
188
153
  return { command: [], version: undefined, error: `${versions} is not a directory` };
189
154
  }
190
155
  const newest = readdirSync(versions, { withFileTypes: true })
@@ -256,18 +221,18 @@ export function isLive(summary) {
256
221
  /**
257
222
  * Probes the Cursor bench, or prints its entry when the call names `--resolve`.
258
223
  *
259
- * @param argv - The arguments after the script path.
224
+ * @param values - The flag values `parseArgs` read.
260
225
  * @param cap - The validated cap in seconds.
261
226
  * @param root - The directory the round trip runs in.
262
227
  * @returns Exit 0 when live or resolved, 3 when dark, with the report to print.
263
228
  */
264
- export function probeCursor(argv, cap, root) {
229
+ export function probeCursor(values, cap, root) {
265
230
  const entry = resolveCursor();
266
- const model = readOption(argv, '--model') ?? CURSOR_MODEL;
231
+ const model = typeof values.model === 'string' ? values.model : CURSOR_MODEL;
267
232
  if (entry.error !== undefined || entry.version === undefined) {
268
233
  return { report: { bench: 'cursor', ...entry, live: false }, exit: 3 };
269
234
  }
270
- if (argv.includes('--resolve')) {
235
+ if (values.resolve === true) {
271
236
  return {
272
237
  report: { bench: 'cursor', command: entry.command, version: entry.version },
273
238
  exit: 0,
@@ -302,20 +267,23 @@ export function probeCursor(argv, cap, root) {
302
267
  * Probes the Codex bench: its version, its login, and one bounded exec.
303
268
  *
304
269
  * @param command - The executable and the arguments that precede the Codex arguments, such as `['codex']`.
305
- * @param argv - The arguments after the script path.
270
+ * @param values - The flag values `parseArgs` read.
306
271
  * @param cap - The validated cap in seconds.
307
272
  * @param root - The directory the round trip runs in.
308
273
  * @returns Exit 0 when live, 3 when dark, with the report to print.
309
274
  */
310
- export function probeCodex(command, argv, cap, root) {
275
+ export function probeCodex(command, values, cap, root) {
311
276
  const [file, ...prefix] = command;
312
277
  const version = readVersion(command);
313
278
  const login = file === undefined
314
279
  ? undefined
315
280
  : spawnSync(file, [...prefix, 'login', 'status'], { encoding: 'utf8', windowsHide: true });
316
- const model = readOption(argv, '--model') ?? CODEX_MODEL;
317
- const sandbox = readOption(argv, '--sandbox') ??
318
- (process.platform === 'win32' ? 'danger-full-access' : 'read-only');
281
+ const model = typeof values.model === 'string' ? values.model : CODEX_MODEL;
282
+ const sandbox = typeof values.sandbox === 'string'
283
+ ? values.sandbox
284
+ : process.platform === 'win32'
285
+ ? 'danger-full-access'
286
+ : 'read-only';
319
287
  const status = login === undefined ? '' : `${login.stdout ?? ''}${login.stderr ?? ''}`.trim();
320
288
  if (version === undefined || login?.status !== 0) {
321
289
  return { report: { bench: 'codex', version, login: status, live: false }, exit: 3 };
@@ -355,14 +323,14 @@ export function probeCodex(command, argv, cap, root) {
355
323
  * Probes the Claude bench: its version and one bounded print-mode prompt.
356
324
  *
357
325
  * @param command - The executable and the arguments that precede the Claude arguments, such as `['claude']`.
358
- * @param argv - The arguments after the script path.
326
+ * @param values - The flag values `parseArgs` read.
359
327
  * @param cap - The validated cap in seconds.
360
328
  * @param root - The directory the round trip runs in.
361
329
  * @returns Exit 0 when live, 3 when dark, with the report to print.
362
330
  */
363
- export function probeClaude(command, argv, cap, root) {
331
+ export function probeClaude(command, values, cap, root) {
364
332
  const version = readVersion(command);
365
- const model = readOption(argv, '--model') ?? CLAUDE_MODEL;
333
+ const model = typeof values.model === 'string' ? values.model : CLAUDE_MODEL;
366
334
  if (version === undefined) {
367
335
  return { report: { bench: 'claude', version, live: false }, exit: 3 };
368
336
  }
@@ -383,17 +351,17 @@ export function probeClaude(command, argv, cap, root) {
383
351
  /**
384
352
  * Runs the probe the call names, against the real `codex` or `claude` command.
385
353
  *
386
- * @param argv - The arguments after the script path, which name one bench.
354
+ * @param values - The flag values `parseArgs` read, which name one bench.
387
355
  * @param cap - The validated cap in seconds.
388
356
  * @param root - The directory the round trip runs in.
389
357
  * @returns What the probe decided.
390
358
  */
391
- export function selectProbe(argv, cap, root) {
392
- if (argv.includes('--cursor'))
393
- return probeCursor(argv, cap, root);
394
- if (argv.includes('--codex'))
395
- return probeCodex(['codex'], argv, cap, root);
396
- return probeClaude(['claude'], argv, cap, root);
359
+ export function selectProbe(values, cap, root) {
360
+ if (values.cursor === true)
361
+ return probeCursor(values, cap, root);
362
+ if (values.codex === true)
363
+ return probeCodex(['codex'], values, cap, root);
364
+ return probeClaude(['claude'], values, cap, root);
397
365
  }
398
366
  /**
399
367
  * Runs the script on its arguments.
@@ -402,35 +370,32 @@ export function selectProbe(argv, cap, root) {
402
370
  * @returns The exit code: 0 live, 3 dark, 64 on usage.
403
371
  */
404
372
  export function main(argv) {
405
- const unknown = readUnknownFlags(argv, FLAGS);
406
- if (unknown.length > 0) {
407
- console.error(`bench: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
408
- return 64;
409
- }
410
- const missing = readMissingFlags(argv, VALUE_FLAGS);
411
- if (missing.length > 0) {
412
- console.error(`bench: ${missing.join(', ')} given with no value`);
373
+ const parsed = parseArguments(argv);
374
+ if (!parsed.success) {
375
+ console.error(`bench: ${parsed.error}; ${USAGE}`);
413
376
  return 64;
414
377
  }
415
- if (BENCH_FLAGS.filter((flag) => argv.includes(flag)).length !== 1) {
378
+ const { values } = parsed.value;
379
+ if ([values.cursor, values.codex, values.claude].filter((value) => value === true).length !== 1) {
416
380
  console.error(USAGE);
417
381
  return 64;
418
382
  }
419
- if (argv.includes('--resolve') && !argv.includes('--cursor')) {
383
+ if (values.resolve === true && values.cursor !== true) {
420
384
  console.error('bench: --resolve belongs to --cursor and reads nothing for another bench');
421
385
  return 64;
422
386
  }
423
- const sandbox = readOption(argv, '--sandbox');
387
+ const sandbox = typeof values.sandbox === 'string' ? values.sandbox : undefined;
424
388
  if (sandbox !== undefined && !SANDBOX_MODES.includes(sandbox)) {
425
- console.error(`bench: --sandbox takes one of ${SANDBOX_MODES.join(', ')}; got ${quote(sandbox)}`);
389
+ console.error(`bench: --sandbox takes one of ${SANDBOX_MODES.join(', ')}, not ${quote(sandbox)}; ${USAGE}`);
426
390
  return 64;
427
391
  }
428
- const cap = parseCap(readOption(argv, '--cap'));
392
+ const text = typeof values.cap === 'string' ? values.cap : undefined;
393
+ const cap = parseCap(text);
429
394
  if (cap === undefined) {
430
- console.error(`bench: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}`);
395
+ console.error(`bench: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}, not ${quote(text ?? '')}; ${USAGE}`);
431
396
  return 64;
432
397
  }
433
- const probe = selectProbe(argv, cap, process.cwd());
398
+ const probe = selectProbe(values, cap, process.cwd());
434
399
  console.log(JSON.stringify(probe.report));
435
400
  return probe.exit;
436
401
  }
@@ -1,20 +1,7 @@
1
- // Write a unit brief from the template, or check that every path a brief names resolves. Run from
2
- // the checkout root:
3
- // node .agents/skills/orkestrel-dispatch/scripts/brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]
4
- // node .agents/skills/orkestrel-dispatch/scripts/brief.ts --check tmp/codex/UNIT-brief.md
5
- // The first form copies the brief template beside this skill (`../../../templates/brief.md`, so a
6
- // target's installed copy finds it too) to tmp/<lane>/<unit>-brief.md with UNIT_ID and SHORT_SUBJECT
7
- // filled, and writes <unit>-brief-<n>.md when a brief already exists, so a launched brief is never
8
- // edited. The second form reads every backticked token carrying a slash (a backslash counts and is
9
- // read as a slash), strips a `:line` or
10
- // `:line-line` suffix, resolves it from the working directory, and prints the ones that do not
11
- // exist; a bare filename is outside the check. It also names each template section the brief omits:
12
- // the `## Role and engine` section, and the `## Execution` section with its spawn-nothing sentence.
13
- // The two forms are two modes; name one. The script refuses a flag it does not read, the
14
- // `--flag=value` form included. Exit 3 when a path or a section is missing, 64 on usage.
15
1
  import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
16
2
  import { dirname, join, resolve } from 'node:path';
17
3
  import { fileURLToPath } from 'node:url';
4
+ import { parseArgs } from 'node:util';
18
5
  /** Names the brief template, found from this script's own location. */
19
6
  export const TEMPLATE = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'templates', 'brief.md');
20
7
  /** Maps each lane name to the directory its briefs are written under. */
@@ -29,53 +16,34 @@ export const REQUIREMENTS = [
29
16
  { heading: '## Role and engine', sentence: undefined },
30
17
  { heading: '## Execution', sentence: 'Perform the assignment yourself and spawn nothing.' },
31
18
  ];
32
- /** Lists the flags that take a value. */
33
- export const VALUE_FLAGS = ['--unit', '--lane', '--subject', '--check'];
34
- /** Lists every flag the script reads, value flags and switches alike. */
35
- export const FLAGS = VALUE_FLAGS;
36
19
  /** Holds the usage line printed when a call names no mode. */
37
20
  export const USAGE = 'usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT] | --check PATH';
21
+ /** Declares every flag the script reads, for `parseArgs`. */
22
+ export const OPTIONS = Object.freeze({
23
+ unit: Object.freeze({ type: 'string' }),
24
+ lane: Object.freeze({ type: 'string' }),
25
+ subject: Object.freeze({ type: 'string' }),
26
+ check: Object.freeze({ type: 'string' }),
27
+ });
38
28
  /**
39
- * Reads the value that follows a flag.
40
- *
41
- * @remarks
42
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
43
- * and the `--flag=value` form is not read.
44
- *
45
- * @param argv - The arguments after the script path.
46
- * @param name - The flag, such as `--unit`.
47
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
48
- * another flag.
49
- */
50
- export function readOption(argv, name) {
51
- const index = argv.indexOf(name);
52
- const value = index === -1 ? undefined : argv[index + 1];
53
- return value === undefined || value.startsWith('--') ? undefined : value;
54
- }
55
- /**
56
- * Names the value flags a caller gave with no value.
57
- *
58
- * @param argv - The arguments after the script path.
59
- * @param names - The flags that take a value.
60
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
61
- */
62
- export function readMissingFlags(argv, names) {
63
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
64
- }
65
- /**
66
- * Names the flags a caller gave that the script does not read.
67
- *
68
- * @remarks
69
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
70
- * scan.
29
+ * Parses the arguments in strict mode against `OPTIONS`.
71
30
  *
72
31
  * @param argv - The arguments after the script path.
73
- * @param flags - Every flag the script reads, value flags and switches alike.
74
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
32
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
75
33
  */
76
- export function readUnknownFlags(argv, flags) {
77
- const end = argv.indexOf('--');
78
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
34
+ export function parseArguments(argv) {
35
+ try {
36
+ const { values, positionals } = parseArgs({
37
+ args: [...argv],
38
+ options: OPTIONS,
39
+ strict: true,
40
+ allowPositionals: false,
41
+ });
42
+ return { success: true, value: { values, positionals } };
43
+ }
44
+ catch (error) {
45
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
46
+ }
79
47
  }
80
48
  /**
81
49
  * Checks whether a backticked token reads as a repository path.
@@ -157,24 +125,32 @@ export function resolveBriefPath(directory, unit, count = 1) {
157
125
  /**
158
126
  * Writes a brief from the template.
159
127
  *
160
- * @param argv - The arguments after the script path.
128
+ * @param values - The flag values `parseArgs` read.
161
129
  * @returns The exit code: 0 on success, 64 on usage or a missing template.
162
130
  */
163
- export function writeBrief(argv) {
164
- const unit = readOption(argv, '--unit');
165
- const lane = readOption(argv, '--lane');
166
- const directory = lane === undefined ? undefined : LANES[lane];
167
- if (unit === undefined || directory === undefined || !/^[A-Za-z0-9._-]+$/u.test(unit)) {
131
+ export function writeBrief(values) {
132
+ const unit = typeof values.unit === 'string' ? values.unit : undefined;
133
+ const lane = typeof values.lane === 'string' ? values.lane : undefined;
134
+ if (unit === undefined || lane === undefined) {
168
135
  console.error('usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]');
169
136
  return 64;
170
137
  }
138
+ if (!/^[A-Za-z0-9._-]+$/u.test(unit)) {
139
+ console.error(`brief: --unit takes letters, digits, dots, underscores, and hyphens, not ${JSON.stringify(unit)}`);
140
+ return 64;
141
+ }
142
+ const directory = LANES[lane];
143
+ if (directory === undefined) {
144
+ console.error(`brief: --lane takes units, cursor, codex, or claude, not ${JSON.stringify(lane)}`);
145
+ return 64;
146
+ }
171
147
  if (!existsSync(TEMPLATE)) {
172
148
  console.error(`brief: the template is missing at ${TEMPLATE}`);
173
149
  return 64;
174
150
  }
175
151
  mkdirSync(directory, { recursive: true });
176
152
  const path = resolveBriefPath(directory, unit);
177
- const subject = readOption(argv, '--subject') ?? 'SHORT_SUBJECT';
153
+ const subject = typeof values.subject === 'string' ? values.subject : 'SHORT_SUBJECT';
178
154
  const content = readFileSync(TEMPLATE, 'utf8')
179
155
  .replace(/UNIT_ID/gu, unit)
180
156
  .replace(/SHORT_SUBJECT/gu, subject);
@@ -190,7 +166,7 @@ export function writeBrief(argv) {
190
166
  * missing or a section is omitted, 64 when the brief is not a file.
191
167
  */
192
168
  export function checkBrief(path) {
193
- if (!existsSync(path) || !statSync(path).isFile()) {
169
+ if (statSync(path, { throwIfNoEntry: false })?.isFile() !== true) {
194
170
  console.error(`brief: ${path} is not a file`);
195
171
  return 64;
196
172
  }
@@ -211,25 +187,21 @@ export function checkBrief(path) {
211
187
  * usage.
212
188
  */
213
189
  export function main(argv) {
214
- const unknown = readUnknownFlags(argv, FLAGS);
215
- if (unknown.length > 0) {
216
- console.error(`brief: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
217
- return 64;
218
- }
219
- const missing = readMissingFlags(argv, VALUE_FLAGS);
220
- if (missing.length > 0) {
221
- console.error(`brief: ${missing.join(', ')} given with no value`);
190
+ const parsed = parseArguments(argv);
191
+ if (!parsed.success) {
192
+ console.error(`brief: ${parsed.error}; ${USAGE}`);
222
193
  return 64;
223
194
  }
224
- const check = readOption(argv, '--check');
225
- if (check !== undefined && argv.includes('--unit')) {
226
- console.error('brief: --check and --unit are two modes; name one');
195
+ const { values } = parsed.value;
196
+ const check = typeof values.check === 'string' ? values.check : undefined;
197
+ if (check !== undefined && values.unit !== undefined) {
198
+ console.error(`brief: --check and --unit are two modes; name one; ${USAGE}`);
227
199
  return 64;
228
200
  }
229
201
  if (check !== undefined)
230
202
  return checkBrief(check);
231
- if (argv.includes('--unit'))
232
- return writeBrief(argv);
203
+ if (values.unit !== undefined)
204
+ return writeBrief(values);
233
205
  console.error(USAGE);
234
206
  return 64;
235
207
  }
@@ -1,70 +1,35 @@
1
- // Run a plan of commands in order and journal each one. Run from the checkout root:
2
- // node .agents/skills/orkestrel-dispatch/scripts/chain.ts --plan FILE.json --journal DIR
3
- // The plan is a JSON array of steps, each `{ "name": "...", "command": "...", "args": ["..."] }`
4
- // with an optional `"cwd"` (a directory, relative to the working directory) and `"env"` (a record
5
- // of strings laid over this process's environment by case-folded name, so an added variable drops
6
- // every inherited one whose lower-cased name it claims). A step name is letters, digits, dots,
7
- // underscores, and hyphens, opens with a letter or digit, and is unique in the plan. Each step runs
8
- // with no shell and closed stdin, in plan order, with its standard output and standard error
9
- // written together to `DIR/<name>.txt`; the script prints one `name exit=N durationMs=N` line per
10
- // step and stops at the first step that does not exit 0. Because no shell runs, a command that is a
11
- // Windows `.cmd` shim, such as `npm`, starts only through the interpreter it wraps. A step that
12
- // must not stop the chain belongs in a second plan; launch the chain itself through `launch.ts`
13
- // for a cap. The script refuses a flag it does not read, the `--flag=value` form included.
14
- // Exit 0 when every step exited 0, the failing step's exit code when one did not, 2 when a step
15
- // cannot start, 64 on usage.
16
1
  import { spawnSync } from 'node:child_process';
17
2
  import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync } from 'node:fs';
18
3
  import { join, resolve } from 'node:path';
19
- /** Lists the flags that take a value. */
20
- export const VALUE_FLAGS = ['--plan', '--journal'];
21
- /** Lists every flag the script reads, value flags and switches alike. */
22
- export const FLAGS = VALUE_FLAGS;
4
+ import { parseArgs } from 'node:util';
5
+ /** Declares every flag the script reads, for `parseArgs`. */
6
+ export const OPTIONS = Object.freeze({
7
+ plan: Object.freeze({ type: 'string' }),
8
+ journal: Object.freeze({ type: 'string' }),
9
+ });
23
10
  /** Holds the usage line printed when a call names no plan or no journal. */
24
11
  export const USAGE = 'usage: chain.ts --plan FILE.json --journal DIR';
25
12
  /** Matches a step name that is safe as a journal file name. */
26
13
  export const STEP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
27
14
  /**
28
- * Reads the value that follows a flag.
29
- *
30
- * @remarks
31
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
32
- * and the `--flag=value` form is not read.
33
- *
34
- * @param argv - The arguments after the script path.
35
- * @param name - The flag, such as `--plan`.
36
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
37
- * another flag.
38
- */
39
- export function readOption(argv, name) {
40
- const index = argv.indexOf(name);
41
- const value = index === -1 ? undefined : argv[index + 1];
42
- return value === undefined || value.startsWith('--') ? undefined : value;
43
- }
44
- /**
45
- * Names the value flags a caller gave with no value.
46
- *
47
- * @param argv - The arguments after the script path.
48
- * @param names - The flags that take a value.
49
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
50
- */
51
- export function readMissingFlags(argv, names) {
52
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
53
- }
54
- /**
55
- * Names the flags a caller gave that the script does not read.
56
- *
57
- * @remarks
58
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
59
- * scan.
15
+ * Parses the arguments in strict mode against `OPTIONS`.
60
16
  *
61
17
  * @param argv - The arguments after the script path.
62
- * @param flags - Every flag the script reads, value flags and switches alike.
63
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
18
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
64
19
  */
65
- export function readUnknownFlags(argv, flags) {
66
- const end = argv.indexOf('--');
67
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
20
+ export function parseArguments(argv) {
21
+ try {
22
+ const { values, positionals } = parseArgs({
23
+ args: [...argv],
24
+ options: OPTIONS,
25
+ strict: true,
26
+ allowPositionals: false,
27
+ });
28
+ return { success: true, value: { values, positionals } };
29
+ }
30
+ catch (error) {
31
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
32
+ }
68
33
  }
69
34
  /**
70
35
  * Checks whether a value is a non-null, non-array object.
@@ -263,18 +228,14 @@ export function formatStep(step, finish) {
263
228
  * cannot start, 64 on usage.
264
229
  */
265
230
  export function main(argv) {
266
- const unknown = readUnknownFlags(argv, FLAGS);
267
- if (unknown.length > 0) {
268
- console.error(`chain: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
269
- return 64;
270
- }
271
- const missing = readMissingFlags(argv, VALUE_FLAGS);
272
- if (missing.length > 0) {
273
- console.error(`chain: ${missing.join(', ')} given with no value`);
231
+ const parsed = parseArguments(argv);
232
+ if (!parsed.success) {
233
+ console.error(`chain: ${parsed.error}; ${USAGE}`);
274
234
  return 64;
275
235
  }
276
- const path = readOption(argv, '--plan');
277
- const journal = readOption(argv, '--journal');
236
+ const { values } = parsed.value;
237
+ const path = typeof values.plan === 'string' ? values.plan : undefined;
238
+ const journal = typeof values.journal === 'string' ? values.journal : undefined;
278
239
  if (path === undefined || journal === undefined || !existsSync(path)) {
279
240
  console.error(USAGE);
280
241
  return 64;