@orkestrel/scaffold 0.0.133 → 0.0.134

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1018 -194
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +95 -108
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +27 -3
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  35. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  36. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  37. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  38. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  42. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  43. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
  45. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
  46. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  47. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  52. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  53. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  54. package/dist/host/claude/agents/orkestrel.md +4 -4
  55. package/dist/host/claude/rules/documentation.md +1 -1
  56. package/dist/host/claude/rules/patterns.md +5 -4
  57. package/dist/host/claude/rules/styles.md +1 -1
  58. package/dist/host/claude/rules/tests.md +3 -3
  59. package/dist/host/claude/rules/workspace.md +47 -35
  60. package/dist/host/configs/helpers.ts +40 -15
  61. package/dist/host/dotfiles/oxlintrc.json +62 -0
  62. package/dist/host/guides/form.md +79 -4
  63. package/dist/host/guides/scaffold.md +93 -65
  64. package/dist/host/guides/table.md +20 -6
  65. package/dist/host/guides/test.md +9 -7
  66. package/dist/host/manifest.json +44 -44
  67. package/dist/host/tests/config.test.ts +201 -11
  68. package/dist/host/tests/policy.test.ts +14 -21
  69. package/dist/host/tests/setupPolicy.ts +43 -36
  70. package/dist/src/core/index.cjs +191 -93
  71. package/dist/src/core/index.cjs.map +1 -1
  72. package/dist/src/core/index.d.cts +27 -13
  73. package/dist/src/core/index.d.ts +27 -13
  74. package/dist/src/core/index.js +189 -93
  75. package/dist/src/core/index.js.map +1 -1
  76. package/dist/src/server/index.cjs +8 -9
  77. package/dist/src/server/index.cjs.map +1 -1
  78. package/dist/src/server/index.d.cts +1 -1
  79. package/dist/src/server/index.d.ts +1 -1
  80. package/dist/src/server/index.js +8 -9
  81. package/dist/src/server/index.js.map +1 -1
  82. package/package.json +2 -2
@@ -1,98 +1,38 @@
1
- // Apply an edit file of exact old-to-new replacements. Run from the checkout root:
2
- // node .agents/skills/orkestrel-dispatch/scripts/patch.ts EDITS.md (--plan | --apply) [--skip N ...]
3
- // An edit file holds blocks of this shape, in the order they apply:
4
- // ### path/relative/to/the/working/directory
5
- // reason: one line saying why
6
- // old:
7
- // ```ts
8
- // the exact text to replace
9
- // ```
10
- // new:
11
- // ```ts
12
- // the replacement text
13
- // ```
14
- // A fence opens with three or more backticks and closes with the same count, so a block can carry a
15
- // shorter fence. Prose outside the blocks is ignored, but a stray `###`, `reason:`, `old:`, or `new:`
16
- // line that opens no complete block is refused. Every `old` text must occur exactly once in its file
17
- // after the earlier edits to that file, however the blocks spell its path (`src/a.ts` and `./src/a.ts`
18
- // name one file), and nothing is written unless every selected edit resolves.
19
- // `--plan` prints each edit's resolution and writes nothing; `--apply` writes the files after every
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.
22
- // Exit 0 when every selected edit resolved, 1 when one did not, 64 on usage.
23
1
  import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
24
2
  import { isAbsolute, relative, resolve, sep } from 'node:path';
25
- /** Lists the flags that each select one operation. */
26
- export const MODE_FLAGS = ['--plan', '--apply'];
27
- /** Lists the flags that take a value. */
28
- export const VALUE_FLAGS = ['--skip'];
29
- /** Lists every flag the script reads, value flags and switches alike. */
30
- export const FLAGS = [...MODE_FLAGS, ...VALUE_FLAGS];
3
+ import { parseArgs } from 'node:util';
31
4
  /** Holds the usage line printed when a call names no edit file or no mode, or two. */
32
5
  export const USAGE = 'usage: patch.ts EDITS.md (--plan | --apply) [--skip N ...]; name one mode; --skip repeats';
33
- /** Matches one edit block with its path, reason, and fenced old and new texts. */
34
- 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;
35
- /** Matches a line that belongs to an edit block and so must not remain outside one. */
36
- export const STRAY_LINE = /^(?:### |reason:|old:|new:)/u;
37
- /**
38
- * Names the value flags a caller gave with no value, at any occurrence.
39
- *
40
- * @param argv - The arguments after the script path.
41
- * @param names - The flags that take a value.
42
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
43
- */
44
- export function readMissingFlags(argv, names) {
45
- return names.filter((name) => argv.some((argument, index) => argument === name && isMissingValue(argv, index)));
46
- }
47
- /**
48
- * Checks whether the argument after a flag is absent or is another flag.
49
- *
50
- * @param argv - The arguments after the script path.
51
- * @param index - The position of the flag.
52
- * @returns True when no value follows the flag; false otherwise.
53
- */
54
- export function isMissingValue(argv, index) {
55
- const value = argv[index + 1];
56
- return value === undefined || value.startsWith('--');
57
- }
58
- /**
59
- * Names the flags a caller gave that the script does not read.
60
- *
61
- * @remarks
62
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
63
- * scan.
64
- *
65
- * @param argv - The arguments after the script path.
66
- * @param flags - Every flag the script reads, value flags and switches alike.
67
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
68
- */
69
- export function readUnknownFlags(argv, flags) {
70
- const end = argv.indexOf('--');
71
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
72
- }
6
+ /** Declares every flag the script reads, for `parseArgs`. */
7
+ export const OPTIONS = Object.freeze({
8
+ plan: Object.freeze({ type: 'boolean' }),
9
+ apply: Object.freeze({ type: 'boolean' }),
10
+ skip: Object.freeze({ type: 'string', multiple: true }),
11
+ });
73
12
  /**
74
- * Reads every value that follows a repeatable flag.
13
+ * Parses the arguments in strict mode against `OPTIONS`.
75
14
  *
76
15
  * @param argv - The arguments after the script path.
77
- * @param name - The flag, such as `--skip`.
78
- * @returns The values in order, empty when the flag never appears.
16
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
79
17
  */
80
- export function readOptions(argv, name) {
81
- return argv.flatMap((argument, index) => {
82
- const value = argv[index + 1];
83
- return argument === name && value !== undefined && !value.startsWith('--') ? [value] : [];
84
- });
85
- }
86
- /**
87
- * Reads the arguments that are neither a flag nor the value of a value flag.
88
- *
89
- * @param argv - The arguments after the script path.
90
- * @param valueFlags - The flags that take a value.
91
- * @returns The positional arguments in order.
92
- */
93
- export function readPositionals(argv, valueFlags) {
94
- return argv.filter((argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''));
18
+ export function parseArguments(argv) {
19
+ try {
20
+ const { values, positionals } = parseArgs({
21
+ args: [...argv],
22
+ options: OPTIONS,
23
+ strict: true,
24
+ allowPositionals: true,
25
+ });
26
+ return { success: true, value: { values, positionals } };
27
+ }
28
+ catch (error) {
29
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
30
+ }
95
31
  }
32
+ /** Matches one edit block with its path, reason, and fenced old and new texts. */
33
+ 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;
34
+ /** Matches a line that belongs to an edit block and so must not remain outside one. */
35
+ export const STRAY_LINE = /^(?:### |reason:|old:|new:)/u;
96
36
  /**
97
37
  * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
98
38
  *
@@ -247,9 +187,39 @@ export function readFileKey(target) {
247
187
  export function readTargetProblem(root, target) {
248
188
  if (!isInside(root, target))
249
189
  return 'path leaves the working directory';
250
- if (!existsSync(target) || !statSync(target).isFile())
251
- return 'no such file';
252
- return undefined;
190
+ return readFileProblem(target);
191
+ }
192
+ /**
193
+ * Names why a path is not a file this script can read.
194
+ *
195
+ * @remarks
196
+ * A stat that throws, such as one refused with `EACCES` or given a path that holds a NUL byte, is a
197
+ * problem named by its error code, never an uncaught error.
198
+ *
199
+ * @param path - The path to read.
200
+ * @returns The problem, or undefined when the path is a file.
201
+ */
202
+ export function readFileProblem(path) {
203
+ try {
204
+ return statSync(path, { throwIfNoEntry: false })?.isFile() === true ? undefined : 'no such file';
205
+ }
206
+ catch (error) {
207
+ const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
208
+ ? error.code
209
+ : String(error);
210
+ return `cannot be read: ${code}`;
211
+ }
212
+ }
213
+ /**
214
+ * Collects the strings a repeatable flag's value holds.
215
+ *
216
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
217
+ * @returns Each string in order, empty when the flag never appears.
218
+ */
219
+ export function collectStrings(value) {
220
+ return Array.isArray(value)
221
+ ? value.filter((member) => typeof member === 'string')
222
+ : [];
253
223
  }
254
224
  /**
255
225
  * Runs the script on its arguments.
@@ -258,24 +228,19 @@ export function readTargetProblem(root, target) {
258
228
  * @returns The exit code: 0 when every selected edit resolved, 1 when one did not, 64 on usage.
259
229
  */
260
230
  export function main(argv) {
261
- const unknown = readUnknownFlags(argv, FLAGS);
262
- if (unknown.length > 0) {
263
- console.error(`patch: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
264
- return 64;
265
- }
266
- const missing = readMissingFlags(argv, VALUE_FLAGS);
267
- if (missing.length > 0) {
268
- console.error(`patch: ${missing.join(', ')} given with no value`);
231
+ const parsed = parseArguments(argv);
232
+ if (!parsed.success) {
233
+ console.error(`patch: ${parsed.error}; ${USAGE}`);
269
234
  return 64;
270
235
  }
271
- const modes = MODE_FLAGS.filter((flag) => argv.includes(flag));
272
- const sources = readPositionals(argv, VALUE_FLAGS);
273
- const source = sources[0];
274
- if (modes.length !== 1 || sources.length !== 1 || source === undefined) {
236
+ const { values, positionals } = parsed.value;
237
+ const apply = values.apply === true;
238
+ const [source, ...extra] = positionals;
239
+ if (apply === (values.plan === true) || extra.length > 0 || source === undefined) {
275
240
  console.error(USAGE);
276
241
  return 64;
277
242
  }
278
- if (!existsSync(source) || !statSync(source).isFile()) {
243
+ if (readFileProblem(source) !== undefined) {
279
244
  console.error(`patch: ${quote(source)} is not a readable edit file; ${USAGE}`);
280
245
  return 64;
281
246
  }
@@ -286,7 +251,7 @@ export function main(argv) {
286
251
  console.error(`patch: ${quote(source)} ${edits.length === 0 ? 'holds no complete edit block' : `has a line that opens no complete block: ${strays.map(quote).join(', ')}`}; a block is a "### path" line, a "reason:" line, and fenced "old:" and "new:" texts`);
287
252
  return 64;
288
253
  }
289
- const skips = readOptions(argv, '--skip');
254
+ const skips = collectStrings(values.skip);
290
255
  const invalid = readInvalidSkips(skips, edits.length);
291
256
  if (invalid.length > 0) {
292
257
  console.error(`patch: --skip ${invalid.map(quote).join(', ')} names no edit; the file holds edits 1 to ${String(edits.length)}`);
@@ -310,7 +275,6 @@ export function main(argv) {
310
275
  console.log('nothing written');
311
276
  return 1;
312
277
  }
313
- const apply = argv.includes('--apply');
314
278
  if (apply) {
315
279
  for (const file of resolution.files)
316
280
  writeFileSync(resolve(root, file.path), file.text);
@@ -1,67 +1,36 @@
1
- // Read a bench lane's answer, session id, and liveness from its journal. Run from the checkout root:
2
- // node .agents/skills/orkestrel-dispatch/scripts/result.ts --cursor tmp/cursor/UNIT.jsonl [--out tmp/cursor/UNIT-result.md]
3
- // node .agents/skills/orkestrel-dispatch/scripts/result.ts --claude tmp/claude/UNIT.jsonl [--out tmp/claude/UNIT-result.md]
4
- // node .agents/skills/orkestrel-dispatch/scripts/result.ts --codex tmp/codex/UNIT.jsonl [--out tmp/codex/UNIT-result.md]
5
- // A Cursor or Claude journal is the `--output-format stream-json` stream: the `init` event carries
6
- // the session id and the `result` event carries the answer. A Codex journal is the `--json` stream:
7
- // the `thread.started` event carries the thread id and the answer sits in the sibling `UNIT-last.md`
8
- // file that `--output-last-message` wrote. The summary also reads the sibling `UNIT.err` file that
9
- // launch.ts wrote (`exit`, `capped`, `durationMs`) and the journal's `bytes`, `ageMs`, and last
10
- // event, which is the liveness reading for a run still going. The answer is written to --out when
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.
14
1
  import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
15
2
  import { dirname } from 'node:path';
16
- /** Lists the flags that each select one journal reader. */
17
- export const MODE_FLAGS = ['--cursor', '--claude', '--codex'];
18
- /** Lists the flags that take a value. */
19
- export const VALUE_FLAGS = [...MODE_FLAGS, '--out'];
20
- /** Lists every flag the script reads, value flags and switches alike. */
21
- export const FLAGS = VALUE_FLAGS;
3
+ import { parseArgs } from 'node:util';
4
+ /** Lists the flags that each select one journal reader, by the name `parseArgs` reads them under. */
5
+ export const MODES = ['cursor', 'claude', 'codex'];
22
6
  /** Holds the usage line printed when a call names no journal or two modes. */
23
7
  export const USAGE = 'usage: result.ts (--cursor JOURNAL | --claude JOURNAL | --codex JOURNAL) [--out PATH]; name one mode';
8
+ /** Declares every flag the script reads, for `parseArgs`. */
9
+ export const OPTIONS = Object.freeze({
10
+ cursor: Object.freeze({ type: 'string' }),
11
+ claude: Object.freeze({ type: 'string' }),
12
+ codex: Object.freeze({ type: 'string' }),
13
+ out: Object.freeze({ type: 'string' }),
14
+ });
24
15
  /**
25
- * Reads the value that follows a flag.
26
- *
27
- * @remarks
28
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
29
- * and the `--flag=value` form is not read.
16
+ * Parses the arguments in strict mode against `OPTIONS`.
30
17
  *
31
18
  * @param argv - The arguments after the script path.
32
- * @param name - The flag, such as `--out`.
33
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
34
- * another flag.
19
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
35
20
  */
36
- export function readOption(argv, name) {
37
- const index = argv.indexOf(name);
38
- const value = index === -1 ? undefined : argv[index + 1];
39
- return value === undefined || value.startsWith('--') ? undefined : value;
40
- }
41
- /**
42
- * Names the value flags a caller gave with no value.
43
- *
44
- * @param argv - The arguments after the script path.
45
- * @param names - The flags that take a value.
46
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
47
- */
48
- export function readMissingFlags(argv, names) {
49
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
50
- }
51
- /**
52
- * Names the flags a caller gave that the script does not read.
53
- *
54
- * @remarks
55
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
56
- * scan.
57
- *
58
- * @param argv - The arguments after the script path.
59
- * @param flags - Every flag the script reads, value flags and switches alike.
60
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
61
- */
62
- export function readUnknownFlags(argv, flags) {
63
- const end = argv.indexOf('--');
64
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
21
+ export function parseArguments(argv) {
22
+ try {
23
+ const { values, positionals } = parseArgs({
24
+ args: [...argv],
25
+ options: OPTIONS,
26
+ strict: true,
27
+ allowPositionals: false,
28
+ });
29
+ return { success: true, value: { values, positionals } };
30
+ }
31
+ catch (error) {
32
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
33
+ }
65
34
  }
66
35
  /**
67
36
  * Reads the last non-empty line of a text as a JSON object.
@@ -202,26 +171,23 @@ export function describeEvent(event) {
202
171
  * @returns The exit code: 0 when the lane answered, 3 when it carries no session or answer, 64 on usage.
203
172
  */
204
173
  export function main(argv) {
205
- const unknown = readUnknownFlags(argv, FLAGS);
206
- if (unknown.length > 0) {
207
- console.error(`result: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
208
- return 64;
209
- }
210
- const missing = readMissingFlags(argv, VALUE_FLAGS);
211
- if (missing.length > 0) {
212
- console.error(`result: ${missing.join(', ')} given with no value`);
174
+ const parsed = parseArguments(argv);
175
+ if (!parsed.success) {
176
+ console.error(`result: ${parsed.error}; ${USAGE}`);
213
177
  return 64;
214
178
  }
215
- const modes = MODE_FLAGS.filter((flag) => argv.includes(flag));
216
- const mode = modes[0];
217
- const path = mode === undefined ? undefined : readOption(argv, mode);
218
- const out = readOption(argv, '--out');
179
+ const { values } = parsed.value;
180
+ const modes = MODES.filter((name) => values[name] !== undefined);
181
+ const [mode] = modes;
182
+ const chosen = mode === undefined ? undefined : values[mode];
183
+ const path = typeof chosen === 'string' ? chosen : undefined;
184
+ const out = typeof values.out === 'string' ? values.out : undefined;
219
185
  if (modes.length !== 1 || mode === undefined || path === undefined || !existsSync(path)) {
220
186
  console.error(USAGE);
221
187
  return 64;
222
188
  }
223
189
  const events = readEvents(path);
224
- const result = mode === '--codex' ? readCodex(path, events) : readStream(events);
190
+ const result = mode === 'codex' ? readCodex(path, events) : readStream(events);
225
191
  const errors = readErrors(path);
226
192
  const stat = statSync(path);
227
193
  if (result.answer !== undefined && out !== undefined) {
@@ -1,24 +1,7 @@
1
- // Campaign artifact sweep. Run from the checkout root with Node's type stripping:
2
- // node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --report
3
- // node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --tmp [--older-than MINUTES]
4
- // node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --unit UNIT [--delete]
5
- // --report lists leftovers under tmp/ and .orkestrel/ by age and deletes nothing. It also checks
6
- // every .md file under .orkestrel/: a backticked repository-relative path that git ignores prints
7
- // `<file>:<line> cites ignored path <path>` (a path git tracks is never reported, nor is a glob or
8
- // placeholder whose literal prefix git tracks), and an absolute machine path on a line prints
9
- // `<file>:<line> names a machine path`. Both lines are report-only.
10
- // --tmp deletes launch files older than the threshold (default 60 minutes), removes emptied
11
- // directories, and refuses while any launch file changed in the last 2 minutes.
12
- // --unit lists one accepted unit's files under the launch directories (the brief, report, claims,
13
- // journal, errors, status, pid, and last-message files whose name is UNIT followed by `-` or `.`), and
14
- // --delete removes them, refusing while one changed in the last 2 minutes.
15
- // --tmp and --unit --delete never delete a file git tracks: each prints `kept tracked <path>` and the
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.
19
1
  import { spawnSync } from 'node:child_process';
20
2
  import { existsSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
21
3
  import { basename, join } from 'node:path';
4
+ import { parseArgs } from 'node:util';
22
5
  /** Lists the directories under `tmp/` that hold launch files. */
23
6
  export const LAUNCH_DIRECTORIES = [
24
7
  'tmp/units',
@@ -55,53 +38,35 @@ export const MACHINE_PATH = /(?<![\w.-])(?:[A-Za-z]:[\\/]|\/(?:Users|home)\/|~\/
55
38
  export const BACKTICKED = /`([^`\n]+)`/gu;
56
39
  /** Matches the first glob or placeholder character in a path. */
57
40
  export const PLACEHOLDER = /[*?<{]/u;
58
- /** Lists the flags that take a value. */
59
- export const VALUE_FLAGS = ['--unit', '--older-than'];
60
- /** Lists every flag the script reads, value flags and switches alike. */
61
- export const FLAGS = [...VALUE_FLAGS, '--report', '--tmp', '--delete'];
62
41
  /** Holds the usage line printed when a call names an unknown mode. */
63
42
  export const USAGE = 'usage: sweep.ts --report | --tmp [--older-than MINUTES] | --unit UNIT [--delete]';
43
+ /** Declares every flag the script reads, for `parseArgs`. */
44
+ export const OPTIONS = Object.freeze({
45
+ unit: Object.freeze({ type: 'string' }),
46
+ 'older-than': Object.freeze({ type: 'string' }),
47
+ report: Object.freeze({ type: 'boolean' }),
48
+ tmp: Object.freeze({ type: 'boolean' }),
49
+ delete: Object.freeze({ type: 'boolean' }),
50
+ });
64
51
  /**
65
- * Reads the value that follows a flag.
66
- *
67
- * @remarks
68
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
69
- * and the `--flag=value` form is not read.
70
- *
71
- * @param argv - The arguments after the script path.
72
- * @param name - The flag, such as `--unit`.
73
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
74
- * another flag.
75
- */
76
- export function readOption(argv, name) {
77
- const index = argv.indexOf(name);
78
- const value = index === -1 ? undefined : argv[index + 1];
79
- return value === undefined || value.startsWith('--') ? undefined : value;
80
- }
81
- /**
82
- * Names the value flags a caller gave with no value.
83
- *
84
- * @param argv - The arguments after the script path.
85
- * @param names - The flags that take a value.
86
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
87
- */
88
- export function readMissingFlags(argv, names) {
89
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
90
- }
91
- /**
92
- * Names the flags a caller gave that the script does not read.
93
- *
94
- * @remarks
95
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
96
- * scan.
52
+ * Parses the arguments in strict mode against `OPTIONS`.
97
53
  *
98
54
  * @param argv - The arguments after the script path.
99
- * @param flags - Every flag the script reads, value flags and switches alike.
100
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
55
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
101
56
  */
102
- export function readUnknownFlags(argv, flags) {
103
- const end = argv.indexOf('--');
104
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
57
+ export function parseArguments(argv) {
58
+ try {
59
+ const { values, positionals } = parseArgs({
60
+ args: [...argv],
61
+ options: OPTIONS,
62
+ strict: true,
63
+ allowPositionals: false,
64
+ });
65
+ return { success: true, value: { values, positionals } };
66
+ }
67
+ catch (error) {
68
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
69
+ }
105
70
  }
106
71
  /**
107
72
  * Normalizes a host path to forward slashes.
@@ -110,7 +75,7 @@ export function readUnknownFlags(argv, flags) {
110
75
  * @returns The same path with every backslash replaced by a slash.
111
76
  */
112
77
  export function normalizeSlashes(path) {
113
- return path.split('\\').join('/');
78
+ return path.replaceAll('\\', '/');
114
79
  }
115
80
  /**
116
81
  * Lists every regular file beneath a directory, skipping the directories the script never reads.
@@ -208,16 +173,16 @@ export function removeEmptyDirectories(directory) {
208
173
  }
209
174
  }
210
175
  /**
211
- * Reads the `--older-than` threshold in minutes.
176
+ * Parses the `--older-than` threshold in minutes.
212
177
  *
213
- * @param argv - The arguments after the script path.
178
+ * @param text - The value after `--older-than`, or undefined when the flag is absent.
214
179
  * @returns The default threshold when the flag is absent, the number when it is finite and above 0,
215
180
  * and undefined otherwise.
216
181
  */
217
- export function readThreshold(argv) {
218
- if (!argv.includes('--older-than'))
182
+ export function parseThreshold(text) {
183
+ if (text === undefined)
219
184
  return DEFAULT_THRESHOLD;
220
- const value = Number(readOption(argv, '--older-than'));
185
+ const value = Number(text);
221
186
  return Number.isFinite(value) && value > 0 ? value : undefined;
222
187
  }
223
188
  /**
@@ -423,13 +388,13 @@ export function listUnitFiles(unit) {
423
388
  /**
424
389
  * Lists or deletes one unit's launch files.
425
390
  *
426
- * @param unit - The unit name, or undefined when the call gave none.
391
+ * @param unit - The unit name.
427
392
  * @param remove - If true, deletes the untracked files; if false, lists them.
428
393
  * @returns The exit code: 0 on success, 2 when a deletion is refused, 64 on usage.
429
394
  */
430
395
  export function runUnit(unit, remove) {
431
- if (unit === undefined || !/^[A-Za-z0-9._][A-Za-z0-9._-]*$/u.test(unit)) {
432
- console.error('usage: sweep.ts --unit UNIT [--delete]');
396
+ if (!/^[A-Za-z0-9._][A-Za-z0-9._-]*$/u.test(unit)) {
397
+ console.error(`sweep: --unit takes letters, digits, dots, underscores, and hyphens, not opening with a hyphen, not ${JSON.stringify(unit)}; ${USAGE}`);
433
398
  return 64;
434
399
  }
435
400
  const files = listUnitFiles(unit);
@@ -458,36 +423,34 @@ export function runUnit(unit, remove) {
458
423
  * @returns The exit code: 0 on success, 2 when a deletion is refused, 64 on usage.
459
424
  */
460
425
  export function main(argv) {
461
- const unknown = readUnknownFlags(argv, FLAGS);
462
- if (unknown.length > 0) {
463
- console.error(`sweep: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
464
- return 64;
465
- }
466
- const missing = readMissingFlags(argv, VALUE_FLAGS);
467
- if (missing.length > 0) {
468
- console.error(`sweep: ${missing.join(', ')} given with no value`);
426
+ const parsed = parseArguments(argv);
427
+ if (!parsed.success) {
428
+ console.error(`sweep: ${parsed.error}; ${USAGE}`);
469
429
  return 64;
470
430
  }
431
+ const { values } = parsed.value;
471
432
  if (!existsSync('.git')) {
472
433
  console.error('sweep: run from the repository root');
473
434
  return 64;
474
435
  }
475
- const modes = ['--report', '--tmp', '--unit'].filter((flag) => argv.includes(flag));
436
+ const unit = typeof values.unit === 'string' ? values.unit : undefined;
437
+ const modes = [values.report, values.tmp, unit].filter((value) => value !== undefined);
476
438
  if (modes.length > 1) {
477
- console.error('usage: sweep.ts names one mode: --report | --tmp [--older-than MINUTES] | --unit UNIT [--delete]');
439
+ console.error(`sweep: --report, --tmp, and --unit are three modes; name one; ${USAGE}`);
478
440
  return 64;
479
441
  }
480
- if (argv.includes('--tmp')) {
481
- const threshold = readThreshold(argv);
442
+ if (values.tmp === true) {
443
+ const text = typeof values['older-than'] === 'string' ? values['older-than'] : undefined;
444
+ const threshold = parseThreshold(text);
482
445
  if (threshold === undefined) {
483
- console.error('usage: sweep.ts --tmp [--older-than MINUTES]; MINUTES is a positive number');
446
+ console.error(`sweep: --older-than takes a number of minutes above 0, not ${JSON.stringify(text)}; ${USAGE}`);
484
447
  return 64;
485
448
  }
486
449
  return runSweep(threshold);
487
450
  }
488
- if (argv.includes('--unit'))
489
- return runUnit(readOption(argv, '--unit'), argv.includes('--delete'));
490
- if (argv.length === 0 || argv.includes('--report'))
451
+ if (unit !== undefined)
452
+ return runUnit(unit, values.delete === true);
453
+ if (argv.length === 0 || values.report === true)
491
454
  return runReport();
492
455
  console.error(USAGE);
493
456
  return 64;