@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
@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
2
2
  import { createHash } from 'node:crypto';
3
3
  import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
4
4
  import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
5
+ import { isDeepStrictEqual, parseArgs } from 'node:util';
5
6
  /** Lists the manifest fields a pin rewrites. */
6
7
  export const FIELDS = ['dependencies', 'devDependencies'];
7
8
  /** Lists the modes in the order the script checks them. */
@@ -20,17 +21,11 @@ export const EXIT_DRIFT = 3;
20
21
  export const EXIT_USAGE = 64;
21
22
  /** Holds the refusal for a manifest the script would reformat. */
22
23
  export const FORMAT_PROBLEM = 'package.json is not tab-indented JSON with a trailing newline; the script would reformat it';
23
- /** Lists the value flags each mode reads. */
24
- export const VALUE_FLAGS = {
25
- pin: ['--consumer', '--source', '--override'],
26
- restore: ['--consumer', '--package'],
27
- status: ['--consumer'],
28
- };
29
- /** Lists the switch flags each mode reads. */
30
- export const SWITCH_FLAGS = {
31
- pin: ['--pin', '--no-build', '--dry-run', '--json'],
32
- restore: ['--restore', '--json'],
33
- status: ['--status', '--json'],
24
+ /** Lists the flags each mode reads, by the name `parseArgs` reads them under. */
25
+ export const MODE_OPTIONS = {
26
+ pin: ['pin', 'consumer', 'source', 'override', 'no-build', 'dry-run', 'json'],
27
+ restore: ['restore', 'consumer', 'package', 'json'],
28
+ status: ['status', 'consumer', 'json'],
34
29
  };
35
30
  /**
36
31
  * Lists the `package.json` keys oxfmt sorts ahead of `overrides`.
@@ -118,6 +113,39 @@ export const USAGE = [
118
113
  ' swap.ts --restore --consumer DIR [--package NAME ...] [--json]',
119
114
  ' swap.ts --status --consumer DIR [--json]',
120
115
  ].join('\n');
116
+ /** Declares every flag the script reads, for `parseArgs`. */
117
+ export const OPTIONS = Object.freeze({
118
+ pin: Object.freeze({ type: 'boolean' }),
119
+ restore: Object.freeze({ type: 'boolean' }),
120
+ status: Object.freeze({ type: 'boolean' }),
121
+ consumer: Object.freeze({ type: 'string' }),
122
+ source: Object.freeze({ type: 'string', multiple: true }),
123
+ override: Object.freeze({ type: 'string', multiple: true }),
124
+ package: Object.freeze({ type: 'string', multiple: true }),
125
+ 'no-build': Object.freeze({ type: 'boolean' }),
126
+ 'dry-run': Object.freeze({ type: 'boolean' }),
127
+ json: Object.freeze({ type: 'boolean' }),
128
+ });
129
+ /**
130
+ * Parses the arguments in strict mode against `OPTIONS`.
131
+ *
132
+ * @param argv - The arguments after the script path.
133
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
134
+ */
135
+ export function parseArguments(argv) {
136
+ try {
137
+ const { values, positionals } = parseArgs({
138
+ args: [...argv],
139
+ options: OPTIONS,
140
+ strict: true,
141
+ allowPositionals: false,
142
+ });
143
+ return { success: true, value: { values, positionals } };
144
+ }
145
+ catch (error) {
146
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
147
+ }
148
+ }
121
149
  /** Names the manifest fields that hold specs, including nested overrides. */
122
150
  export const SPEC_FIELDS = Object.freeze([
123
151
  'dependencies',
@@ -192,47 +220,7 @@ export function removeTree(path) {
192
220
  * @returns The same path with every backslash replaced by a slash.
193
221
  */
194
222
  export function normalizeSlashes(path) {
195
- return path.split('\\').join('/');
196
- }
197
- /**
198
- * Reads the value that follows a flag.
199
- *
200
- * @remarks
201
- * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
202
- * with `--` is a missing value, and the `--flag=value` form is not read.
203
- *
204
- * @param argv - The arguments after the script path.
205
- * @param name - The flag, such as `--consumer`.
206
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
207
- * another flag.
208
- */
209
- export function readOption(argv, name) {
210
- const index = argv.indexOf(name);
211
- const value = index === -1 ? undefined : argv[index + 1];
212
- return value === undefined || value.startsWith('--') ? undefined : value;
213
- }
214
- /**
215
- * Names the value flags a caller gave with no value.
216
- *
217
- * @param argv - The arguments after the script path.
218
- * @param names - The flags that take a value.
219
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
220
- */
221
- export function readMissingFlags(argv, names) {
222
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
223
- }
224
- /**
225
- * Reads every value that follows a repeatable flag.
226
- *
227
- * @param argv - The arguments after the script path.
228
- * @param name - The flag, such as `--source`.
229
- * @returns The values in order, empty when the flag never appears.
230
- */
231
- export function readOptions(argv, name) {
232
- return argv.flatMap((argument, index) => {
233
- const value = argv[index + 1];
234
- return argument === name && value !== undefined && !value.startsWith('--') ? [value] : [];
235
- });
223
+ return path.replaceAll('\\', '/');
236
224
  }
237
225
  /**
238
226
  * Parses a whole text as one JSON object.
@@ -900,24 +888,16 @@ export function matchesRange(text, range) {
900
888
  * Parses the command line.
901
889
  *
902
890
  * @param argv - The arguments after the script path.
903
- * @returns The command, or the reason the line is refused: no mode or two modes, a flag the mode does
904
- * not read (the `--flag=value` form included), a flag with no value, no consumer, or a pin with no
905
- * source.
891
+ * @returns The command, or the reason the line is refused: the `parseArgs` refusal, no mode or two
892
+ * modes, a flag the mode does not read, no consumer, or a pin with no source.
906
893
  */
907
894
  export function parseCommand(argv) {
908
- const known = MODES.flatMap((candidate) => [
909
- `--${candidate}`,
910
- ...VALUE_FLAGS[candidate],
911
- ...SWITCH_FLAGS[candidate],
912
- ]);
913
- // A bare `--` ends the arguments the script reads; nothing after it is a flag of this script.
914
- const end = argv.indexOf('--');
915
- const foreign = (end === -1 ? argv : argv.slice(0, end)).filter((token) => token.startsWith('--') && !known.includes(token));
916
- if (foreign.length > 0) {
917
- return { ok: false, message: `${foreign.join(', ')} is not a flag this script reads` };
918
- }
919
- const given = MODES.filter((candidate) => argv.includes(`--${candidate}`));
920
- const mode = MODES.find((candidate) => argv.includes(`--${candidate}`));
895
+ const parsed = parseArguments(argv);
896
+ if (!parsed.success)
897
+ return { ok: false, message: parsed.error };
898
+ const { values } = parsed.value;
899
+ const given = MODES.filter((candidate) => values[candidate] === true);
900
+ const [mode] = given;
921
901
  if (mode === undefined)
922
902
  return { ok: false, message: 'Give one of --pin, --restore, and --status' };
923
903
  if (given.length > 1) {
@@ -926,22 +906,17 @@ export function parseCommand(argv) {
926
906
  message: `Give one mode, not ${given.map((candidate) => `--${candidate}`).join(' and ')}`,
927
907
  };
928
908
  }
929
- const values = VALUE_FLAGS[mode];
930
- const switches = SWITCH_FLAGS[mode];
931
- const unknown = argv.filter((token, index) => token.startsWith('--')
932
- ? !values.includes(token) && !switches.includes(token)
933
- : !values.includes(argv[index - 1] ?? ''));
909
+ const unknown = Object.keys(values).filter((name) => values[name] !== undefined && !MODE_OPTIONS[mode].includes(name));
934
910
  if (unknown.length > 0) {
935
- return { ok: false, message: `--${mode} does not read ${unknown.join(', ')}` };
936
- }
937
- const missing = readMissingFlags(argv, values);
938
- if (missing.length > 0) {
939
- return { ok: false, message: `${missing.join(', ')} given with no value` };
911
+ return {
912
+ ok: false,
913
+ message: `--${mode} does not read ${unknown.map((name) => `--${name}`).join(', ')}`,
914
+ };
940
915
  }
941
- const consumer = readOption(argv, '--consumer');
916
+ const consumer = typeof values.consumer === 'string' ? values.consumer : undefined;
942
917
  if (consumer === undefined)
943
918
  return { ok: false, message: '--consumer DIR is required' };
944
- const sources = readOptions(argv, '--source');
919
+ const sources = collectStrings(values.source);
945
920
  if (mode === 'pin' && sources.length === 0) {
946
921
  return { ok: false, message: '--pin takes at least one --source DIR' };
947
922
  }
@@ -951,14 +926,25 @@ export function parseCommand(argv) {
951
926
  mode,
952
927
  consumer: resolve(consumer),
953
928
  sources: sources.map((source) => resolve(source)),
954
- overrides: readOptions(argv, '--override'),
955
- packages: readOptions(argv, '--package'),
956
- build: !argv.includes('--no-build'),
957
- dry: argv.includes('--dry-run'),
958
- json: argv.includes('--json'),
929
+ overrides: collectStrings(values.override),
930
+ packages: collectStrings(values.package),
931
+ build: values['no-build'] !== true,
932
+ dry: values['dry-run'] === true,
933
+ json: values.json === true,
959
934
  },
960
935
  };
961
936
  }
937
+ /**
938
+ * Collects the strings a repeatable flag's value holds.
939
+ *
940
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
941
+ * @returns Each string in order, empty when the flag never appears.
942
+ */
943
+ export function collectStrings(value) {
944
+ return Array.isArray(value)
945
+ ? value.filter((member) => typeof member === 'string')
946
+ : [];
947
+ }
962
948
  /**
963
949
  * Computes the SHA-256 digest of bytes.
964
950
  *
@@ -1247,7 +1233,7 @@ export function proveInstalled(consumer, tarball, declared, copies) {
1247
1233
  ]
1248
1234
  : []),
1249
1235
  ...(installed?.link === true ? [`${name} is installed as a link`] : []),
1250
- ...(real && JSON.stringify(present) !== JSON.stringify(tarball.files)
1236
+ ...(real && !isDeepStrictEqual(present, tarball.files)
1251
1237
  ? [`${name} file set differs from its pack list`]
1252
1238
  : []),
1253
1239
  ...(differing.length > 0 ? [`${name} differs from its source in ${differing.join(', ')}`] : []),
@@ -1385,7 +1371,7 @@ export function printReport(json, lines, report) {
1385
1371
  * @returns The usage exit code.
1386
1372
  */
1387
1373
  export function reportUsage(message) {
1388
- process.stderr.write(`swap: ${message}\n${USAGE}\n`);
1374
+ process.stderr.write(`swap: ${message}; ${USAGE}\n`);
1389
1375
  return EXIT_USAGE;
1390
1376
  }
1391
1377
  /**
@@ -1904,7 +1890,7 @@ export function executeStatus(command) {
1904
1890
  const archive = join(tarballs, entry.tarball);
1905
1891
  const git = existsSync(entry.source) ? inspectCheckout(entry.source) : undefined;
1906
1892
  const held = entry.field === undefined ? current[name] : declaration?.spec;
1907
- const link = existsSync(top) && lstatSync(top).isSymbolicLink();
1893
+ const link = lstatSync(top, { throwIfNoEntry: false })?.isSymbolicLink() === true;
1908
1894
  const installed = existsSync(top)
1909
1895
  ? {
1910
1896
  version: readString(loadJSONRecord(join(top, 'package.json')), 'version'),
@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
3
3
  import { copyFileSync, existsSync, lstatSync, readFileSync, mkdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
4
4
  import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
+ import { parseArgs } from 'node:util';
6
7
  /** Lists the steps of a visit in the order they run. */
7
8
  export const STEPS = [
8
9
  'pin',
@@ -66,23 +67,43 @@ export const PINS = fileURLToPath(new URL(`./pins${EXTENSION}`, import.meta.url)
66
67
  * group holds a rename's new path, the second its original, and the third any other entry's path.
67
68
  */
68
69
  export const DIRTY_ENTRY = /(?=[RC][^\0]|[^\0][RC])[^\0]{2} ([^\0]*)\0([^\0]*)(?:\0|$)|[^\0]{2} ([^\0]*)(?:\0|$)/gu;
69
- /** Lists every flag the script reads, value flags and switches alike. */
70
- export const FLAGS = [
71
- '--visit',
72
- '--plan',
73
- '--target',
74
- '--offline',
75
- '--regenerate',
76
- '--from',
77
- '--to',
78
- '--prior',
79
- '--dry-run',
80
- '--json',
81
- '--out',
82
- '--catalog',
83
- ];
84
70
  /** Holds the usage line the script prints when no mode was given. */
85
71
  export const USAGE = 'usage: wave.ts --visit [--target DIR] [--offline] [--regenerate] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE] | --plan [--catalog PATH] [--json]';
72
+ /** Declares every flag the script reads, for `parseArgs`. */
73
+ export const OPTIONS = Object.freeze({
74
+ visit: Object.freeze({ type: 'boolean' }),
75
+ plan: Object.freeze({ type: 'boolean' }),
76
+ target: Object.freeze({ type: 'string' }),
77
+ offline: Object.freeze({ type: 'boolean' }),
78
+ regenerate: Object.freeze({ type: 'boolean' }),
79
+ from: Object.freeze({ type: 'string' }),
80
+ to: Object.freeze({ type: 'string' }),
81
+ prior: Object.freeze({ type: 'string' }),
82
+ 'dry-run': Object.freeze({ type: 'boolean' }),
83
+ json: Object.freeze({ type: 'boolean' }),
84
+ out: Object.freeze({ type: 'string' }),
85
+ catalog: Object.freeze({ type: 'string' }),
86
+ });
87
+ /**
88
+ * Parses the arguments in strict mode against `OPTIONS`.
89
+ *
90
+ * @param argv - The arguments after the script path.
91
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
92
+ */
93
+ export function parseArguments(argv) {
94
+ try {
95
+ const { values, positionals } = parseArgs({
96
+ args: [...argv],
97
+ options: OPTIONS,
98
+ strict: true,
99
+ allowPositionals: false,
100
+ });
101
+ return { success: true, value: { values, positionals } };
102
+ }
103
+ catch (error) {
104
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
105
+ }
106
+ }
86
107
  /** Names the manifest fields that hold specs, including nested overrides. */
87
108
  export const SPEC_FIELDS = Object.freeze([
88
109
  'dependencies',
@@ -157,49 +178,7 @@ export function removeTree(path) {
157
178
  * @returns The same path with every backslash replaced by a slash.
158
179
  */
159
180
  export function normalizeSlashes(path) {
160
- return path.split('\\').join('/');
161
- }
162
- /**
163
- * Reads the value that follows a flag.
164
- *
165
- * @remarks
166
- * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
167
- * with `--` is a missing value, 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 `--target`.
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, name) {
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
- * Names the value flags a caller gave with no value.
181
- *
182
- * @param argv - The arguments after the script path.
183
- * @param names - The flags that take a value.
184
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
185
- */
186
- export function readMissingFlags(argv, names) {
187
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
188
- }
189
- /**
190
- * Names the flags a caller gave that the script does not read.
191
- *
192
- * @remarks
193
- * Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
194
- * argument is unknown, because the script reads no such form.
195
- *
196
- * @param argv - The arguments after the script path.
197
- * @param flags - Every flag the script reads, value flags and switches alike.
198
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
199
- */
200
- export function readUnknownFlags(argv, flags) {
201
- const end = argv.indexOf('--');
202
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
181
+ return path.replaceAll('\\', '/');
203
182
  }
204
183
  /**
205
184
  * Reads the last non-empty line of a text as a JSON object.
@@ -1185,31 +1164,48 @@ export function computeRanges(ranges, releases) {
1185
1164
  }, { ranges, moved: [] });
1186
1165
  }
1187
1166
  /**
1188
- * Writes the re-pinned ranges into the target's manifest.
1167
+ * Writes the re-pinned ranges into the target's manifest, keeping every peer range at its floor.
1168
+ *
1169
+ * @remarks
1170
+ * A `peerDependencies` range moves only when its floor fails the release, and no reading the visit
1171
+ * takes names a floor the release needs, so every peer the registry moved past stays as declared and
1172
+ * is reported as kept.
1189
1173
  *
1190
1174
  * @param target - The target directory.
1191
1175
  * @param releases - The audit's release readings.
1192
- * @returns One message per range moved; the manifest is rewritten only when a range moved.
1176
+ * @returns One message per range moved and one per peer range kept; the manifest is rewritten only
1177
+ * when a range moved.
1178
+ * @example
1179
+ * ```ts
1180
+ * writeRanges('.', [{ name: 'vite', range: '^8', latest: '8.3.8' }])
1181
+ * // { moved: ['vite ^8.3.7 -> ^8.3.8'], kept: ['peer vite ^8.3.7 left alone, not ^8.3.8'] }
1182
+ * ```
1193
1183
  */
1194
1184
  export function writeRanges(target, releases) {
1195
1185
  const manifest = readManifest(target);
1196
1186
  if (manifest === undefined)
1197
- return [];
1187
+ return { moved: [], kept: [] };
1198
1188
  const fields = RANGE_FIELDS.flatMap((field) => {
1199
1189
  const block = manifest[field];
1200
1190
  if (typeof block !== 'object' || block === null)
1201
1191
  return [];
1202
- return [{ field, ...computeRanges(Object.fromEntries(Object.entries(block)), releases) }];
1192
+ const ranges = Object.fromEntries(Object.entries(block));
1193
+ return [{ field, ranges, moves: computeRanges(ranges, releases) }];
1203
1194
  });
1204
- const moved = fields.flatMap((entry) => entry.moved);
1195
+ const peers = fields.filter((entry) => entry.field === 'peerDependencies');
1196
+ const kept = peers.flatMap((entry) => Object.entries(entry.ranges)
1197
+ .filter(([name, range]) => entry.moves.ranges[name] !== range)
1198
+ .map(([name, range]) => `peer ${name} ${String(range)} left alone, not ${String(entry.moves.ranges[name])}`));
1199
+ const pinned = fields.filter((entry) => entry.field !== 'peerDependencies');
1200
+ const moved = pinned.flatMap((entry) => entry.moves.moved);
1205
1201
  if (moved.length > 0) {
1206
1202
  const written = {
1207
1203
  ...manifest,
1208
- ...Object.fromEntries(fields.map((entry) => [entry.field, entry.ranges])),
1204
+ ...Object.fromEntries(pinned.map((entry) => [entry.field, entry.moves.ranges])),
1209
1205
  };
1210
1206
  writeFileSync(join(target, 'package.json'), `${JSON.stringify(written, null, '\t')}\n`);
1211
1207
  }
1212
- return moved;
1208
+ return { moved, kept };
1213
1209
  }
1214
1210
  /**
1215
1211
  * Runs the pin step.
@@ -1226,8 +1222,8 @@ export function runPin(runner, scaffoldFile, scaffoldPrefix, offline) {
1226
1222
  const releases = readReleases(audit.stdout);
1227
1223
  if (releases === undefined || (audit.status !== 0 && audit.status !== 1))
1228
1224
  return;
1229
- const moved = writeRanges(runner.target, releases);
1230
- appendStep(runner, 'pin', 'rewrite audit release ranges to the registry caret', moved.length === 0 ? 'no range moved' : moved.join(', '));
1225
+ const { moved, kept } = writeRanges(runner.target, releases);
1226
+ appendStep(runner, 'pin', 'rewrite audit release ranges to the registry caret', [moved.length === 0 ? 'no range moved' : moved.join(', '), ...kept].join('; '));
1231
1227
  }
1232
1228
  else {
1233
1229
  appendStep(runner, 'pin', 'rewrite audit release ranges to the registry caret', 'dry run');
@@ -1447,12 +1443,12 @@ export function describeChange(moved, movedWord, sameWord) {
1447
1443
  /**
1448
1444
  * Runs one repository's visit.
1449
1445
  *
1450
- * @param argv - The arguments after the script path.
1446
+ * @param values - The flag values `parseArgs` read.
1451
1447
  * @returns The finished visit, or undefined when the target carries no readable manifest or no
1452
1448
  * scaffold executable.
1453
1449
  */
1454
- export function runVisit(argv) {
1455
- const target = readOption(argv, '--target') ?? process.cwd();
1450
+ export function runVisit(values) {
1451
+ const target = typeof values.target === 'string' ? values.target : process.cwd();
1456
1452
  if (!existsSync(join(target, 'package.json'))) {
1457
1453
  console.error(`wave: ${target} carries no package.json`);
1458
1454
  return undefined;
@@ -1468,8 +1464,8 @@ export function runVisit(argv) {
1468
1464
  const [scaffoldFile, ...scaffoldPrefix] = scaffold;
1469
1465
  if (scaffoldFile === undefined)
1470
1466
  return undefined;
1471
- const from = STEPS.indexOf(readOption(argv, '--from') ?? 'pin');
1472
- const to = STEPS.indexOf(readOption(argv, '--to') ?? 'compare');
1467
+ const from = STEPS.indexOf(typeof values.from === 'string' ? values.from : 'pin');
1468
+ const to = STEPS.indexOf(typeof values.to === 'string' ? values.to : 'compare');
1473
1469
  const selected = new Set(STEPS.slice(from, to + 1));
1474
1470
  const manifest = readManifest(target);
1475
1471
  if (manifest === undefined) {
@@ -1480,10 +1476,10 @@ export function runVisit(argv) {
1480
1476
  const version = readString(manifest, 'version');
1481
1477
  const runner = {
1482
1478
  target: resolve(target),
1483
- dry: argv.includes('--dry-run'),
1484
- offline: argv.includes('--offline'),
1485
- regenerate: argv.includes('--regenerate'),
1486
- directory: argv.includes('--dry-run') ||
1479
+ dry: values['dry-run'] === true,
1480
+ offline: values.offline === true,
1481
+ regenerate: values.regenerate === true,
1482
+ directory: values['dry-run'] === true ||
1487
1483
  (name === SCAFFOLD && from === STEPS.indexOf('record') && to === from)
1488
1484
  ? undefined
1489
1485
  : readJournalDirectory(resolve(target)),
@@ -1516,7 +1512,7 @@ export function runVisit(argv) {
1516
1512
  if (selected.has('install') && !failed(runner.steps))
1517
1513
  runInstall(runner, 'install');
1518
1514
  const hits = selected.has('pins') && !failed(runner.steps)
1519
- ? runPins(runner, before, readOption(argv, '--prior') ?? version)
1515
+ ? runPins(runner, before, typeof values.prior === 'string' ? values.prior : version)
1520
1516
  : undefined;
1521
1517
  const format = selected.has('format') && !failed(runner.steps) ? runFormat(runner) : undefined;
1522
1518
  if (selected.has('record') && !failed(runner.steps))
@@ -1622,64 +1618,55 @@ export function renderVisit(visit) {
1622
1618
  * on usage.
1623
1619
  */
1624
1620
  export function main(argv) {
1625
- const unknown = readUnknownFlags(argv, FLAGS);
1626
- if (unknown.length > 0) {
1627
- console.error(`wave: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
1628
- return 64;
1629
- }
1630
- const missing = readMissingFlags(argv, [
1631
- '--target',
1632
- '--from',
1633
- '--to',
1634
- '--prior',
1635
- '--catalog',
1636
- '--out',
1637
- ]);
1638
- if (missing.length > 0) {
1639
- console.error(`wave: ${missing.join(', ')} given with no value`);
1621
+ const parsed = parseArguments(argv);
1622
+ if (!parsed.success) {
1623
+ console.error(`wave: ${parsed.error}; ${USAGE}`);
1640
1624
  return 64;
1641
1625
  }
1642
- if (argv.includes('--plan') && argv.includes('--visit')) {
1643
- console.error('wave: --plan and --visit are two modes; name one');
1626
+ const { values } = parsed.value;
1627
+ if (values.plan === true && values.visit === true) {
1628
+ console.error(`wave: --plan and --visit are two modes; name one; ${USAGE}`);
1644
1629
  return 64;
1645
1630
  }
1646
- if (argv.includes('--plan')) {
1647
- if (argv.includes('--regenerate')) {
1648
- console.error('wave: --regenerate requires --visit, not --plan');
1631
+ if (values.plan === true) {
1632
+ if (values.regenerate === true) {
1633
+ console.error(`wave: --regenerate requires --visit, not --plan; ${USAGE}`);
1649
1634
  return 64;
1650
1635
  }
1651
- const layers = readLayers(readOption(argv, '--catalog') ?? CATALOG);
1636
+ const layers = readLayers(typeof values.catalog === 'string' ? values.catalog : CATALOG);
1652
1637
  if (layers === undefined) {
1653
1638
  console.error('wave: no marker-bounded catalog table; run scaffold catalog first');
1654
1639
  return 2;
1655
1640
  }
1656
- if (argv.includes('--json'))
1641
+ if (values.json === true)
1657
1642
  console.log(JSON.stringify(Object.fromEntries(layers)));
1658
1643
  else
1659
1644
  for (const [layer, members] of layers)
1660
1645
  console.log(`${layer}\t${members.join(', ')}`);
1661
1646
  return 0;
1662
1647
  }
1663
- if (!argv.includes('--visit')) {
1648
+ if (values.visit !== true) {
1664
1649
  console.error(USAGE);
1665
1650
  return 64;
1666
1651
  }
1667
- const from = STEPS.indexOf(readOption(argv, '--from') ?? 'pin');
1668
- const to = STEPS.indexOf(readOption(argv, '--to') ?? 'compare');
1652
+ const first = typeof values.from === 'string' ? values.from : 'pin';
1653
+ const last = typeof values.to === 'string' ? values.to : 'compare';
1654
+ const from = STEPS.indexOf(first);
1655
+ const to = STEPS.indexOf(last);
1669
1656
  if (from === -1 || to === -1 || to < from) {
1670
- console.error(`wave: --from and --to name steps in order from: ${STEPS.join(', ')}`);
1657
+ console.error(`wave: --from and --to take steps in order from: ${STEPS.join(', ')}, not ${JSON.stringify(first)} and ${JSON.stringify(last)}; ${USAGE}`);
1671
1658
  return 64;
1672
1659
  }
1673
- const prior = readOption(argv, '--prior');
1660
+ const prior = typeof values.prior === 'string' ? values.prior : undefined;
1674
1661
  if (prior !== undefined && !VERSION.test(prior)) {
1675
- console.error('wave: --prior takes the version the package carried before its bump, MAJOR.MINOR.PATCH');
1662
+ console.error(`wave: --prior takes the version the package carried before its bump, MAJOR.MINOR.PATCH, not ${JSON.stringify(prior)}; ${USAGE}`);
1676
1663
  return 64;
1677
1664
  }
1678
- const visit = runVisit(argv);
1665
+ const visit = runVisit(values);
1679
1666
  if (visit === undefined)
1680
1667
  return 2;
1681
- const output = argv.includes('--json') ? `${JSON.stringify(visit)}\n` : renderVisit(visit);
1682
- const out = readOption(argv, '--out');
1668
+ const output = values.json === true ? `${JSON.stringify(visit)}\n` : renderVisit(visit);
1669
+ const out = typeof values.out === 'string' ? values.out : undefined;
1683
1670
  if (out === undefined)
1684
1671
  process.stdout.write(output);
1685
1672
  else {