@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
@@ -14,11 +14,13 @@
14
14
  // `DIR/plan.json` and every omitted step to `DIR/omitted.txt`, prints each omitted step on its own
15
15
  // line, and runs the sibling `chain.ts` with stdio inherited and `npm_config_prefer_online=true`
16
16
  // merged into its environment. `--dry-run` prints the steps and omissions, writes nothing, and runs
17
- // nothing; `--json`, which `--dry-run` must accompany, prints them as one JSON value.
17
+ // nothing; `--json`, which `--dry-run` must accompany, prints them as one JSON value. The script
18
+ // reads its flags with `parseArgs` in strict mode.
18
19
  // Exit with the chain's code: 0 when every step exited 0, the failing step's code when one did not,
19
20
  // 2 when a step or the chain cannot start. Exit 2 when the journal cannot be written, 64 on usage,
20
21
  // and 65 when no complete step list can be derived or an `--omit` names no derived step. A step
21
22
  // exiting 65 reads alike with that refusal.
23
+ import type { ParseArgsOptionsConfig } from 'node:util'
22
24
  import { spawnSync } from 'node:child_process'
23
25
  import {
24
26
  closeSync,
@@ -32,17 +34,54 @@ import {
32
34
  } from 'node:fs'
33
35
  import { dirname, extname, join } from 'node:path'
34
36
  import { fileURLToPath } from 'node:url'
35
-
36
- /** Lists the flags that take a value. */
37
- export const VALUE_FLAGS: readonly string[] = ['--journal', '--omit']
38
-
39
- /** Lists every flag the script reads, value flags and switches alike. */
40
- export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--no-ci', '--dry-run', '--json']
37
+ import { parseArgs } from 'node:util'
41
38
 
42
39
  /** Holds the usage line printed when a call names no journal or gives a malformed flag. */
43
40
  export const USAGE =
44
41
  'usage: steps.ts --journal DIR [--omit NAME=REASON ...] [--no-ci] [--dry-run] [--json]'
45
42
 
43
+ /** Declares every flag the script reads, for `parseArgs`. */
44
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
45
+ journal: Object.freeze({ type: 'string' }),
46
+ omit: Object.freeze({ type: 'string', multiple: true }),
47
+ 'no-ci': Object.freeze({ type: 'boolean' }),
48
+ 'dry-run': Object.freeze({ type: 'boolean' }),
49
+ json: 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
+ }
84
+
46
85
  /** Matches a step name `chain.ts` accepts. */
47
86
  export const STEP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u
48
87
 
@@ -152,75 +191,6 @@ export function parseJson(text: string): unknown {
152
191
  }
153
192
  }
154
193
 
155
- /**
156
- * Reads the value after each occurrence of a flag.
157
- *
158
- * @param argv - The arguments after the script path.
159
- * @param name - The flag, such as `--omit`.
160
- * @returns One member per occurrence, undefined where the flag is last or a value opens with `--`.
161
- */
162
- export function readValues(
163
- argv: readonly string[],
164
- name: string,
165
- ): ReadonlyArray<string | undefined> {
166
- return argv.flatMap((argument, index) => {
167
- if (argument !== name) return []
168
- const value = argv[index + 1]
169
- return [value === undefined || value.startsWith('--') ? undefined : value]
170
- })
171
- }
172
-
173
- /**
174
- * Names the value flags a caller gave with no value.
175
- *
176
- * @param argv - The arguments after the script path.
177
- * @param names - The flags that take a value.
178
- * @returns Each named flag with an occurrence that is last or followed by another flag.
179
- */
180
- export function readMissingFlags(
181
- argv: readonly string[],
182
- names: readonly string[],
183
- ): readonly string[] {
184
- return names.filter((name) => readValues(argv, name).includes(undefined))
185
- }
186
-
187
- /**
188
- * Names the flags a caller gave that the script does not read.
189
- *
190
- * @remarks
191
- * A `--flag=value` argument is unknown, because the script reads no such form. The script passes no
192
- * command on, so a bare `--` is unknown too, and the scan stops there and reads nothing after it.
193
- *
194
- * @param argv - The arguments after the script path.
195
- * @param flags - Every flag the script reads, value flags and switches alike.
196
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
197
- */
198
- export function readUnknownFlags(
199
- argv: readonly string[],
200
- flags: readonly string[],
201
- ): readonly string[] {
202
- const end = argv.indexOf('--')
203
- return (end === -1 ? argv : argv.slice(0, end + 1)).filter(
204
- (argument) => argument.startsWith('--') && !flags.includes(argument),
205
- )
206
- }
207
-
208
- /**
209
- * Names the arguments no flag reads as its value.
210
- *
211
- * @param argv - The arguments after the script path.
212
- * @param names - The flags that take a value.
213
- * @returns Each argument that neither opens with `--` nor follows a value flag.
214
- */
215
- export function readStrayArguments(
216
- argv: readonly string[],
217
- names: readonly string[],
218
- ): readonly string[] {
219
- return argv.filter(
220
- (argument, index) => !argument.startsWith('--') && !names.includes(argv[index - 1] ?? ''),
221
- )
222
- }
223
-
224
194
  /**
225
195
  * Parses one `--omit` value.
226
196
  *
@@ -236,28 +206,22 @@ export function parseOmission(text: string): Omission | undefined {
236
206
  }
237
207
 
238
208
  /**
239
- * Reads the first usage problem in the arguments.
209
+ * Reads the first usage problem in the flag values `parseArgs` read.
240
210
  *
241
- * @param argv - The arguments after the script path.
242
- * @returns The refusal to print, or undefined when the arguments are well formed.
211
+ * @param values - The flag values.
212
+ * @returns The refusal to print, or undefined when the values are well formed.
243
213
  */
244
- export function readUsageProblem(argv: readonly string[]): string | undefined {
245
- const unknown = readUnknownFlags(argv, FLAGS)
246
- if (unknown.length > 0) return `${unknown.join(', ')} is not a flag this script reads; ${USAGE}`
247
- const missing = readMissingFlags(argv, VALUE_FLAGS)
248
- if (missing.length > 0) return `${missing.join(', ')} given with no value; ${USAGE}`
249
- const strays = readStrayArguments(argv, VALUE_FLAGS)
250
- if (strays.length > 0) return `${strays.map(quote).join(', ')} is not read by a flag; ${USAGE}`
251
- if (readValues(argv, '--journal').length === 0) return USAGE
252
- if (argv.includes('--json') && !argv.includes('--dry-run')) {
214
+ export function readUsageProblem(values: Arguments['values']): string | undefined {
215
+ if (typeof values.journal !== 'string') return USAGE
216
+ if (values.json === true && values['dry-run'] !== true) {
253
217
  return `--json reads only with --dry-run, because the chain prints to standard output; ${USAGE}`
254
218
  }
255
- const values = readValues(argv, '--omit').flatMap((value) => (value === undefined ? [] : [value]))
256
- const malformed = values.filter((value) => parseOmission(value) === undefined)
219
+ const omits = collectStrings(values.omit)
220
+ const malformed = omits.filter((value) => parseOmission(value) === undefined)
257
221
  if (malformed.length > 0) {
258
- return `--omit takes NAME=REASON with a non-empty one-line reason, given ${malformed.map(quote).join(', ')}`
222
+ return `--omit takes NAME=REASON with a non-empty one-line reason, not ${malformed.map(quote).join(', ')}; ${USAGE}`
259
223
  }
260
- const names = values.map((value) => value.slice(0, value.indexOf('=')))
224
+ const names = omits.map((value) => value.slice(0, value.indexOf('=')))
261
225
  const repeated = [...new Set(names.filter((name, index) => names.indexOf(name) !== index))]
262
226
  if (repeated.length > 0) {
263
227
  return `--omit names a step more than once: ${repeated.map(quote).join(', ')}`
@@ -268,16 +232,28 @@ export function readUsageProblem(argv: readonly string[]): string | undefined {
268
232
  /**
269
233
  * Reads the given `--omit` values as omissions.
270
234
  *
271
- * @param argv - Arguments that `readUsageProblem` found no problem in.
235
+ * @param values - Flag values that `readUsageProblem` found no problem in.
272
236
  * @returns One omission per occurrence, in argument order.
273
237
  */
274
- export function readOmissions(argv: readonly string[]): readonly Omission[] {
275
- return readValues(argv, '--omit').flatMap((value) => {
276
- const omission = value === undefined ? undefined : parseOmission(value)
238
+ export function readOmissions(values: Arguments['values']): readonly Omission[] {
239
+ return collectStrings(values.omit).flatMap((value) => {
240
+ const omission = parseOmission(value)
277
241
  return omission === undefined ? [] : [omission]
278
242
  })
279
243
  }
280
244
 
245
+ /**
246
+ * Collects the strings a repeatable flag's value holds.
247
+ *
248
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
249
+ * @returns Each string in order, empty when the flag never appears.
250
+ */
251
+ export function collectStrings(value: unknown): readonly string[] {
252
+ return Array.isArray(value)
253
+ ? value.filter((member): member is string => typeof member === 'string')
254
+ : []
255
+ }
256
+
281
257
  /**
282
258
  * Parses one segment of `prepublishOnly`.
283
259
  *
@@ -609,14 +585,20 @@ export function runChain(journal: string): number {
609
585
  * names no derived step.
610
586
  */
611
587
  export function main(argv: readonly string[]): number {
612
- const usage = readUsageProblem(argv)
613
- const [journal] = readValues(argv, '--journal')
588
+ const parsed = parseArguments(argv)
589
+ if (!parsed.success) {
590
+ console.error(`steps: ${parsed.error}; ${USAGE}`)
591
+ return 64
592
+ }
593
+ const { values } = parsed.value
594
+ const usage = readUsageProblem(values)
595
+ const journal = typeof values.journal === 'string' ? values.journal : undefined
614
596
  if (usage !== undefined || journal === undefined) {
615
597
  console.error(`steps: ${usage ?? USAGE}`)
616
598
  return 64
617
599
  }
618
600
  const derivation = readDerivation(process.cwd())
619
- const omissions = readOmissions(argv)
601
+ const omissions = readOmissions(values)
620
602
  const problems = [
621
603
  ...derivation.problems,
622
604
  ...(derivation.problems.length > 0 ? [] : readOmissionProblems(omissions, derivation.segments)),
@@ -626,17 +608,17 @@ export function main(argv: readonly string[]): number {
626
608
  return 65
627
609
  }
628
610
  const omitted = [
629
- ...readCiOmissions(argv.includes('--no-ci'), () => readHolders('node_modules')),
611
+ ...readCiOmissions(values['no-ci'] === true, () => readHolders('node_modules')),
630
612
  ...omissions,
631
613
  ]
632
614
  const selected = selectSegments(derivation.segments, omitted)
633
615
  const plan = buildPlan(selected, resolveNpm())
634
- if (argv.includes('--json')) {
616
+ if (values.json === true) {
635
617
  console.log(JSON.stringify({ steps: plan, omitted }))
636
618
  return 0
637
619
  }
638
620
  const lines = omitted.map((omission) => formatOmission(omission))
639
- if (argv.includes('--dry-run')) {
621
+ if (values['dry-run'] === true) {
640
622
  console.log([...selected.map((segment) => formatSegment(segment)), ...lines].join('\n'))
641
623
  return 0
642
624
  }
@@ -35,7 +35,9 @@
35
35
  // --pin and --restore write a receipt create-only to tmp/units/swap-<consumer>-<time>.json under the
36
36
  // working directory. Every mode prints text lines, or one JSON line with --json.
37
37
  // Exit 0 on success, 1 when a command or a proof failed, 3 when --status reports drift, 64 on usage,
38
- // including a flag the mode does not read and the `--flag=value` form.
38
+ // including a flag the mode does not read. The script reads its flags with `parseArgs` in strict
39
+ // mode.
40
+ import type { ParseArgsOptionsConfig } from 'node:util'
39
41
  import type { SpawnSyncReturns } from 'node:child_process'
40
42
  import { spawnSync } from 'node:child_process'
41
43
  import { createHash } from 'node:crypto'
@@ -52,6 +54,7 @@ import {
52
54
  writeFileSync,
53
55
  } from 'node:fs'
54
56
  import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
57
+ import { isDeepStrictEqual, parseArgs } from 'node:util'
55
58
 
56
59
  /** Describes a package manifest as a read-only record. */
57
60
  export type Manifest = Readonly<Record<string, unknown>>
@@ -211,18 +214,11 @@ export const EXIT_USAGE = 64
211
214
  export const FORMAT_PROBLEM =
212
215
  'package.json is not tab-indented JSON with a trailing newline; the script would reformat it'
213
216
 
214
- /** Lists the value flags each mode reads. */
215
- export const VALUE_FLAGS: Readonly<Record<SwapMode, readonly string[]>> = {
216
- pin: ['--consumer', '--source', '--override'],
217
- restore: ['--consumer', '--package'],
218
- status: ['--consumer'],
219
- }
220
-
221
- /** Lists the switch flags each mode reads. */
222
- export const SWITCH_FLAGS: Readonly<Record<SwapMode, readonly string[]>> = {
223
- pin: ['--pin', '--no-build', '--dry-run', '--json'],
224
- restore: ['--restore', '--json'],
225
- status: ['--status', '--json'],
217
+ /** Lists the flags each mode reads, by the name `parseArgs` reads them under. */
218
+ export const MODE_OPTIONS: Readonly<Record<SwapMode, readonly string[]>> = {
219
+ pin: ['pin', 'consumer', 'source', 'override', 'no-build', 'dry-run', 'json'],
220
+ restore: ['restore', 'consumer', 'package', 'json'],
221
+ status: ['status', 'consumer', 'json'],
226
222
  }
227
223
 
228
224
  /**
@@ -316,6 +312,53 @@ export const USAGE = [
316
312
  ' swap.ts --status --consumer DIR [--json]',
317
313
  ].join('\n')
318
314
 
315
+ /** Declares every flag the script reads, for `parseArgs`. */
316
+ export const OPTIONS: ParseArgsOptionsConfig = Object.freeze({
317
+ pin: Object.freeze({ type: 'boolean' }),
318
+ restore: Object.freeze({ type: 'boolean' }),
319
+ status: Object.freeze({ type: 'boolean' }),
320
+ consumer: Object.freeze({ type: 'string' }),
321
+ source: Object.freeze({ type: 'string', multiple: true }),
322
+ override: Object.freeze({ type: 'string', multiple: true }),
323
+ package: Object.freeze({ type: 'string', multiple: true }),
324
+ 'no-build': Object.freeze({ type: 'boolean' }),
325
+ 'dry-run': Object.freeze({ type: 'boolean' }),
326
+ json: Object.freeze({ type: 'boolean' }),
327
+ })
328
+
329
+ /** Describes the arguments `parseArgs` read: each flag's value by name, and the positionals. */
330
+ export interface Arguments {
331
+ readonly values: Readonly<
332
+ Record<string, string | boolean | ReadonlyArray<string | boolean> | undefined>
333
+ >
334
+ readonly positionals: readonly string[]
335
+ }
336
+
337
+ /** Describes how `parseArgs` read the arguments: the arguments, or the message it refused them with. */
338
+ export type ArgumentsResult =
339
+ | { readonly success: true; readonly value: Arguments }
340
+ | { readonly success: false; readonly error: string }
341
+
342
+ /**
343
+ * Parses the arguments in strict mode against `OPTIONS`.
344
+ *
345
+ * @param argv - The arguments after the script path.
346
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
347
+ */
348
+ export function parseArguments(argv: readonly string[]): ArgumentsResult {
349
+ try {
350
+ const { values, positionals } = parseArgs({
351
+ args: [...argv],
352
+ options: OPTIONS,
353
+ strict: true,
354
+ allowPositionals: false,
355
+ })
356
+ return { success: true, value: { values, positionals } }
357
+ } catch (error) {
358
+ return { success: false, error: error instanceof Error ? error.message : String(error) }
359
+ }
360
+ }
361
+
319
362
  /** Names the manifest fields that hold specs, including nested overrides. */
320
363
  export const SPEC_FIELDS: readonly string[] = Object.freeze([
321
364
  'dependencies',
@@ -406,53 +449,7 @@ export function removeTree(path: string): void {
406
449
  * @returns The same path with every backslash replaced by a slash.
407
450
  */
408
451
  export function normalizeSlashes(path: string): string {
409
- return path.split('\\').join('/')
410
- }
411
-
412
- /**
413
- * Reads the value that follows a flag.
414
- *
415
- * @remarks
416
- * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
417
- * with `--` is a missing value, and the `--flag=value` form is not read.
418
- *
419
- * @param argv - The arguments after the script path.
420
- * @param name - The flag, such as `--consumer`.
421
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
422
- * another flag.
423
- */
424
- export function readOption(argv: readonly string[], name: string): string | undefined {
425
- const index = argv.indexOf(name)
426
- const value = index === -1 ? undefined : argv[index + 1]
427
- return value === undefined || value.startsWith('--') ? undefined : value
428
- }
429
-
430
- /**
431
- * Names the value flags a caller gave with no value.
432
- *
433
- * @param argv - The arguments after the script path.
434
- * @param names - The flags that take a value.
435
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
436
- */
437
- export function readMissingFlags(
438
- argv: readonly string[],
439
- names: readonly string[],
440
- ): readonly string[] {
441
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined)
442
- }
443
-
444
- /**
445
- * Reads every value that follows a repeatable flag.
446
- *
447
- * @param argv - The arguments after the script path.
448
- * @param name - The flag, such as `--source`.
449
- * @returns The values in order, empty when the flag never appears.
450
- */
451
- export function readOptions(argv: readonly string[], name: string): readonly string[] {
452
- return argv.flatMap((argument, index) => {
453
- const value = argv[index + 1]
454
- return argument === name && value !== undefined && !value.startsWith('--') ? [value] : []
455
- })
452
+ return path.replaceAll('\\', '/')
456
453
  }
457
454
 
458
455
  /**
@@ -1243,26 +1240,15 @@ export function matchesRange(text: string, range: string): boolean {
1243
1240
  * Parses the command line.
1244
1241
  *
1245
1242
  * @param argv - The arguments after the script path.
1246
- * @returns The command, or the reason the line is refused: no mode or two modes, a flag the mode does
1247
- * not read (the `--flag=value` form included), a flag with no value, no consumer, or a pin with no
1248
- * source.
1243
+ * @returns The command, or the reason the line is refused: the `parseArgs` refusal, no mode or two
1244
+ * modes, a flag the mode does not read, no consumer, or a pin with no source.
1249
1245
  */
1250
1246
  export function parseCommand(argv: readonly string[]): CommandResult {
1251
- const known = MODES.flatMap((candidate) => [
1252
- `--${candidate}`,
1253
- ...VALUE_FLAGS[candidate],
1254
- ...SWITCH_FLAGS[candidate],
1255
- ])
1256
- // A bare `--` ends the arguments the script reads; nothing after it is a flag of this script.
1257
- const end = argv.indexOf('--')
1258
- const foreign = (end === -1 ? argv : argv.slice(0, end)).filter(
1259
- (token) => token.startsWith('--') && !known.includes(token),
1260
- )
1261
- if (foreign.length > 0) {
1262
- return { ok: false, message: `${foreign.join(', ')} is not a flag this script reads` }
1263
- }
1264
- const given = MODES.filter((candidate) => argv.includes(`--${candidate}`))
1265
- const mode = MODES.find((candidate) => argv.includes(`--${candidate}`))
1247
+ const parsed = parseArguments(argv)
1248
+ if (!parsed.success) return { ok: false, message: parsed.error }
1249
+ const { values } = parsed.value
1250
+ const given = MODES.filter((candidate) => values[candidate] === true)
1251
+ const [mode] = given
1266
1252
  if (mode === undefined)
1267
1253
  return { ok: false, message: 'Give one of --pin, --restore, and --status' }
1268
1254
  if (given.length > 1) {
@@ -1271,23 +1257,18 @@ export function parseCommand(argv: readonly string[]): CommandResult {
1271
1257
  message: `Give one mode, not ${given.map((candidate) => `--${candidate}`).join(' and ')}`,
1272
1258
  }
1273
1259
  }
1274
- const values = VALUE_FLAGS[mode]
1275
- const switches = SWITCH_FLAGS[mode]
1276
- const unknown = argv.filter((token, index) =>
1277
- token.startsWith('--')
1278
- ? !values.includes(token) && !switches.includes(token)
1279
- : !values.includes(argv[index - 1] ?? ''),
1260
+ const unknown = Object.keys(values).filter(
1261
+ (name) => values[name] !== undefined && !MODE_OPTIONS[mode].includes(name),
1280
1262
  )
1281
1263
  if (unknown.length > 0) {
1282
- return { ok: false, message: `--${mode} does not read ${unknown.join(', ')}` }
1283
- }
1284
- const missing = readMissingFlags(argv, values)
1285
- if (missing.length > 0) {
1286
- return { ok: false, message: `${missing.join(', ')} given with no value` }
1264
+ return {
1265
+ ok: false,
1266
+ message: `--${mode} does not read ${unknown.map((name) => `--${name}`).join(', ')}`,
1267
+ }
1287
1268
  }
1288
- const consumer = readOption(argv, '--consumer')
1269
+ const consumer = typeof values.consumer === 'string' ? values.consumer : undefined
1289
1270
  if (consumer === undefined) return { ok: false, message: '--consumer DIR is required' }
1290
- const sources = readOptions(argv, '--source')
1271
+ const sources = collectStrings(values.source)
1291
1272
  if (mode === 'pin' && sources.length === 0) {
1292
1273
  return { ok: false, message: '--pin takes at least one --source DIR' }
1293
1274
  }
@@ -1297,15 +1278,27 @@ export function parseCommand(argv: readonly string[]): CommandResult {
1297
1278
  mode,
1298
1279
  consumer: resolve(consumer),
1299
1280
  sources: sources.map((source) => resolve(source)),
1300
- overrides: readOptions(argv, '--override'),
1301
- packages: readOptions(argv, '--package'),
1302
- build: !argv.includes('--no-build'),
1303
- dry: argv.includes('--dry-run'),
1304
- json: argv.includes('--json'),
1281
+ overrides: collectStrings(values.override),
1282
+ packages: collectStrings(values.package),
1283
+ build: values['no-build'] !== true,
1284
+ dry: values['dry-run'] === true,
1285
+ json: values.json === true,
1305
1286
  },
1306
1287
  }
1307
1288
  }
1308
1289
 
1290
+ /**
1291
+ * Collects the strings a repeatable flag's value holds.
1292
+ *
1293
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
1294
+ * @returns Each string in order, empty when the flag never appears.
1295
+ */
1296
+ export function collectStrings(value: unknown): readonly string[] {
1297
+ return Array.isArray(value)
1298
+ ? value.filter((member): member is string => typeof member === 'string')
1299
+ : []
1300
+ }
1301
+
1309
1302
  /**
1310
1303
  * Computes the SHA-256 digest of bytes.
1311
1304
  *
@@ -1624,7 +1617,7 @@ export function proveInstalled(
1624
1617
  ]
1625
1618
  : []),
1626
1619
  ...(installed?.link === true ? [`${name} is installed as a link`] : []),
1627
- ...(real && JSON.stringify(present) !== JSON.stringify(tarball.files)
1620
+ ...(real && !isDeepStrictEqual(present, tarball.files)
1628
1621
  ? [`${name} file set differs from its pack list`]
1629
1622
  : []),
1630
1623
  ...(differing.length > 0 ? [`${name} differs from its source in ${differing.join(', ')}`] : []),
@@ -1780,7 +1773,7 @@ export function printReport(
1780
1773
  * @returns The usage exit code.
1781
1774
  */
1782
1775
  export function reportUsage(message: string): number {
1783
- process.stderr.write(`swap: ${message}\n${USAGE}\n`)
1776
+ process.stderr.write(`swap: ${message}; ${USAGE}\n`)
1784
1777
  return EXIT_USAGE
1785
1778
  }
1786
1779
 
@@ -2370,7 +2363,7 @@ export function executeStatus(command: Command): number {
2370
2363
  const archive = join(tarballs, entry.tarball)
2371
2364
  const git = existsSync(entry.source) ? inspectCheckout(entry.source) : undefined
2372
2365
  const held = entry.field === undefined ? current[name] : declaration?.spec
2373
- const link = existsSync(top) && lstatSync(top).isSymbolicLink()
2366
+ const link = lstatSync(top, { throwIfNoEntry: false })?.isSymbolicLink() === true
2374
2367
  const installed = existsSync(top)
2375
2368
  ? {
2376
2369
  version: readString(loadJSONRecord(join(top, 'package.json')), 'version'),