@orkestrel/scaffold 0.0.133 → 0.0.135

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 (92) 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 +1568 -213
  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 +387 -109
  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 +275 -33
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/AGENTS.md +1 -1
  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 +1990 -274
  46. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  47. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +28 -7
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  52. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +483 -127
  53. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  54. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  55. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  56. package/dist/host/claude/agents/orkestrel.md +16 -16
  57. package/dist/host/claude/rules/architecture.md +1 -1
  58. package/dist/host/claude/rules/documentation.md +1 -1
  59. package/dist/host/claude/rules/patterns.md +7 -4
  60. package/dist/host/claude/rules/styles.md +1 -1
  61. package/dist/host/claude/rules/tests.md +3 -3
  62. package/dist/host/claude/rules/workspace.md +50 -37
  63. package/dist/host/configs/helpers.ts +117 -71
  64. package/dist/host/dotfiles/oxlintrc.json +6 -0
  65. package/dist/host/guides/agent.md +989 -395
  66. package/dist/host/guides/database.md +357 -342
  67. package/dist/host/guides/form.md +79 -4
  68. package/dist/host/guides/middleware.md +5 -5
  69. package/dist/host/guides/ollama.md +41 -42
  70. package/dist/host/guides/scaffold.md +170 -70
  71. package/dist/host/guides/study.md +12 -12
  72. package/dist/host/guides/table.md +20 -6
  73. package/dist/host/guides/test.md +166 -52
  74. package/dist/host/guides/toolbox.md +127 -81
  75. package/dist/host/guides/workspace.md +21 -14
  76. package/dist/host/manifest.json +54 -54
  77. package/dist/host/tests/config.test.ts +251 -7
  78. package/dist/host/tests/policy.test.ts +14 -21
  79. package/dist/host/tests/setupPolicy.ts +43 -36
  80. package/dist/src/core/index.cjs +533 -139
  81. package/dist/src/core/index.cjs.map +1 -1
  82. package/dist/src/core/index.d.cts +223 -16
  83. package/dist/src/core/index.d.ts +223 -16
  84. package/dist/src/core/index.js +524 -139
  85. package/dist/src/core/index.js.map +1 -1
  86. package/dist/src/server/index.cjs +23 -14
  87. package/dist/src/server/index.cjs.map +1 -1
  88. package/dist/src/server/index.d.cts +3 -2
  89. package/dist/src/server/index.d.ts +3 -2
  90. package/dist/src/server/index.js +24 -15
  91. package/dist/src/server/index.js.map +1 -1
  92. package/package.json +2 -2
@@ -6,10 +6,14 @@
6
6
  // `new:` texts, where each `old` text must occur exactly once in its file after the earlier edits to
7
7
  // that file. The script resolves every edit before it touches a file, saves each file's original
8
8
  // bytes under `tmp/probes/mutate/`, writes the mutated files, runs the command with no shell and
9
- // its output sent to this script's standard error, restores the original bytes and proves each
10
- // file's SHA-256 digest equals the original, runs the command again, and prints one JSON line:
11
- // `{"edits":N,"files":[{"path":"...","digest":"..."}],"mutatedExit":N,"restoredExit":N,"restored":true}`.
12
- // The saved bytes are deleted once the restore is proven. Edits that spell one file two ways
9
+ // its standard output and standard error written together, in order, to `<edits>.mutated.log`
10
+ // beside the edit file, prints the last 40 lines of that log to standard error, restores the
11
+ // original bytes and proves each file's SHA-256 digest equals the original, runs the command again
12
+ // with its output in `<edits>.restored.log`, and prints one JSON line:
13
+ // `{"edits":N,"files":[{"path":"...","digest":"..."}],"mutatedExit":N,"restoredExit":N,"mutatedLog":"<edits>.mutated.log","restoredLog":"<edits>.restored.log","restored":true}`.
14
+ // Each log path is the edit file's path as the caller gave it plus the suffix; a later run over the
15
+ // same edit file overwrites both logs, and the script deletes neither. The saved bytes are deleted
16
+ // once the restore is proven. Edits that spell one file two ways
13
17
  // (`a.ts` and `./a.ts`, or a case-only difference on a host that folds case) apply to it in order,
14
18
  // each against the text the earlier ones left. A mutation that leaves the suite uncollected also
15
19
  // reads as a failing run, so read the command's own test count on standard error.
@@ -18,17 +22,20 @@
18
22
  // node .agents/skills/orkestrel-falsify/scripts/mutate.ts --restore tmp/probes/mutate/run-NAME
19
23
  // writes each saved original back, proves each file's SHA-256 digest against the run's manifest,
20
24
  // deletes the run directory, and prints `{"files":[{"path":"...","digest":"..."}],"restored":true}`.
21
- // The script refuses a flag it does not read before the bare `--`, the `--flag=value` form included,
22
- // and names an unknown flag before a flag given with no value.
25
+ // The script reads its flags before the first bare `--` with `parseArgs` in strict mode, and passes
26
+ // every argument after it to the command.
23
27
  // Exit 0 when the mutated run failed and the restored run passed (or a `--restore` is proven), 3
24
- // when either did not, 2 when a restore is not proven or the command cannot start, 64 on usage, an
25
- // edit that does not resolve, or a run directory an earlier run left.
28
+ // when either did not, 2 when a restore is not proven or the command cannot start or a log cannot
29
+ // be opened, 64 on usage, an edit that does not resolve, or a run directory an earlier run left.
30
+ import type { ParseArgsOptionsConfig } from 'node:util'
26
31
  import { spawnSync } from 'node:child_process'
27
32
  import { createHash } from 'node:crypto'
28
33
  import {
34
+ closeSync,
29
35
  existsSync,
30
36
  mkdirSync,
31
37
  mkdtempSync,
38
+ openSync,
32
39
  readdirSync,
33
40
  readFileSync,
34
41
  realpathSync,
@@ -37,17 +44,51 @@ import {
37
44
  writeFileSync,
38
45
  } from 'node:fs'
39
46
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
40
-
41
- /** Lists the flags that take a value. */
42
- export const VALUE_FLAGS: readonly string[] = ['--edits', '--restore']
43
-
44
- /** Lists every flag the script reads, value flags and switches alike. */
45
- export const FLAGS: readonly string[] = VALUE_FLAGS
47
+ import { parseArgs } from 'node:util'
46
48
 
47
49
  /** Holds the usage line printed when a call names no edit file or no command. */
48
50
  export const USAGE =
49
51
  'usage: mutate.ts --edits EDITS.md -- COMMAND [ARGS...] | mutate.ts --restore tmp/probes/mutate/run-NAME'
50
52
 
53
+ /** Declares every flag the script reads, for `parseArgs`. */
54
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
55
+ edits: Object.freeze({ type: 'string' }),
56
+ restore: Object.freeze({ type: 'string' }),
57
+ })
58
+
59
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
60
+ export interface Arguments {
61
+ readonly values: Readonly<
62
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
63
+ >
64
+ readonly positionals: readonly string[]
65
+ }
66
+
67
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
68
+ export type ArgumentsResult =
69
+ | { readonly success: true; readonly value: Arguments }
70
+ | { readonly success: false; readonly error: string }
71
+
72
+ /**
73
+ * Parses the arguments in strict mode against `OPTIONS`.
74
+ *
75
+ * @param argv - The arguments after the script path.
76
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
77
+ */
78
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
79
+ try {
80
+ const { values, positionals } = parseArgs({
81
+ args: [...argv],
82
+ options: OPTIONS,
83
+ strict: true,
84
+ allowPositionals: false,
85
+ })
86
+ return { success: true, value: { values, positionals } }
87
+ } catch (error) {
88
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
89
+ }
90
+ }
91
+
51
92
  /** Holds the directory, under the working directory, that keeps the original bytes of a run. */
52
93
  export const BACKUP_ROOT = 'tmp/probes/mutate'
53
94
 
@@ -57,6 +98,15 @@ export const RUN_PREFIX = 'run-'
57
98
  /** Holds the name of the manifest file a run directory keeps beside its saved bytes. */
58
99
  export const MANIFEST = 'manifest.json'
59
100
 
101
+ /** Holds how many of the last lines of the mutated run's log the script prints to standard error. */
102
+ export const TAIL_LINES = 40
103
+
104
+ /** Holds the suffix that names the mutated run's log beside the edit file. */
105
+ export const MUTATED_SUFFIX = '.mutated.log'
106
+
107
+ /** Holds the suffix that names the restored run's log beside the edit file. */
108
+ export const RESTORED_SUFFIX = '.restored.log'
109
+
60
110
  /** Matches one edit block with its path, reason, and fenced old and new texts. */
61
111
  export const EDIT_BLOCK =
62
112
  /^### (.+?)[ \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
@@ -98,75 +148,6 @@ export interface Finish {
98
148
  readonly error: string | undefined
99
149
  }
100
150
 
101
- /**
102
- * Names the value flags a caller gave with no value.
103
- *
104
- * @param argv - The arguments before the bare `--`.
105
- * @param names - The flags that take a value.
106
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
107
- */
108
- export function readMissingFlags(
109
- argv: readonly string[],
110
- names: readonly string[],
111
- ): readonly string[] {
112
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
113
- }
114
-
115
- /**
116
- * Reads the value that follows a flag.
117
- *
118
- * @remarks
119
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
120
- * and the `--flag=value` form is not read.
121
- *
122
- * @param argv - The arguments before the bare `--`.
123
- * @param name - The flag, such as `--edits`.
124
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
125
- * another flag.
126
- */
127
- export function readOption(argv: readonly string[], name: string): string | undefined {
128
- const index = argv.indexOf(name)
129
- const value = index === -1 ? undefined : argv[index + 1]
130
- return value === undefined || value.startsWith('--') ? undefined : value
131
- }
132
-
133
- /**
134
- * Names the flags a caller gave that the script does not read.
135
- *
136
- * @remarks
137
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
138
- * scan, because it opens the command the script runs.
139
- *
140
- * @param argv - The arguments after the script path.
141
- * @param flags - Every flag the script reads, value flags and switches alike.
142
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
143
- */
144
- export function readUnknownFlags(
145
- argv: readonly string[],
146
- flags: readonly string[],
147
- ): readonly string[] {
148
- const end = argv.indexOf('--')
149
- return (end === -1 ? argv : argv.slice(0, end)).filter(
150
- (argument) => argument.startsWith('--') && !flags.includes(argument),
151
- )
152
- }
153
-
154
- /**
155
- * Reads the arguments that are neither a flag nor the value of a value flag.
156
- *
157
- * @param argv - The arguments before the bare `--`.
158
- * @param valueFlags - The flags that take a value.
159
- * @returns The positional arguments in order.
160
- */
161
- export function readPositionals(
162
- argv: readonly string[],
163
- valueFlags: readonly string[],
164
- ): readonly string[] {
165
- return argv.filter(
166
- (argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
167
- )
168
- }
169
-
170
151
  /**
171
152
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
172
153
  *
@@ -292,6 +273,28 @@ export function keyEdit(root: string, edit: Edit): string {
292
273
  return foldPath(resolve(root, edit.path), process.platform)
293
274
  }
294
275
 
276
+ /**
277
+ * Names why a path is not a file this script can read.
278
+ *
279
+ * @remarks
280
+ * A stat that throws, such as one refused with `EACCES` or given a path that holds a NUL byte, is a
281
+ * problem named by its error code, never an uncaught error.
282
+ *
283
+ * @param path - The path to read.
284
+ * @returns The problem, or undefined when the path is a file.
285
+ */
286
+ export function readFileProblem(path: string): string | undefined {
287
+ try {
288
+ return statSync(path, { throwIfNoEntry: false })?.isFile() === true ? undefined : 'no such file'
289
+ } catch (error) {
290
+ const code =
291
+ error instanceof Error && 'code' in error && typeof error.code === 'string'
292
+ ? error.code
293
+ : String(error)
294
+ return `cannot be read: ${code}`
295
+ }
296
+ }
297
+
295
298
  /**
296
299
  * Resolves every edit against the files under a root, writing nothing.
297
300
  *
@@ -310,9 +313,8 @@ export function resolveMutations(root: string, edits: readonly Edit[]): Resoluti
310
313
  if (!isInside(root, target)) {
311
314
  return { mutation: undefined, problems: [`${path}: path leaves the working directory`] }
312
315
  }
313
- if (!existsSync(target) || !statSync(target).isFile()) {
314
- return { mutation: undefined, problems: [`${path}: no such file`] }
315
- }
316
+ const problem = readFileProblem(target)
317
+ if (problem !== undefined) return { mutation: undefined, problems: [`${path}: ${problem}`] }
316
318
  const original = readFileSync(target)
317
319
  const applied = applyEdits(original.toString('utf8'), own)
318
320
  return {
@@ -330,22 +332,65 @@ export function resolveMutations(root: string, edits: readonly Edit[]): Resoluti
330
332
  }
331
333
 
332
334
  /**
333
- * Runs the command with no shell, its output sent to this process's standard error.
335
+ * Opens a log file for writing, creating or emptying it.
336
+ *
337
+ * @param log - The path of the log file.
338
+ * @returns The file descriptor, or the host's refusal message when the file cannot be opened.
339
+ */
340
+ export function openLog(log: string): number | string {
341
+ try {
342
+ return openSync(log, 'w')
343
+ } catch (error) {
344
+ return error instanceof Error ? error.message : String(error)
345
+ }
346
+ }
347
+
348
+ /**
349
+ * Runs the command with no shell, its standard output and standard error written together, in
350
+ * order, to a log file that the run creates or overwrites.
334
351
  *
335
352
  * @param command - The executable to run.
336
353
  * @param args - The arguments after the executable.
337
- * @returns The exit code, or undefined with the reason when the command cannot start or a signal
338
- * ended it.
354
+ * @param log - The path of the log file.
355
+ * @returns The exit code, or undefined with the reason when the log cannot be opened, the command
356
+ * cannot start, or a signal ended it.
339
357
  */
340
- export function runCommand(command: string, args: readonly string[]): Finish {
341
- const result = spawnSync(command, args, {
342
- stdio: ['ignore', 2, 2],
343
- windowsHide: true,
344
- shell: false,
345
- })
346
- const error =
347
- result.error?.message ?? (result.signal === null ? undefined : `ended by ${result.signal}`)
348
- return { exit: error === undefined ? (result.status ?? undefined) : undefined, error }
358
+ export function runCommand(command: string, args: readonly string[], log: string): Finish {
359
+ const descriptor = openLog(log)
360
+ if (typeof descriptor === 'string') return { exit: undefined, error: descriptor }
361
+ try {
362
+ const result = spawnSync(command, args, {
363
+ stdio: ['ignore', descriptor, descriptor],
364
+ windowsHide: true,
365
+ shell: false,
366
+ })
367
+ const error =
368
+ result.error?.message ?? (result.signal === null ? undefined : `ended by ${result.signal}`)
369
+ return { exit: error === undefined ? (result.status ?? undefined) : undefined, error }
370
+ } finally {
371
+ closeSync(descriptor)
372
+ }
373
+ }
374
+
375
+ /**
376
+ * Reads the last lines of a log file.
377
+ *
378
+ * @param log - The path of the log file.
379
+ * @param count - How many trailing lines to keep.
380
+ * @returns The last `count` lines, each ending in a line break, or an empty text when the file
381
+ * cannot be read.
382
+ */
383
+ export function readTail(log: string, count: number): string {
384
+ try {
385
+ const lines = readFileSync(log, 'utf8').split(/\r\n|\n/u)
386
+ if (lines.at(-1) === '') lines.pop()
387
+ return lines
388
+ .slice(-count)
389
+ .map((line) => `${line}\n`)
390
+ .join('')
391
+ } catch {
392
+ return ''
393
+ }
349
394
  }
350
395
 
351
396
  /**
@@ -396,6 +441,7 @@ export function digestFile(path: string): string | undefined {
396
441
  * @param mutations - The mutations to apply.
397
442
  * @param command - The executable to run.
398
443
  * @param args - The arguments after the executable.
444
+ * @param log - The path of the log file the run writes its output to.
399
445
  * @returns How the mutated run ended.
400
446
  */
401
447
  export function runMutated(
@@ -403,10 +449,11 @@ export function runMutated(
403
449
  mutations: readonly Mutation[],
404
450
  command: string,
405
451
  args: readonly string[],
452
+ log: string,
406
453
  ): Finish {
407
454
  try {
408
455
  for (const mutation of mutations) writeFileSync(resolve(root, mutation.path), mutation.mutated)
409
- return runCommand(command, args)
456
+ return runCommand(command, args, log)
410
457
  } catch (error) {
411
458
  return { exit: undefined, error: error instanceof Error ? error.message : String(error) }
412
459
  }
@@ -603,35 +650,29 @@ export function main(argv: readonly string[]): number {
603
650
  const end = argv.indexOf('--')
604
651
  const own = end === -1 ? argv : argv.slice(0, end)
605
652
  const command = end === -1 ? [] : argv.slice(end + 1)
606
- const unknown = readUnknownFlags(argv, FLAGS)
607
- if (unknown.length > 0) {
608
- console.error(`mutate: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
653
+ const parsed = parseArguments(own)
654
+ if (!parsed.success) {
655
+ console.error(`mutate: ${parsed.error}; ${USAGE}`)
609
656
  return 64
610
657
  }
611
- const missing = readMissingFlags(own, VALUE_FLAGS)
612
- if (missing.length > 0) {
613
- console.error(`mutate: ${missing.join(', ')} given with no value`)
614
- return 64
615
- }
616
- const restore = readOption(own, '--restore')
658
+ const { values } = parsed.value
659
+ const source = typeof values.edits === 'string' ? values.edits : undefined
660
+ const restore = typeof values.restore === 'string' ? values.restore : undefined
617
661
  if (restore !== undefined) {
618
- if (end !== -1 || own.includes('--edits') || readPositionals(own, VALUE_FLAGS).length > 0) {
619
- console.error(USAGE)
662
+ if (end !== -1 || source !== undefined) {
663
+ console.error(
664
+ `mutate: --restore and --edits with a command are two modes; name one; ${USAGE}`,
665
+ )
620
666
  return 64
621
667
  }
622
668
  return restoreRun(process.cwd(), restore)
623
669
  }
624
- const source = readOption(own, '--edits')
625
670
  const executable = command[0]
626
- if (
627
- source === undefined ||
628
- executable === undefined ||
629
- readPositionals(own, VALUE_FLAGS).length > 0
630
- ) {
671
+ if (source === undefined || executable === undefined) {
631
672
  console.error(USAGE)
632
673
  return 64
633
674
  }
634
- if (!existsSync(source) || !statSync(source).isFile()) {
675
+ if (readFileProblem(source) !== undefined) {
635
676
  console.error(`mutate: ${quote(source)} is not a readable edit file; ${USAGE}`)
636
677
  return 64
637
678
  }
@@ -661,7 +702,12 @@ export function main(argv: readonly string[]): number {
661
702
  }
662
703
  const saved = saveOriginals(root, resolution.mutations)
663
704
  console.error(`mutate: originals saved under ${saved}`)
664
- const mutated = runMutated(root, resolution.mutations, executable, command.slice(1))
705
+ const mutatedLog = `${source}${MUTATED_SUFFIX}`
706
+ const restoredLog = `${source}${RESTORED_SUFFIX}`
707
+ const mutated = runMutated(root, resolution.mutations, executable, command.slice(1), mutatedLog)
708
+ console.error(
709
+ `mutate: last ${String(TAIL_LINES)} lines of ${mutatedLog}:\n${readTail(mutatedLog, TAIL_LINES)}`,
710
+ )
665
711
  const refusal = tryRestore(root, resolution.mutations)
666
712
  const drift = readDrift(root, resolution.mutations)
667
713
  if (refusal !== undefined || drift.length > 0) {
@@ -675,7 +721,7 @@ export function main(argv: readonly string[]): number {
675
721
  console.error(`mutate: the command did not exit: ${mutated.error ?? 'unknown'}`)
676
722
  return 2
677
723
  }
678
- const restored = runCommand(executable, command.slice(1))
724
+ const restored = runCommand(executable, command.slice(1), restoredLog)
679
725
  rmSync(saved, { recursive: true, force: true })
680
726
  if (restored.exit === undefined) {
681
727
  console.error(`mutate: the restored run did not exit: ${restored.error ?? 'unknown'}`)
@@ -690,6 +736,8 @@ export function main(argv: readonly string[]): number {
690
736
  })),
691
737
  mutatedExit: mutated.exit,
692
738
  restoredExit: restored.exit,
739
+ mutatedLog,
740
+ restoredLog,
693
741
  restored: true,
694
742
  }),
695
743
  )
@@ -403,7 +403,7 @@ When instructions sit behind an index and demand-loaded bodies, keep the indexes
403
403
 
404
404
  - **Refuse.** An index alone, because “an index with no loader tool is inert for the model”. A scripted skill study as uptake or ordering evidence, because the scripted driver has no model. A fleet-wide module-count limit, a shared index ceiling, or background consolidation, because the recorded research motivates progressive disclosure only and no consumer earns these.
405
405
  - **Reading.** In the `@orkestrel/agent` package, on the scripted context study: a no-fold turn carries the acknowledgement, and the body arrives at the next run. The scripted study does not prove memo order or load rate.
406
- - **Example.** `@orkestrel/agent` `4d897eec`: the timing study of skill bodies, with `@orkestrel/toolbox` owning the later model-driven loader.
406
+ - **Example.** `@orkestrel/agent` `4d897eec`: the timing study of skill bodies, with the model-driven loader built into `@orkestrel/agent` as the `load` built-in.
407
407
 
408
408
  ### Admit a declared numeric language instead of listing bad spellings
409
409
 
@@ -1,7 +1,7 @@
1
1
  // Let Vitest select each gate's tests, then compare its identities with each config/mode universe.
2
2
  // Run from the checkout root:
3
3
  // node .agents/skills/orkestrel-harden/scripts/discovery.ts [--config vite.config.ts] [--projects a,b] [--json]
4
- // Each value is a separate argument: `--flag=value` and any flag the script does not read exit 64.
4
+ // The script reads its flags with `parseArgs` in strict mode, so a flag it does not read exits 64.
5
5
  // Roots are the package scripts no `npm run` invokes; `npm test` runs the root `test`, which stays a
6
6
  // root. Follow root chains and forwarded arguments through `npm run [-s|--silent] NAME`,
7
7
  // `npm run-script`, `npm test`, and `npm t`. Read a command past an environment prefix, `cross-env`,
@@ -31,6 +31,7 @@
31
31
  // Exit 0 with no flag, 3 with a flag, 2 for missing Vitest, an option table without a required
32
32
  // option, unsupported related commands, CLI/help/argument/listing/output failures, repeated
33
33
  // test-file changes, or filesystem/JSON errors; exit 64 on usage.
34
+ import type { ParseArgsOptionsConfig } from 'node:util'
34
35
  import { spawnSync } from 'node:child_process'
35
36
  import {
36
37
  existsSync,
@@ -43,6 +44,7 @@ import {
43
44
  } from 'node:fs'
44
45
  import { tmpdir } from 'node:os'
45
46
  import { basename, join, relative, resolve } from 'node:path'
47
+ import { isDeepStrictEqual, parseArgs } from 'node:util'
46
48
 
47
49
  /** Names the Vitest entry the census runs. */
48
50
  export const VITEST = 'node_modules/vitest/vitest.mjs'
@@ -66,12 +68,49 @@ export const REQUIRED_OPTIONS: readonly string[] = [
66
68
  '--staticParse',
67
69
  ]
68
70
 
69
- /** Lists the flags this script reads, value flags and switches alike. */
70
- export const FLAGS: readonly string[] = ['--config', '--projects', '--json']
71
-
72
71
  /** Holds the usage line printed on a usage refusal. */
73
72
  export const USAGE = 'usage: discovery.ts [--config vite.config.ts] [--projects a,b] [--json]'
74
73
 
74
+ /** Declares every flag the script reads, for `parseArgs`. */
75
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
76
+ config: Object.freeze({ type: 'string' }),
77
+ projects: Object.freeze({ type: 'string' }),
78
+ json: Object.freeze({ type: 'boolean' }),
79
+ })
80
+
81
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
82
+ export interface Arguments {
83
+ readonly values: Readonly<
84
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
85
+ >
86
+ readonly positionals: readonly string[]
87
+ }
88
+
89
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
90
+ export type ArgumentsResult =
91
+ | { readonly success: true; readonly value: Arguments }
92
+ | { readonly success: false; readonly error: string }
93
+
94
+ /**
95
+ * Parses the arguments in strict mode against `OPTIONS`.
96
+ *
97
+ * @param argv - The arguments after the script path.
98
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
99
+ */
100
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
101
+ try {
102
+ const { values, positionals } = parseArgs({
103
+ args: [...argv],
104
+ options: OPTIONS,
105
+ strict: true,
106
+ allowPositionals: false,
107
+ })
108
+ return { success: true, value: { values, positionals } }
109
+ } catch (error) {
110
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
111
+ }
112
+ }
113
+
75
114
  /** Names the options a gate listing drops, because they change the run and not the selection. */
76
115
  export const OMITTED = new Set([
77
116
  'reporter',
@@ -315,60 +354,7 @@ export interface Span {
315
354
  * @returns The same path with every backslash replaced by a slash.
316
355
  */
317
356
  export function normalizeSlashes(path: string): string {
318
- return path.split('\\').join('/')
319
- }
320
-
321
- /**
322
- * Reads the value that follows a flag.
323
- *
324
- * @remarks
325
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
326
- * and the `--flag=value` form is not read.
327
- *
328
- * @param argv - The arguments after the script path.
329
- * @param name - The flag, such as `--config`.
330
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
331
- * another flag.
332
- */
333
- export function readOption(argv: readonly string[], name: string): string | undefined {
334
- const index = argv.indexOf(name)
335
- const value = index === -1 ? undefined : argv[index + 1]
336
- return value === undefined || value.startsWith('--') ? undefined : value
337
- }
338
-
339
- /**
340
- * Names the value flags a caller gave with no value.
341
- *
342
- * @param argv - The arguments after the script path.
343
- * @param names - The flags that take a value.
344
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
345
- */
346
- export function readMissingFlags(
347
- argv: readonly string[],
348
- names: readonly string[],
349
- ): readonly string[] {
350
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
351
- }
352
-
353
- /**
354
- * Names the flags a caller gave that the script does not read.
355
- *
356
- * @remarks
357
- * Reads the arguments before a bare `--`. A `--flag=value` argument is unknown, because the script
358
- * reads `--flag value` pairs only.
359
- *
360
- * @param argv - The arguments after the script path.
361
- * @param flags - Every flag the script reads, value flags and switches alike.
362
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
363
- */
364
- export function readUnknownFlags(
365
- argv: readonly string[],
366
- flags: readonly string[],
367
- ): readonly string[] {
368
- const end = argv.indexOf('--')
369
- return (end === -1 ? argv : argv.slice(0, end)).filter(
370
- (argument) => argument.startsWith('--') && !flags.includes(argument),
371
- )
357
+ return path.replaceAll('\\', '/')
372
358
  }
373
359
 
374
360
  /** Describes one file a tree walk found, with the modification time the snapshot reads. */
@@ -1417,10 +1403,9 @@ export function readUnit(
1417
1403
  if (universe === undefined) return undefined
1418
1404
  const collected = universe.entries
1419
1405
  const selected = collectResults(reached, (gate) => {
1420
- const selection =
1421
- JSON.stringify(gate.args) === JSON.stringify(universeArguments)
1422
- ? collected
1423
- : listCollected(gate.args, gate.full, cache)?.entries
1406
+ const selection = isDeepStrictEqual(gate.args, universeArguments)
1407
+ ? collected
1408
+ : listCollected(gate.args, gate.full, cache)?.entries
1424
1409
  if (selection === undefined) {
1425
1410
  console.error(`discovery: gate ${gate.chain}: vitest list refused ${gate.args.join(' ')}`)
1426
1411
  return undefined
@@ -1663,19 +1648,13 @@ export function collectStableListings(
1663
1648
  * @returns The exit code: 0 no flag, 3 a flag, 2 a tool failure, 64 usage.
1664
1649
  */
1665
1650
  export function main(argv: readonly string[]): number {
1666
- const unknown = readUnknownFlags(argv, FLAGS)
1667
- if (unknown.length > 0) {
1668
- console.error(
1669
- `discovery: ${unknown.map(describeName).join(', ')} is not a flag this script reads; give each value as its own argument. ${USAGE}`,
1670
- )
1651
+ const parsed = parseArguments(argv)
1652
+ if (!parsed.success) {
1653
+ console.error(`discovery: ${parsed.error}; ${USAGE}`)
1671
1654
  return 64
1672
1655
  }
1673
- const missing = readMissingFlags(argv, ['--config', '--projects'])
1674
- if (missing.length > 0) {
1675
- console.error(`discovery: ${missing.join(', ')} given with no value`)
1676
- return 64
1677
- }
1678
- const config = readOption(argv, '--config') ?? 'vite.config.ts'
1656
+ const { values } = parsed.value
1657
+ const config = typeof values.config === 'string' ? values.config : 'vite.config.ts'
1679
1658
  if (!existsSync(config) || !existsSync('package.json')) {
1680
1659
  console.error(USAGE)
1681
1660
  return 64
@@ -1694,7 +1673,11 @@ export function main(argv: readonly string[]): number {
1694
1673
  return 2
1695
1674
  }
1696
1675
  const named = [
1697
- ...new Set((readOption(argv, '--projects') ?? '').split(',').filter((name) => name !== '')),
1676
+ ...new Set(
1677
+ (typeof values.projects === 'string' ? values.projects : '')
1678
+ .split(',')
1679
+ .filter((name) => name !== ''),
1680
+ ),
1698
1681
  ]
1699
1682
  const read = readGates(readScripts(), canonical, options)
1700
1683
  if (named.length > 0) {
@@ -1784,7 +1767,7 @@ export function main(argv: readonly string[]): number {
1784
1767
  markers: countMarkers(resolve(file)),
1785
1768
  }))
1786
1769
  const flagged = undiscovered.length + ungated.length + empty.length > 0
1787
- if (argv.includes('--json')) {
1770
+ if (values.json === true) {
1788
1771
  console.log(
1789
1772
  JSON.stringify({ config, projects, ungated, empty, workbenches, undiscovered, census }),
1790
1773
  )