@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
@@ -3,13 +3,15 @@
3
3
  // node .agents/skills/orkestrel-dispatch/scripts/cite.ts PATH [--root DIR] [--json]
4
4
  // A citation resolves when its path exists under the root (a path relative to the root resolves
5
5
  // first, and a backslash reads as a slash) and the line is within the file, where a trailing line
6
- // break ends the last line. A citation naming a bare filename that no root-relative
7
- // file matches resolves when exactly one file under the root carries that name, outside
8
- // node_modules, dist, tmp, .git, .orkestrel, and .idea. The summary lists every citation that does
9
- // not resolve, with the reason. The script refuses a flag it does not read, the `--flag=value` form
10
- // included. Exit 0 when all resolve, 3 when any does not, 64 on usage.
6
+ // break ends the last line. A citation naming a bare filename that no root-relative file matches
7
+ // resolves when exactly one file under the root carries that name, outside node_modules, dist, tmp,
8
+ // .git, .orkestrel, and .idea. The summary lists every citation that does not resolve, with the
9
+ // reason. The script reads its flags with `parseArgs` in strict mode. Exit 0 when all resolve, 3
10
+ // when any does not, 64 on usage.
11
+ import type { ParseArgsOptionsConfig } from 'node:util'
11
12
  import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
12
13
  import { basename, join, relative, resolve } from 'node:path'
14
+ import { parseArgs } from 'node:util'
13
15
 
14
16
  /** Matches one `file:line` or `file:line-line` citation in a text. */
15
17
  export const CITATION =
@@ -25,15 +27,48 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
25
27
  '.idea',
26
28
  ])
27
29
 
28
- /** Lists the flags that take a value. */
29
- export const VALUE_FLAGS: readonly string[] = ['--root']
30
-
31
- /** Lists every flag the script reads, value flags and switches alike. */
32
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--json']
33
-
34
30
  /** Holds the usage line printed when a call names no report. */
35
31
  export const USAGE = 'usage: cite.ts PATH [--root DIR] [--json]'
36
32
 
33
+ /** Declares every flag the script reads, for `parseArgs`. */
34
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
35
+ root: Object.freeze({ type: 'string' }),
36
+ json: Object.freeze({ type: 'boolean' }),
37
+ })
38
+
39
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
40
+ export interface Arguments {
41
+ readonly values: Readonly<
42
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
43
+ >
44
+ readonly positionals: readonly string[]
45
+ }
46
+
47
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
48
+ export type ArgumentsResult =
49
+ | { readonly success: true; readonly value: Arguments }
50
+ | { readonly success: false; readonly error: string }
51
+
52
+ /**
53
+ * Parses the arguments in strict mode against `OPTIONS`.
54
+ *
55
+ * @param argv - The arguments after the script path.
56
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
57
+ */
58
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
59
+ try {
60
+ const { values, positionals } = parseArgs({
61
+ args: [...argv],
62
+ options: OPTIONS,
63
+ strict: true,
64
+ allowPositionals: true,
65
+ })
66
+ return { success: true, value: { values, positionals } }
67
+ } catch (error) {
68
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
69
+ }
70
+ }
71
+
37
72
  /** Describes one citation that did not resolve and why. */
38
73
  export interface Unresolved {
39
74
  readonly citation: string
@@ -60,59 +95,6 @@ export interface WalkedFile {
60
95
  readonly modified: number
61
96
  }
62
97
 
63
- /**
64
- * Reads the value that follows a flag.
65
- *
66
- * @remarks
67
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
68
- * and the `--flag=value` form is not read.
69
- *
70
- * @param argv - The arguments after the script path.
71
- * @param name - The flag, such as `--root`.
72
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
73
- * another flag.
74
- */
75
- export function readOption(argv: readonly string[], name: string): string | undefined {
76
- const index = argv.indexOf(name)
77
- const value = index === -1 ? undefined : argv[index + 1]
78
- return value === undefined || value.startsWith('--') ? undefined : value
79
- }
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(
89
- argv: readonly string[],
90
- names: readonly string[],
91
- ): readonly string[] {
92
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
93
- }
94
-
95
- /**
96
- * Names the flags a caller gave that the script does not read.
97
- *
98
- * @remarks
99
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
100
- * scan.
101
- *
102
- * @param argv - The arguments after the script path.
103
- * @param flags - Every flag the script reads, value flags and switches alike.
104
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
105
- */
106
- export function readUnknownFlags(
107
- argv: readonly string[],
108
- flags: readonly string[],
109
- ): readonly string[] {
110
- const end = argv.indexOf('--')
111
- return (end === -1 ? argv : argv.slice(0, end)).filter(
112
- (argument) => argument.startsWith('--') && !flags.includes(argument),
113
- )
114
- }
115
-
116
98
  /**
117
99
  * Normalizes a host path to forward slashes.
118
100
  *
@@ -120,7 +102,7 @@ export function readUnknownFlags(
120
102
  * @returns The same path with every backslash replaced by a slash.
121
103
  */
122
104
  export function normalizeSlashes(path: string): string {
123
- return path.split('\\').join('/')
105
+ return path.replaceAll('\\', '/')
124
106
  }
125
107
 
126
108
  /**
@@ -214,6 +196,7 @@ export function countLines(path: string): number {
214
196
  */
215
197
  export function resolveDirect(root: string, file: string): string | undefined {
216
198
  const direct = resolve(root, normalizeSlashes(file))
199
+ // The path comes from report text, and existsSync answers false where a stat would throw.
217
200
  return existsSync(direct) && statSync(direct).isFile() ? direct : undefined
218
201
  }
219
202
 
@@ -280,21 +263,15 @@ export function judgeLines(
280
263
  * @returns The exit code: 0 when every citation resolves, 3 when one does not, 64 on usage.
281
264
  */
282
265
  export function main(argv: readonly string[]): number {
283
- const unknown = readUnknownFlags(argv, FLAGS)
284
- if (unknown.length > 0) {
285
- console.error(`cite: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`)
286
- return 64
287
- }
288
- const missing = readMissingFlags(argv, VALUE_FLAGS)
289
- if (missing.length > 0) {
290
- console.error(`cite: ${missing.join(', ')} given with no value`)
266
+ const parsed = parseArguments(argv)
267
+ if (!parsed.success) {
268
+ console.error(`cite: ${parsed.error}; ${USAGE}`)
291
269
  return 64
292
270
  }
293
- const root = readOption(argv, '--root') ?? process.cwd()
294
- const path = argv.find(
295
- (argument, position) => !argument.startsWith('--') && argv[position - 1] !== '--root',
296
- )
297
- if (path === undefined || !existsSync(path)) {
271
+ const { values, positionals } = parsed.value
272
+ const root = typeof values.root === 'string' ? values.root : process.cwd()
273
+ const [path, ...extra] = positionals
274
+ if (path === undefined || extra.length > 0 || !existsSync(path)) {
298
275
  console.error(USAGE)
299
276
  return 64
300
277
  }
@@ -320,7 +297,7 @@ export function main(argv: readonly string[]): number {
320
297
  : judgeLines(resolved.path, entry.line, entry.end, counts)
321
298
  return reason === undefined ? [] : [{ citation: entry.citation, reason }]
322
299
  })
323
- if (argv.includes('--json')) {
300
+ if (values.json === true) {
324
301
  console.log(JSON.stringify({ path, root, citations, unresolved }))
325
302
  } else {
326
303
  console.log(`cite: ${citations} citation(s) in ${path}, ${unresolved.length} unresolved`)
@@ -12,11 +12,12 @@
12
12
  // removed before the spawn, so neither appears when the command cannot start. The summary line
13
13
  // prints last, after the command exits, and the errors file ends with `exit=<code>`. At the cap,
14
14
  // Windows kills the process tree; any other host kills the command alone, not its descendants.
15
- // The launcher's own flags are read before `--` alone, and it refuses a flag it does not read there,
16
- // the `--flag=value` form included. Exit: the command's code; 124 when capped;
15
+ // The launcher reads its own flags before the first bare `--` with `parseArgs` in strict mode, and
16
+ // passes every argument after it to the command. Exit: the command's code; 124 when capped;
17
17
  // 127 when the command could not start (the errors file names why); 64 on usage, including a
18
18
  // journal and errors path that are the same file and a cap that is not a number of seconds from 0
19
19
  // to 2147483.
20
+ import type { ParseArgsOptionsConfig } from 'node:util'
20
21
  import type { ChildProcess } from 'node:child_process'
21
22
  import { spawn, spawnSync } from 'node:child_process'
22
23
  import {
@@ -29,6 +30,7 @@ import {
29
30
  writeFileSync,
30
31
  } from 'node:fs'
31
32
  import { dirname } from 'node:path'
33
+ import { parseArgs } from 'node:util'
32
34
 
33
35
  /**
34
36
  * Holds the longest cap in whole seconds.
@@ -39,70 +41,56 @@ import { dirname } from 'node:path'
39
41
  */
40
42
  export const MAX_CAP_SECONDS = 2_147_483
41
43
 
42
- /** Lists the flags that take a value. */
43
- export const VALUE_FLAGS: readonly string[] = ['--journal', '--errors', '--cap']
44
+ /** Holds the usage line printed when a call names no journal, no errors file, or no command. */
45
+ export const USAGE =
46
+ 'usage: launch.ts --journal PATH --errors PATH [--cap SECONDS] [--status] -- COMMAND [ARGS...]'
44
47
 
45
- /** Lists every flag the launcher reads before the separator, value flags and switches alike. */
46
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--status']
48
+ /** Declares every flag the script reads, for `parseArgs`. */
49
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
50
+ journal: Object.freeze({ type: 'string' }),
51
+ errors: Object.freeze({ type: 'string' }),
52
+ cap: Object.freeze({ type: 'string' }),
53
+ status: Object.freeze({ type: 'boolean' }),
54
+ })
47
55
 
48
- /** Describes how the command ended: its code, its signal, or the reason it could not start. */
49
- export interface Exit {
50
- readonly code: number | null
51
- readonly signal: NodeJS.Signals | null
52
- readonly error: string | undefined
56
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
57
+ export interface Arguments {
58
+ readonly values: Readonly<
59
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
60
+ >
61
+ readonly positionals: readonly string[]
53
62
  }
54
63
 
55
- /**
56
- * Reads the value that follows a flag.
57
- *
58
- * @remarks
59
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
60
- * and the `--flag=value` form is not read.
61
- *
62
- * @param argv - The arguments after the script path.
63
- * @param name - The flag, such as `--journal`.
64
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
65
- * another flag.
66
- */
67
- export function readOption(argv: readonly string[], name: string): string | undefined {
68
- const index = argv.indexOf(name)
69
- const value = index === -1 ? undefined : argv[index + 1]
70
- return value === undefined || value.startsWith('--') ? undefined : value
71
- }
64
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
65
+ export type ArgumentsResult =
66
+ | { readonly success: true; readonly value: Arguments }
67
+ | { readonly success: false; readonly error: string }
72
68
 
73
69
  /**
74
- * Names the value flags a caller gave with no value.
70
+ * Parses the arguments in strict mode against `OPTIONS`.
75
71
  *
76
72
  * @param argv - The arguments after the script path.
77
- * @param names - The flags that take a value.
78
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
73
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
79
74
  */
80
- export function readMissingFlags(
81
- argv: readonly string[],
82
- names: readonly string[],
83
- ): readonly string[] {
84
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
75
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
76
+ try {
77
+ const { values, positionals } = parseArgs({
78
+ args: [...argv],
79
+ options: OPTIONS,
80
+ strict: true,
81
+ allowPositionals: false,
82
+ })
83
+ return { success: true, value: { values, positionals } }
84
+ } catch (error) {
85
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
86
+ }
85
87
  }
86
88
 
87
- /**
88
- * Names the flags a caller gave that the script does not read.
89
- *
90
- * @remarks
91
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
92
- * scan, so the command after it keeps every argument.
93
- *
94
- * @param argv - The arguments after the script path.
95
- * @param flags - Every flag the script reads, value flags and switches alike.
96
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
97
- */
98
- export function readUnknownFlags(
99
- argv: readonly string[],
100
- flags: readonly string[],
101
- ): readonly string[] {
102
- const end = argv.indexOf('--')
103
- return (end === -1 ? argv : argv.slice(0, end)).filter(
104
- (argument) => argument.startsWith('--') && !flags.includes(argument),
105
- )
89
+ /** Describes how the command ended: its code, its signal, or the reason it could not start. */
90
+ export interface Exit {
91
+ readonly code: number | null
92
+ readonly signal: NodeJS.Signals | null
93
+ readonly error: string | undefined
106
94
  }
107
95
 
108
96
  /**
@@ -213,39 +201,38 @@ export function waitForExit(child: ChildProcess): Promise<Exit> {
213
201
  */
214
202
  export async function main(argv: readonly string[]): Promise<number> {
215
203
  const separator = argv.indexOf('--')
216
- // The launcher's own flags end at the separator; everything after it belongs to the command.
217
- const own = separator === -1 ? argv : argv.slice(0, separator)
218
- const unknown = readUnknownFlags(argv, FLAGS)
219
- if (unknown.length > 0) {
220
- console.error(
221
- `launch: ${unknown.join(', ')} is not a flag this launcher reads before --; flags: ${FLAGS.join(' ')}`,
222
- )
204
+ const parsed = parseArguments(separator === -1 ? argv : argv.slice(0, separator))
205
+ if (!parsed.success) {
206
+ console.error(`launch: ${parsed.error}; ${USAGE}`)
223
207
  return 64
224
208
  }
225
- const journal = readOption(own, '--journal')
226
- const errors = readOption(own, '--errors')
227
- const cap =
228
- readMissingFlags(own, ['--cap']).length > 0
229
- ? Number.NaN
230
- : Number(readOption(own, '--cap') ?? '0')
209
+ const { values } = parsed.value
210
+ const journal = typeof values.journal === 'string' ? values.journal : undefined
211
+ const errors = typeof values.errors === 'string' ? values.errors : undefined
212
+ const text = typeof values.cap === 'string' ? values.cap : '0'
213
+ const cap = Number(text)
231
214
  const [command, ...args] = separator === -1 ? [] : argv.slice(separator + 1)
232
215
  if (
233
216
  separator === -1 ||
234
217
  journal === undefined ||
235
218
  errors === undefined ||
236
- journal === errors ||
237
- !Number.isFinite(cap) ||
238
- cap < 0 ||
239
- cap > MAX_CAP_SECONDS ||
240
219
  command === undefined ||
241
220
  command === ''
242
221
  ) {
222
+ console.error(USAGE)
223
+ return 64
224
+ }
225
+ if (journal === errors) {
226
+ console.error(`launch: --journal and --errors name the same file; ${USAGE}`)
227
+ return 64
228
+ }
229
+ if (text === '' || !Number.isFinite(cap) || cap < 0 || cap > MAX_CAP_SECONDS) {
243
230
  console.error(
244
- `usage: launch.ts --journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]; the journal and the errors file differ, and the cap is a number of seconds from 0 to ${String(MAX_CAP_SECONDS)} (0 for none)`,
231
+ `launch: --cap takes a number of seconds from 0 to ${String(MAX_CAP_SECONDS)} (0 for none), not ${JSON.stringify(text)}; ${USAGE}`,
245
232
  )
246
233
  return 64
247
234
  }
248
- const status = own.includes('--status')
235
+ const status = values.status === true
249
236
  const capMilliseconds = cap > 0 ? computeCapMilliseconds(cap) : undefined
250
237
  mkdirSync(dirname(journal), { recursive: true })
251
238
  mkdirSync(dirname(errors), { recursive: true })
@@ -8,12 +8,15 @@
8
8
  // seconds) ends, then kills the login by its pid. Each status read gets the time left to the cap
9
9
  // and is ended when it passes. --cap is a number of seconds above 0 and at most 2147483, checked
10
10
  // before anything starts.
11
- // --claude reads `claude auth status` and prints it. Name one bench per run; the script refuses a
12
- // flag it does not read, the `--flag=value` form included. The JSON summary carries `live`; exit 0
11
+ // --claude reads `claude auth status` and prints it. Name one bench per run; the script reads its
12
+ // flags with `parseArgs` in strict mode. The JSON summary carries `live`; exit 0
13
13
  // when the bench is logged in, 3 when it is not, 64 on usage.
14
+ import type { ParseArgsOptionsConfig } from 'node:util'
14
15
  import { spawn, spawnSync } from 'node:child_process'
15
16
  import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync } from 'node:fs'
17
+ import { setTimeout } from 'node:timers/promises'
16
18
  import { dirname } from 'node:path'
19
+ import { parseArgs } from 'node:util'
17
20
 
18
21
  /** Names the file that journals the device-auth login output. */
19
22
  export const JOURNAL = 'tmp/codex/login.log'
@@ -36,11 +39,48 @@ export const URL_PATTERN = /https?:\/\/[^\s"'<>]+/u
36
39
  /** Matches the one-time code the login prints, such as `ABCD-12345`. */
37
40
  export const CODE_PATTERN = /\b([A-Z0-9]{4,5}-[A-Z0-9]{4,5})\b/u
38
41
 
39
- /** Lists the flags that take a value. */
40
- export const VALUE_FLAGS: readonly string[] = ['--cap']
42
+ /** Holds the usage line printed when a call names no bench or two. */
43
+ export const USAGE = 'usage: login.ts --codex [--cap SECONDS] | --claude'
41
44
 
42
- /** Lists every flag the script reads, value flags and switches alike. */
43
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--codex', '--claude']
45
+ /** Declares every flag the script reads, for `parseArgs`. */
46
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
47
+ cap: Object.freeze({ type: 'string' }),
48
+ codex: Object.freeze({ type: 'boolean' }),
49
+ claude: Object.freeze({ type: 'boolean' }),
50
+ })
51
+
52
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
53
+ export interface Arguments {
54
+ readonly values: Readonly<
55
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
56
+ >
57
+ readonly positionals: readonly string[]
58
+ }
59
+
60
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
61
+ export type ArgumentsResult =
62
+ | { readonly success: true; readonly value: Arguments }
63
+ | { readonly success: false; readonly error: string }
64
+
65
+ /**
66
+ * Parses the arguments in strict mode against `OPTIONS`.
67
+ *
68
+ * @param argv - The arguments after the script path.
69
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
70
+ */
71
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
72
+ try {
73
+ const { values, positionals } = parseArgs({
74
+ args: [...argv],
75
+ options: OPTIONS,
76
+ strict: true,
77
+ allowPositionals: false,
78
+ })
79
+ return { success: true, value: { values, positionals } }
80
+ } catch (error) {
81
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
82
+ }
83
+ }
44
84
 
45
85
  /** Describes whether a bench's status command started, whether it reports a login, and its text. */
46
86
  export interface Status {
@@ -87,59 +127,6 @@ export const CODEX_FLOW: Flow = {
87
127
  /** Holds the real Claude status command. */
88
128
  export const CLAUDE_STATUS: Invocation = { command: 'claude', args: ['auth', 'status'] }
89
129
 
90
- /**
91
- * Reads the value that follows a flag.
92
- *
93
- * @remarks
94
- * The first occurrence of a flag wins, a following value that opens with `--` is a missing value,
95
- * and the `--flag=value` form is not read.
96
- *
97
- * @param argv - The arguments after the script path.
98
- * @param name - The flag, such as `--cap`.
99
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
100
- * another flag.
101
- */
102
- export function readOption(argv: readonly string[], name: string): string | undefined {
103
- const index = argv.indexOf(name)
104
- const value = index === -1 ? undefined : argv[index + 1]
105
- return value === undefined || value.startsWith('--') ? undefined : value
106
- }
107
-
108
- /**
109
- * Names the value flags a caller gave with no value.
110
- *
111
- * @param argv - The arguments after the script path.
112
- * @param names - The flags that take a value.
113
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
114
- */
115
- export function readMissingFlags(
116
- argv: readonly string[],
117
- names: readonly string[],
118
- ): readonly string[] {
119
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
120
- }
121
-
122
- /**
123
- * Names the flags a caller gave that the script does not read.
124
- *
125
- * @remarks
126
- * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
127
- * scan.
128
- *
129
- * @param argv - The arguments after the script path.
130
- * @param flags - Every flag the script reads, value flags and switches alike.
131
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
132
- */
133
- export function readUnknownFlags(
134
- argv: readonly string[],
135
- flags: readonly string[],
136
- ): readonly string[] {
137
- const end = argv.indexOf('--')
138
- return (end === -1 ? argv : argv.slice(0, end)).filter(
139
- (argument) => argument.startsWith('--') && !flags.includes(argument),
140
- )
141
- }
142
-
143
130
  /**
144
131
  * Parses the `--cap` value into a number of seconds.
145
132
  *
@@ -205,18 +192,6 @@ export function terminateTree(pid: number): void {
205
192
  } catch {}
206
193
  }
207
194
 
208
- /**
209
- * Waits a number of milliseconds.
210
- *
211
- * @param ms - The milliseconds to wait.
212
- * @returns A promise that resolves when the time has passed.
213
- */
214
- export function waitFor(ms: number): Promise<void> {
215
- return new Promise((resolve) => {
216
- setTimeout(resolve, ms)
217
- })
218
- }
219
-
220
195
  /**
221
196
  * Polls the login journal and the login status until the bench is logged in or the cap ends.
222
197
  *
@@ -238,7 +213,7 @@ export async function pollLogin(
238
213
  ): Promise<Poll> {
239
214
  const deadline = started + capSeconds * 1000
240
215
  if (Date.now() >= deadline) return { url, code, live: false }
241
- await waitFor(flow.intervalMs)
216
+ await setTimeout(flow.intervalMs)
242
217
  const text = existsSync(flow.journal) ? readFileSync(flow.journal, 'utf8') : ''
243
218
  const nextUrl = url ?? text.match(URL_PATTERN)?.[0]
244
219
  if (url === undefined && nextUrl !== undefined) announce(`login: open ${nextUrl}`)
@@ -317,42 +292,37 @@ export function loginClaude(status: Invocation): Outcome {
317
292
  * @returns The exit code: 0 when logged in, 3 when not, 64 on usage.
318
293
  */
319
294
  export async function main(argv: readonly string[]): Promise<number> {
320
- const unknown = readUnknownFlags(argv, FLAGS)
321
- if (unknown.length > 0) {
322
- console.error(
323
- `login: ${unknown.join(', ')} is not a flag this script reads; usage: login.ts --codex [--cap SECONDS] | --claude`,
324
- )
325
- return 64
326
- }
327
- const missing = readMissingFlags(argv, VALUE_FLAGS)
328
- if (missing.length > 0) {
329
- console.error(`login: ${missing.join(', ')} given with no value`)
295
+ const parsed = parseArguments(argv)
296
+ if (!parsed.success) {
297
+ console.error(`login: ${parsed.error}; ${USAGE}`)
330
298
  return 64
331
299
  }
332
- if (argv.includes('--codex') && argv.includes('--claude')) {
333
- console.error('usage: login.ts names one bench: --codex [--cap SECONDS] | --claude')
300
+ const { values } = parsed.value
301
+ if (values.codex === true && values.claude === true) {
302
+ console.error(`login: --codex and --claude are two modes; name one bench; ${USAGE}`)
334
303
  return 64
335
304
  }
336
- const cap = parseCap(readOption(argv, '--cap'))
305
+ const text = typeof values.cap === 'string' ? values.cap : undefined
306
+ const cap = parseCap(text)
337
307
  if (cap === undefined) {
338
308
  console.error(
339
- `login: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}`,
309
+ `login: --cap takes a number of seconds above 0 and at most ${String(MAX_CAP_SECONDS)}, not ${JSON.stringify(text)}; ${USAGE}`,
340
310
  )
341
311
  return 64
342
312
  }
343
- if (argv.includes('--codex')) {
313
+ if (values.codex === true) {
344
314
  const outcome = await loginCodex(cap, CODEX_FLOW, (line) => {
345
315
  console.error(line)
346
316
  })
347
317
  console.log(JSON.stringify(outcome.report))
348
318
  return outcome.exit
349
319
  }
350
- if (argv.includes('--claude')) {
320
+ if (values.claude === true) {
351
321
  const outcome = loginClaude(CLAUDE_STATUS)
352
322
  console.log(JSON.stringify(outcome.report))
353
323
  return outcome.exit
354
324
  }
355
- console.error('usage: login.ts --codex [--cap SECONDS] | --claude')
325
+ console.error(USAGE)
356
326
  return 64
357
327
  }
358
328