@orkestrel/scaffold 0.0.132 → 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 (86) 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 +30 -6
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/agents/orchestration.md +1 -0
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  35. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  36. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  37. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  38. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  42. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  43. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  45. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
  46. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
  47. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
  52. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  53. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  54. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  55. package/dist/host/claude/agents/orkestrel.md +54 -54
  56. package/dist/host/claude/rules/documentation.md +1 -1
  57. package/dist/host/claude/rules/patterns.md +5 -4
  58. package/dist/host/claude/rules/styles.md +1 -1
  59. package/dist/host/claude/rules/tests.md +8 -3
  60. package/dist/host/claude/rules/workspace.md +47 -35
  61. package/dist/host/configs/helpers.ts +40 -15
  62. package/dist/host/dotfiles/oxlintrc.json +62 -0
  63. package/dist/host/guides/browser.md +1 -1
  64. package/dist/host/guides/form.md +79 -4
  65. package/dist/host/guides/queue.md +3 -1
  66. package/dist/host/guides/scaffold.md +95 -67
  67. package/dist/host/guides/table.md +20 -6
  68. package/dist/host/guides/test.md +342 -202
  69. package/dist/host/guides/workflow.md +4 -2
  70. package/dist/host/manifest.json +48 -48
  71. package/dist/host/tests/config.test.ts +201 -11
  72. package/dist/host/tests/policy.test.ts +15 -22
  73. package/dist/host/tests/setupPolicy.ts +43 -36
  74. package/dist/src/core/index.cjs +194 -97
  75. package/dist/src/core/index.cjs.map +1 -1
  76. package/dist/src/core/index.d.cts +27 -13
  77. package/dist/src/core/index.d.ts +27 -13
  78. package/dist/src/core/index.js +192 -97
  79. package/dist/src/core/index.js.map +1 -1
  80. package/dist/src/server/index.cjs +8 -9
  81. package/dist/src/server/index.cjs.map +1 -1
  82. package/dist/src/server/index.d.cts +1 -1
  83. package/dist/src/server/index.d.ts +1 -1
  84. package/dist/src/server/index.js +8 -9
  85. package/dist/src/server/index.js.map +1 -1
  86. package/package.json +5 -5
@@ -111,6 +111,7 @@ The harness's own engine orchestrates: Claude Fable 5.2 or Claude Opus 5.5 in Cl
111
111
  - Size the effort to the task before spending: a lookup takes one lane, routed per § Routing, and only open-ended work with independent, high-value parts fans out, per § Parallelism.
112
112
  - Locate the evidence with short broad probes before any deep pass: a run of the shipped command, a census, a search. Go deep only on a defect or gap a run has shown, in one lane, with the narrowest instrument that answers it: a counting probe or a mutation.
113
113
  - When work is experimental or its viability is open, settle viability first with throwaway probes and a thin end-to-end prototype under `tmp/probes/`, breadth-first, before any design's deep phase, any long measured run, or any build. Write each probe and prototype so its cases and assertions carry into the test, study, or journey it would become. A probe takes whatever leeway its question needs. When a unit adopts one, keep its cases and assertions and rewrite everything else to the rules, never copying it: names, placement, kind files, shared fixtures, and the test, study, or journey conventions. Review judges promoted code as it judges any other. A probe that answers no opens a design question before anything builds on it.
114
+ - When evidence needs a model's or a service's response, take it from a seeded `@orkestrel/study` scenario. Record the live run once, reach each trial and goal the question needs through `study execute` with `--seed <result>:<trial>:<goal>`, `--trial`, and `--goals`, replay it offline with `--replay` under `--prefix` or `--roles`, and drive a scripted provider where no recording holds the response. Start a live run only for a response no recording holds.
114
115
  - When a defect class can recur across packages, census the class across every package before a review of any one: a script lists the whole population, `scout` marks each listed row against the brief's explicit criteria, and `analyst` or the Orchestrator rules each marked row once and fixes it at its cause. A list made by hand is no population.
115
116
  - Define a class in a census by what the code does, never by how it spells it. Where a baseline build exists, run a seeded differential against it over the repair's input domain, and report a search's hits as a floor, never as the class.
116
117
  - Set every stop with what reopens it, and record both in the plan. At a re-examination, hold the stop unless a proposal names the condition it meets; a stop that names no condition passes only on the user's ruling. Before a continuation, record whether its unit repairs an admitted row or reopens the stopped seam.
@@ -14,12 +14,14 @@
14
14
  // script runs launch.ts and result.ts as child processes beside it and imports neither. The JSON
15
15
  // summary carries the command, the version, the session id, the answer, and `live`. --cap is a
16
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.
17
+ // run; the script reads its flags with `parseArgs` in strict mode. Exit 0 when the bench answered
18
+ // READY, 3 when it is dark, 64 on usage.
19
+ import type { ParseArgsOptionsConfig } from 'node:util'
19
20
  import { spawnSync } from 'node:child_process'
20
21
  import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
21
22
  import { dirname, extname, join } from 'node:path'
22
23
  import { fileURLToPath } from 'node:url'
24
+ import { parseArgs } from 'node:util'
23
25
 
24
26
  /** Names the directory this script runs from, which holds the launch and result siblings. */
25
27
  export const SCRIPTS = dirname(fileURLToPath(import.meta.url))
@@ -52,19 +54,54 @@ export const SANDBOX_MODES: readonly string[] = [
52
54
  'danger-full-access',
53
55
  ]
54
56
 
55
- /** Lists the flags that each select one bench. */
56
- export const BENCH_FLAGS: readonly string[] = ['--cursor', '--codex', '--claude']
57
-
58
- /** Lists the flags that take a value. */
59
- export const VALUE_FLAGS: readonly string[] = ['--model', '--cap', '--sandbox']
60
-
61
- /** Lists every flag the script reads, value flags and switches alike. */
62
- export const FLAGS: readonly string[] = [...BENCH_FLAGS, '--resolve', ...VALUE_FLAGS]
63
-
64
57
  /** Holds the usage line printed when a call names no bench or more than one. */
65
58
  export const USAGE =
66
59
  'usage: bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS] | --codex [--model ID] [--sandbox MODE] [--cap SECONDS] | --claude [--model ALIAS] [--cap SECONDS]; name one bench'
67
60
 
61
+ /** Declares every flag the script reads, for `parseArgs`. */
62
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
63
+ cursor: Object.freeze({ type: 'boolean' }),
64
+ codex: Object.freeze({ type: 'boolean' }),
65
+ claude: Object.freeze({ type: 'boolean' }),
66
+ resolve: Object.freeze({ type: 'boolean' }),
67
+ model: Object.freeze({ type: 'string' }),
68
+ cap: Object.freeze({ type: 'string' }),
69
+ sandbox: Object.freeze({ type: 'string' }),
70
+ })
71
+
72
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
73
+ export interface Arguments {
74
+ readonly values: Readonly<
75
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
76
+ >
77
+ readonly positionals: readonly string[]
78
+ }
79
+
80
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
81
+ export type ArgumentsResult =
82
+ | { readonly success: true; readonly value: Arguments }
83
+ | { readonly success: false; readonly error: string }
84
+
85
+ /**
86
+ * Parses the arguments in strict mode against `OPTIONS`.
87
+ *
88
+ * @param argv - The arguments after the script path.
89
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
90
+ */
91
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
92
+ try {
93
+ const { values, positionals } = parseArgs({
94
+ args: [...argv],
95
+ options: OPTIONS,
96
+ strict: true,
97
+ allowPositionals: false,
98
+ })
99
+ return { success: true, value: { values, positionals } }
100
+ } catch (error) {
101
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
102
+ }
103
+ }
104
+
68
105
  /** Names one bench a probe can run against. */
69
106
  export type Bench = 'cursor' | 'codex' | 'claude'
70
107
 
@@ -90,59 +127,6 @@ export interface Probe {
90
127
  readonly exit: number
91
128
  }
92
129
 
93
- /**
94
- * Reads the value that follows a flag.
95
- *
96
- * @remarks
97
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
98
- * and the `--flag=value` form is not read.
99
- *
100
- * @param argv - The arguments after the script path.
101
- * @param name - The flag, such as `--cap`.
102
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
103
- * another flag.
104
- */
105
- export function readOption(argv: readonly string[], name: string): string | undefined {
106
- const index = argv.indexOf(name)
107
- const value = index === -1 ? undefined : argv[index + 1]
108
- return value === undefined || value.startsWith('--') ? undefined : value
109
- }
110
-
111
- /**
112
- * Names the value flags a caller gave with no value.
113
- *
114
- * @param argv - The arguments after the script path.
115
- * @param names - The flags that take a value.
116
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
117
- */
118
- export function readMissingFlags(
119
- argv: readonly string[],
120
- names: readonly string[],
121
- ): readonly string[] {
122
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
123
- }
124
-
125
- /**
126
- * Names the flags a caller gave that the script does not read.
127
- *
128
- * @remarks
129
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
130
- * scan.
131
- *
132
- * @param argv - The arguments after the script path.
133
- * @param flags - Every flag the script reads, value flags and switches alike.
134
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
135
- */
136
- export function readUnknownFlags(
137
- argv: readonly string[],
138
- flags: readonly string[],
139
- ): readonly string[] {
140
- const end = argv.indexOf('--')
141
- return (end === -1 ? argv : argv.slice(0, end)).filter(
142
- (argument) => argument.startsWith('--') && !flags.includes(argument),
143
- )
144
- }
145
-
146
130
  /**
147
131
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
148
132
  *
@@ -243,7 +227,7 @@ export function resolveCursor(): Entry {
243
227
  if (local === undefined)
244
228
  return { command: [], version: undefined, error: 'LOCALAPPDATA is not set' }
245
229
  const versions = join(local, 'cursor-agent', 'versions')
246
- if (!existsSync(versions) || !statSync(versions).isDirectory()) {
230
+ if (statSync(versions, { throwIfNoEntry: false })?.isDirectory() !== true) {
247
231
  return { command: [], version: undefined, error: `${versions} is not a directory` }
248
232
  }
249
233
  const newest = readdirSync(versions, { withFileTypes: true })
@@ -333,18 +317,18 @@ export function isLive(summary: Summary): boolean {
333
317
  /**
334
318
  * Probes the Cursor bench, or prints its entry when the call names `--resolve`.
335
319
  *
336
- * @param argv - The arguments after the script path.
320
+ * @param values - The flag values `parseArgs` read.
337
321
  * @param cap - The validated cap in seconds.
338
322
  * @param root - The directory the round trip runs in.
339
323
  * @returns Exit 0 when live or resolved, 3 when dark, with the report to print.
340
324
  */
341
- export function probeCursor(argv: readonly string[], cap: number, root: string): Probe {
325
+ export function probeCursor(values: Arguments['values'], cap: number, root: string): Probe {
342
326
  const entry = resolveCursor()
343
- const model = readOption(argv, '--model') ?? CURSOR_MODEL
327
+ const model = typeof values.model === 'string' ? values.model : CURSOR_MODEL
344
328
  if (entry.error !== undefined || entry.version === undefined) {
345
329
  return { report: { bench: 'cursor', ...entry, live: false }, exit: 3 }
346
330
  }
347
- if (argv.includes('--resolve')) {
331
+ if (values.resolve === true) {
348
332
  return {
349
333
  report: { bench: 'cursor', command: entry.command, version: entry.version },
350
334
  exit: 0,
@@ -385,14 +369,14 @@ export function probeCursor(argv: readonly string[], cap: number, root: string):
385
369
  * Probes the Codex bench: its version, its login, and one bounded exec.
386
370
  *
387
371
  * @param command - The executable and the arguments that precede the Codex arguments, such as `['codex']`.
388
- * @param argv - The arguments after the script path.
372
+ * @param values - The flag values `parseArgs` read.
389
373
  * @param cap - The validated cap in seconds.
390
374
  * @param root - The directory the round trip runs in.
391
375
  * @returns Exit 0 when live, 3 when dark, with the report to print.
392
376
  */
393
377
  export function probeCodex(
394
378
  command: readonly string[],
395
- argv: readonly string[],
379
+ values: Arguments['values'],
396
380
  cap: number,
397
381
  root: string,
398
382
  ): Probe {
@@ -402,10 +386,13 @@ export function probeCodex(
402
386
  file === undefined
403
387
  ? undefined
404
388
  : spawnSync(file, [...prefix, 'login', 'status'], { encoding: 'utf8', windowsHide: true })
405
- const model = readOption(argv, '--model') ?? CODEX_MODEL
389
+ const model = typeof values.model === 'string' ? values.model : CODEX_MODEL
406
390
  const sandbox =
407
- readOption(argv, '--sandbox') ??
408
- (process.platform === 'win32' ? 'danger-full-access' : 'read-only')
391
+ typeof values.sandbox === 'string'
392
+ ? values.sandbox
393
+ : process.platform === 'win32'
394
+ ? 'danger-full-access'
395
+ : 'read-only'
409
396
  const status = login === undefined ? '' : `${login.stdout ?? ''}${login.stderr ?? ''}`.trim()
410
397
  if (version === undefined || login?.status !== 0) {
411
398
  return { report: { bench: 'codex', version, login: status, live: false }, exit: 3 }
@@ -451,19 +438,19 @@ export function probeCodex(
451
438
  * Probes the Claude bench: its version and one bounded print-mode prompt.
452
439
  *
453
440
  * @param command - The executable and the arguments that precede the Claude arguments, such as `['claude']`.
454
- * @param argv - The arguments after the script path.
441
+ * @param values - The flag values `parseArgs` read.
455
442
  * @param cap - The validated cap in seconds.
456
443
  * @param root - The directory the round trip runs in.
457
444
  * @returns Exit 0 when live, 3 when dark, with the report to print.
458
445
  */
459
446
  export function probeClaude(
460
447
  command: readonly string[],
461
- argv: readonly string[],
448
+ values: Arguments['values'],
462
449
  cap: number,
463
450
  root: string,
464
451
  ): Probe {
465
452
  const version = readVersion(command)
466
- const model = readOption(argv, '--model') ?? CLAUDE_MODEL
453
+ const model = typeof values.model === 'string' ? values.model : CLAUDE_MODEL
467
454
  if (version === undefined) {
468
455
  return { report: { bench: 'claude', version, live: false }, exit: 3 }
469
456
  }
@@ -490,15 +477,15 @@ export function probeClaude(
490
477
  /**
491
478
  * Runs the probe the call names, against the real `codex` or `claude` command.
492
479
  *
493
- * @param argv - The arguments after the script path, which name one bench.
480
+ * @param values - The flag values `parseArgs` read, which name one bench.
494
481
  * @param cap - The validated cap in seconds.
495
482
  * @param root - The directory the round trip runs in.
496
483
  * @returns What the probe decided.
497
484
  */
498
- export function selectProbe(argv: readonly string[], cap: number, root: string): Probe {
499
- if (argv.includes('--cursor')) return probeCursor(argv, cap, root)
500
- if (argv.includes('--codex')) return probeCodex(['codex'], argv, cap, root)
501
- return probeClaude(['claude'], argv, cap, root)
485
+ export function selectProbe(values: Arguments['values'], cap: number, root: string): Probe {
486
+ if (values.cursor === true) return probeCursor(values, cap, root)
487
+ if (values.codex === true) return probeCodex(['codex'], values, cap, root)
488
+ return probeClaude(['claude'], values, cap, root)
502
489
  }
503
490
 
504
491
  /**
@@ -508,39 +495,36 @@ export function selectProbe(argv: readonly string[], cap: number, root: string):
508
495
  * @returns The exit code: 0 live, 3 dark, 64 on usage.
509
496
  */
510
497
  export function main(argv: readonly string[]): number {
511
- const unknown = readUnknownFlags(argv, FLAGS)
512
- if (unknown.length > 0) {
513
- console.error(`bench: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
514
- return 64
515
- }
516
- const missing = readMissingFlags(argv, VALUE_FLAGS)
517
- if (missing.length > 0) {
518
- console.error(`bench: ${missing.join(', ')} given with no value`)
498
+ const parsed = parseArguments(argv)
499
+ if (!parsed.success) {
500
+ console.error(`bench: ${parsed.error}; ${USAGE}`)
519
501
  return 64
520
502
  }
521
- if (BENCH_FLAGS.filter((flag) => argv.includes(flag)).length !== 1) {
503
+ const { values } = parsed.value
504
+ if ([values.cursor, values.codex, values.claude].filter((value) => value === true).length !== 1) {
522
505
  console.error(USAGE)
523
506
  return 64
524
507
  }
525
- if (argv.includes('--resolve') && !argv.includes('--cursor')) {
508
+ if (values.resolve === true && values.cursor !== true) {
526
509
  console.error('bench: --resolve belongs to --cursor and reads nothing for another bench')
527
510
  return 64
528
511
  }
529
- const sandbox = readOption(argv, '--sandbox')
512
+ const sandbox = typeof values.sandbox === 'string' ? values.sandbox : undefined
530
513
  if (sandbox !== undefined && !SANDBOX_MODES.includes(sandbox)) {
531
514
  console.error(
532
- `bench: --sandbox takes one of ${SANDBOX_MODES.join(', ')}; got ${quote(sandbox)}`,
515
+ `bench: --sandbox takes one of ${SANDBOX_MODES.join(', ')}, not ${quote(sandbox)}; ${USAGE}`,
533
516
  )
534
517
  return 64
535
518
  }
536
- const cap = parseCap(readOption(argv, '--cap'))
519
+ const text = typeof values.cap === 'string' ? values.cap : undefined
520
+ const cap = parseCap(text)
537
521
  if (cap === undefined) {
538
522
  console.error(
539
- `bench: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}`,
523
+ `bench: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}, not ${quote(text ?? '')}; ${USAGE}`,
540
524
  )
541
525
  return 64
542
526
  }
543
- const probe = selectProbe(argv, cap, process.cwd())
527
+ const probe = selectProbe(values, cap, process.cwd())
544
528
  console.log(JSON.stringify(probe.report))
545
529
  return probe.exit
546
530
  }
@@ -10,11 +10,13 @@
10
10
  // `:line-line` suffix, resolves it from the working directory, and prints the ones that do not
11
11
  // exist; a bare filename is outside the check. It also names each template section the brief omits:
12
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.
13
+ // The two forms are two modes; name one. The script reads its flags with `parseArgs` in strict
14
+ // mode. Exit 3 when a path or a section is missing, 64 on usage.
15
+ import type { ParseArgsOptionsConfig } from 'node:util'
15
16
  import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
16
17
  import { dirname, join, resolve } from 'node:path'
17
18
  import { fileURLToPath } from 'node:url'
19
+ import { parseArgs } from 'node:util'
18
20
 
19
21
  /** Names the brief template, found from this script's own location. */
20
22
  export const TEMPLATE = resolve(
@@ -46,67 +48,49 @@ export const REQUIREMENTS: readonly Requirement[] = [
46
48
  { heading: '## Execution', sentence: 'Perform the assignment yourself and spawn nothing.' },
47
49
  ]
48
50
 
49
- /** Lists the flags that take a value. */
50
- export const VALUE_FLAGS: readonly string[] = ['--unit', '--lane', '--subject', '--check']
51
-
52
- /** Lists every flag the script reads, value flags and switches alike. */
53
- export const FLAGS: readonly string[] = VALUE_FLAGS
54
-
55
51
  /** Holds the usage line printed when a call names no mode. */
56
52
  export const USAGE =
57
53
  'usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT] | --check PATH'
58
54
 
59
- /**
60
- * Reads the value that follows a flag.
61
- *
62
- * @remarks
63
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
64
- * and the `--flag=value` form is not read.
65
- *
66
- * @param argv - The arguments after the script path.
67
- * @param name - The flag, such as `--unit`.
68
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
69
- * another flag.
70
- */
71
- export function readOption(argv: readonly string[], name: string): string | undefined {
72
- const index = argv.indexOf(name)
73
- const value = index === -1 ? undefined : argv[index + 1]
74
- return value === undefined || value.startsWith('--') ? undefined : value
75
- }
55
+ /** Declares every flag the script reads, for `parseArgs`. */
56
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
57
+ unit: Object.freeze({ type: 'string' }),
58
+ lane: Object.freeze({ type: 'string' }),
59
+ subject: Object.freeze({ type: 'string' }),
60
+ check: Object.freeze({ type: 'string' }),
61
+ })
76
62
 
77
- /**
78
- * Names the value flags a caller gave with no value.
79
- *
80
- * @param argv - The arguments after the script path.
81
- * @param names - The flags that take a value.
82
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
83
- */
84
- export function readMissingFlags(
85
- argv: readonly string[],
86
- names: readonly string[],
87
- ): readonly string[] {
88
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
63
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
64
+ export interface Arguments {
65
+ readonly values: Readonly<
66
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
67
+ >
68
+ readonly positionals: readonly string[]
89
69
  }
90
70
 
71
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
72
+ export type ArgumentsResult =
73
+ | { readonly success: true; readonly value: Arguments }
74
+ | { readonly success: false; readonly error: string }
75
+
91
76
  /**
92
- * Names the flags a caller gave that the script does not read.
93
- *
94
- * @remarks
95
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
96
- * scan.
77
+ * Parses the arguments in strict mode against `OPTIONS`.
97
78
  *
98
79
  * @param argv - The arguments after the script path.
99
- * @param flags - Every flag the script reads, value flags and switches alike.
100
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
80
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
101
81
  */
102
- export function readUnknownFlags(
103
- argv: readonly string[],
104
- flags: readonly string[],
105
- ): readonly string[] {
106
- const end = argv.indexOf('--')
107
- return (end === -1 ? argv : argv.slice(0, end)).filter(
108
- (argument) => argument.startsWith('--') && !flags.includes(argument),
109
- )
82
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
83
+ try {
84
+ const { values, positionals } = parseArgs({
85
+ args: [...argv],
86
+ options: OPTIONS,
87
+ strict: true,
88
+ allowPositionals: false,
89
+ })
90
+ return { success: true, value: { values, positionals } }
91
+ } catch (error) {
92
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
93
+ }
110
94
  }
111
95
 
112
96
  /**
@@ -192,24 +176,36 @@ export function resolveBriefPath(directory: string, unit: string, count = 1): st
192
176
  /**
193
177
  * Writes a brief from the template.
194
178
  *
195
- * @param argv - The arguments after the script path.
179
+ * @param values - The flag values `parseArgs` read.
196
180
  * @returns The exit code: 0 on success, 64 on usage or a missing template.
197
181
  */
198
- export function writeBrief(argv: readonly string[]): number {
199
- const unit = readOption(argv, '--unit')
200
- const lane = readOption(argv, '--lane')
201
- const directory = lane === undefined ? undefined : LANES[lane]
202
- if (unit === undefined || directory === undefined || !/^[A-Za-z0-9._-]+$/u.test(unit)) {
182
+ export function writeBrief(values: Arguments['values']): number {
183
+ const unit = typeof values.unit === 'string' ? values.unit : undefined
184
+ const lane = typeof values.lane === 'string' ? values.lane : undefined
185
+ if (unit === undefined || lane === undefined) {
203
186
  console.error('usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]')
204
187
  return 64
205
188
  }
189
+ if (!/^[A-Za-z0-9._-]+$/u.test(unit)) {
190
+ console.error(
191
+ `brief: --unit takes letters, digits, dots, underscores, and hyphens, not ${JSON.stringify(unit)}`,
192
+ )
193
+ return 64
194
+ }
195
+ const directory = LANES[lane]
196
+ if (directory === undefined) {
197
+ console.error(
198
+ `brief: --lane takes units, cursor, codex, or claude, not ${JSON.stringify(lane)}`,
199
+ )
200
+ return 64
201
+ }
206
202
  if (!existsSync(TEMPLATE)) {
207
203
  console.error(`brief: the template is missing at ${TEMPLATE}`)
208
204
  return 64
209
205
  }
210
206
  mkdirSync(directory, { recursive: true })
211
207
  const path = resolveBriefPath(directory, unit)
212
- const subject = readOption(argv, '--subject') ?? 'SHORT_SUBJECT'
208
+ const subject = typeof values.subject === 'string' ? values.subject : 'SHORT_SUBJECT'
213
209
  const content = readFileSync(TEMPLATE, 'utf8')
214
210
  .replace(/UNIT_ID/gu, unit)
215
211
  .replace(/SHORT_SUBJECT/gu, subject)
@@ -226,7 +222,7 @@ export function writeBrief(argv: readonly string[]): number {
226
222
  * missing or a section is omitted, 64 when the brief is not a file.
227
223
  */
228
224
  export function checkBrief(path: string): number {
229
- if (!existsSync(path) || !statSync(path).isFile()) {
225
+ if (statSync(path, { throwIfNoEntry: false })?.isFile() !== true) {
230
226
  console.error(`brief: ${path} is not a file`)
231
227
  return 64
232
228
  }
@@ -247,23 +243,19 @@ export function checkBrief(path: string): number {
247
243
  * usage.
248
244
  */
249
245
  export function main(argv: readonly string[]): number {
250
- const unknown = readUnknownFlags(argv, FLAGS)
251
- if (unknown.length > 0) {
252
- console.error(`brief: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
253
- return 64
254
- }
255
- const missing = readMissingFlags(argv, VALUE_FLAGS)
256
- if (missing.length > 0) {
257
- console.error(`brief: ${missing.join(', ')} given with no value`)
246
+ const parsed = parseArguments(argv)
247
+ if (!parsed.success) {
248
+ console.error(`brief: ${parsed.error}; ${USAGE}`)
258
249
  return 64
259
250
  }
260
- const check = readOption(argv, '--check')
261
- if (check !== undefined && argv.includes('--unit')) {
262
- console.error('brief: --check and --unit are two modes; name one')
251
+ const { values } = parsed.value
252
+ const check = typeof values.check === 'string' ? values.check : undefined
253
+ if (check !== undefined && values.unit !== undefined) {
254
+ console.error(`brief: --check and --unit are two modes; name one; ${USAGE}`)
263
255
  return 64
264
256
  }
265
257
  if (check !== undefined) return checkBrief(check)
266
- if (argv.includes('--unit')) return writeBrief(argv)
258
+ if (values.unit !== undefined) return writeBrief(values)
267
259
  console.error(USAGE)
268
260
  return 64
269
261
  }
@@ -10,18 +10,20 @@
10
10
  // step and stops at the first step that does not exit 0. Because no shell runs, a command that is a
11
11
  // Windows `.cmd` shim, such as `npm`, starts only through the interpreter it wraps. A step that
12
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.
13
+ // for a cap. The script reads its flags with `parseArgs` in strict mode.
14
14
  // Exit 0 when every step exited 0, the failing step's exit code when one did not, 2 when a step
15
15
  // cannot start, 64 on usage.
16
+ import type { ParseArgsOptionsConfig } from 'node:util'
16
17
  import { spawnSync } from 'node:child_process'
17
18
  import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync } from 'node:fs'
18
19
  import { join, resolve } from 'node:path'
20
+ import { parseArgs } from 'node:util'
19
21
 
20
- /** Lists the flags that take a value. */
21
- export const VALUE_FLAGS: readonly string[] = ['--plan', '--journal']
22
-
23
- /** Lists every flag the script reads, value flags and switches alike. */
24
- export const FLAGS: readonly string[] = VALUE_FLAGS
22
+ /** Declares every flag the script reads, for `parseArgs`. */
23
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
24
+ plan: Object.freeze({ type: 'string' }),
25
+ journal: Object.freeze({ type: 'string' }),
26
+ })
25
27
 
26
28
  /** Holds the usage line printed when a call names no plan or no journal. */
27
29
  export const USAGE = 'usage: chain.ts --plan FILE.json --journal DIR'
@@ -44,6 +46,19 @@ export interface Plan {
44
46
  readonly problems: readonly string[]
45
47
  }
46
48
 
49
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
50
+ export interface Arguments {
51
+ readonly values: Readonly<
52
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
53
+ >
54
+ readonly positionals: readonly string[]
55
+ }
56
+
57
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
58
+ export type ArgumentsResult =
59
+ | { readonly success: true; readonly value: Arguments }
60
+ | { readonly success: false; readonly error: string }
61
+
47
62
  /** Describes one finished step: how it ended and how long it took. */
48
63
  export interface Finish {
49
64
  readonly exit: number | undefined
@@ -52,56 +67,23 @@ export interface Finish {
52
67
  }
53
68
 
54
69
  /**
55
- * Reads the value that follows a flag.
56
- *
57
- * @remarks
58
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
59
- * and the `--flag=value` form is not read.
60
- *
61
- * @param argv - The arguments after the script path.
62
- * @param name - The flag, such as `--plan`.
63
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
64
- * another flag.
65
- */
66
- export function readOption(argv: readonly string[], name: string): string | undefined {
67
- const index = argv.indexOf(name)
68
- const value = index === -1 ? undefined : argv[index + 1]
69
- return value === undefined || value.startsWith('--') ? undefined : value
70
- }
71
-
72
- /**
73
- * Names the value flags a caller gave with no value.
74
- *
75
- * @param argv - The arguments after the script path.
76
- * @param names - The flags that take a value.
77
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
78
- */
79
- export function readMissingFlags(
80
- argv: readonly string[],
81
- names: readonly string[],
82
- ): readonly string[] {
83
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
84
- }
85
-
86
- /**
87
- * Names the flags a caller gave that the script does not read.
88
- *
89
- * @remarks
90
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
91
- * scan.
70
+ * Parses the arguments in strict mode against `OPTIONS`.
92
71
  *
93
72
  * @param argv - The arguments after the script path.
94
- * @param flags - Every flag the script reads, value flags and switches alike.
95
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
73
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
96
74
  */
97
- export function readUnknownFlags(
98
- argv: readonly string[],
99
- flags: readonly string[],
100
- ): readonly string[] {
101
- const end = argv.indexOf('--')
102
- return (end === -1 ? argv : argv.slice(0, end)).filter(
103
- (argument) => argument.startsWith('--') && !flags.includes(argument),
104
- )
75
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
76
+ try {
77
+ const { values, positionals } = parseArgs({
78
+ args: [...argv],
79
+ options: OPTIONS,
80
+ strict: true,
81
+ allowPositionals: false,
82
+ })
83
+ return { success: true, value: { values, positionals } }
84
+ } catch (error) {
85
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
86
+ }
105
87
  }
106
88
 
107
89
  /**
@@ -313,18 +295,14 @@ export function formatStep(step: Step, finish: Finish): string {
313
295
  * cannot start, 64 on usage.
314
296
  */
315
297
  export function main(argv: readonly string[]): number {
316
- const unknown = readUnknownFlags(argv, FLAGS)
317
- if (unknown.length > 0) {
318
- console.error(`chain: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
319
- return 64
320
- }
321
- const missing = readMissingFlags(argv, VALUE_FLAGS)
322
- if (missing.length > 0) {
323
- console.error(`chain: ${missing.join(', ')} given with no value`)
298
+ const parsed = parseArguments(argv)
299
+ if (!parsed.success) {
300
+ console.error(`chain: ${parsed.error}; ${USAGE}`)
324
301
  return 64
325
302
  }
326
- const path = readOption(argv, '--plan')
327
- const journal = readOption(argv, '--journal')
303
+ const { values } = parsed.value
304
+ const path = typeof values.plan === 'string' ? values.plan : undefined
305
+ const journal = typeof values.journal === 'string' ? values.journal : undefined
328
306
  if (path === undefined || journal === undefined || !existsSync(path)) {
329
307
  console.error(USAGE)
330
308
  return 64