@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
@@ -18,24 +18,57 @@
18
18
  // name one file), and nothing is written unless every selected edit resolves.
19
19
  // `--plan` prints each edit's resolution and writes nothing; `--apply` writes the files after every
20
20
  // edit resolved. `--skip N` leaves out edit number N, as the plan numbers them, and repeats. The
21
- // script refuses a flag it does not read, the `--flag=value` form included.
21
+ // script reads its flags with `parseArgs` in strict mode.
22
22
  // Exit 0 when every selected edit resolved, 1 when one did not, 64 on usage.
23
+ import type { ParseArgsOptionsConfig } from 'node:util'
23
24
  import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
24
25
  import { isAbsolute, relative, resolve, sep } from 'node:path'
25
-
26
- /** Lists the flags that each select one operation. */
27
- export const MODE_FLAGS: readonly string[] = ['--plan', '--apply']
28
-
29
- /** Lists the flags that take a value. */
30
- export const VALUE_FLAGS: readonly string[] = ['--skip']
31
-
32
- /** Lists every flag the script reads, value flags and switches alike. */
33
- export const FLAGS: readonly string[] = [...MODE_FLAGS, ...VALUE_FLAGS]
26
+ import { parseArgs } from 'node:util'
34
27
 
35
28
  /** Holds the usage line printed when a call names no edit file or no mode, or two. */
36
29
  export const USAGE =
37
30
  'usage: patch.ts EDITS.md (--plan | --apply) [--skip N ...]; name one mode; --skip repeats'
38
31
 
32
+ /** Declares every flag the script reads, for `parseArgs`. */
33
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
34
+ plan: Object.freeze({ type: 'boolean' }),
35
+ apply: Object.freeze({ type: 'boolean' }),
36
+ skip: Object.freeze({ type: 'string', multiple: true }),
37
+ })
38
+
39
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
40
+ export interface Arguments {
41
+ readonly values: Readonly<
42
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
43
+ >
44
+ readonly positionals: readonly string[]
45
+ }
46
+
47
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
48
+ export type ArgumentsResult =
49
+ | { readonly success: true; readonly value: Arguments }
50
+ | { readonly success: false; readonly error: string }
51
+
52
+ /**
53
+ * Parses the arguments in strict mode against `OPTIONS`.
54
+ *
55
+ * @param argv - The arguments after the script path.
56
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
57
+ */
58
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
59
+ try {
60
+ const { values, positionals } = parseArgs({
61
+ args: [...argv],
62
+ options: OPTIONS,
63
+ strict: true,
64
+ allowPositionals: true,
65
+ })
66
+ return { success: true, value: { values, positionals } }
67
+ } catch (error) {
68
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
69
+ }
70
+ }
71
+
39
72
  /** Matches one edit block with its path, reason, and fenced old and new texts. */
40
73
  export const EDIT_BLOCK =
41
74
  /^### (.+?)[ \t]*\n+reason:[ \t]*(.*?)[ \t]*\n+old:\n+(`{3,})[^\n`]*\n([\s\S]*?)\n\3[ \t]*\n+new:\n+(`{3,})[^\n`]*\n([\s\S]*?)\n?\5[ \t]*$/gmu
@@ -72,85 +105,6 @@ export interface Resolved {
72
105
  readonly text: string
73
106
  }
74
107
 
75
- /**
76
- * Names the value flags a caller gave with no value, at any occurrence.
77
- *
78
- * @param argv - The arguments after the script path.
79
- * @param names - The flags that take a value.
80
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
81
- */
82
- export function readMissingFlags(
83
- argv: readonly string[],
84
- names: readonly string[],
85
- ): readonly string[] {
86
- return names.filter((name) =>
87
- argv.some((argument, index) => argument === name && isMissingValue(argv, index)),
88
- )
89
- }
90
-
91
- /**
92
- * Checks whether the argument after a flag is absent or is another flag.
93
- *
94
- * @param argv - The arguments after the script path.
95
- * @param index - The position of the flag.
96
- * @returns True when no value follows the flag; false otherwise.
97
- */
98
- export function isMissingValue(argv: readonly string[], index: number): boolean {
99
- const value = argv[index + 1]
100
- return value === undefined || value.startsWith('--')
101
- }
102
-
103
- /**
104
- * Names the flags a caller gave that the script does not read.
105
- *
106
- * @remarks
107
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
108
- * scan.
109
- *
110
- * @param argv - The arguments after the script path.
111
- * @param flags - Every flag the script reads, value flags and switches alike.
112
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
113
- */
114
- export function readUnknownFlags(
115
- argv: readonly string[],
116
- flags: readonly string[],
117
- ): readonly string[] {
118
- const end = argv.indexOf('--')
119
- return (end === -1 ? argv : argv.slice(0, end)).filter(
120
- (argument) => argument.startsWith('--') && !flags.includes(argument),
121
- )
122
- }
123
-
124
- /**
125
- * Reads every value that follows a repeatable flag.
126
- *
127
- * @param argv - The arguments after the script path.
128
- * @param name - The flag, such as `--skip`.
129
- * @returns The values in order, empty when the flag never appears.
130
- */
131
- export function readOptions(argv: readonly string[], name: string): readonly string[] {
132
- return argv.flatMap((argument, index) => {
133
- const value = argv[index + 1]
134
- return argument === name && value !== undefined && !value.startsWith('--') ? [value] : []
135
- })
136
- }
137
-
138
- /**
139
- * Reads the arguments that are neither a flag nor the value of a value flag.
140
- *
141
- * @param argv - The arguments after the script path.
142
- * @param valueFlags - The flags that take a value.
143
- * @returns The positional arguments in order.
144
- */
145
- export function readPositionals(
146
- argv: readonly string[],
147
- valueFlags: readonly string[],
148
- ): readonly string[] {
149
- return argv.filter(
150
- (argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
151
- )
152
- }
153
-
154
108
  /**
155
109
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
156
110
  *
@@ -322,8 +276,41 @@ export function readFileKey(target: string): string {
322
276
  */
323
277
  export function readTargetProblem(root: string, target: string): string | undefined {
324
278
  if (!isInside(root, target)) return 'path leaves the working directory'
325
- if (!existsSync(target) || !statSync(target).isFile()) return 'no such file'
326
- return undefined
279
+ return readFileProblem(target)
280
+ }
281
+
282
+ /**
283
+ * Names why a path is not a file this script can read.
284
+ *
285
+ * @remarks
286
+ * A stat that throws, such as one refused with `EACCES` or given a path that holds a NUL byte, is a
287
+ * problem named by its error code, never an uncaught error.
288
+ *
289
+ * @param path - The path to read.
290
+ * @returns The problem, or undefined when the path is a file.
291
+ */
292
+ export function readFileProblem(path: string): string | undefined {
293
+ try {
294
+ return statSync(path, { throwIfNoEntry: false })?.isFile() === true ? undefined : 'no such file'
295
+ } catch (error) {
296
+ const code =
297
+ error instanceof Error && 'code' in error && typeof error.code === 'string'
298
+ ? error.code
299
+ : String(error)
300
+ return `cannot be read: ${code}`
301
+ }
302
+ }
303
+
304
+ /**
305
+ * Collects the strings a repeatable flag's value holds.
306
+ *
307
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
308
+ * @returns Each string in order, empty when the flag never appears.
309
+ */
310
+ export function collectStrings(value: unknown): readonly string[] {
311
+ return Array.isArray(value)
312
+ ? value.filter((member): member is string => typeof member === 'string')
313
+ : []
327
314
  }
328
315
 
329
316
  /**
@@ -333,24 +320,19 @@ export function readTargetProblem(root: string, target: string): string | undefi
333
320
  * @returns The exit code: 0 when every selected edit resolved, 1 when one did not, 64 on usage.
334
321
  */
335
322
  export function main(argv: readonly string[]): number {
336
- const unknown = readUnknownFlags(argv, FLAGS)
337
- if (unknown.length > 0) {
338
- console.error(`patch: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
339
- return 64
340
- }
341
- const missing = readMissingFlags(argv, VALUE_FLAGS)
342
- if (missing.length > 0) {
343
- console.error(`patch: ${missing.join(', ')} given with no value`)
323
+ const parsed = parseArguments(argv)
324
+ if (!parsed.success) {
325
+ console.error(`patch: ${parsed.error}; ${USAGE}`)
344
326
  return 64
345
327
  }
346
- const modes = MODE_FLAGS.filter((flag) => argv.includes(flag))
347
- const sources = readPositionals(argv, VALUE_FLAGS)
348
- const source = sources[0]
349
- if (modes.length !== 1 || sources.length !== 1 || source === undefined) {
328
+ const { values, positionals } = parsed.value
329
+ const apply = values.apply === true
330
+ const [source, ...extra] = positionals
331
+ if (apply === (values.plan === true) || extra.length > 0 || source === undefined) {
350
332
  console.error(USAGE)
351
333
  return 64
352
334
  }
353
- if (!existsSync(source) || !statSync(source).isFile()) {
335
+ if (readFileProblem(source) !== undefined) {
354
336
  console.error(`patch: ${quote(source)} is not a readable edit file; ${USAGE}`)
355
337
  return 64
356
338
  }
@@ -363,7 +345,7 @@ export function main(argv: readonly string[]): number {
363
345
  )
364
346
  return 64
365
347
  }
366
- const skips = readOptions(argv, '--skip')
348
+ const skips = collectStrings(values.skip)
367
349
  const invalid = readInvalidSkips(skips, edits.length)
368
350
  if (invalid.length > 0) {
369
351
  console.error(
@@ -386,7 +368,6 @@ export function main(argv: readonly string[]): number {
386
368
  console.log('nothing written')
387
369
  return 1
388
370
  }
389
- const apply = argv.includes('--apply')
390
371
  if (apply) {
391
372
  for (const file of resolution.files) writeFileSync(resolve(root, file.path), file.text)
392
373
  }
@@ -9,24 +9,61 @@
9
9
  // launch.ts wrote (`exit`, `capped`, `durationMs`) and the journal's `bytes`, `ageMs`, and last
10
10
  // event, which is the liveness reading for a run still going. The answer is written to --out when
11
11
  // given, and a journal with no session or answer exits 3 so a driver cannot pass off an empty lane.
12
- // Name one mode per run; the script refuses a flag it does not read, the `--flag=value` form
13
- // included. Exit 0 when the lane answered, 3 when it carries no session or answer, 64 on usage.
12
+ // Name one mode per run; the script reads its flags with `parseArgs` in strict mode. Exit 0 when
13
+ // the lane answered, 3 when it carries no session or answer, 64 on usage.
14
+ import type { ParseArgsOptionsConfig } from 'node:util'
14
15
  import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
15
16
  import { dirname } from 'node:path'
17
+ import { parseArgs } from 'node:util'
16
18
 
17
- /** Lists the flags that each select one journal reader. */
18
- export const MODE_FLAGS: readonly string[] = ['--cursor', '--claude', '--codex']
19
-
20
- /** Lists the flags that take a value. */
21
- export const VALUE_FLAGS: readonly string[] = [...MODE_FLAGS, '--out']
22
-
23
- /** Lists every flag the script reads, value flags and switches alike. */
24
- export const FLAGS: readonly string[] = VALUE_FLAGS
19
+ /** Lists the flags that each select one journal reader, by the name `parseArgs` reads them under. */
20
+ export const MODES: readonly string[] = ['cursor', 'claude', 'codex']
25
21
 
26
22
  /** Holds the usage line printed when a call names no journal or two modes. */
27
23
  export const USAGE =
28
24
  'usage: result.ts (--cursor JOURNAL | --claude JOURNAL | --codex JOURNAL) [--out PATH]; name one mode'
29
25
 
26
+ /** Declares every flag the script reads, for `parseArgs`. */
27
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
28
+ cursor: Object.freeze({ type: 'string' }),
29
+ claude: Object.freeze({ type: 'string' }),
30
+ codex: Object.freeze({ type: 'string' }),
31
+ out: Object.freeze({ type: 'string' }),
32
+ })
33
+
34
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
35
+ export interface Arguments {
36
+ readonly values: Readonly<
37
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
38
+ >
39
+ readonly positionals: readonly string[]
40
+ }
41
+
42
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
43
+ export type ArgumentsResult =
44
+ | { readonly success: true; readonly value: Arguments }
45
+ | { readonly success: false; readonly error: string }
46
+
47
+ /**
48
+ * Parses the arguments in strict mode against `OPTIONS`.
49
+ *
50
+ * @param argv - The arguments after the script path.
51
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
52
+ */
53
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
54
+ try {
55
+ const { values, positionals } = parseArgs({
56
+ args: [...argv],
57
+ options: OPTIONS,
58
+ strict: true,
59
+ allowPositionals: false,
60
+ })
61
+ return { success: true, value: { values, positionals } }
62
+ } catch (error) {
63
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
64
+ }
65
+ }
66
+
30
67
  /** Describes what a journal's events say: the session, the answer, and the run's duration. */
31
68
  export interface SessionResult {
32
69
  readonly session: string | undefined
@@ -41,59 +78,6 @@ export interface Errors {
41
78
  readonly durationMs: number | undefined
42
79
  }
43
80
 
44
- /**
45
- * Reads the value that follows a flag.
46
- *
47
- * @remarks
48
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
49
- * and the `--flag=value` form is not read.
50
- *
51
- * @param argv - The arguments after the script path.
52
- * @param name - The flag, such as `--out`.
53
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
54
- * another flag.
55
- */
56
- export function readOption(argv: readonly string[], name: string): string | undefined {
57
- const index = argv.indexOf(name)
58
- const value = index === -1 ? undefined : argv[index + 1]
59
- return value === undefined || value.startsWith('--') ? undefined : value
60
- }
61
-
62
- /**
63
- * Names the value flags a caller gave with no value.
64
- *
65
- * @param argv - The arguments after the script path.
66
- * @param names - The flags that take a value.
67
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
68
- */
69
- export function readMissingFlags(
70
- argv: readonly string[],
71
- names: readonly string[],
72
- ): readonly string[] {
73
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
74
- }
75
-
76
- /**
77
- * Names the flags a caller gave that the script does not read.
78
- *
79
- * @remarks
80
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
81
- * scan.
82
- *
83
- * @param argv - The arguments after the script path.
84
- * @param flags - Every flag the script reads, value flags and switches alike.
85
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
86
- */
87
- export function readUnknownFlags(
88
- argv: readonly string[],
89
- flags: readonly string[],
90
- ): readonly string[] {
91
- const end = argv.indexOf('--')
92
- return (end === -1 ? argv : argv.slice(0, end)).filter(
93
- (argument) => argument.startsWith('--') && !flags.includes(argument),
94
- )
95
- }
96
-
97
81
  /**
98
82
  * Reads the last non-empty line of a text as a JSON object.
99
83
  *
@@ -248,26 +232,23 @@ export function describeEvent(event: Record<string, unknown> | undefined): strin
248
232
  * @returns The exit code: 0 when the lane answered, 3 when it carries no session or answer, 64 on usage.
249
233
  */
250
234
  export function main(argv: readonly string[]): number {
251
- const unknown = readUnknownFlags(argv, FLAGS)
252
- if (unknown.length > 0) {
253
- console.error(`result: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
254
- return 64
255
- }
256
- const missing = readMissingFlags(argv, VALUE_FLAGS)
257
- if (missing.length > 0) {
258
- console.error(`result: ${missing.join(', ')} given with no value`)
235
+ const parsed = parseArguments(argv)
236
+ if (!parsed.success) {
237
+ console.error(`result: ${parsed.error}; ${USAGE}`)
259
238
  return 64
260
239
  }
261
- const modes = MODE_FLAGS.filter((flag) => argv.includes(flag))
262
- const mode = modes[0]
263
- const path = mode === undefined ? undefined : readOption(argv, mode)
264
- const out = readOption(argv, '--out')
240
+ const { values } = parsed.value
241
+ const modes = MODES.filter((name) => values[name] !== undefined)
242
+ const [mode] = modes
243
+ const chosen = mode === undefined ? undefined : values[mode]
244
+ const path = typeof chosen === 'string' ? chosen : undefined
245
+ const out = typeof values.out === 'string' ? values.out : undefined
265
246
  if (modes.length !== 1 || mode === undefined || path === undefined || !existsSync(path)) {
266
247
  console.error(USAGE)
267
248
  return 64
268
249
  }
269
250
  const events = readEvents(path)
270
- const result = mode === '--codex' ? readCodex(path, events) : readStream(events)
251
+ const result = mode === 'codex' ? readCodex(path, events) : readStream(events)
271
252
  const errors = readErrors(path)
272
253
  const stat = statSync(path)
273
254
  if (result.answer !== undefined && out !== undefined) {
@@ -14,11 +14,13 @@
14
14
  // --delete removes them, refusing while one changed in the last 2 minutes.
15
15
  // --tmp and --unit --delete never delete a file git tracks: each prints `kept tracked <path>` and the
16
16
  // refusal ignores a tracked file; --unit alone marks a tracked file in its listing.
17
- // Name one mode per run; the script refuses a flag it does not read, the `--flag=value` form
18
- // included. Exit 0 on success, 2 when a deletion is refused, 64 on usage.
17
+ // Name one mode per run; the script reads its flags with `parseArgs` in strict mode. Exit 0 on
18
+ // success, 2 when a deletion is refused, 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, rmSync, statSync } from 'node:fs'
21
22
  import { basename, join } from 'node:path'
23
+ import { parseArgs } from 'node:util'
22
24
 
23
25
  /** Lists the directories under `tmp/` that hold launch files. */
24
26
  export const LAUNCH_DIRECTORIES: readonly string[] = [
@@ -65,16 +67,52 @@ export const BACKTICKED = /`([^`\n]+)`/gu
65
67
  /** Matches the first glob or placeholder character in a path. */
66
68
  export const PLACEHOLDER = /[*?<{]/u
67
69
 
68
- /** Lists the flags that take a value. */
69
- export const VALUE_FLAGS: readonly string[] = ['--unit', '--older-than']
70
-
71
- /** Lists every flag the script reads, value flags and switches alike. */
72
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--report', '--tmp', '--delete']
73
-
74
70
  /** Holds the usage line printed when a call names an unknown mode. */
75
71
  export const USAGE =
76
72
  'usage: sweep.ts --report | --tmp [--older-than MINUTES] | --unit UNIT [--delete]'
77
73
 
74
+ /** Declares every flag the script reads, for `parseArgs`. */
75
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
76
+ unit: Object.freeze({ type: 'string' }),
77
+ 'older-than': Object.freeze({ type: 'string' }),
78
+ report: Object.freeze({ type: 'boolean' }),
79
+ tmp: Object.freeze({ type: 'boolean' }),
80
+ delete: Object.freeze({ type: 'boolean' }),
81
+ })
82
+
83
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
84
+ export interface Arguments {
85
+ readonly values: Readonly<
86
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
87
+ >
88
+ readonly positionals: readonly string[]
89
+ }
90
+
91
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
92
+ export type ArgumentsResult =
93
+ | { readonly success: true; readonly value: Arguments }
94
+ | { readonly success: false; readonly error: string }
95
+
96
+ /**
97
+ * Parses the arguments in strict mode against `OPTIONS`.
98
+ *
99
+ * @param argv - The arguments after the script path.
100
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
101
+ */
102
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
103
+ try {
104
+ const { values, positionals } = parseArgs({
105
+ args: [...argv],
106
+ options: OPTIONS,
107
+ strict: true,
108
+ allowPositionals: false,
109
+ })
110
+ return { success: true, value: { values, positionals } }
111
+ } catch (error) {
112
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
113
+ }
114
+ }
115
+
78
116
  /** Describes one file a tree walk found, with the modification time the sweep reads. */
79
117
  export interface WalkedFile {
80
118
  readonly path: string
@@ -95,59 +133,6 @@ export interface Finding {
95
133
  readonly citation: Citation | undefined
96
134
  }
97
135
 
98
- /**
99
- * Reads the value that follows a flag.
100
- *
101
- * @remarks
102
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
103
- * and the `--flag=value` form is not read.
104
- *
105
- * @param argv - The arguments after the script path.
106
- * @param name - The flag, such as `--unit`.
107
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
108
- * another flag.
109
- */
110
- export function readOption(argv: readonly string[], name: string): string | undefined {
111
- const index = argv.indexOf(name)
112
- const value = index === -1 ? undefined : argv[index + 1]
113
- return value === undefined || value.startsWith('--') ? undefined : value
114
- }
115
-
116
- /**
117
- * Names the value flags a caller gave with no value.
118
- *
119
- * @param argv - The arguments after the script path.
120
- * @param names - The flags that take a value.
121
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
122
- */
123
- export function readMissingFlags(
124
- argv: readonly string[],
125
- names: readonly string[],
126
- ): readonly string[] {
127
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
128
- }
129
-
130
- /**
131
- * Names the flags a caller gave that the script does not read.
132
- *
133
- * @remarks
134
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
135
- * scan.
136
- *
137
- * @param argv - The arguments after the script path.
138
- * @param flags - Every flag the script reads, value flags and switches alike.
139
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
140
- */
141
- export function readUnknownFlags(
142
- argv: readonly string[],
143
- flags: readonly string[],
144
- ): readonly string[] {
145
- const end = argv.indexOf('--')
146
- return (end === -1 ? argv : argv.slice(0, end)).filter(
147
- (argument) => argument.startsWith('--') && !flags.includes(argument),
148
- )
149
- }
150
-
151
136
  /**
152
137
  * Normalizes a host path to forward slashes.
153
138
  *
@@ -155,7 +140,7 @@ export function readUnknownFlags(
155
140
  * @returns The same path with every backslash replaced by a slash.
156
141
  */
157
142
  export function normalizeSlashes(path: string): string {
158
- return path.split('\\').join('/')
143
+ return path.replaceAll('\\', '/')
159
144
  }
160
145
 
161
146
  /**
@@ -253,15 +238,15 @@ export function removeEmptyDirectories(directory: string): void {
253
238
  }
254
239
 
255
240
  /**
256
- * Reads the `--older-than` threshold in minutes.
241
+ * Parses the `--older-than` threshold in minutes.
257
242
  *
258
- * @param argv - The arguments after the script path.
243
+ * @param text - The value after `--older-than`, or undefined when the flag is absent.
259
244
  * @returns The default threshold when the flag is absent, the number when it is finite and above 0,
260
245
  * and undefined otherwise.
261
246
  */
262
- export function readThreshold(argv: readonly string[]): number | undefined {
263
- if (!argv.includes('--older-than')) return DEFAULT_THRESHOLD
264
- const value = Number(readOption(argv, '--older-than'))
247
+ export function parseThreshold(text: string | undefined): number | undefined {
248
+ if (text === undefined) return DEFAULT_THRESHOLD
249
+ const value = Number(text)
265
250
  return Number.isFinite(value) && value > 0 ? value : undefined
266
251
  }
267
252
 
@@ -479,13 +464,15 @@ export function listUnitFiles(unit: string): ReadonlyArray<{ path: string; modif
479
464
  /**
480
465
  * Lists or deletes one unit's launch files.
481
466
  *
482
- * @param unit - The unit name, or undefined when the call gave none.
467
+ * @param unit - The unit name.
483
468
  * @param remove - If true, deletes the untracked files; if false, lists them.
484
469
  * @returns The exit code: 0 on success, 2 when a deletion is refused, 64 on usage.
485
470
  */
486
- export function runUnit(unit: string | undefined, remove: boolean): number {
487
- if (unit === undefined || !/^[A-Za-z0-9._][A-Za-z0-9._-]*$/u.test(unit)) {
488
- console.error('usage: sweep.ts --unit UNIT [--delete]')
471
+ export function runUnit(unit: string, remove: boolean): number {
472
+ if (!/^[A-Za-z0-9._][A-Za-z0-9._-]*$/u.test(unit)) {
473
+ console.error(
474
+ `sweep: --unit takes letters, digits, dots, underscores, and hyphens, not opening with a hyphen, not ${JSON.stringify(unit)}; ${USAGE}`,
475
+ )
489
476
  return 64
490
477
  }
491
478
  const files = listUnitFiles(unit)
@@ -518,37 +505,35 @@ export function runUnit(unit: string | undefined, remove: boolean): number {
518
505
  * @returns The exit code: 0 on success, 2 when a deletion is refused, 64 on usage.
519
506
  */
520
507
  export function main(argv: readonly string[]): number {
521
- const unknown = readUnknownFlags(argv, FLAGS)
522
- if (unknown.length > 0) {
523
- console.error(`sweep: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
524
- return 64
525
- }
526
- const missing = readMissingFlags(argv, VALUE_FLAGS)
527
- if (missing.length > 0) {
528
- console.error(`sweep: ${missing.join(', ')} given with no value`)
508
+ const parsed = parseArguments(argv)
509
+ if (!parsed.success) {
510
+ console.error(`sweep: ${parsed.error}; ${USAGE}`)
529
511
  return 64
530
512
  }
513
+ const { values } = parsed.value
531
514
  if (!existsSync('.git')) {
532
515
  console.error('sweep: run from the repository root')
533
516
  return 64
534
517
  }
535
- const modes = ['--report', '--tmp', '--unit'].filter((flag) => argv.includes(flag))
518
+ const unit = typeof values.unit === 'string' ? values.unit : undefined
519
+ const modes = [values.report, values.tmp, unit].filter((value) => value !== undefined)
536
520
  if (modes.length > 1) {
537
- console.error(
538
- 'usage: sweep.ts names one mode: --report | --tmp [--older-than MINUTES] | --unit UNIT [--delete]',
539
- )
521
+ console.error(`sweep: --report, --tmp, and --unit are three modes; name one; ${USAGE}`)
540
522
  return 64
541
523
  }
542
- if (argv.includes('--tmp')) {
543
- const threshold = readThreshold(argv)
524
+ if (values.tmp === true) {
525
+ const text = typeof values['older-than'] === 'string' ? values['older-than'] : undefined
526
+ const threshold = parseThreshold(text)
544
527
  if (threshold === undefined) {
545
- console.error('usage: sweep.ts --tmp [--older-than MINUTES]; MINUTES is a positive number')
528
+ console.error(
529
+ `sweep: --older-than takes a number of minutes above 0, not ${JSON.stringify(text)}; ${USAGE}`,
530
+ )
546
531
  return 64
547
532
  }
548
533
  return runSweep(threshold)
549
534
  }
550
- if (argv.includes('--unit')) return runUnit(readOption(argv, '--unit'), argv.includes('--delete'))
551
- if (argv.length === 0 || argv.includes('--report')) return runReport()
535
+ if (unit !== undefined) return runUnit(unit, values.delete === true)
536
+ if (argv.length === 0 || values.report === true) return runReport()
552
537
  console.error(USAGE)
553
538
  return 64
554
539
  }
@@ -12,7 +12,7 @@ One round. It ends with a ruling. `.agents/orchestration.md` § Size gate decide
12
12
 
13
13
  Run from the checkout root. The script's opening comment owns its behavior.
14
14
 
15
- - `scripts/mutate.ts --edits EDITS.md -- COMMAND [ARGS...]` runs the mutation probe. It resolves an edit file, the `### <path>` block shape that `.agents/skills/orkestrel-dispatch/scripts/patch.ts` reads, before it touches a file; saves the originals under `tmp/probes/mutate/`; writes the mutated files; runs the command with no shell and its output on standard error; restores the bytes and proves each file's SHA-256 digest; runs the command again; and prints one JSON line with both exits. A mutation that leaves the suite uncollected also reads as a failing run, so read the command's own test count on standard error. When the probe compares two arms rather than proving a kill, read the `mutatedExit` and `restoredExit` fields from the JSON line: exit 3 reports a passing mutated run. A run killed mid-command leaves the tree mutated: the next run refuses to start while a run directory remains and names the line that restores it, `scripts/mutate.ts --restore tmp/probes/mutate/run-NAME`, which writes the saved originals back, proves each digest from the manifest, and deletes the directory. Exit 0 when the mutated run failed and the restored run passed (or a `--restore` is proven), 3 when either did not, 2 when a restore is not proven or the command cannot start, 64 usage, an edit that does not resolve, or a run directory left behind.
15
+ - `scripts/mutate.ts --edits EDITS.md -- COMMAND [ARGS...]` runs the mutation probe. It resolves an edit file, the `### <path>` block shape that `.agents/skills/orkestrel-dispatch/scripts/patch.ts` reads, before it touches a file; saves the originals under `tmp/probes/mutate/`; writes the mutated files; runs the command with no shell and its output in `<edits>.mutated.log` beside the edit file, then prints that log's last 40 lines on standard error; restores the bytes and proves each file's SHA-256 digest; runs the command again with its output in `<edits>.restored.log`; and prints one JSON line with both exits and both log paths, `mutatedLog` and `restoredLog`. Each run overwrites the logs of an earlier run over the same edit file. A mutation that leaves the suite uncollected also reads as a failing run, so read the command's own test count in `mutatedLog`. To confirm a probe is red for the intended reason, read the failing cases in `mutatedLog` and the passing run in `restoredLog` rather than a shared journal. When the probe compares two arms rather than proving a kill, read the `mutatedExit` and `restoredExit` fields from the JSON line: exit 3 reports a passing mutated run. A run killed mid-command leaves the tree mutated: the next run refuses to start while a run directory remains and names the line that restores it, `scripts/mutate.ts --restore tmp/probes/mutate/run-NAME`, which writes the saved originals back, proves each digest from the manifest, and deletes the directory. Exit 0 when the mutated run failed and the restored run passed (or a `--restore` is proven), 3 when either did not, 2 when a restore is not proven, the command cannot start, or a log cannot be opened, 64 usage, an edit that does not resolve, or a run directory left behind.
16
16
 
17
17
  ## Run a round the size gate does not name when
18
18
 
@@ -38,7 +38,7 @@ Read `references/brief.md` for the claim form.
38
38
 
39
39
  - Medium: one lane, with an independent reviewer per `.agents/orchestration.md` § Engines. Large: the objective lane and the subjective lane, same claims file, each in a clean context, neither shown the other's answer before reconciliation. Add `checker` when criteria are mechanical.
40
40
  - Tell a lane when its own engine wrote the half it audits.
41
- - Give a lane with no shell the evidence a read-only allowlist cannot produce: run the probe yourself, record its control and output, and hand it over. Run a mutation probe with `scripts/mutate.ts`; its JSON line carries both exits.
41
+ - Give a lane with no shell the evidence a read-only allowlist cannot produce: run the probe yourself, record its control and output, and hand it over. Run a mutation probe with `scripts/mutate.ts`; its JSON line carries both exits and the paths of both logs.
42
42
  - Auditors edit no source and spawn nothing. Their reports are immutable after they return.
43
43
 
44
44
  ## Verdict shape