@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
@@ -21,22 +21,59 @@
21
21
  // absent when that median is 0). It rules nothing: it carries no bar and no verdict.
22
22
  // Print text by default or one JSON line with `--json`; `--out` writes `.json` or `.txt`
23
23
  // independently. Launch the script through `launch.ts` from the dispatch skill for a cap. The script
24
- // refuses a flag it does not read, the `--flag=value` form included, and every positional argument.
24
+ // reads its flags with `parseArgs` in strict mode and refuses every positional argument.
25
25
  // Exit 0 when every sample read, 2 when a sample failed or `--out` could not be written, 64 on usage.
26
+ import type { ParseArgsOptionsConfig } from 'node:util'
26
27
  import { spawnSync } from 'node:child_process'
27
28
  import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
28
29
  import { dirname, extname, resolve } from 'node:path'
29
-
30
- /** Lists the flags that take a value. */
31
- export const VALUE_FLAGS: readonly string[] = ['--plan', '--rounds', '--out']
32
-
33
- /** Lists every flag the script reads, value flags and switches alike. */
34
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--json']
30
+ import { parseArgs } from 'node:util'
35
31
 
36
32
  /** Holds the usage line printed when a call names no plan or no round count. */
37
33
  export const USAGE =
38
34
  'usage: interleave.ts --plan FILE.json --rounds N [--json] [--out FILE.json|FILE.txt]'
39
35
 
36
+ /** Declares every flag the script reads, for `parseArgs`. */
37
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
38
+ plan: Object.freeze({ type: 'string' }),
39
+ rounds: Object.freeze({ type: 'string' }),
40
+ out: Object.freeze({ type: 'string' }),
41
+ json: Object.freeze({ type: 'boolean' }),
42
+ })
43
+
44
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
45
+ export interface Arguments {
46
+ readonly values: Readonly<
47
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
48
+ >
49
+ readonly positionals: readonly string[]
50
+ }
51
+
52
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
53
+ export type ArgumentsResult =
54
+ | { readonly success: true; readonly value: Arguments }
55
+ | { readonly success: false; readonly error: string }
56
+
57
+ /**
58
+ * Parses the arguments in strict mode against `OPTIONS`.
59
+ *
60
+ * @param argv - The arguments after the script path.
61
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
62
+ */
63
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
64
+ try {
65
+ const { values, positionals } = parseArgs({
66
+ args: [...argv],
67
+ options: OPTIONS,
68
+ strict: true,
69
+ allowPositionals: false,
70
+ })
71
+ return { success: true, value: { values, positionals } }
72
+ } catch (error) {
73
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
74
+ }
75
+ }
76
+
40
77
  /** Caps the characters of an untrusted text a diagnostic echoes. */
41
78
  export const QUOTE_LIMIT = 200
42
79
 
@@ -114,78 +151,6 @@ export interface Report {
114
151
  readonly relative: number | undefined
115
152
  }
116
153
 
117
- /**
118
- * Reads the value that follows a flag.
119
- *
120
- * @remarks
121
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
122
- * and the `--flag=value` form is not read.
123
- *
124
- * @param argv - The arguments after the script path.
125
- * @param name - The flag, such as `--plan`.
126
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
127
- * another flag.
128
- */
129
- export function readOption(argv: readonly string[], name: string): string | undefined {
130
- const index = argv.indexOf(name)
131
- const value = index === -1 ? undefined : argv[index + 1]
132
- return value === undefined || value.startsWith('--') ? undefined : value
133
- }
134
-
135
- /**
136
- * Names the value flags a caller gave with no value.
137
- *
138
- * @param argv - The arguments after the script path.
139
- * @param names - The flags that take a value.
140
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
141
- */
142
- export function readMissingFlags(
143
- argv: readonly string[],
144
- names: readonly string[],
145
- ): readonly string[] {
146
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
147
- }
148
-
149
- /**
150
- * Names the flags a caller gave that the script does not read.
151
- *
152
- * @remarks
153
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
154
- * scan.
155
- *
156
- * @param argv - The arguments after the script path.
157
- * @param flags - Every flag the script reads, value flags and switches alike.
158
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
159
- */
160
- export function readUnknownFlags(
161
- argv: readonly string[],
162
- flags: readonly string[],
163
- ): readonly string[] {
164
- const end = argv.indexOf('--')
165
- return (end === -1 ? argv : argv.slice(0, end)).filter(
166
- (argument) => argument.startsWith('--') && !flags.includes(argument),
167
- )
168
- }
169
-
170
- /**
171
- * Reads the arguments the script has no place for: a positional, or a bare `--`, which would open a
172
- * command this script does not pass on.
173
- *
174
- * @param argv - The arguments after the script path.
175
- * @param valueFlags - The flags that take a value.
176
- * @returns Each such argument in order.
177
- */
178
- export function readStrayArguments(
179
- argv: readonly string[],
180
- valueFlags: readonly string[],
181
- ): readonly string[] {
182
- return argv.filter(
183
- (argument, index) =>
184
- (argument === '--' || !argument.startsWith('--')) &&
185
- !valueFlags.includes(argv[index - 1] ?? ''),
186
- )
187
- }
188
-
189
154
  /**
190
155
  * Checks whether a value is a non-null, non-array object.
191
156
  *
@@ -464,7 +429,7 @@ export function runSchedule(sides: Sides, schedule: readonly Slot[]): Run {
464
429
  */
465
430
  export function computeMedian(values: readonly number[]): number {
466
431
  if (values.length === 0) throw new Error('interleave: a median needs at least one number')
467
- const sorted = [...values].sort((left, right) => left - right)
432
+ const sorted = values.toSorted((left, right) => left - right)
468
433
  const middle = sorted.slice(
469
434
  Math.floor((sorted.length - 1) / 2),
470
435
  Math.floor(sorted.length / 2) + 1,
@@ -598,36 +563,27 @@ export function writeOutput(path: string, text: string): string | undefined {
598
563
  * written, 64 on usage.
599
564
  */
600
565
  export function main(argv: readonly string[]): number {
601
- const unknown = readUnknownFlags(argv, FLAGS)
602
- if (unknown.length > 0) {
603
- console.error(`interleave: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
604
- return 64
605
- }
606
- const missing = readMissingFlags(argv, VALUE_FLAGS)
607
- if (missing.length > 0) {
608
- console.error(`interleave: ${missing.join(', ')} given with no value`)
609
- return 64
610
- }
611
- const stray = readStrayArguments(argv, VALUE_FLAGS)
612
- if (stray.length > 0) {
613
- console.error(`interleave: ${stray.map(quote).join(', ')} is not an argument; ${USAGE}`)
566
+ const parsed = parseArguments(argv)
567
+ if (!parsed.success) {
568
+ console.error(`interleave: ${parsed.error}; ${USAGE}`)
614
569
  return 64
615
570
  }
616
- const path = readOption(argv, '--plan')
617
- const count = readOption(argv, '--rounds')
618
- const out = readOption(argv, '--out')
571
+ const { values } = parsed.value
572
+ const path = typeof values.plan === 'string' ? values.plan : undefined
573
+ const count = typeof values.rounds === 'string' ? values.rounds : undefined
574
+ const out = typeof values.out === 'string' ? values.out : undefined
619
575
  if (path === undefined || count === undefined) {
620
576
  console.error(USAGE)
621
577
  return 64
622
578
  }
623
579
  if (out !== undefined && !['.json', '.txt'].includes(extname(out))) {
624
- console.error(`interleave: --out takes a .json or .txt file, got ${quote(out)}`)
580
+ console.error(`interleave: --out takes a .json or .txt file, not ${quote(out)}; ${USAGE}`)
625
581
  return 64
626
582
  }
627
583
  const rounds = parseRounds(count)
628
584
  if (rounds === undefined) {
629
585
  console.error(
630
- `interleave: --rounds takes an even whole number of at least 2, got ${quote(count)}`,
586
+ `interleave: --rounds takes an even whole number of at least 2, not ${quote(count)}; ${USAGE}`,
631
587
  )
632
588
  return 64
633
589
  }
@@ -650,7 +606,7 @@ export function main(argv: readonly string[]): number {
650
606
  const report = computeReport(run.readings)
651
607
  const json = JSON.stringify(report)
652
608
  const rendered = renderReport(report)
653
- console.log(argv.includes('--json') ? json : rendered)
609
+ console.log(values.json === true ? json : rendered)
654
610
  const refusal =
655
611
  out === undefined ? undefined : writeOutput(out, extname(out) === '.json' ? json : rendered)
656
612
  if (refusal !== undefined) {
@@ -14,23 +14,58 @@
14
14
  // id and the plugin's own scope for a built-in plugin such as `typescript-eslint`); any other
15
15
  // diagnostic, a parse error included, is not a hit and refuses the measurement, because a file the
16
16
  // linter could not read has no count. A linter that exits other than 0 or 1, or exits 1 with no
17
- // diagnostic, refuses it too. The script refuses a flag it does not read, the `--flag=value` form
18
- // included, and names an unknown flag before a flag given with no value.
17
+ // diagnostic, refuses it too. The script reads its flags with `parseArgs` in strict mode, and
18
+ // refuses a PATH that opens with `-`, which the linter would read as a flag.
19
19
  // Exit 0 when the rule has no hit, 3 when it has, 2 when the linter cannot run or reports another
20
20
  // diagnostic, 64 on usage.
21
+ import type { ParseArgsOptionsConfig } from 'node:util'
21
22
  import { spawnSync } from 'node:child_process'
22
23
  import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
23
24
  import { isAbsolute, join, resolve } from 'node:path'
24
-
25
- /** Lists the flags that take a value. */
26
- export const VALUE_FLAGS: readonly string[] = ['--rule', '--options']
27
-
28
- /** Lists every flag the script reads, value flags and switches alike. */
29
- export const FLAGS: readonly string[] = VALUE_FLAGS
25
+ import { parseArgs } from 'node:util'
30
26
 
31
27
  /** Holds the usage line printed when a call names no rule or no path. */
32
28
  export const USAGE = 'usage: measure.ts --rule ID [--options JSON] PATH...'
33
29
 
30
+ /** Declares every flag the script reads, for `parseArgs`. */
31
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
32
+ rule: Object.freeze({ type: 'string' }),
33
+ options: Object.freeze({ type: 'string' }),
34
+ })
35
+
36
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
37
+ export interface Arguments {
38
+ readonly values: Readonly<
39
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
40
+ >
41
+ readonly positionals: readonly string[]
42
+ }
43
+
44
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
45
+ export type ArgumentsResult =
46
+ | { readonly success: true; readonly value: Arguments }
47
+ | { readonly success: false; readonly error: string }
48
+
49
+ /**
50
+ * Parses the arguments in strict mode against `OPTIONS`.
51
+ *
52
+ * @param argv - The arguments after the script path.
53
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
54
+ */
55
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
56
+ try {
57
+ const { values, positionals } = parseArgs({
58
+ args: [...argv],
59
+ options: OPTIONS,
60
+ strict: true,
61
+ allowPositionals: true,
62
+ })
63
+ return { success: true, value: { values, positionals } }
64
+ } catch (error) {
65
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
66
+ }
67
+ }
68
+
34
69
  /** Holds the directory, under the working directory, that keeps the variant configs. */
35
70
  export const PROBE_ROOT = 'tmp/probes/lint'
36
71
 
@@ -51,75 +86,6 @@ export interface Hits {
51
86
  readonly foreign: readonly string[]
52
87
  }
53
88
 
54
- /**
55
- * Reads the value that follows a flag.
56
- *
57
- * @remarks
58
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
59
- * and the `--flag=value` form is not read.
60
- *
61
- * @param argv - The arguments after the script path.
62
- * @param name - The flag, such as `--rule`.
63
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
64
- * another flag.
65
- */
66
- export function readOption(argv: readonly string[], name: string): string | undefined {
67
- const index = argv.indexOf(name)
68
- const value = index === -1 ? undefined : argv[index + 1]
69
- return value === undefined || value.startsWith('--') ? undefined : value
70
- }
71
-
72
- /**
73
- * Names the value flags a caller gave with no value.
74
- *
75
- * @param argv - The arguments after the script path.
76
- * @param names - The flags that take a value.
77
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
78
- */
79
- export function readMissingFlags(
80
- argv: readonly string[],
81
- names: readonly string[],
82
- ): readonly string[] {
83
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
84
- }
85
-
86
- /**
87
- * Names the flags a caller gave that the script does not read.
88
- *
89
- * @remarks
90
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
91
- * scan.
92
- *
93
- * @param argv - The arguments after the script path.
94
- * @param flags - Every flag the script reads, value flags and switches alike.
95
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
96
- */
97
- export function readUnknownFlags(
98
- argv: readonly string[],
99
- flags: readonly string[],
100
- ): readonly string[] {
101
- const end = argv.indexOf('--')
102
- return (end === -1 ? argv : argv.slice(0, end)).filter(
103
- (argument) => argument.startsWith('--') && !flags.includes(argument),
104
- )
105
- }
106
-
107
- /**
108
- * Reads the arguments that are neither a flag nor the value of a value flag.
109
- *
110
- * @param argv - The arguments after the script path.
111
- * @param valueFlags - The flags that take a value.
112
- * @returns The positional arguments in order.
113
- */
114
- export function readPositionals(
115
- argv: readonly string[],
116
- valueFlags: readonly string[],
117
- ): readonly string[] {
118
- return argv.filter(
119
- (argument, index) => !argument.startsWith('--') && !valueFlags.includes(argv[index - 1] ?? ''),
120
- )
121
- }
122
-
123
89
  /**
124
90
  * Checks whether a value is a non-null, non-array object.
125
91
  *
@@ -137,7 +103,7 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
137
103
  * @returns The same path with every backslash replaced by a slash.
138
104
  */
139
105
  export function normalizeSlashes(path: string): string {
140
- return path.split('\\').join('/')
106
+ return path.replaceAll('\\', '/')
141
107
  }
142
108
 
143
109
  /**
@@ -351,25 +317,28 @@ export function formatHits(rule: string, hits: Hits): string {
351
317
  * 64 on usage.
352
318
  */
353
319
  export function main(argv: readonly string[]): number {
354
- const unknown = readUnknownFlags(argv, FLAGS)
355
- if (unknown.length > 0) {
356
- console.error(`measure: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
320
+ const parsed = parseArguments(argv)
321
+ if (!parsed.success) {
322
+ console.error(`measure: ${parsed.error}; ${USAGE}`)
357
323
  return 64
358
324
  }
359
- const missing = readMissingFlags(argv, VALUE_FLAGS)
360
- if (missing.length > 0) {
361
- console.error(`measure: ${missing.join(', ')} given with no value`)
362
- return 64
363
- }
364
- const rule = readOption(argv, '--rule')
365
- const paths = readPositionals(argv, VALUE_FLAGS)
325
+ const { values, positionals: paths } = parsed.value
326
+ const rule = typeof values.rule === 'string' ? values.rule : undefined
366
327
  if (rule === undefined || paths.length === 0) {
367
328
  console.error(USAGE)
368
329
  return 64
369
330
  }
370
- const options = readRuleOptions(readOption(argv, '--options'))
331
+ const dashed = paths.filter((path) => path.startsWith('-'))
332
+ if (dashed.length > 0) {
333
+ console.error(
334
+ `measure: PATH takes a path that does not open with "-", which the linter reads as a flag, not ${dashed.map(quote).join(', ')}; ${USAGE}`,
335
+ )
336
+ return 64
337
+ }
338
+ const text = typeof values.options === 'string' ? values.options : undefined
339
+ const options = readRuleOptions(text)
371
340
  if (options === undefined) {
372
- console.error(`measure: --options ${quote(readOption(argv, '--options') ?? '')} is not JSON`)
341
+ console.error(`measure: --options takes a JSON value, not ${quote(text ?? '')}; ${USAGE}`)
373
342
  return 64
374
343
  }
375
344
  const root = process.cwd()
@@ -1,9 +1,9 @@
1
1
  // Run from the checkout root:
2
2
  // node .agents/skills/orkestrel-harden/scripts/titles.ts --base REV [--root DIR] [--json] [--out FILE]
3
- // Each value is a separate argument: `--flag=value` and any flag the script does not read exit 64,
4
- // and so does a REV that opens with `-`. The baseline is read from the tree REV names, resolved
5
- // once with `--end-of-options`, with paths relative to --root, so a --root below the repository top
6
- // works.
3
+ // The script reads its flags with `parseArgs` in strict mode, so a flag it does not read exits 64,
4
+ // and so does `--base` followed by a value that opens with `-`. The baseline is read from the tree
5
+ // REV names, resolved once with `--end-of-options`, with paths relative to --root, so a --root below
6
+ // the repository top works.
7
7
  // Compare exact decoded describe/it/test/suite title counts in tests/**/*.test.ts against REV. A
8
8
  // baseline title with a deficit is moved when another tests/**/*.ts string literal spells it, and
9
9
  // missing otherwise. A moved row is a claim to rule, not proof: a literal that only spells the
@@ -25,6 +25,7 @@
25
25
  // Only .test.ts files register titles; a .test.tsx or .test.mts file is invisible to it.
26
26
  // Exit 0 with no missing or moved titles and no lost-dynamic file, 3 with any, 2 on git, filesystem
27
27
  // or token refusal, 64 on usage.
28
+ import type { ParseArgsOptionsConfig } from 'node:util'
28
29
  import { spawnSync } from 'node:child_process'
29
30
  import {
30
31
  existsSync,
@@ -36,13 +37,52 @@ import {
36
37
  writeFileSync,
37
38
  } from 'node:fs'
38
39
  import { dirname, extname, join, relative, resolve } from 'node:path'
39
-
40
- /** Lists the flags this script reads, value flags and switches alike. */
41
- export const FLAGS: readonly string[] = ['--base', '--root', '--json', '--out']
40
+ import { parseArgs } from 'node:util'
42
41
 
43
42
  /** Holds the usage line printed on a usage refusal. */
44
43
  export const USAGE = 'usage: titles.ts --base REV [--root DIR] [--json] [--out FILE.json|FILE.txt]'
45
44
 
45
+ /** Declares every flag the script reads, for `parseArgs`. */
46
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
47
+ base: Object.freeze({ type: 'string' }),
48
+ root: Object.freeze({ type: 'string' }),
49
+ json: Object.freeze({ type: 'boolean' }),
50
+ out: Object.freeze({ type: 'string' }),
51
+ })
52
+
53
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
54
+ export interface Arguments {
55
+ readonly values: Readonly<
56
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
57
+ >
58
+ readonly positionals: readonly string[]
59
+ }
60
+
61
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
62
+ export type ArgumentsResult =
63
+ | { readonly success: true; readonly value: Arguments }
64
+ | { readonly success: false; readonly error: string }
65
+
66
+ /**
67
+ * Parses the arguments in strict mode against `OPTIONS`.
68
+ *
69
+ * @param argv - The arguments after the script path.
70
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
71
+ */
72
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
73
+ try {
74
+ const { values, positionals } = parseArgs({
75
+ args: [...argv],
76
+ options: OPTIONS,
77
+ strict: true,
78
+ allowPositionals: false,
79
+ })
80
+ return { success: true, value: { values, positionals } }
81
+ } catch (error) {
82
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
83
+ }
84
+ }
85
+
46
86
  /** Caps the characters of a name an error message echoes. */
47
87
  export const NAME_LIMIT = 80
48
88
 
@@ -156,60 +196,7 @@ export interface WalkedFile {
156
196
  * @returns The same path with every backslash replaced by a slash.
157
197
  */
158
198
  export function normalizeSlashes(path: string): string {
159
- return path.split('\\').join('/')
160
- }
161
-
162
- /**
163
- * Reads the value that follows a flag.
164
- *
165
- * @remarks
166
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
167
- * and the `--flag=value` form is not read.
168
- *
169
- * @param argv - The arguments after the script path.
170
- * @param name - The flag, such as `--base`.
171
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
172
- * another flag.
173
- */
174
- export function readOption(argv: readonly string[], name: string): string | undefined {
175
- const index = argv.indexOf(name)
176
- const value = index === -1 ? undefined : argv[index + 1]
177
- return value === undefined || value.startsWith('--') ? undefined : value
178
- }
179
-
180
- /**
181
- * Names the value flags a caller gave with no value.
182
- *
183
- * @param argv - The arguments after the script path.
184
- * @param names - The flags that take a value.
185
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
186
- */
187
- export function readMissingFlags(
188
- argv: readonly string[],
189
- names: readonly string[],
190
- ): readonly string[] {
191
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
192
- }
193
-
194
- /**
195
- * Names the flags a caller gave that the script does not read.
196
- *
197
- * @remarks
198
- * Reads the arguments before a bare `--`. A `--flag=value` argument is unknown, because the script
199
- * reads `--flag value` pairs only.
200
- *
201
- * @param argv - The arguments after the script path.
202
- * @param flags - Every flag the script reads, value flags and switches alike.
203
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
204
- */
205
- export function readUnknownFlags(
206
- argv: readonly string[],
207
- flags: readonly string[],
208
- ): readonly string[] {
209
- const end = argv.indexOf('--')
210
- return (end === -1 ? argv : argv.slice(0, end)).filter(
211
- (argument) => argument.startsWith('--') && !flags.includes(argument),
212
- )
199
+ return path.replaceAll('\\', '/')
213
200
  }
214
201
 
215
202
  /**
@@ -884,32 +871,25 @@ export function renderReport(report: Report): string {
884
871
  * failure, 64 usage.
885
872
  */
886
873
  export function main(argv: readonly string[]): number {
887
- const unknown = readUnknownFlags(argv, FLAGS)
888
- if (unknown.length > 0) {
889
- console.error(
890
- `titles: ${unknown.map(describeName).join(', ')} is not a flag this script reads; give each value as its own argument. ${USAGE}`,
891
- )
874
+ const parsed = parseArguments(argv)
875
+ if (!parsed.success) {
876
+ console.error(`titles: ${parsed.error}; ${USAGE}`)
892
877
  return 64
893
878
  }
894
- const missing = readMissingFlags(argv, ['--base', '--root', '--out'])
895
- if (missing.length > 0) {
896
- console.error(`titles: ${missing.join(', ')} given with no value`)
897
- return 64
898
- }
899
- const base = readOption(argv, '--base')
900
- const out = readOption(argv, '--out')
901
- if (base === undefined || (out !== undefined && !['.json', '.txt'].includes(extname(out)))) {
879
+ const { values } = parsed.value
880
+ const base = typeof values.base === 'string' ? values.base : undefined
881
+ const out = typeof values.out === 'string' ? values.out : undefined
882
+ if (base === undefined) {
902
883
  console.error(USAGE)
903
884
  return 64
904
885
  }
905
- if (base.startsWith('-')) {
906
- console.error(
907
- `titles: --base ${describeName(base)} opens with "-"; give a revision name or hash`,
908
- )
886
+ if (out !== undefined && !['.json', '.txt'].includes(extname(out))) {
887
+ console.error(`titles: --out takes a .json or .txt file, not ${describeName(out)}; ${USAGE}`)
909
888
  return 64
910
889
  }
911
890
  try {
912
- const report = readReport(base, resolve(readOption(argv, '--root') ?? process.cwd()))
891
+ const root = typeof values.root === 'string' ? values.root : process.cwd()
892
+ const report = readReport(base, resolve(root))
913
893
  const json = JSON.stringify(report)
914
894
  const text = renderReport(report)
915
895
  if (out !== undefined) {
@@ -917,7 +897,7 @@ export function main(argv: readonly string[]): number {
917
897
  mkdirSync(dirname(target), { recursive: true })
918
898
  writeFileSync(target, `${extname(target) === '.json' ? json : text}\n`)
919
899
  }
920
- console.log(argv.includes('--json') ? json : text)
900
+ console.log(values.json === true ? json : text)
921
901
  return report.missing.length + report.moved.length + report.lostDynamic.length > 0 ? 3 : 0
922
902
  } catch (error) {
923
903
  console.error(`titles: ${error instanceof Error ? error.message : String(error)}`)
@@ -21,18 +21,18 @@ description: >-
21
21
  Run from the checkout root. The script's opening comment owns its behavior.
22
22
 
23
23
  - `scripts/cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]` reads a Vitest `--reporter=json` report and requires every case a `--passed` name matches to have passed and every case a `--failed` name matches to have failed. A name matches a case's full name or its own title exactly; both flags repeat. A name that matches no case is missing, and a failed case no name matches is refused, as is a test file that failed with no failed case (it did not collect, or a hook threw) and a report whose `success` is false while nothing in it failed. It prints one summary line, each difference, and `ok` or `differences=N`. Exit 0 when the report matches, 3 when it does not, 2 when the report cannot be read as a Vitest report, 64 usage.
24
- - `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] -- COMMAND [ARGS...]` runs one process-running command at a time on this host, in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label and `live`, `dead`, or `unread`, and names the holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 70, or 75 reads like the lane's own code. The opening comment owns the limits and the migration stop.
24
+ - `scripts/lane.ts --label NAME --journal PATH --errors PATH --cap SECONDS [--root DIR] [--solo] -- COMMAND [ARGS...]` runs process-running commands on this host in one heavy lane and several light lanes, each in arrival order, across every checkout and shell of one user account: it takes a ticket, waits with no timer, runs the command through `.agents/skills/orkestrel-dispatch/scripts/launch.ts`, kills and reads the command's process tree until no member remains, and releases. A ticket runs light only while `limits.json` exists under the lane root and the command's kind or its own run records read it light; every other ticket runs heavy, one at a time. `--solo` runs heavy with no light run beside it. `scripts/lane.ts --status [--root DIR] [--json]` prints each ticket in arrival order with its label, `live`, `dead`, or `unread`, its lane, and whether it holds, and names the heavy holder and every light holder; it writes nothing, and an absent root reads as an empty queue. The two forms are two modes, and `--status` with a run's flag is refused. Exit: the launcher's code, 1 when a signal ended the launcher, 64 usage, 69 when a light run passed its threshold and the lane ended it, 75 when the lane refused before the command ran, 70 when the command ran and its tree still reads as present or its ticket could not be removed; `--status` exits 0 on a read and 75 when the root cannot be listed. A command that itself exits 64, 69, 70, or 75 reads like the lane's own code. The opening comment owns the lane rules, the limits, and the migration stop.
25
25
 
26
26
  ## Bound the host
27
27
 
28
28
  The host budget counts every lane on the machine: this session's, each peer session's, and the Orchestrator's own commands.
29
29
 
30
- - Set the lane bound in the plan before the first dispatch. Run one process-running command at a time on the host: a test, a build, a browser, or a capture, the Orchestrator's included, each launched through the serializer § Share an execution lane between sessions names; a bench exec, an owned-file format check, lint, type check, or `policy` run that reads only its owned paths' violations runs beside it. The bound counts commands, never a lane's whole life: while another lane's command runs, a writer keeps drafting, changes no file a live command reads, and batches its tests into one command, and a unit that needs no later unit starts at once. Report to the user before a launch that would start a process-running command outside that serializer.
30
+ - Set the lane bound in the plan before the first dispatch. Launch every process-running command on the host, a test, a build, a browser, or a capture, the Orchestrator's included, through the serializer § Share an execution lane between sessions names; it runs one heavy command at a time and, when `limits.json` exists under its root, light commands beside it within that file's slots and budgets. A bench exec, an owned-file format check, lint, type check, or `policy` run that reads only its owned paths' violations runs beside it. Write `limits.json` only from a measurement of heavy commands beside light runs on that host, never by hand. The bound counts commands, never a lane's whole life: while another lane's command runs, a writer keeps drafting, changes no file a live command reads, and batches its tests into one command, and a unit that needs no later unit starts at once. Report to the user before a launch that would start a process-running command outside that serializer.
31
31
  - Count running lanes and owned test processes at each launch.
32
32
  - Limit terminal launches: chain commands that do not gate each other into one launch (as a plan for `.agents/skills/orkestrel-dispatch/scripts/chain.ts`), write long output to a file and read it once, never poll with repeated short calls, never retry a run in a loop, and check once for owned leftovers before a launch.
33
33
  - Find the cause of an interrupted run before relaunching it.
34
34
  - While a lane that runs shell commands is live, count orphaned console and window processes. Brief a lane that needs no shell to run no command. Kill only a recorded process id, and clear orphans only when none of your lanes is live. Never kill another session's or lane's process; ask the user.
35
- - While a timing or live-model measurement runs, start no other test, build, or model work on the host.
35
+ - Run a timing or live-model measurement through the lane with `--solo`, and while it runs, start no other test, build, or model work on the host.
36
36
 
37
37
  ## Keep lanes visible
38
38
 
@@ -117,7 +117,7 @@ expect: <red or green, named cases, required artifact>
117
117
 
118
118
  Apply this section when two sessions on one machine share the tests, checks, builds, and captures the host can run at once.
119
119
 
120
- - Run each process-running command through `scripts/lane.ts`, which orders the commands across sessions, and send no handover message. On its exit 75 or 70, report its standard error line to the user and start no process-running command.
120
+ - Run each process-running command through `scripts/lane.ts`, which orders the commands across sessions and picks each command's lane, and send no handover message. Declare no weight; pass `--solo` only for a timing or live-model measurement. On its exit 75 or 70, report its standard error line to the user and start no process-running command. On its exit 69, rerun the command through the lane; its run record queues it heavy.
121
121
  - Pass the command to `scripts/lane.ts` directly after `--`, never through `bash -c`: a background child under `bash` can survive the forced kill with a parent that names neither the launcher nor the command, and the next arrival then overlaps it.
122
122
  - When a host's sessions run another serializer, keep using it until a scaffold release carries `scripts/lane.ts` and no command runs on the host, then move every caller in one step, because a second queue does not see the first.
123
123
  - While another session holds the lane, edit your own files, read, and queue your commands. Set no clock windows and send no per-command acknowledgments.