@orkestrel/scaffold 0.0.107 → 0.0.109

package/dist/agents/skills/orkestrel-publish/scripts/wave.js

@@ -1,10 +1,10 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { copyFileSync, existsSync, lstatSync, readFileSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, readFileSync, mkdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseJsonRecord, isRecord, normalizeSlashes, removeTree, scanLocalSpecs, readJsonObject, readMissingFlags, readOption, readString, runNpm, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const STEPS = [
+/** Lists the steps of a visit in the order they run. */
+export const STEPS = [
     'pin',
     'commit',
     'overwrite',
@@ -16,20 +16,268 @@ const STEPS = [
     'gates',
     'compare',
 ];
-const GATES = ['format:check', 'lint:check', 'check', 'build', 'test'];
-const RUNTIME_FIELDS = ['dependencies', 'peerDependencies'];
-const RANGE_FIELDS = [...RUNTIME_FIELDS, 'devDependencies'];
-const CATALOG = '.claude/agents/orkestrel.md';
-const OFFLINE_REFUSAL = "'catalog' does not take --offline";
-// The vendored host is staged from this package's checkout, so overwriting it from the host deletes
-// and replaces its own canon.
-const SCAFFOLD = '@orkestrel/scaffold';
-const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
-// The checkout runs the `.ts` sources and a built twin under `dist/agents` runs `.js` siblings.
-const EXTENSION = extname(fileURLToPath(import.meta.url));
-const COMPARE = fileURLToPath(new URL(`./compare${EXTENSION}`, import.meta.url));
-const PINS = fileURLToPath(new URL(`./pins${EXTENSION}`, import.meta.url));
-function readManifest(target) {
+/** Lists the package scripts the gates step runs, in order. */
+export const GATES = ['format:check', 'lint:check', 'check', 'build', 'test'];
+/** Lists the manifest fields whose ranges ship to a consumer. */
+export const RUNTIME_FIELDS = ['dependencies', 'peerDependencies'];
+/** Lists the manifest fields whose ranges a visit re-pins. */
+export const RANGE_FIELDS = [...RUNTIME_FIELDS, 'devDependencies'];
+/** Names the agent file that carries the catalog table. */
+export const CATALOG = '.claude/agents/orkestrel.md';
+/** Holds the text an offline overwrite refusal names. */
+export const OFFLINE_REFUSAL = "'catalog' does not take --offline";
+/**
+ * Names the package whose checkout the vendored host is staged from.
+ *
+ * @remarks
+ * The vendored host is staged from this package's checkout, so overwriting it from the host deletes
+ * and replaces its own canon.
+ */
+export const SCAFFOLD = '@orkestrel/scaffold';
+/** Matches a plain version, optionally with a prerelease. */
+export const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+/**
+ * Names the extension of the running file.
+ *
+ * @remarks
+ * The checkout runs the `.ts` sources and a built twin under `dist/agents` runs `.js` siblings.
+ */
+export const EXTENSION = extname(fileURLToPath(import.meta.url));
+/** Holds the path of the sibling `compare` script. */
+export const COMPARE = fileURLToPath(new URL(`./compare${EXTENSION}`, import.meta.url));
+/** Holds the path of the sibling `pins` script. */
+export const PINS = fileURLToPath(new URL(`./pins${EXTENSION}`, import.meta.url));
+/**
+ * Matches one entry of `git status --porcelain=v1 -z` output.
+ *
+ * @remarks
+ * A rename or copy entry carries its original path as a second NUL-terminated field. The first
+ * group holds a rename's new path, the second its original, and the third any other entry's path.
+ */
+export const DIRTY_ENTRY = /(?=[RC][^\0]|[^\0][RC])[^\0]{2} ([^\0]*)\0([^\0]*)(?:\0|$)|[^\0]{2} ([^\0]*)(?:\0|$)/gu;
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = [
+    '--visit',
+    '--plan',
+    '--target',
+    '--offline',
+    '--regenerate',
+    '--from',
+    '--to',
+    '--prior',
+    '--dry-run',
+    '--json',
+    '--out',
+    '--catalog',
+];
+/** Holds the usage line the script prints when no mode was given. */
+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]';
+/** Names the manifest fields that hold specs, including nested overrides. */
+export const SPEC_FIELDS = Object.freeze([
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+    'overrides',
+]);
+/** Matches npm local prefixes and path starts, including drive-relative paths. */
+export const LOCAL_SPEC_PATTERN = /^(?:file:|link:|\.|~[\\/]|[\\/]|[A-Za-z]:)/iu;
+/** Matches archive specs with no protocol and a tgz, tar.gz, or tar extension. */
+export const ARCHIVE_SPEC_PATTERN = /^[^:]+\.(?:tgz|tar\.gz|tar)$/iu;
+/** Matches hosted user/repository shorthand even when its name ends in an archive extension. */
+export const SHORTHAND_SPEC_PATTERN = /^[^:@%/\s.-][^:@%/\s]*\/[^:@\s/%]+$/u;
+/**
+ * Checks whether a value is a non-null, non-array object.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is an object other than null or an array; false otherwise.
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Checks whether npm resolves a spec from the local host.
+ *
+ * @param spec - The package spec, with leading whitespace ignored.
+ * @returns True if the spec names a local path or archive; false otherwise.
+ */
+export function matchesLocalSpec(spec) {
+    const text = spec.trimStart();
+    return (LOCAL_SPEC_PATTERN.test(text) ||
+        (ARCHIVE_SPEC_PATTERN.test(text) && !SHORTHAND_SPEC_PATTERN.test(text)));
+}
+/**
+ * Collects string specs with the dotted path of each nested record member.
+ *
+ * @param path - The field path that prefixes each finding.
+ * @param value - A string or finite, acyclic manifest record; other values contribute no specs.
+ * @returns The path and spec pairs in record order.
+ */
+export function collectSpecs(path, value) {
+    if (typeof value === 'string')
+        return [[path, value]];
+    if (!isRecord(value))
+        return [];
+    return Object.entries(value).flatMap(([key, child]) => collectSpecs(`${path}.${key}`, child));
+}
+/**
+ * Finds local specs in the manifest's spec fields, including nested overrides.
+ *
+ * @param manifest - A finite, acyclic package manifest record.
+ * @returns Each local spec's dotted field path and spec, in field and record order.
+ */
+export function scanLocalSpecs(manifest) {
+    return SPEC_FIELDS.flatMap((field) => collectSpecs(field, manifest[field]).filter(([, spec]) => matchesLocalSpec(spec)));
+}
+/**
+ * Removes a tree with bounded retries for transient host removal errors.
+ *
+ * @param path - The directory to remove; a missing path succeeds.
+ * @returns Nothing after the removal succeeds.
+ * @throws Thrown when removal fails after the bounded retries or the host refuses the path.
+ */
+export function removeTree(path) {
+    rmSync(path, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+}
+/**
+ * Normalizes a host path to forward slashes.
+ *
+ * @param path - A host path.
+ * @returns The same path with every backslash replaced by a slash.
+ */
+export function normalizeSlashes(path) {
+    return path.split('\\').join('/');
+}
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * Reads `--flag value` pairs: the first occurrence of a flag wins, a following value that opens
+ * with `--` is a missing value, and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--target`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * Reads the arguments before a bare `--`, which opens a command a script passes on. A `--flag=value`
+ * argument is unknown, because the script reads no such form.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Reads the last non-empty line of a text as a JSON object.
+ *
+ * @param text - Text whose last line a script printed as JSON.
+ * @returns The parsed object, or undefined when the last line is not a JSON object.
+ */
+export function parseJsonLine(text) {
+    const line = text
+        .split(/\r\n|\n/)
+        .filter((candidate) => candidate.trim() !== '')
+        .at(-1);
+    if (line === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return Object.fromEntries(Object.entries(parsed));
+        }
+    }
+    catch { }
+    return undefined;
+}
+/**
+ * Parses a whole text as one JSON object.
+ *
+ * @param text - A JSON document, formatted or not, such as a manifest or `npm view --json` output.
+ * @returns The parsed object, or undefined when the text is not a JSON object.
+ */
+export function parseJsonRecord(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return Object.fromEntries(Object.entries(parsed));
+        }
+    }
+    catch { }
+    return undefined;
+}
+/**
+ * Reads a string member of a record.
+ *
+ * @param record - The record, or undefined.
+ * @param key - The member name.
+ * @returns The string, or undefined when the member is absent or not a string.
+ */
+export function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Resolves the npm command for this host.
+ *
+ * @remarks
+ * The `npm-cli.js` entry beside the running Node binary spawns without a shell on every host; the
+ * `npm` shim on Windows is a `.cmd` file that needs one, so that path is the fallback alone.
+ *
+ * @returns The file to spawn, the arguments that precede npm's own, and whether a shell is needed.
+ */
+export function resolveNpm() {
+    const cli = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (existsSync(cli))
+        return { file: process.execPath, prefix: [cli], shell: false };
+    return { file: 'npm', prefix: [], shell: process.platform === 'win32' };
+}
+/**
+ * Runs npm with the given arguments and returns the finished child.
+ *
+ * @param args - The npm arguments, such as `['install']`.
+ * @param cwd - The working directory. Default: the current directory.
+ * @returns The spawn result with `utf8` stdout and stderr.
+ */
+export function runNpm(args, cwd) {
+    const npm = resolveNpm();
+    return spawnSync(npm.file, [...npm.prefix, ...args], {
+        encoding: 'utf8',
+        windowsHide: true,
+        shell: npm.shell,
+        maxBuffer: 64 * 1024 * 1024,
+        ...(cwd === undefined ? {} : { cwd }),
+    });
+}
+/**
+ * Reads a target's package manifest.
+ *
+ * @param target - The target directory.
+ * @returns The manifest record, or undefined when it is absent, unreadable, or not a JSON object.
+ */
+export function readManifest(target) {
     try {
         return parseJsonRecord(readFileSync(join(target, 'package.json'), 'utf8'));
     }
@@ -37,7 +285,14 @@ function readManifest(target) {
         return undefined;
     }
 }
-function readRanges(manifest, fields) {
+/**
+ * Reads the ranges a manifest declares in the named fields.
+ *
+ * @param manifest - The manifest record.
+ * @param fields - The fields to read.
+ * @returns Each string range keyed by `field name`.
+ */
+export function readRanges(manifest, fields) {
     return new Map(fields.flatMap((field) => {
         const block = manifest[field];
         if (typeof block !== 'object' || block === null)
@@ -45,7 +300,14 @@ function readRanges(manifest, fields) {
         return Object.entries(block).flatMap(([name, range]) => typeof range === 'string' ? [[`${field} ${name}`, range]] : []);
     }));
 }
-function compareRanges(published, final) {
+/**
+ * Lists how the final ranges differ from the published ones.
+ *
+ * @param published - The ranges the published manifest declares.
+ * @param final - The ranges the target declares now.
+ * @returns One message per range added, removed, or changed, sorted by key.
+ */
+export function compareRanges(published, final) {
     const names = [...new Set([...published.keys(), ...final.keys()])].sort();
     return names.flatMap((name) => {
         const before = published.get(name);
@@ -59,7 +321,14 @@ function compareRanges(published, final) {
         return [`${name} ${before} -> ${after}`];
     });
 }
-function resolveScaffold(target) {
+/**
+ * Resolves the scaffold executable a target runs.
+ *
+ * @param target - The target directory.
+ * @returns Node and the installed scaffold entry, else Node and the target's own built entry, else
+ * none.
+ */
+export function resolveScaffold(target) {
     const installed = join(target, 'node_modules', '@orkestrel', 'scaffold', 'dist', 'bin', 'main.js');
     if (existsSync(installed))
         return [process.execPath, installed];
@@ -68,8 +337,15 @@ function resolveScaffold(target) {
         return [process.execPath, own];
     return [];
 }
-function readReleases(text) {
-    const releases = readJsonObject(text)?.releases;
+/**
+ * Reads the release readings out of an audit's standard output.
+ *
+ * @param text - The audit's standard output, whose last line is the JSON envelope.
+ * @returns One release per reading that names a dependency and its range, or undefined when the
+ * envelope carries no `releases` list.
+ */
+export function readReleases(text) {
+    const releases = parseJsonLine(text)?.releases;
     if (!Array.isArray(releases))
         return undefined;
     return releases.flatMap((entry) => {
@@ -83,15 +359,30 @@ function readReleases(text) {
         return [{ name, range, latest: readString(record, 'latest') }];
     });
 }
-function describeCommand(file, args) {
+/**
+ * Renders a command as the line a step row carries.
+ *
+ * @param file - The executable.
+ * @param args - Its arguments.
+ * @returns The command line, naming the running Node binary as `node`.
+ */
+export function renderCommand(file, args) {
     return [file === process.execPath ? 'node' : file, ...args].join(' ');
 }
-// A JSON verb writes its refusal envelope or its partial-run note on stdout, so the stderr tail
-// alone reads empty for exactly the failures the operator needs named.
-function describeFailure(result) {
+/**
+ * Names why a finished command failed.
+ *
+ * @remarks
+ * A JSON verb writes its refusal envelope or its partial-run note on stdout, so the stderr tail
+ * alone reads empty for exactly the failures the operator needs named.
+ *
+ * @param result - The finished command.
+ * @returns Nothing for exit 0; else the `code: message` envelope, the `note`, or the last stderr lines.
+ */
+export function describeFailure(result) {
     if (result.status === 0)
         return undefined;
-    const value = readJsonObject(result.stdout);
+    const value = parseJsonLine(result.stdout);
     const error = value?.error;
     if (typeof error === 'object' && error !== null && !Array.isArray(error)) {
         const envelope = Object.fromEntries(Object.entries(error));
@@ -109,13 +400,33 @@ function describeFailure(result) {
         .slice(-3)
         .join(' | ');
 }
-function readVerdict(result) {
+/**
+ * Reads the verdict of a finished command by its exit alone.
+ *
+ * @param result - The finished command.
+ * @returns The exit and the failure note.
+ */
+export function readVerdict(result) {
     return { exit: result.status ?? undefined, note: describeFailure(result) };
 }
-// A judge reads the finished command and answers the exit and note its one log entry carries, so no
-// entry is amended after it is appended.
-function runStep(runner, step, file, args, cwd, judge = readVerdict, input) {
-    const command = describeCommand(file, args);
+/**
+ * Runs a command as one step of the visit and logs its row.
+ *
+ * @remarks
+ * A judge reads the finished command and answers the exit and note its one log entry carries, so no
+ * entry is amended after it is appended.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step's name.
+ * @param file - The executable.
+ * @param args - Its arguments.
+ * @param cwd - The working directory.
+ * @param judge - Reads the exit and note from the result. Default: {@link readVerdict}.
+ * @param input - Standard input for the command. Default: none.
+ * @returns The finished command, or undefined under --dry-run.
+ */
+export function runStep(runner, step, file, args, cwd, judge = readVerdict, input) {
+    const command = renderCommand(file, args);
     if (runner.dry) {
         runner.steps.push({ step, command, exit: undefined, durationMs: 0, note: 'dry run' });
         return undefined;
@@ -133,8 +444,17 @@ function runStep(runner, step, file, args, cwd, judge = readVerdict, input) {
     appendResult(runner, step, command, result, durationMs, verdict);
     return result;
 }
-// The audit exits 1 on the drift the pin step exists to close, so its exit is a reading here.
-function judgePin(result) {
+/**
+ * Judges the pin step's audit.
+ *
+ * @remarks
+ * The audit exits 1 on the drift the pin step exists to close, so its exit is a reading here.
+ *
+ * @param result - The audit.
+ * @returns Exit 0 with the reading count when the audit printed releases and exited 0 or 1; else a
+ * failing exit with the reason.
+ */
+export function judgePin(result) {
     const releases = readReleases(result.stdout);
     if (releases === undefined || (result.status !== 0 && result.status !== 1)) {
         return {
@@ -144,16 +464,34 @@ function judgePin(result) {
     }
     return { exit: 0, note: `${releases.length} release reading(s)` };
 }
-function judgeOverwrite(result, offline) {
+/**
+ * Judges the overwrite command.
+ *
+ * @param result - The overwrite.
+ * @param offline - If `true`, an exit of 1 whose note names the catalog refusal passes; if `false`,
+ * the exit alone decides.
+ * @returns The verdict.
+ */
+export function judgeOverwrite(result, offline) {
     if (!offline || result.status !== 1)
         return readVerdict(result);
-    const note = readString(readJsonObject(result.stdout), 'note');
+    const note = readString(parseJsonLine(result.stdout), 'note');
     return note !== undefined && note.includes(OFFLINE_REFUSAL)
         ? { exit: 0, note: 'offline overwrite skipped the catalog step by design' }
         : { exit: 1, note: describeFailure(result) };
 }
-// The audit reads the canonical sources of scaffold's own checkout as foreign paths and exits 1.
-function judgeVerify(result, own) {
+/**
+ * Judges the verify step's audit.
+ *
+ * @remarks
+ * The audit reads the canonical sources of scaffold's own checkout as foreign paths and exits 1.
+ *
+ * @param result - The audit.
+ * @param own - If `true`, the target is scaffold's own checkout and an exit of 1 passes; if `false`,
+ * the exit alone decides.
+ * @returns The verdict; an audit that printed no releases envelope fails.
+ */
+export function judgeVerify(result, own) {
     if (readReleases(result.stdout) === undefined) {
         return {
             exit: result.status === null || result.status === 0 ? 2 : result.status,
@@ -164,7 +502,16 @@ function judgeVerify(result, own) {
         ? { exit: 0, note: 'foreign-path findings are expected on the scaffold checkout' }
         : readVerdict(result);
 }
-function runNpmStep(runner, step, args, judge = readVerdict) {
+/**
+ * Runs npm as one step of the visit and logs its row.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step's name.
+ * @param args - The npm arguments.
+ * @param judge - Reads the exit and note from the result. Default: {@link readVerdict}.
+ * @returns The finished command, or undefined under --dry-run.
+ */
+export function runNpmStep(runner, step, args, judge = readVerdict) {
     const command = `npm ${args.join(' ')}`;
     if (runner.dry) {
         runner.steps.push({
@@ -183,7 +530,19 @@ function runNpmStep(runner, step, args, judge = readVerdict) {
     appendResult(runner, step, command, result, Date.now() - started, judge(result));
     return result;
 }
-function writeJournal(runner, step, command, exit, stdout, stderr) {
+/**
+ * Writes one step's full output to the visit's journal directory.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step's name.
+ * @param command - The command line.
+ * @param exit - The exit code.
+ * @param stdout - The standard output.
+ * @param stderr - The standard error.
+ * @returns The journal path, the failure that stopped the write, or neither when the visit keeps no
+ * journal.
+ */
+export function writeJournal(runner, step, command, exit, stdout, stderr) {
     if (runner.directory === undefined)
         return {};
     const path = join(runner.directory, `${String(runner.steps.length + 1).padStart(2, '0')}-${step}.log`);
@@ -198,7 +557,18 @@ function writeJournal(runner, step, command, exit, stdout, stderr) {
         return { failure: `journal failed: ${path}: ${String(error)}` };
     }
 }
-function appendResult(runner, step, command, result, durationMs, verdict) {
+/**
+ * Appends a finished command's row to the visit's log.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step's name.
+ * @param command - The command line.
+ * @param result - The finished command.
+ * @param durationMs - How long it ran.
+ * @param verdict - The exit and note to record; a journal failure turns the exit into 1.
+ * @returns Nothing after the row is appended.
+ */
+export function appendResult(runner, step, command, result, durationMs, verdict) {
     const journal = writeJournal(runner, step, command, result.status ?? undefined, result.stdout ?? '', result.stderr ?? '');
     runner.steps.push({
         step,
@@ -213,7 +583,17 @@ function appendResult(runner, step, command, result, durationMs, verdict) {
             }),
     });
 }
-function appendStep(runner, step, command, note, exit = 0) {
+/**
+ * Appends a row for a step the script ran itself.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step's name.
+ * @param command - The label the row carries as its command.
+ * @param note - What the step found or did.
+ * @param exit - The exit the row records. Default: 0.
+ * @returns Nothing after the row is appended.
+ */
+export function appendStep(runner, step, command, note, exit = 0) {
     const journal = runner.dry ? {} : writeJournal(runner, step, command, exit, note, '');
     runner.steps.push({
         step,
@@ -224,14 +604,32 @@ function appendStep(runner, step, command, note, exit = 0) {
         ...(journal.path === undefined ? {} : { journal: journal.path }),
     });
 }
-function failed(runner) {
-    return runner.steps.some((entry) => entry.superseded !== true &&
+/**
+ * Checks whether a visit's log holds a failure.
+ *
+ * @remarks
+ * The one predicate the visit's steps and the script's exit code share. A superseded row, a row with
+ * no exit (a dry run), and a pins or compare row are readings, not failures.
+ *
+ * @param steps - The rows logged so far.
+ * @returns True if a row exited nonzero, was not superseded, and is not a pins or compare row; false
+ * otherwise.
+ */
+export function failed(steps) {
+    return steps.some((entry) => entry.superseded !== true &&
         entry.exit !== undefined &&
         entry.exit !== 0 &&
         entry.step !== 'pins' &&
         entry.step !== 'compare');
 }
-function extractConflict(result) {
+/**
+ * Reads the resolution conflict an install reported.
+ *
+ * @param result - The finished install.
+ * @returns The conflict line npm printed, a generic reason when it printed none, or undefined when
+ * the install did not fail with ERESOLVE.
+ */
+export function extractConflict(result) {
     const output = `${result.stdout}\n${result.stderr}`;
     if (!/\bcode ERESOLVE\b/u.test(output))
         return undefined;
@@ -239,7 +637,14 @@ function extractConflict(result) {
     return ((lines.find((line) => line.includes('Conflicting peer dependency:')) ??
         lines.find((line) => line.includes('Could not resolve dependency:')))?.replace(/^npm (?:error|ERR!)\s*/u, '') ?? 'the install could not move a locked peer');
 }
-function runInstall(runner, step) {
+/**
+ * Runs the install and regenerates the lock when asked and the install cannot resolve.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step the rows belong to.
+ * @returns Nothing after the rows are appended.
+ */
+export function runInstall(runner, step) {
     // npm can unlink a node_modules junction before reporting its resolution failure.
     if (!runner.dry &&
         runner.regenerate &&
@@ -264,14 +669,28 @@ function runInstall(runner, step) {
         runner.regenerate)
         regenerateLock(runner, step, installed);
 }
-function refuseLocalSpecs(runner, step) {
+/**
+ * Refuses a manifest that holds local dependency specs.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step that refuses.
+ * @returns True if a failing row was appended; false when the manifest holds none.
+ */
+export function refuseLocalSpecs(runner, step) {
     const specs = scanLocalSpecs(readManifest(runner.target) ?? {});
     if (specs.length === 0)
         return false;
     appendStep(runner, step, 'scan manifest specs', `local dependency specs: ${specs.map(([path, spec]) => `${path}: ${spec}`).join(', ')}; restore the pins first`, 1);
     return true;
 }
-function readRegenerationRefusal(runner) {
+/**
+ * Names why the lock must not be regenerated.
+ *
+ * @param runner - The visit's state.
+ * @returns The first refusal, or undefined when the lock is tracked and clean, the manifest holds no
+ * local spec or workspace, `tmp/` is ignored, and the target is its work tree's root.
+ */
+export function readRegenerationRefusal(runner) {
     if (runStep(runner, 'regenerate', 'git', ['ls-files', '--error-unmatch', 'package-lock.json'], runner.target)?.status !== 0)
         return 'package-lock.json is untracked';
     const status = runStep(runner, 'regenerate', 'git', ['status', '--porcelain', '--', 'package-lock.json'], runner.target);
@@ -291,7 +710,16 @@ function readRegenerationRefusal(runner) {
         return 'the target is not the root of its work tree';
     return undefined;
 }
-function moveModules(source, target, attempt = 0) {
+/**
+ * Renames a directory, retrying while the host holds it.
+ *
+ * @param source - The directory to move.
+ * @param target - Its new path.
+ * @param attempt - The retries spent so far. Default: 0.
+ * @returns Nothing after the rename.
+ * @throws Thrown when the rename fails for another reason or after the retries.
+ */
+export function moveModules(source, target, attempt = 0) {
     try {
         renameSync(source, target);
     }
@@ -302,7 +730,15 @@ function moveModules(source, target, attempt = 0) {
         moveModules(source, target, attempt + 1);
     }
 }
-function regenerateLock(runner, step, conflict) {
+/**
+ * Regenerates the lock and the installed tree from the manifest.
+ *
+ * @param runner - The visit's state.
+ * @param step - The step the rows belong to.
+ * @param conflict - The install that failed with ERESOLVE.
+ * @returns Nothing after the rows are appended; a failed regeneration restores the tree and lock.
+ */
+export function regenerateLock(runner, step, conflict) {
     const refusal = readRegenerationRefusal(runner);
     if (refusal !== undefined || runner.directory === undefined) {
         appendStep(runner, step, 'regenerate lock and modules', `ERESOLVE; regeneration refused: ${refusal ?? 'tmp/ is not git-ignored'}`, 1);
@@ -348,8 +784,18 @@ function regenerateLock(runner, step, conflict) {
     if (result.listed !== undefined)
         appendResult(runner, step, 'npm ls --all --json', result.listed, 0, readVerdict(result.listed));
 }
-// Journal writes and backup disposal cannot enter the transaction's rollback boundary.
-function regenerateTree(target, manifest, before) {
+/**
+ * Installs from a manifest with no lock and proves the tree.
+ *
+ * @remarks
+ * Journal writes and backup disposal cannot enter the transaction's rollback boundary.
+ *
+ * @param target - The target directory.
+ * @param manifest - The manifest bytes before the install.
+ * @param before - The SHA-256 of the lock before.
+ * @returns Exit 0 when the install, the tree listing, and the unchanged manifest prove it; else exit 1.
+ */
+export function regenerateTree(target, manifest, before) {
     const lock = join(target, 'package-lock.json');
     try {
         unlinkSync(lock);
@@ -374,7 +820,15 @@ function regenerateTree(target, manifest, before) {
         return { exit: 1, note: `ERESOLVE; ${String(error)}` };
     }
 }
-function discardBackup(target, moved, backup) {
+/**
+ * Discards the backups after a proved regeneration.
+ *
+ * @param target - The target directory.
+ * @param moved - The moved previous tree.
+ * @param backup - The saved lock.
+ * @returns Nothing on success, else the failure with the backup paths kept.
+ */
+export function discardBackup(target, moved, backup) {
     try {
         for (const path of [moved, backup, join(target, 'node_modules')])
             validateWavePath(target, path);
@@ -385,7 +839,16 @@ function discardBackup(target, moved, backup) {
         return `backup cleanup failed: ${String(error)}; proved installation retained; backups: ${backup}; ${moved}`;
     }
 }
-function restoreLock(target, moved, backup, before) {
+/**
+ * Restores the previous tree and lock after a failed regeneration.
+ *
+ * @param target - The target directory.
+ * @param moved - The moved previous tree.
+ * @param backup - The saved lock.
+ * @param before - The SHA-256 the saved lock must still have.
+ * @returns `tree and lock restored`, else the failure with the backup paths kept.
+ */
+export function restoreLock(target, moved, backup, before) {
     try {
         for (const path of [
             moved,
@@ -408,7 +871,16 @@ function restoreLock(target, moved, backup, before) {
         return `rollback failed: ${String(error)}; backups: ${backup}; ${moved}`;
     }
 }
-function validateWavePath(target, destination) {
+/**
+ * Checks that a destination stays inside the target and crosses no link.
+ *
+ * @param target - The target directory.
+ * @param destination - The path to write or remove.
+ * @returns Nothing when the path is safe.
+ * @throws Thrown when the path resolves outside the target, an ancestor is a link or not a
+ * directory, or an ancestor's real location leaves the target's.
+ */
+export function validateWavePath(target, destination) {
     const root = resolve(target);
     const path = resolve(destination);
     const location = relative(root, path);
@@ -432,19 +904,26 @@ function validateWavePath(target, destination) {
             throw new Error(`unsafe wave path: ${entry} resolves outside ${physical}`);
     }
 }
-function readDirtyPaths(text) {
-    const [entry, ...rest] = text.split('\0');
-    if (entry === undefined || entry === '')
-        return [];
-    const renamed = /[RC]/u.test(entry.slice(0, 2));
-    const original = renamed ? rest[0] : undefined;
-    return [
-        entry.slice(3),
-        ...(original === undefined ? [] : [original]),
-        ...readDirtyPaths((renamed ? rest.slice(1) : rest).join('\0')),
-    ];
+/**
+ * Reads the dirty paths out of `git status --porcelain=v1 -z` output.
+ *
+ * @remarks
+ * One pass over the entries with {@link DIRTY_ENTRY}, so the cost grows with the text and no entry
+ * recurses.
+ *
+ * @param text - The command's standard output.
+ * @returns Each entry's path; a rename or copy also lists its original path.
+ */
+export function readDirtyPaths(text) {
+    return [...text.matchAll(DIRTY_ENTRY)].flatMap((match) => match[1] === undefined ? [match[3] ?? ''] : [match[1], match[2] ?? '']);
 }
-function readReceipt(target) {
+/**
+ * Reads the receipt the overwrite step left.
+ *
+ * @param target - The target directory.
+ * @returns The receipt, or undefined when it is absent, unreadable, or lacks a field in its type.
+ */
+export function readReceipt(target) {
     try {
         const value = parseJsonRecord(readFileSync(join(target, 'tmp', 'units', 'wave', 'overwrite.json'), 'utf8'));
         if (value === undefined ||
@@ -468,7 +947,15 @@ function readReceipt(target) {
         return undefined;
     }
 }
-function runRecord(runner, name) {
+/**
+ * Runs the record step.
+ *
+ * @param runner - The visit's state.
+ * @param name - The package name the manifest declares.
+ * @returns Nothing after the rows are appended; the overwrite's paths are committed when the receipt
+ * attributes every dirty path to them.
+ */
+export function runRecord(runner, name) {
     if (name === SCAFFOLD) {
         appendStep(runner, 'record', 'git commit', `skipped: ${SCAFFOLD}`);
         return;
@@ -509,17 +996,26 @@ function runRecord(runner, name) {
         return;
     }
     runStep(runner, 'record', 'git', ['--literal-pathspecs', 'add', '-A', '--pathspec-from-file=-', '--pathspec-file-nul'], runner.target, readVerdict, `${dirty.join('\0')}\0`);
-    if (failed(runner))
+    if (failed(runner.steps))
         return;
     runStep(runner, 'record', 'git', ['commit', '-m', `Overwrite with scaffold ${receipt.version}`], runner.target);
-    if (failed(runner))
+    if (failed(runner.steps))
         return;
     runStep(runner, 'record', 'git', ['status', '--porcelain'], runner.target, (result) => result.status === 0 && result.stdout.trim() !== ''
         ? { exit: 1, note: `tree remains dirty: ${result.stdout}` }
         : readVerdict(result));
 }
-// A later release of the same name reads the range the earlier reading wrote.
-function computeRanges(ranges, releases) {
+/**
+ * Moves each named dependency to the registry caret of its latest release.
+ *
+ * @remarks
+ * A later release of the same name reads the range the earlier reading wrote.
+ *
+ * @param ranges - The block's ranges by name.
+ * @param releases - The audit's release readings.
+ * @returns The ranges after the moves and one message per move.
+ */
+export function computeRanges(ranges, releases) {
     return releases.reduce((state, release) => {
         if (release.latest === undefined || !(release.name in state.ranges))
             return state;
@@ -532,7 +1028,14 @@ function computeRanges(ranges, releases) {
             };
     }, { ranges, moved: [] });
 }
-function writeRanges(target, releases) {
+/**
+ * Writes the re-pinned ranges into the target's manifest.
+ *
+ * @param target - The target directory.
+ * @param releases - The audit's release readings.
+ * @returns One message per range moved; the manifest is rewritten only when a range moved.
+ */
+export function writeRanges(target, releases) {
     const manifest = readManifest(target);
     if (manifest === undefined)
         return [];
@@ -552,7 +1055,16 @@ function writeRanges(target, releases) {
     }
     return moved;
 }
-function runPin(runner, scaffoldFile, scaffoldPrefix, offline) {
+/**
+ * Runs the pin step.
+ *
+ * @param runner - The visit's state.
+ * @param scaffoldFile - The scaffold executable.
+ * @param scaffoldPrefix - The arguments that precede scaffold's own.
+ * @param offline - The `--offline` argument, or none.
+ * @returns Nothing after the rows are appended.
+ */
+export function runPin(runner, scaffoldFile, scaffoldPrefix, offline) {
     const audit = runStep(runner, 'pin', scaffoldFile, [...scaffoldPrefix, 'audit', '--json', ...offline], runner.target, judgePin);
     if (audit !== undefined) {
         const releases = readReleases(audit.stdout);
@@ -566,7 +1078,13 @@ function runPin(runner, scaffoldFile, scaffoldPrefix, offline) {
     }
     runInstall(runner, 'pin');
 }
-function runCommit(runner) {
+/**
+ * Runs the commit step.
+ *
+ * @param runner - The visit's state.
+ * @returns Nothing after the rows are appended.
+ */
+export function runCommit(runner) {
     if (refuseLocalSpecs(runner, 'commit'))
         return;
     const status = runStep(runner, 'commit', 'git', ['status', '--porcelain', '--', 'package.json', 'package-lock.json'], runner.target);
@@ -585,10 +1103,19 @@ function runCommit(runner) {
         appendStep(runner, 'commit', 'git commit', 'manifest and lockfile already committed');
     }
 }
-function runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline) {
+/**
+ * Runs the overwrite step.
+ *
+ * @param runner - The visit's state.
+ * @param scaffoldFile - The scaffold executable.
+ * @param scaffoldPrefix - The arguments that precede scaffold's own.
+ * @param offline - The `--offline` argument, or none.
+ * @returns Nothing after the rows are appended and the receipt is written.
+ */
+export function runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline) {
     const overwrite = runStep(runner, 'overwrite', scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline], runner.target, (result) => judgeOverwrite(result, runner.offline));
-    if (overwrite !== undefined && !failed(runner) && runner.directory !== undefined) {
-        const receipt = readJsonObject(overwrite.stdout);
+    if (overwrite !== undefined && !failed(runner.steps) && runner.directory !== undefined) {
+        const receipt = parseJsonLine(overwrite.stdout);
         const head = runStep(runner, 'overwrite', 'git', ['rev-parse', 'HEAD'], runner.target);
         const installed = readManifest(join(runner.target, 'node_modules', '@orkestrel', 'scaffold'));
         const version = readString(installed, 'version');
@@ -610,11 +1137,21 @@ function runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline) {
             }
         }
     }
-    if (!failed(runner)) {
+    if (!failed(runner.steps)) {
         runStep(runner, 'overwrite', scaffoldFile, [...scaffoldPrefix, 'audit', ...offline], runner.target);
     }
 }
-function runVerify(runner, scaffoldFile, scaffoldPrefix, offline, own) {
+/**
+ * Runs the verify step.
+ *
+ * @param runner - The visit's state.
+ * @param scaffoldFile - The scaffold executable.
+ * @param scaffoldPrefix - The arguments that precede scaffold's own.
+ * @param offline - The `--offline` argument, or none.
+ * @param own - If `true`, the target is scaffold's own checkout; if `false`, it is another package.
+ * @returns Nothing after the rows are appended.
+ */
+export function runVerify(runner, scaffoldFile, scaffoldPrefix, offline, own) {
     const audit = runStep(runner, 'verify', scaffoldFile, [...scaffoldPrefix, 'audit', '--json', ...offline], runner.target, (result) => judgeVerify(result, own));
     if (audit === undefined)
         return;
@@ -628,7 +1165,15 @@ function runVerify(runner, scaffoldFile, scaffoldPrefix, offline, own) {
             .map((release) => `${release.name} ${release.range} vs ${String(release.latest)}`)
             .join(', '), drift.length === 0 ? 0 : 1);
 }
-function runPins(runner, before, version) {
+/**
+ * Runs the pins step.
+ *
+ * @param runner - The visit's state.
+ * @param before - The ranges the manifest declared before the visit.
+ * @param version - The version to sweep for, or undefined when none is known.
+ * @returns The number of hit lines, or undefined when the sweep did not run.
+ */
+export function runPins(runner, before, version) {
     const after = readRanges(readManifest(runner.target) ?? {}, RANGE_FIELDS);
     const prior = [...before]
         .filter(([name, range]) => after.get(name) !== range)
@@ -642,7 +1187,14 @@ function runPins(runner, before, version) {
         ? undefined
         : swept.stdout.split(/\r\n|\n/).filter((line) => /^\S+:\d+: /u.test(line)).length;
 }
-function runCompare(runner, name) {
+/**
+ * Runs the compare step.
+ *
+ * @param runner - The visit's state.
+ * @param name - The package name the manifest declares.
+ * @returns The bump ruling the two readings reach.
+ */
+export function runCompare(runner, name) {
     const compared = runStep(runner, 'compare', process.execPath, [COMPARE, '--json'], runner.target);
     const distMoved = compared === undefined
         ? undefined
@@ -663,10 +1215,25 @@ function runCompare(runner, name) {
     const ranges = compareRanges(readRanges(published, RUNTIME_FIELDS), readRanges(readManifest(runner.target) ?? {}, RUNTIME_FIELDS));
     return { distMoved, rangesMoved: ranges.length > 0, ranges, hits: undefined };
 }
-function describeReading(moved, movedWord, sameWord) {
+/**
+ * Words one reading of the ruling.
+ *
+ * @param moved - The reading, or undefined when unanswered.
+ * @param movedWord - The word for a moved reading.
+ * @param sameWord - The word for an unmoved reading.
+ * @returns `unanswered`, the moved word, or the same word.
+ */
+export function describeChange(moved, movedWord, sameWord) {
     return moved === undefined ? 'unanswered' : moved ? movedWord : sameWord;
 }
-function runVisit(argv) {
+/**
+ * Runs one repository's visit.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The finished visit, or undefined when the target carries no readable manifest or no
+ * scaffold executable.
+ */
+export function runVisit(argv) {
     const target = readOption(argv, '--target') ?? process.cwd();
     if (!existsSync(join(target, 'package.json'))) {
         console.error(`wave: ${target} carries no package.json`);
@@ -711,37 +1278,37 @@ function runVisit(argv) {
     }
     const before = readRanges(manifest, RANGE_FIELDS);
     const offline = runner.offline ? ['--offline'] : [];
-    if (selected.has('pin') && !failed(runner))
+    if (selected.has('pin') && !failed(runner.steps))
         runPin(runner, scaffoldFile, scaffoldPrefix, offline);
-    if (selected.has('commit') && !failed(runner))
+    if (selected.has('commit') && !failed(runner.steps))
         runCommit(runner);
-    if (selected.has('overwrite') && !failed(runner)) {
+    if (selected.has('overwrite') && !failed(runner.steps)) {
         if (name === SCAFFOLD) {
-            appendStep(runner, 'overwrite', describeCommand(scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline]), `skipped with its audit: ${SCAFFOLD} is the package whose checkout the vendored host is staged from`);
+            appendStep(runner, 'overwrite', renderCommand(scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline]), `skipped with its audit: ${SCAFFOLD} is the package whose checkout the vendored host is staged from`);
         }
         else
             runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline);
     }
-    if (selected.has('verify') && !failed(runner)) {
+    if (selected.has('verify') && !failed(runner.steps)) {
         runVerify(runner, scaffoldFile, scaffoldPrefix, offline, name === SCAFFOLD);
     }
-    if (selected.has('install') && !failed(runner))
+    if (selected.has('install') && !failed(runner.steps))
         runInstall(runner, 'install');
-    const hits = selected.has('pins') && !failed(runner)
+    const hits = selected.has('pins') && !failed(runner.steps)
         ? runPins(runner, before, readOption(argv, '--prior') ?? version)
         : undefined;
-    if (selected.has('format') && !failed(runner))
+    if (selected.has('format') && !failed(runner.steps))
         runNpmStep(runner, 'format', ['run', 'format']);
-    if (selected.has('record') && !failed(runner))
+    if (selected.has('record') && !failed(runner.steps))
         runRecord(runner, name);
-    if (selected.has('gates') && !failed(runner)) {
+    if (selected.has('gates') && !failed(runner.steps)) {
         for (const gate of GATES) {
-            if (failed(runner))
+            if (failed(runner.steps))
                 break;
             runNpmStep(runner, 'gates', ['run', gate]);
         }
     }
-    const compared = selected.has('compare') && !failed(runner)
+    const compared = selected.has('compare') && !failed(runner.steps)
         ? runCompare(runner, name)
         : { distMoved: undefined, rangesMoved: undefined, ranges: undefined, hits: undefined };
     const ruling = { ...compared, hits };
@@ -750,17 +1317,24 @@ function runVisit(argv) {
         : ruling.distMoved === undefined || ruling.rangesMoved === undefined
             ? 'unanswered'
             : 'no bump';
-    const reading = `dist ${describeReading(ruling.distMoved, 'moved', 'same')}, ranges ${describeReading(ruling.rangesMoved, 'moved', 'same')}${hits === undefined ? '' : `, ${hits} self-pin hit(s)`}`;
+    const changes = `dist ${describeChange(ruling.distMoved, 'moved', 'same')}, ranges ${describeChange(ruling.rangesMoved, 'moved', 'same')}${hits === undefined ? '' : `, ${hits} self-pin hit(s)`}`;
     return {
         target,
         name,
         version,
         steps: runner.steps,
         ruling,
-        row: `| ${name ?? target} | ${version ?? '?'} | ${bump} | ${reading} | round |`,
+        row: `| ${name ?? target} | ${version ?? '?'} | ${bump} | ${changes} | round |`,
     };
 }
-function readJournalDirectory(target) {
+/**
+ * Chooses the directory a visit journals its steps in.
+ *
+ * @param target - The target directory.
+ * @returns A new stamped directory under the target's `tmp/units/wave/` when the target is inside a
+ * work tree that ignores `tmp/`, else undefined.
+ */
+export function readJournalDirectory(target) {
     const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
         cwd: target,
         encoding: 'utf8',
@@ -777,7 +1351,14 @@ function readJournalDirectory(target) {
         ? join(target, 'tmp', 'units', 'wave', new Date().toISOString().replace(/[:.]/gu, '-'))
         : undefined;
 }
-function readLayers(catalogPath) {
+/**
+ * Reads the packages by layer out of the catalog table.
+ *
+ * @param catalogPath - The agent file that carries the marker-bounded table.
+ * @returns Each layer's `name range` members, layers in numeric order, or undefined when the file or
+ * its markers are absent.
+ */
+export function readLayers(catalogPath) {
     if (!existsSync(catalogPath))
         return undefined;
     const text = readFileSync(catalogPath, 'utf8');
@@ -798,16 +1379,34 @@ function readLayers(catalogPath) {
         .map(([layer, members]) => [layer, members.map(({ member }) => member)])
         .sort(([left], [right]) => Number(left.slice(1)) - Number(right.slice(1))));
 }
-function renderVisit(visit) {
+/**
+ * Renders a visit as text lines.
+ *
+ * @param visit - The finished visit.
+ * @returns One line per step, the ruling, each moved range, and the release row.
+ */
+export function renderVisit(visit) {
     const lines = [
         ...visit.steps.map((entry) => `wave: ${entry.step.padEnd(9)} exit=${entry.exit === undefined ? 'dry' : String(entry.exit)} ${String(entry.durationMs).padStart(7)} ms  ${entry.command}${entry.note === undefined ? '' : `  (${entry.note})`}${entry.journal === undefined ? '' : `  journal=${entry.journal}`}`),
-        `wave: ruling dist ${describeReading(visit.ruling.distMoved, 'moved', 'same')}, ranges ${describeReading(visit.ruling.rangesMoved, 'moved', 'same')}${visit.ruling.hits === undefined ? '' : `, ${visit.ruling.hits} self-pin hit(s)`}`,
+        `wave: ruling dist ${describeChange(visit.ruling.distMoved, 'moved', 'same')}, ranges ${describeChange(visit.ruling.rangesMoved, 'moved', 'same')}${visit.ruling.hits === undefined ? '' : `, ${visit.ruling.hits} self-pin hit(s)`}`,
         ...(visit.ruling.ranges ?? []).map((range) => `wave: range ${range}`),
         visit.row,
     ];
     return `${lines.join('\n')}\n`;
 }
-function main(argv) {
+/**
+ * Runs the mode the arguments name.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when every step passed, 1 when one failed, 2 when a reading failed, 64
+ * on usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`wave: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
+        return 64;
+    }
     const missing = readMissingFlags(argv, [
         '--target',
         '--from',
@@ -842,7 +1441,7 @@ function main(argv) {
         return 0;
     }
     if (!argv.includes('--visit')) {
-        console.error('usage: wave.ts --visit [--target DIR] [--offline] [--regenerate] [--from STEP] [--to STEP] [--prior VERSION] [--dry-run] [--json] [--out FILE] | --plan [--catalog PATH] [--json]');
+        console.error(USAGE);
         return 64;
     }
     const from = STEPS.indexOf(readOption(argv, '--from') ?? 'pin');
@@ -868,12 +1467,8 @@ function main(argv) {
         writeFileSync(out, output);
         console.log(`wave: wrote ${out}`);
     }
-    return visit.steps.some((entry) => entry.superseded !== true &&
-        entry.exit !== undefined &&
-        entry.exit !== 0 &&
-        entry.step !== 'pins' &&
-        entry.step !== 'compare')
-        ? 1
-        : 0;
+    return failed(visit.steps) ? 1 : 0;
+}
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    process.exitCode = main(process.argv.slice(2));
 }
-process.exitCode = main(process.argv.slice(2));