@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
@@ -1,100 +1,51 @@
1
- // Prove a test catches a mutation: apply an edit file, run a command, restore the files, run the
2
- // command again. Run from the checkout root:
3
- // node .agents/skills/orkestrel-falsify/scripts/mutate.ts --edits EDITS.md -- COMMAND [ARGS...]
4
- // The edit file has the shape `patch.ts` of the `orkestrel-dispatch` skill reads: blocks of a
5
- // `### <path>` heading (relative to the working directory), a `reason:` line, and fenced `old:` and
6
- // `new:` texts, where each `old` text must occur exactly once in its file after the earlier edits to
7
- // that file. The script resolves every edit before it touches a file, saves each file's original
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
13
- // (`a.ts` and `./a.ts`, or a case-only difference on a host that folds case) apply to it in order,
14
- // each against the text the earlier ones left. A mutation that leaves the suite uncollected also
15
- // reads as a failing run, so read the command's own test count on standard error.
16
- // A killed parent leaves the tree mutated, so a run refuses to start while a run directory remains
17
- // and names the line that restores it, and
18
- // node .agents/skills/orkestrel-falsify/scripts/mutate.ts --restore tmp/probes/mutate/run-NAME
19
- // writes each saved original back, proves each file's SHA-256 digest against the run's manifest,
20
- // 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.
23
- // 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.
26
1
  import { spawnSync } from 'node:child_process';
27
2
  import { createHash } from 'node:crypto';
28
- import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
3
+ import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
29
4
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
30
- /** Lists the flags that take a value. */
31
- export const VALUE_FLAGS = ['--edits', '--restore'];
32
- /** Lists every flag the script reads, value flags and switches alike. */
33
- export const FLAGS = VALUE_FLAGS;
5
+ import { parseArgs } from 'node:util';
34
6
  /** Holds the usage line printed when a call names no edit file or no command. */
35
7
  export const USAGE = 'usage: mutate.ts --edits EDITS.md -- COMMAND [ARGS...] | mutate.ts --restore tmp/probes/mutate/run-NAME';
8
+ /** Declares every flag the script reads, for `parseArgs`. */
9
+ export const OPTIONS = Object.freeze({
10
+ edits: Object.freeze({ type: 'string' }),
11
+ restore: Object.freeze({ type: 'string' }),
12
+ });
13
+ /**
14
+ * Parses the arguments in strict mode against `OPTIONS`.
15
+ *
16
+ * @param argv - The arguments after the script path.
17
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
18
+ */
19
+ export function parseArguments(argv) {
20
+ try {
21
+ const { values, positionals } = parseArgs({
22
+ args: [...argv],
23
+ options: OPTIONS,
24
+ strict: true,
25
+ allowPositionals: false,
26
+ });
27
+ return { success: true, value: { values, positionals } };
28
+ }
29
+ catch (error) {
30
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
31
+ }
32
+ }
36
33
  /** Holds the directory, under the working directory, that keeps the original bytes of a run. */
37
34
  export const BACKUP_ROOT = 'tmp/probes/mutate';
38
35
  /** Holds the name every run directory opens with. */
39
36
  export const RUN_PREFIX = 'run-';
40
37
  /** Holds the name of the manifest file a run directory keeps beside its saved bytes. */
41
38
  export const MANIFEST = 'manifest.json';
39
+ /** Holds how many of the last lines of the mutated run's log the script prints to standard error. */
40
+ export const TAIL_LINES = 40;
41
+ /** Holds the suffix that names the mutated run's log beside the edit file. */
42
+ export const MUTATED_SUFFIX = '.mutated.log';
43
+ /** Holds the suffix that names the restored run's log beside the edit file. */
44
+ export const RESTORED_SUFFIX = '.restored.log';
42
45
  /** Matches one edit block with its path, reason, and fenced old and new texts. */
43
46
  export const EDIT_BLOCK = /^### (.+?)[ \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;
44
47
  /** Matches a line that belongs to an edit block and so must not remain outside one. */
45
48
  export const STRAY_LINE = /^(?:### |reason:|old:|new:)/u;
46
- /**
47
- * Names the value flags a caller gave with no value.
48
- *
49
- * @param argv - The arguments before the bare `--`.
50
- * @param names - The flags that take a value.
51
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
52
- */
53
- export function readMissingFlags(argv, names) {
54
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
55
- }
56
- /**
57
- * Reads the value that follows a flag.
58
- *
59
- * @remarks
60
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
61
- * and the `--flag=value` form is not read.
62
- *
63
- * @param argv - The arguments before the bare `--`.
64
- * @param name - The flag, such as `--edits`.
65
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
66
- * another flag.
67
- */
68
- export function readOption(argv, name) {
69
- const index = argv.indexOf(name);
70
- const value = index === -1 ? undefined : argv[index + 1];
71
- return value === undefined || value.startsWith('--') ? undefined : value;
72
- }
73
- /**
74
- * Names the flags a caller gave that the script does not read.
75
- *
76
- * @remarks
77
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
78
- * scan, because it opens the command the script runs.
79
- *
80
- * @param argv - The arguments after the script path.
81
- * @param flags - Every flag the script reads, value flags and switches alike.
82
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
83
- */
84
- export function readUnknownFlags(argv, flags) {
85
- const end = argv.indexOf('--');
86
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
87
- }
88
- /**
89
- * Reads the arguments that are neither a flag nor the value of a value flag.
90
- *
91
- * @param argv - The arguments before the bare `--`.
92
- * @param valueFlags - The flags that take a value.
93
- * @returns The positional arguments in order.
94
- */
95
- export function readPositionals(argv, valueFlags) {
96
- return argv.filter((argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''));
97
- }
98
49
  /**
99
50
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
100
51
  *
@@ -206,6 +157,27 @@ export function foldPath(path, platform) {
206
157
  export function keyEdit(root, edit) {
207
158
  return foldPath(resolve(root, edit.path), process.platform);
208
159
  }
160
+ /**
161
+ * Names why a path is not a file this script can read.
162
+ *
163
+ * @remarks
164
+ * A stat that throws, such as one refused with `EACCES` or given a path that holds a NUL byte, is a
165
+ * problem named by its error code, never an uncaught error.
166
+ *
167
+ * @param path - The path to read.
168
+ * @returns The problem, or undefined when the path is a file.
169
+ */
170
+ export function readFileProblem(path) {
171
+ try {
172
+ return statSync(path, { throwIfNoEntry: false })?.isFile() === true ? undefined : 'no such file';
173
+ }
174
+ catch (error) {
175
+ const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
176
+ ? error.code
177
+ : String(error);
178
+ return `cannot be read: ${code}`;
179
+ }
180
+ }
209
181
  /**
210
182
  * Resolves every edit against the files under a root, writing nothing.
211
183
  *
@@ -224,9 +196,9 @@ export function resolveMutations(root, edits) {
224
196
  if (!isInside(root, target)) {
225
197
  return { mutation: undefined, problems: [`${path}: path leaves the working directory`] };
226
198
  }
227
- if (!existsSync(target) || !statSync(target).isFile()) {
228
- return { mutation: undefined, problems: [`${path}: no such file`] };
229
- }
199
+ const problem = readFileProblem(target);
200
+ if (problem !== undefined)
201
+ return { mutation: undefined, problems: [`${path}: ${problem}`] };
230
202
  const original = readFileSync(target);
231
203
  const applied = applyEdits(original.toString('utf8'), own);
232
204
  return {
@@ -240,21 +212,67 @@ export function resolveMutations(root, edits) {
240
212
  };
241
213
  }
242
214
  /**
243
- * Runs the command with no shell, its output sent to this process's standard error.
215
+ * Opens a log file for writing, creating or emptying it.
216
+ *
217
+ * @param log - The path of the log file.
218
+ * @returns The file descriptor, or the host's refusal message when the file cannot be opened.
219
+ */
220
+ export function openLog(log) {
221
+ try {
222
+ return openSync(log, 'w');
223
+ }
224
+ catch (error) {
225
+ return error instanceof Error ? error.message : String(error);
226
+ }
227
+ }
228
+ /**
229
+ * Runs the command with no shell, its standard output and standard error written together, in
230
+ * order, to a log file that the run creates or overwrites.
244
231
  *
245
232
  * @param command - The executable to run.
246
233
  * @param args - The arguments after the executable.
247
- * @returns The exit code, or undefined with the reason when the command cannot start or a signal
248
- * ended it.
234
+ * @param log - The path of the log file.
235
+ * @returns The exit code, or undefined with the reason when the log cannot be opened, the command
236
+ * cannot start, or a signal ended it.
249
237
  */
250
- export function runCommand(command, args) {
251
- const result = spawnSync(command, args, {
252
- stdio: ['ignore', 2, 2],
253
- windowsHide: true,
254
- shell: false,
255
- });
256
- const error = result.error?.message ?? (result.signal === null ? undefined : `ended by ${result.signal}`);
257
- return { exit: error === undefined ? (result.status ?? undefined) : undefined, error };
238
+ export function runCommand(command, args, log) {
239
+ const descriptor = openLog(log);
240
+ if (typeof descriptor === 'string')
241
+ return { exit: undefined, error: descriptor };
242
+ try {
243
+ const result = spawnSync(command, args, {
244
+ stdio: ['ignore', descriptor, descriptor],
245
+ windowsHide: true,
246
+ shell: false,
247
+ });
248
+ const error = result.error?.message ?? (result.signal === null ? undefined : `ended by ${result.signal}`);
249
+ return { exit: error === undefined ? (result.status ?? undefined) : undefined, error };
250
+ }
251
+ finally {
252
+ closeSync(descriptor);
253
+ }
254
+ }
255
+ /**
256
+ * Reads the last lines of a log file.
257
+ *
258
+ * @param log - The path of the log file.
259
+ * @param count - How many trailing lines to keep.
260
+ * @returns The last `count` lines, each ending in a line break, or an empty text when the file
261
+ * cannot be read.
262
+ */
263
+ export function readTail(log, count) {
264
+ try {
265
+ const lines = readFileSync(log, 'utf8').split(/\r\n|\n/u);
266
+ if (lines.at(-1) === '')
267
+ lines.pop();
268
+ return lines
269
+ .slice(-count)
270
+ .map((line) => `${line}\n`)
271
+ .join('');
272
+ }
273
+ catch {
274
+ return '';
275
+ }
258
276
  }
259
277
  /**
260
278
  * Writes each mutation's original bytes back to its file.
@@ -301,13 +319,14 @@ export function digestFile(path) {
301
319
  * @param mutations - The mutations to apply.
302
320
  * @param command - The executable to run.
303
321
  * @param args - The arguments after the executable.
322
+ * @param log - The path of the log file the run writes its output to.
304
323
  * @returns How the mutated run ended.
305
324
  */
306
- export function runMutated(root, mutations, command, args) {
325
+ export function runMutated(root, mutations, command, args, log) {
307
326
  try {
308
327
  for (const mutation of mutations)
309
328
  writeFileSync(resolve(root, mutation.path), mutation.mutated);
310
- return runCommand(command, args);
329
+ return runCommand(command, args, log);
311
330
  }
312
331
  catch (error) {
313
332
  return { exit: undefined, error: error instanceof Error ? error.message : String(error) };
@@ -475,33 +494,27 @@ export function main(argv) {
475
494
  const end = argv.indexOf('--');
476
495
  const own = end === -1 ? argv : argv.slice(0, end);
477
496
  const command = end === -1 ? [] : argv.slice(end + 1);
478
- const unknown = readUnknownFlags(argv, FLAGS);
479
- if (unknown.length > 0) {
480
- console.error(`mutate: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
481
- return 64;
482
- }
483
- const missing = readMissingFlags(own, VALUE_FLAGS);
484
- if (missing.length > 0) {
485
- console.error(`mutate: ${missing.join(', ')} given with no value`);
497
+ const parsed = parseArguments(own);
498
+ if (!parsed.success) {
499
+ console.error(`mutate: ${parsed.error}; ${USAGE}`);
486
500
  return 64;
487
501
  }
488
- const restore = readOption(own, '--restore');
502
+ const { values } = parsed.value;
503
+ const source = typeof values.edits === 'string' ? values.edits : undefined;
504
+ const restore = typeof values.restore === 'string' ? values.restore : undefined;
489
505
  if (restore !== undefined) {
490
- if (end !== -1 || own.includes('--edits') || readPositionals(own, VALUE_FLAGS).length > 0) {
491
- console.error(USAGE);
506
+ if (end !== -1 || source !== undefined) {
507
+ console.error(`mutate: --restore and --edits with a command are two modes; name one; ${USAGE}`);
492
508
  return 64;
493
509
  }
494
510
  return restoreRun(process.cwd(), restore);
495
511
  }
496
- const source = readOption(own, '--edits');
497
512
  const executable = command[0];
498
- if (source === undefined ||
499
- executable === undefined ||
500
- readPositionals(own, VALUE_FLAGS).length > 0) {
513
+ if (source === undefined || executable === undefined) {
501
514
  console.error(USAGE);
502
515
  return 64;
503
516
  }
504
- if (!existsSync(source) || !statSync(source).isFile()) {
517
+ if (readFileProblem(source) !== undefined) {
505
518
  console.error(`mutate: ${quote(source)} is not a readable edit file; ${USAGE}`);
506
519
  return 64;
507
520
  }
@@ -525,7 +538,10 @@ export function main(argv) {
525
538
  }
526
539
  const saved = saveOriginals(root, resolution.mutations);
527
540
  console.error(`mutate: originals saved under ${saved}`);
528
- const mutated = runMutated(root, resolution.mutations, executable, command.slice(1));
541
+ const mutatedLog = `${source}${MUTATED_SUFFIX}`;
542
+ const restoredLog = `${source}${RESTORED_SUFFIX}`;
543
+ const mutated = runMutated(root, resolution.mutations, executable, command.slice(1), mutatedLog);
544
+ console.error(`mutate: last ${String(TAIL_LINES)} lines of ${mutatedLog}:\n${readTail(mutatedLog, TAIL_LINES)}`);
529
545
  const refusal = tryRestore(root, resolution.mutations);
530
546
  const drift = readDrift(root, resolution.mutations);
531
547
  if (refusal !== undefined || drift.length > 0) {
@@ -537,7 +553,7 @@ export function main(argv) {
537
553
  console.error(`mutate: the command did not exit: ${mutated.error ?? 'unknown'}`);
538
554
  return 2;
539
555
  }
540
- const restored = runCommand(executable, command.slice(1));
556
+ const restored = runCommand(executable, command.slice(1), restoredLog);
541
557
  rmSync(saved, { recursive: true, force: true });
542
558
  if (restored.exit === undefined) {
543
559
  console.error(`mutate: the restored run did not exit: ${restored.error ?? 'unknown'}`);
@@ -551,6 +567,8 @@ export function main(argv) {
551
567
  })),
552
568
  mutatedExit: mutated.exit,
553
569
  restoredExit: restored.exit,
570
+ mutatedLog,
571
+ restoredLog,
554
572
  restored: true,
555
573
  }));
556
574
  return mutated.exit !== 0 && restored.exit === 0 ? 0 : 3;
@@ -1,40 +1,8 @@
1
- // Let Vitest select each gate's tests, then compare its identities with each config/mode universe.
2
- // Run from the checkout root:
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.
5
- // Roots are the package scripts no `npm run` invokes; `npm test` runs the root `test`, which stays a
6
- // root. Follow root chains and forwarded arguments through `npm run [-s|--silent] NAME`,
7
- // `npm run-script`, `npm test`, and `npm t`. Read a command past an environment prefix, `cross-env`,
8
- // and a redirection. A gate is a Vitest run; list, bench, watch, dev, `--watch` without `=false`, and
9
- // the mergeReports, listTags, and clearCache invocations are not gates. A test file counts as gated
10
- // by a command only when `node` runs it as an argument (`node FILE`, `node --test FILE`).
11
- // Collect an unfiltered full listing for each config/mode/root/dir, including the base config. Pass
12
- // gate arguments verbatim except the reporter, output-file, coverage, color, cache, silent, UI,
13
- // watch, run-mode, inspector, and standalone options; use filesOnly for file selection and full
14
- // collection with --staticParse=false for name, tag, line, and shard selection, so runtime titles,
15
- // setup modules, and the worker sequencer participate. Compare file/project/name/line/column
16
- // identities without renaming projects. Preserve duplicate names within a listing and merge across
17
- // units. Exit 2 naming the Vitest version when the option table lacks a required option.
18
- // With --projects, list only the named projects: the universe, each gate listing, each project
19
- // reading, the units enumerated, and the empty-project rescan carry the names, and a gate that
20
- // reaches none of them is not listed. An exact name never lists a project outside the set, and the
21
- // refusal for a name that matches none lists no other project either. A name holding `*` or opening
22
- // with `!` is a Vitest pattern the script cannot match beforehand, so a gate that names projects
23
- // keeps its own and a listing for such a name can reach projects beyond the names. Exit 64 for a
24
- // name no project in the config matches, and skip the undiscovered scan.
25
- // Flag ungated projects, empty chained projects, and undiscovered files under tests/ (the test
26
- // and spec names, any extension). Report marker counts for the forms that need a ruling (`.todo`,
27
- // `.skipIf`, `.runIf`, `.fails`, a `retry` option, a timeout option or a numeric last argument),
28
- // read as call forms outside comments and strings; `vitest/no-focused-tests` and `vitest/no-disabled-tests` refuse `.only` and `.skip`. Report empty
29
- // standalone workbenches without a flag: an empty project no chain containing " > " names.
30
- // Retry when test files change during collection; refuse another change during that retry.
31
- // Exit 0 with no flag, 3 with a flag, 2 for missing Vitest, an option table without a required
32
- // option, unsupported related commands, CLI/help/argument/listing/output failures, repeated
33
- // test-file changes, or filesystem/JSON errors; exit 64 on usage.
34
1
  import { spawnSync } from 'node:child_process';
35
2
  import { existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, } from 'node:fs';
36
3
  import { tmpdir } from 'node:os';
37
4
  import { basename, join, relative, resolve } from 'node:path';
5
+ import { isDeepStrictEqual, parseArgs } from 'node:util';
38
6
  /** Names the Vitest entry the census runs. */
39
7
  export const VITEST = 'node_modules/vitest/vitest.mjs';
40
8
  /** Lists the marker names the census counts, in report order. */
@@ -54,10 +22,34 @@ export const REQUIRED_OPTIONS = [
54
22
  '--filesOnly',
55
23
  '--staticParse',
56
24
  ];
57
- /** Lists the flags this script reads, value flags and switches alike. */
58
- export const FLAGS = ['--config', '--projects', '--json'];
59
25
  /** Holds the usage line printed on a usage refusal. */
60
26
  export const USAGE = 'usage: discovery.ts [--config vite.config.ts] [--projects a,b] [--json]';
27
+ /** Declares every flag the script reads, for `parseArgs`. */
28
+ export const OPTIONS = Object.freeze({
29
+ config: Object.freeze({ type: 'string' }),
30
+ projects: Object.freeze({ type: 'string' }),
31
+ json: Object.freeze({ type: 'boolean' }),
32
+ });
33
+ /**
34
+ * Parses the arguments in strict mode against `OPTIONS`.
35
+ *
36
+ * @param argv - The arguments after the script path.
37
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
38
+ */
39
+ export function parseArguments(argv) {
40
+ try {
41
+ const { values, positionals } = parseArgs({
42
+ args: [...argv],
43
+ options: OPTIONS,
44
+ strict: true,
45
+ allowPositionals: false,
46
+ });
47
+ return { success: true, value: { values, positionals } };
48
+ }
49
+ catch (error) {
50
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
51
+ }
52
+ }
61
53
  /** Names the options a gate listing drops, because they change the run and not the selection. */
62
54
  export const OMITTED = new Set([
63
55
  'reporter',
@@ -150,49 +142,7 @@ export const REGISTRARS = new Set(['it', 'test', 'describe', 'suite']);
150
142
  * @returns The same path with every backslash replaced by a slash.
151
143
  */
152
144
  export function normalizeSlashes(path) {
153
- return path.split('\\').join('/');
154
- }
155
- /**
156
- * Reads the value that follows a flag.
157
- *
158
- * @remarks
159
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
160
- * and the `--flag=value` form is not read.
161
- *
162
- * @param argv - The arguments after the script path.
163
- * @param name - The flag, such as `--config`.
164
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
165
- * another flag.
166
- */
167
- export function readOption(argv, name) {
168
- const index = argv.indexOf(name);
169
- const value = index === -1 ? undefined : argv[index + 1];
170
- return value === undefined || value.startsWith('--') ? undefined : value;
171
- }
172
- /**
173
- * Names the value flags a caller gave with no value.
174
- *
175
- * @param argv - The arguments after the script path.
176
- * @param names - The flags that take a value.
177
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
178
- */
179
- export function readMissingFlags(argv, names) {
180
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
181
- }
182
- /**
183
- * Names the flags a caller gave that the script does not read.
184
- *
185
- * @remarks
186
- * Reads the arguments before a bare `--`. A `--flag=value` argument is unknown, because the script
187
- * reads `--flag value` pairs only.
188
- *
189
- * @param argv - The arguments after the script path.
190
- * @param flags - Every flag the script reads, value flags and switches alike.
191
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
192
- */
193
- export function readUnknownFlags(argv, flags) {
194
- const end = argv.indexOf('--');
195
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
145
+ return path.replaceAll('\\', '/');
196
146
  }
197
147
  /**
198
148
  * Lists every regular file beneath a directory, skipping the named directories at any depth.
@@ -1113,7 +1063,7 @@ export function readUnit(unit, named, gates, cache) {
1113
1063
  return undefined;
1114
1064
  const collected = universe.entries;
1115
1065
  const selected = collectResults(reached, (gate) => {
1116
- const selection = JSON.stringify(gate.args) === JSON.stringify(universeArguments)
1066
+ const selection = isDeepStrictEqual(gate.args, universeArguments)
1117
1067
  ? collected
1118
1068
  : listCollected(gate.args, gate.full, cache)?.entries;
1119
1069
  if (selection === undefined) {
@@ -1312,17 +1262,13 @@ export function collectStableListings(config, named, gates, attempt = 0) {
1312
1262
  * @returns The exit code: 0 no flag, 3 a flag, 2 a tool failure, 64 usage.
1313
1263
  */
1314
1264
  export function main(argv) {
1315
- const unknown = readUnknownFlags(argv, FLAGS);
1316
- if (unknown.length > 0) {
1317
- console.error(`discovery: ${unknown.map(describeName).join(', ')} is not a flag this script reads; give each value as its own argument. ${USAGE}`);
1318
- return 64;
1319
- }
1320
- const missing = readMissingFlags(argv, ['--config', '--projects']);
1321
- if (missing.length > 0) {
1322
- console.error(`discovery: ${missing.join(', ')} given with no value`);
1265
+ const parsed = parseArguments(argv);
1266
+ if (!parsed.success) {
1267
+ console.error(`discovery: ${parsed.error}; ${USAGE}`);
1323
1268
  return 64;
1324
1269
  }
1325
- const config = readOption(argv, '--config') ?? 'vite.config.ts';
1270
+ const { values } = parsed.value;
1271
+ const config = typeof values.config === 'string' ? values.config : 'vite.config.ts';
1326
1272
  if (!existsSync(config) || !existsSync('package.json')) {
1327
1273
  console.error(USAGE);
1328
1274
  return 64;
@@ -1339,7 +1285,9 @@ export function main(argv) {
1339
1285
  return 2;
1340
1286
  }
1341
1287
  const named = [
1342
- ...new Set((readOption(argv, '--projects') ?? '').split(',').filter((name) => name !== '')),
1288
+ ...new Set((typeof values.projects === 'string' ? values.projects : '')
1289
+ .split(',')
1290
+ .filter((name) => name !== '')),
1343
1291
  ];
1344
1292
  const read = readGates(readScripts(), canonical, options);
1345
1293
  if (named.length > 0) {
@@ -1415,7 +1363,7 @@ export function main(argv) {
1415
1363
  markers: countMarkers(resolve(file)),
1416
1364
  }));
1417
1365
  const flagged = undiscovered.length + ungated.length + empty.length > 0;
1418
- if (argv.includes('--json')) {
1366
+ if (values.json === true) {
1419
1367
  console.log(JSON.stringify({ config, projects, ungated, empty, workbenches, undiscovered, census }));
1420
1368
  }
1421
1369
  else {