@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 { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
3
3
  import { dirname, join, relative } from 'node:path';
4
4
  import { gunzipSync } from 'node:zlib';
5
+ import { parseArgs } from 'node:util';
5
6
  /** Holds the byte size of one tar block. */
6
7
  export const BLOCK = 512;
7
8
  /** Names the directory every npm tarball entry sits under. */
@@ -17,60 +18,44 @@ export const SKIPPED_DIRECTORIES = new Set([
17
18
  ]);
18
19
  /** Holds the empty skip set, because a dist tree holds nothing a walk skips, so every emitted file counts. */
19
20
  export const NOTHING_SKIPPED = new Set();
20
- /** Lists every flag the script reads, value flags and switches alike. */
21
- export const FLAGS = ['--package', '--version', '--tarball', '--dist', '--json'];
22
21
  /** Holds the usage line the script prints on a usage refusal. */
23
22
  export const USAGE = 'usage: compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]';
23
+ /** Declares every flag the script reads, for `parseArgs`. */
24
+ export const OPTIONS = Object.freeze({
25
+ package: Object.freeze({ type: 'string' }),
26
+ version: Object.freeze({ type: 'string' }),
27
+ tarball: Object.freeze({ type: 'string' }),
28
+ dist: Object.freeze({ type: 'string' }),
29
+ json: Object.freeze({ type: 'boolean' }),
30
+ });
24
31
  /**
25
- * Normalizes a host path to forward slashes.
26
- *
27
- * @param path - A host path.
28
- * @returns The same path with every backslash replaced by a slash.
29
- */
30
- export function normalizeSlashes(path) {
31
- return path.split('\\').join('/');
32
- }
33
- /**
34
- * Reads the value that follows a flag.
35
- *
36
- * @remarks
37
- * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
38
- * with `--` is a missing value, and the `--flag=value` form is not read.
39
- *
40
- * @param argv - The arguments after the script path.
41
- * @param name - The flag, such as `--package`.
42
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
43
- * another flag.
44
- */
45
- export function readOption(argv, name) {
46
- const index = argv.indexOf(name);
47
- const value = index === -1 ? undefined : argv[index + 1];
48
- return value === undefined || value.startsWith('--') ? undefined : value;
49
- }
50
- /**
51
- * Names the value flags a caller gave with no value.
32
+ * Parses the arguments in strict mode against `OPTIONS`.
52
33
  *
53
34
  * @param argv - The arguments after the script path.
54
- * @param names - The flags that take a value.
55
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
35
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
56
36
  */
57
- export function readMissingFlags(argv, names) {
58
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
37
+ export function parseArguments(argv) {
38
+ try {
39
+ const { values, positionals } = parseArgs({
40
+ args: [...argv],
41
+ options: OPTIONS,
42
+ strict: true,
43
+ allowPositionals: false,
44
+ });
45
+ return { success: true, value: { values, positionals } };
46
+ }
47
+ catch (error) {
48
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
49
+ }
59
50
  }
60
51
  /**
61
- * Names the flags a caller gave that the script does not read.
62
- *
63
- * @remarks
64
- * Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
65
- * argument is unknown, because the script reads no such form.
52
+ * Normalizes a host path to forward slashes.
66
53
  *
67
- * @param argv - The arguments after the script path.
68
- * @param flags - Every flag the script reads, value flags and switches alike.
69
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
54
+ * @param path - A host path.
55
+ * @returns The same path with every backslash replaced by a slash.
70
56
  */
71
- export function readUnknownFlags(argv, flags) {
72
- const end = argv.indexOf('--');
73
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
57
+ export function normalizeSlashes(path) {
58
+ return path.replaceAll('\\', '/');
74
59
  }
75
60
  /**
76
61
  * Lists every regular file beneath a directory, skipping the directories named.
@@ -379,27 +364,22 @@ export function differs(left, right) {
379
364
  * cannot be read, 64 on usage.
380
365
  */
381
366
  export async function main(argv) {
382
- const unknown = readUnknownFlags(argv, FLAGS);
383
- if (unknown.length > 0) {
384
- console.error(`compare: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
385
- return 64;
386
- }
387
- const missing = readMissingFlags(argv, ['--package', '--version', '--tarball', '--dist']);
388
- if (missing.length > 0) {
389
- console.error(`compare: ${missing.join(', ')} given with no value`);
367
+ const parsed = parseArguments(argv);
368
+ if (!parsed.success) {
369
+ console.error(`compare: ${parsed.error}; ${USAGE}`);
390
370
  return 64;
391
371
  }
372
+ const { values } = parsed.value;
392
373
  const manifest = readManifest('.');
393
- const name = readOption(argv, '--package') ?? manifest.name;
394
- const dist = readOption(argv, '--dist') ?? 'dist';
395
- const tarball = readOption(argv, '--tarball');
396
- if (name === undefined ||
397
- !existsSync(dist) ||
398
- (argv.includes('--tarball') && tarball === undefined)) {
374
+ const name = typeof values.package === 'string' ? values.package : manifest.name;
375
+ const dist = typeof values.dist === 'string' ? values.dist : 'dist';
376
+ const tarball = typeof values.tarball === 'string' ? values.tarball : undefined;
377
+ if (name === undefined || !existsSync(dist)) {
399
378
  console.error(USAGE);
400
379
  return 64;
401
380
  }
402
- const source = await readSource(name, readOption(argv, '--version'), tarball);
381
+ const requested = typeof values.version === 'string' ? values.version : undefined;
382
+ const source = await readSource(name, requested, tarball);
403
383
  const { archive, version } = source;
404
384
  if (archive === undefined) {
405
385
  console.error(`compare: ${source.failure}`);
@@ -439,7 +419,7 @@ export async function main(argv) {
439
419
  changed,
440
420
  material,
441
421
  };
442
- if (argv.includes('--json'))
422
+ if (values.json === true)
443
423
  console.log(JSON.stringify(summary));
444
424
  else {
445
425
  console.log(`compare: ${name}${version === undefined ? '' : `@${version}`} — ${published.size} published file(s), ${added.length} added, ${removed.length} removed, ${changed.length} changed`);
@@ -1,17 +1,6 @@
1
- // Sweep source, tests, and guides for a prior version or range literal after a bump or a re-pin.
2
- // Run from the publishing package's root:
3
- // node .agents/skills/orkestrel-publish/scripts/pins.ts --version 0.0.76 [--range ^0.0.16 ...] [--paths src,tests,guides] [--json]
4
- // `--range` repeats. A version hit is the literal bounded by characters other than digits and dots,
5
- // so `~0.0.76` and `"0.0.76"` both hit and `0.0.760` does not. A range that is one comparator over
6
- // one version (`^8.3.0`, `~8.3.0`, `>=8.3.0`, `v8.3.0`) hits its bare version in any form, bounded the
7
- // same way, so `--range ^8.3.0` hits `~8.3.0` and `serves 8.3.0` and misses `^8.3.1`; any other
8
- // range (`>=1.2.0 <2.0.0`, `8.x`) hits its literal bounded the same way and not preceded by another
9
- // range operator. Each matching line prints once as path:line: text, naming the first requested
10
- // literal that matched in the order --version then each --range, so the operator rules on it.
11
- // Exit 0 with no hits, 3 with hits, 64 on usage, including a flag the script does not read and the
12
- // `--flag=value` form.
13
1
  import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
14
2
  import { join } from 'node:path';
3
+ import { parseArgs } from 'node:util';
15
4
  /** Matches the file extensions the sweep skips as binary. */
16
5
  export const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u;
17
6
  /** Matches a range that is one comparator over one full version and captures the version. */
@@ -25,73 +14,43 @@ export const SKIPPED_DIRECTORIES = new Set([
25
14
  '.orkestrel',
26
15
  '.idea',
27
16
  ]);
28
- /** Lists every flag the script reads, value flags and switches alike. */
29
- export const FLAGS = ['--version', '--range', '--paths', '--json'];
30
17
  /** Holds the usage line the script prints on a usage refusal. */
31
18
  export const USAGE = 'usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests,guides] [--json]';
19
+ /** Declares every flag the script reads, for `parseArgs`. */
20
+ export const OPTIONS = Object.freeze({
21
+ version: Object.freeze({ type: 'string' }),
22
+ range: Object.freeze({ type: 'string', multiple: true }),
23
+ paths: Object.freeze({ type: 'string' }),
24
+ json: Object.freeze({ type: 'boolean' }),
25
+ });
32
26
  /**
33
- * Normalizes a host path to forward slashes.
34
- *
35
- * @param path - A host path.
36
- * @returns The same path with every backslash replaced by a slash.
37
- */
38
- export function normalizeSlashes(path) {
39
- return path.split('\\').join('/');
40
- }
41
- /**
42
- * Reads the value that follows a flag.
43
- *
44
- * @remarks
45
- * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
46
- * with `--` is a missing value, and the `--flag=value` form is not read.
47
- *
48
- * @param argv - The arguments after the script path.
49
- * @param name - The flag, such as `--paths`.
50
- * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
51
- * another flag.
52
- */
53
- export function readOption(argv, name) {
54
- const index = argv.indexOf(name);
55
- const value = index === -1 ? undefined : argv[index + 1];
56
- return value === undefined || value.startsWith('--') ? undefined : value;
57
- }
58
- /**
59
- * Names the value flags a caller gave with no value.
60
- *
61
- * @param argv - The arguments after the script path.
62
- * @param names - The flags that take a value.
63
- * @returns Each named flag that appears last or is followed by another flag, in argument order.
64
- */
65
- export function readMissingFlags(argv, names) {
66
- return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
67
- }
68
- /**
69
- * Names the flags a caller gave that the script does not read.
70
- *
71
- * @remarks
72
- * Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
73
- * argument is unknown, because the script reads no such form.
27
+ * Parses the arguments in strict mode against `OPTIONS`.
74
28
  *
75
29
  * @param argv - The arguments after the script path.
76
- * @param flags - Every flag the script reads, value flags and switches alike.
77
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
30
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
78
31
  */
79
- export function readUnknownFlags(argv, flags) {
80
- const end = argv.indexOf('--');
81
- return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
32
+ export function parseArguments(argv) {
33
+ try {
34
+ const { values, positionals } = parseArgs({
35
+ args: [...argv],
36
+ options: OPTIONS,
37
+ strict: true,
38
+ allowPositionals: false,
39
+ });
40
+ return { success: true, value: { values, positionals } };
41
+ }
42
+ catch (error) {
43
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
44
+ }
82
45
  }
83
46
  /**
84
- * Reads every value that follows a repeatable flag.
47
+ * Normalizes a host path to forward slashes.
85
48
  *
86
- * @param argv - The arguments after the script path.
87
- * @param name - The flag, such as `--range`.
88
- * @returns The values in order, empty when the flag never appears.
49
+ * @param path - A host path.
50
+ * @returns The same path with every backslash replaced by a slash.
89
51
  */
90
- export function readOptions(argv, name) {
91
- return argv.flatMap((argument, index) => {
92
- const value = argv[index + 1];
93
- return argument === name && value !== undefined && !value.startsWith('--') ? [value] : [];
94
- });
52
+ export function normalizeSlashes(path) {
53
+ return path.replaceAll('\\', '/');
95
54
  }
96
55
  /**
97
56
  * Lists every regular file beneath a directory, skipping the directories the sweep never reads.
@@ -189,6 +148,17 @@ export function sweepFile(path, literals) {
189
148
  : [{ path, line: index + 1, literal: match.literal, text: text.trim() }];
190
149
  });
191
150
  }
151
+ /**
152
+ * Collects the strings a repeatable flag's value holds.
153
+ *
154
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
155
+ * @returns Each string in order, empty when the flag never appears.
156
+ */
157
+ export function collectStrings(value) {
158
+ return Array.isArray(value)
159
+ ? value.filter((member) => typeof member === 'string')
160
+ : [];
161
+ }
192
162
  /**
193
163
  * Runs the sweep and prints its hits.
194
164
  *
@@ -196,19 +166,15 @@ export function sweepFile(path, literals) {
196
166
  * @returns The exit code: 0 with no hits, 3 with hits, 64 on usage.
197
167
  */
198
168
  export function main(argv) {
199
- const unknown = readUnknownFlags(argv, FLAGS);
200
- if (unknown.length > 0) {
201
- console.error(`pins: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
202
- return 64;
203
- }
204
- const missing = readMissingFlags(argv, ['--version', '--range', '--paths']);
205
- if (missing.length > 0) {
206
- console.error(`pins: ${missing.join(', ')} given with no value`);
169
+ const parsed = parseArguments(argv);
170
+ if (!parsed.success) {
171
+ console.error(`pins: ${parsed.error}; ${USAGE}`);
207
172
  return 64;
208
173
  }
209
- const version = readOptions(argv, '--version')[0];
210
- const ranges = readOptions(argv, '--range');
211
- const paths = (readOptions(argv, '--paths')[0] ?? 'src,tests,guides').split(',');
174
+ const { values } = parsed.value;
175
+ const version = typeof values.version === 'string' ? values.version : undefined;
176
+ const ranges = collectStrings(values.range);
177
+ const paths = (typeof values.paths === 'string' ? values.paths : 'src,tests,guides').split(',');
212
178
  if (version === undefined && ranges.length === 0) {
213
179
  console.error(USAGE);
214
180
  return 64;
@@ -233,7 +199,7 @@ export function main(argv) {
233
199
  .filter((file) => !BINARY.test(file))
234
200
  .flatMap((file) => sweepFile(file, literals));
235
201
  const names = literals.map((entry) => entry.literal);
236
- if (argv.includes('--json')) {
202
+ if (values.json === true) {
237
203
  console.log(JSON.stringify({ literals: names, paths: present, skipped, hits }));
238
204
  }
239
205
  else {
@@ -1,34 +1,38 @@
1
- // Derive a release chain from the manifest's `prepublishOnly` script and run it, so a release names
2
- // every step it leaves out. Run from the package root:
3
- // node .agents/skills/orkestrel-publish/scripts/steps.ts --journal DIR [--omit NAME=REASON ...] [--no-ci] [--dry-run] [--json]
4
- // The script splits `prepublishOnly` on `&&` and reads each segment as `npm test`, `npm run NAME`, or
5
- // `npm run NAME -- ARGS...`; any other segment or shell operator is refused by name, because the
6
- // script can then state no complete step list. The plan opens with `ci` (`npm ci --ignore-scripts`)
7
- // and `clean` (`npm run clean`), then the derived steps in script order, each named from its script
8
- // with every character `chain.ts` refuses in a step name replaced by `-`. A name that repeats, or the
9
- // name `omitted`, whose journal would overwrite `omitted.txt`, is refused, case-folded because a
10
- // journal file name folds on Windows. `--omit`, which repeats, leaves one derived step out for a
11
- // non-empty one-line reason; `ci` and `clean` are not omittable through it. On Windows `ci` is left
12
- // out when a `.node`, `.dll`, or `.exe` file under `node_modules` refuses a write-mode open at chain start,
13
- // and `--no-ci` leaves `ci` out with the reason `--no-ci`. The script writes the plan to
14
- // `DIR/plan.json` and every omitted step to `DIR/omitted.txt`, prints each omitted step on its own
15
- // line, and runs the sibling `chain.ts` with stdio inherited and `npm_config_prefer_online=true`
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.
18
- // Exit with the chain's code: 0 when every step exited 0, the failing step's code when one did not,
19
- // 2 when a step or the chain cannot start. Exit 2 when the journal cannot be written, 64 on usage,
20
- // and 65 when no complete step list can be derived or an `--omit` names no derived step. A step
21
- // exiting 65 reads alike with that refusal.
22
1
  import { spawnSync } from 'node:child_process';
23
2
  import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, writeFileSync, } from 'node:fs';
24
3
  import { dirname, extname, join } from 'node:path';
25
4
  import { fileURLToPath } from 'node:url';
26
- /** Lists the flags that take a value. */
27
- export const VALUE_FLAGS = ['--journal', '--omit'];
28
- /** Lists every flag the script reads, value flags and switches alike. */
29
- export const FLAGS = [...VALUE_FLAGS, '--no-ci', '--dry-run', '--json'];
5
+ import { parseArgs } from 'node:util';
30
6
  /** Holds the usage line printed when a call names no journal or gives a malformed flag. */
31
7
  export const USAGE = 'usage: steps.ts --journal DIR [--omit NAME=REASON ...] [--no-ci] [--dry-run] [--json]';
8
+ /** Declares every flag the script reads, for `parseArgs`. */
9
+ export const OPTIONS = Object.freeze({
10
+ journal: Object.freeze({ type: 'string' }),
11
+ omit: Object.freeze({ type: 'string', multiple: true }),
12
+ 'no-ci': Object.freeze({ type: 'boolean' }),
13
+ 'dry-run': Object.freeze({ type: 'boolean' }),
14
+ json: Object.freeze({ type: 'boolean' }),
15
+ });
16
+ /**
17
+ * Parses the arguments in strict mode against `OPTIONS`.
18
+ *
19
+ * @param argv - The arguments after the script path.
20
+ * @returns The values and positionals, or the message `parseArgs` refused the arguments with.
21
+ */
22
+ export function parseArguments(argv) {
23
+ try {
24
+ const { values, positionals } = parseArgs({
25
+ args: [...argv],
26
+ options: OPTIONS,
27
+ strict: true,
28
+ allowPositionals: false,
29
+ });
30
+ return { success: true, value: { values, positionals } };
31
+ }
32
+ catch (error) {
33
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
34
+ }
35
+ }
32
36
  /** Matches a step name `chain.ts` accepts. */
33
37
  export const STEP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
34
38
  /** Matches every character `chain.ts` refuses in a step name. */
@@ -86,56 +90,6 @@ export function parseJson(text) {
86
90
  return undefined;
87
91
  }
88
92
  }
89
- /**
90
- * Reads the value after each occurrence of a flag.
91
- *
92
- * @param argv - The arguments after the script path.
93
- * @param name - The flag, such as `--omit`.
94
- * @returns One member per occurrence, undefined where the flag is last or a value opens with `--`.
95
- */
96
- export function readValues(argv, name) {
97
- return argv.flatMap((argument, index) => {
98
- if (argument !== name)
99
- return [];
100
- const value = argv[index + 1];
101
- return [value === undefined || value.startsWith('--') ? undefined : value];
102
- });
103
- }
104
- /**
105
- * Names the value flags a caller gave with no value.
106
- *
107
- * @param argv - The arguments after the script path.
108
- * @param names - The flags that take a value.
109
- * @returns Each named flag with an occurrence that is last or followed by another flag.
110
- */
111
- export function readMissingFlags(argv, names) {
112
- return names.filter((name) => readValues(argv, name).includes(undefined));
113
- }
114
- /**
115
- * Names the flags a caller gave that the script does not read.
116
- *
117
- * @remarks
118
- * A `--flag=value` argument is unknown, because the script reads no such form. The script passes no
119
- * command on, so a bare `--` is unknown too, and the scan stops there and reads nothing after it.
120
- *
121
- * @param argv - The arguments after the script path.
122
- * @param flags - Every flag the script reads, value flags and switches alike.
123
- * @returns Each argument that opens with `--` and is not a read flag, in argument order.
124
- */
125
- export function readUnknownFlags(argv, flags) {
126
- const end = argv.indexOf('--');
127
- return (end === -1 ? argv : argv.slice(0, end + 1)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
128
- }
129
- /**
130
- * Names the arguments no flag reads as its value.
131
- *
132
- * @param argv - The arguments after the script path.
133
- * @param names - The flags that take a value.
134
- * @returns Each argument that neither opens with `--` nor follows a value flag.
135
- */
136
- export function readStrayArguments(argv, names) {
137
- return argv.filter((argument, index) => !argument.startsWith('--') && !names.includes(argv[index - 1] ?? ''));
138
- }
139
93
  /**
140
94
  * Parses one `--omit` value.
141
95
  *
@@ -151,32 +105,23 @@ export function parseOmission(text) {
151
105
  return { name: text.slice(0, at), reason };
152
106
  }
153
107
  /**
154
- * Reads the first usage problem in the arguments.
108
+ * Reads the first usage problem in the flag values `parseArgs` read.
155
109
  *
156
- * @param argv - The arguments after the script path.
157
- * @returns The refusal to print, or undefined when the arguments are well formed.
110
+ * @param values - The flag values.
111
+ * @returns The refusal to print, or undefined when the values are well formed.
158
112
  */
159
- export function readUsageProblem(argv) {
160
- const unknown = readUnknownFlags(argv, FLAGS);
161
- if (unknown.length > 0)
162
- return `${unknown.join(', ')} is not a flag this script reads; ${USAGE}`;
163
- const missing = readMissingFlags(argv, VALUE_FLAGS);
164
- if (missing.length > 0)
165
- return `${missing.join(', ')} given with no value; ${USAGE}`;
166
- const strays = readStrayArguments(argv, VALUE_FLAGS);
167
- if (strays.length > 0)
168
- return `${strays.map(quote).join(', ')} is not read by a flag; ${USAGE}`;
169
- if (readValues(argv, '--journal').length === 0)
113
+ export function readUsageProblem(values) {
114
+ if (typeof values.journal !== 'string')
170
115
  return USAGE;
171
- if (argv.includes('--json') && !argv.includes('--dry-run')) {
116
+ if (values.json === true && values['dry-run'] !== true) {
172
117
  return `--json reads only with --dry-run, because the chain prints to standard output; ${USAGE}`;
173
118
  }
174
- const values = readValues(argv, '--omit').flatMap((value) => (value === undefined ? [] : [value]));
175
- const malformed = values.filter((value) => parseOmission(value) === undefined);
119
+ const omits = collectStrings(values.omit);
120
+ const malformed = omits.filter((value) => parseOmission(value) === undefined);
176
121
  if (malformed.length > 0) {
177
- return `--omit takes NAME=REASON with a non-empty one-line reason, given ${malformed.map(quote).join(', ')}`;
122
+ return `--omit takes NAME=REASON with a non-empty one-line reason, not ${malformed.map(quote).join(', ')}; ${USAGE}`;
178
123
  }
179
- const names = values.map((value) => value.slice(0, value.indexOf('=')));
124
+ const names = omits.map((value) => value.slice(0, value.indexOf('=')));
180
125
  const repeated = [...new Set(names.filter((name, index) => names.indexOf(name) !== index))];
181
126
  if (repeated.length > 0) {
182
127
  return `--omit names a step more than once: ${repeated.map(quote).join(', ')}`;
@@ -186,15 +131,26 @@ export function readUsageProblem(argv) {
186
131
  /**
187
132
  * Reads the given `--omit` values as omissions.
188
133
  *
189
- * @param argv - Arguments that `readUsageProblem` found no problem in.
134
+ * @param values - Flag values that `readUsageProblem` found no problem in.
190
135
  * @returns One omission per occurrence, in argument order.
191
136
  */
192
- export function readOmissions(argv) {
193
- return readValues(argv, '--omit').flatMap((value) => {
194
- const omission = value === undefined ? undefined : parseOmission(value);
137
+ export function readOmissions(values) {
138
+ return collectStrings(values.omit).flatMap((value) => {
139
+ const omission = parseOmission(value);
195
140
  return omission === undefined ? [] : [omission];
196
141
  });
197
142
  }
143
+ /**
144
+ * Collects the strings a repeatable flag's value holds.
145
+ *
146
+ * @param value - The value `parseArgs` read for a flag declared with `multiple: true`.
147
+ * @returns Each string in order, empty when the flag never appears.
148
+ */
149
+ export function collectStrings(value) {
150
+ return Array.isArray(value)
151
+ ? value.filter((member) => typeof member === 'string')
152
+ : [];
153
+ }
198
154
  /**
199
155
  * Parses one segment of `prepublishOnly`.
200
156
  *
@@ -478,14 +434,20 @@ export function runChain(journal) {
478
434
  * names no derived step.
479
435
  */
480
436
  export function main(argv) {
481
- const usage = readUsageProblem(argv);
482
- const [journal] = readValues(argv, '--journal');
437
+ const parsed = parseArguments(argv);
438
+ if (!parsed.success) {
439
+ console.error(`steps: ${parsed.error}; ${USAGE}`);
440
+ return 64;
441
+ }
442
+ const { values } = parsed.value;
443
+ const usage = readUsageProblem(values);
444
+ const journal = typeof values.journal === 'string' ? values.journal : undefined;
483
445
  if (usage !== undefined || journal === undefined) {
484
446
  console.error(`steps: ${usage ?? USAGE}`);
485
447
  return 64;
486
448
  }
487
449
  const derivation = readDerivation(process.cwd());
488
- const omissions = readOmissions(argv);
450
+ const omissions = readOmissions(values);
489
451
  const problems = [
490
452
  ...derivation.problems,
491
453
  ...(derivation.problems.length > 0 ? [] : readOmissionProblems(omissions, derivation.segments)),
@@ -495,17 +457,17 @@ export function main(argv) {
495
457
  return 65;
496
458
  }
497
459
  const omitted = [
498
- ...readCiOmissions(argv.includes('--no-ci'), () => readHolders('node_modules')),
460
+ ...readCiOmissions(values['no-ci'] === true, () => readHolders('node_modules')),
499
461
  ...omissions,
500
462
  ];
501
463
  const selected = selectSegments(derivation.segments, omitted);
502
464
  const plan = buildPlan(selected, resolveNpm());
503
- if (argv.includes('--json')) {
465
+ if (values.json === true) {
504
466
  console.log(JSON.stringify({ steps: plan, omitted }));
505
467
  return 0;
506
468
  }
507
469
  const lines = omitted.map((omission) => formatOmission(omission));
508
- if (argv.includes('--dry-run')) {
470
+ if (values['dry-run'] === true) {
509
471
  console.log([...selected.map((segment) => formatSegment(segment)), ...lines].join('\n'));
510
472
  return 0;
511
473
  }