@orkestrel/scaffold 0.0.107 → 0.0.109

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

@@ -1,66 +1,45 @@
-// Pin a consumer to fresh local tarballs of the packages it depends on, report every pin against the
-// ledger that records it, and restore the ranges the pins replaced. Run from any directory:
-//   node .agents/skills/orkestrel-publish/scripts/swap.ts --pin --consumer DIR --source DIR [--source DIR ...] [--override NAME ...] [--no-build] [--dry-run] [--json]
-//   node .agents/skills/orkestrel-publish/scripts/swap.ts --restore --consumer DIR [--package NAME ...] [--json]
-//   node .agents/skills/orkestrel-publish/scripts/swap.ts --status --consumer DIR [--json]
-// Give exactly one of --pin, --restore, and --status; --source, --override, and --package repeat.
-// --pin refuses a source whose packed manifest names a local dependency in any dependency field:
-// npm's local forms, a file: or link: prefix, a path start (., ~/, /, \, or a drive letter), or an
-// archive name ending in .tgz, .tar.gz, or .tar that carries no protocol and is not a user/repo
-// shorthand. It builds each source (`npm run build`, unless --no-build), and packs it with
-// --ignore-scripts, a source that carries a ledger of its own packing with the ranges that ledger
-// replaced. Each archive moves to
-// <consumer>/tmp/tarballs/<scope>-<name>-<version>-<12 hex of its SHA-256>.tgz. The ledger
-// <consumer>/tmp/tarballs/pins.json records the replaced range, the tarball and its SHA-256, the
-// source with its commit and dirty flag, whether the overrides block existed before the first pin,
-// and the time, and is written before the manifest. The field that declares each package then takes
-// the tarball's absolute file: spec, because a relative spec breaks after the consumer is itself
-// packed and installed elsewhere. --override NAME sets overrides[NAME] to $NAME when the consumer
-// declares NAME, else to the tarball spec of the source named NAME, and a created block lands where
-// oxfmt sorts it. The install runs with --ignore-scripts and deletes node_modules/.vite, then the
-// proof requires each pinned package, an override-only one included, to be a directory whose file
-// set is its pack list and whose bytes are its source's, no other copy of it to be installed, and
-// every other top-level @orkestrel package to be byte-unchanged; a proved pin records the digest of
-// its installed bytes. --dry-run builds, packs, and writes nothing, and prints the plan.
-// --restore puts back each recorded range (all, or each --package) and every override the pins
-// replaced, keeps an overrides block that existed before the pin, drops the lock entry and the
-// installed copy of each package it restores from the registry or whose override it drops so the
-// install resolves them again, installs, and proves each package is installed at what its range
-// names. Before it writes anything, --restore refuses with 64 a ledger whose package or override
-// keys are not package names, and a removal whose install path resolves outside node_modules.
-// --status writes nothing and reports each drift between the ledger, the manifest, the tarballs, the
-// installed bytes, and the source commits; a manifest spec holds its tarball only when it names the
-// ledger archive's full location.
-// --pin and --restore write a receipt create-only to tmp/units/swap-<consumer>-<time>.json under the
-// working directory. Every mode prints text lines, or one JSON line with --json.
-// Exit 0 on success, 1 when a command or a proof failed, 3 when --status reports drift, 64 on usage.
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, writeFileSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { isRecord, normalizeSlashes, parseJsonRecord, readMissingFlags, readOption, readOptions, readString, removeTree, runNpm, scanLocalSpecs, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const FIELDS = ['dependencies', 'devDependencies'];
-const MODES = ['pin', 'restore', 'status'];
-const TARBALL_DIRECTORY = 'tmp/tarballs';
-const LEDGER_FILE = 'pins.json';
-const RECEIPT_DIRECTORY = 'tmp/units';
-const EXIT_FAILURE = 1;
-const EXIT_DRIFT = 3;
-const EXIT_USAGE = 64;
-const FORMAT_PROBLEM = 'package.json is not tab-indented JSON with a trailing newline; the script would reformat it';
-const VALUE_FLAGS = {
+/** Lists the manifest fields a pin rewrites. */
+export const FIELDS = ['dependencies', 'devDependencies'];
+/** Lists the modes in the order the script checks them. */
+export const MODES = ['pin', 'restore', 'status'];
+/** Names the consumer directory that holds the tarballs and the ledger. */
+export const TARBALL_DIRECTORY = 'tmp/tarballs';
+/** Names the ledger file inside the tarball directory. */
+export const LEDGER_FILE = 'pins.json';
+/** Names the working-directory folder that receives the receipts. */
+export const RECEIPT_DIRECTORY = 'tmp/units';
+/** Holds the exit code for a command or a proof that failed. */
+export const EXIT_FAILURE = 1;
+/** Holds the exit code for a status that reports drift. */
+export const EXIT_DRIFT = 3;
+/** Holds the exit code for a usage refusal. */
+export const EXIT_USAGE = 64;
+/** Holds the refusal for a manifest the script would reformat. */
+export const FORMAT_PROBLEM = 'package.json is not tab-indented JSON with a trailing newline; the script would reformat it';
+/** Lists the value flags each mode reads. */
+export const VALUE_FLAGS = {
     pin: ['--consumer', '--source', '--override'],
     restore: ['--consumer', '--package'],
     status: ['--consumer'],
 };
-const SWITCH_FLAGS = {
+/** Lists the switch flags each mode reads. */
+export const SWITCH_FLAGS = {
     pin: ['--pin', '--no-build', '--dry-run', '--json'],
     restore: ['--restore', '--json'],
     status: ['--status', '--json'],
 };
-// oxfmt 0.72.0 sorts these `package.json` keys ahead of `overrides`; every other key it knows, and
-// every key it does not know, follows it.
-const OVERRIDE_PRECEDERS = [
+/**
+ * Lists the `package.json` keys oxfmt sorts ahead of `overrides`.
+ *
+ * @remarks
+ * Derived for the installed oxfmt, 0.74.0; every other key it knows, and every key it does not know,
+ * follows `overrides`. `swap.test.ts` proves each key against the installed formatter.
+ */
+export const OVERRIDE_PRECEDERS = [
     '$schema',
     'name',
     'displayName',
@@ -123,22 +102,224 @@ const OVERRIDE_PRECEDERS = [
     'bundleDependencies',
     'resolutions',
 ];
-// An optional `@scope/` and a name of the characters a registry URL carries untouched; a path
-// separator beyond the scope's one `/`, an absolute form, and a drive form fall outside it.
-const PACKAGE_NAME_PATTERN = /^(?:@[A-Za-z0-9~-][A-Za-z0-9._~-]*\/)?[A-Za-z0-9~-][A-Za-z0-9._~-]*$/u;
-const PACKAGE_NAME_LIMIT = 214;
-const USAGE = [
+/**
+ * Matches a package name.
+ *
+ * @remarks
+ * An optional `@scope/` and a name of the characters a registry URL carries untouched; a path
+ * separator beyond the scope's one `/`, an absolute form, and a drive form fall outside it.
+ */
+export const PACKAGE_NAME_PATTERN = /^(?:@[A-Za-z0-9~-][A-Za-z0-9._~-]*\/)?[A-Za-z0-9~-][A-Za-z0-9._~-]*$/u;
+/** Holds the longest package name a registry accepts. */
+export const PACKAGE_NAME_LIMIT = 214;
+/** Holds the usage text printed on a usage refusal. */
+export const USAGE = [
     'usage: swap.ts --pin --consumer DIR --source DIR [--source DIR ...] [--override NAME ...] [--no-build] [--dry-run] [--json]',
     '       swap.ts --restore --consumer DIR [--package NAME ...] [--json]',
     '       swap.ts --status --consumer DIR [--json]',
 ].join('\n');
-function isPackageName(name) {
+/** 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 `--consumer`.
+ * @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);
+}
+/**
+ * Reads every value that follows a repeatable flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--source`.
+ * @returns The values in order, empty when the flag never appears.
+ */
+export function readOptions(argv, name) {
+    return argv.flatMap((argument, index) => {
+        const value = argv[index + 1];
+        return argument === name && value !== undefined && !value.startsWith('--') ? [value] : [];
+    });
+}
+/**
+ * Parses a whole text as one JSON object.
+ *
+ * @param text - A JSON document, formatted or not, such as a manifest.
+ * @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 }),
+    });
+}
+/**
+ * Checks whether a ledger key is a package name that stays inside `node_modules`.
+ *
+ * @param name - The ledger key.
+ * @returns True if the key is an optional scope and a name of registry-safe characters within the
+ * registry's length limit and holding no `..`; false otherwise.
+ */
+export function isPackageName(name) {
     return (name.length <= PACKAGE_NAME_LIMIT && !name.includes('..') && PACKAGE_NAME_PATTERN.test(name));
 }
-function isManifestField(value) {
+/**
+ * Checks whether a value names a manifest field a pin rewrites.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is `dependencies` or `devDependencies`; false otherwise.
+ */
+export function isManifestField(value) {
     return value === 'dependencies' || value === 'devDependencies';
 }
-function isLedgerEntry(value) {
+/**
+ * Checks whether a value is a package row of the ledger.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value carries the tarball, hash, source, and time strings and each optional
+ * member in its declared type; false otherwise.
+ */
+export function isLedgerEntry(value) {
     return (isRecord(value) &&
         typeof value.tarball === 'string' &&
         typeof value.sha256 === 'string' &&
@@ -150,14 +331,29 @@ function isLedgerEntry(value) {
         (value.dirty === undefined || typeof value.dirty === 'boolean') &&
         (value.inventory === undefined || typeof value.inventory === 'string'));
 }
-function isOverrideEntry(value) {
+/**
+ * Checks whether a value is an override row of the ledger.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value carries the value and time strings and an optional replaced string;
+ * false otherwise.
+ */
+export function isOverrideEntry(value) {
     return (isRecord(value) &&
         typeof value.value === 'string' &&
         typeof value.at === 'string' &&
         (value.replaced === undefined || typeof value.replaced === 'string'));
 }
-// A ledger with one malformed row is refused whole, so a restore never drops a range it cannot read.
-function parseLedger(value) {
+/**
+ * Parses a ledger record.
+ *
+ * @remarks
+ * A ledger with one malformed row is refused whole, so a restore never drops a range it cannot read.
+ *
+ * @param value - The parsed ledger file.
+ * @returns The ledger, or undefined when a block is missing or any row is malformed.
+ */
+export function parseLedger(value) {
     if (!isRecord(value) || !isRecord(value.packages) || !isRecord(value.overrides))
         return undefined;
     const rows = Object.entries(value.packages);
@@ -174,31 +370,79 @@ function parseLedger(value) {
         ...(value.blockExisted === undefined ? {} : { blockExisted: value.blockExisted }),
     };
 }
-function serializeJSON(value) {
+/**
+ * Serializes a value as every Orkestrel manifest is written.
+ *
+ * @param value - The value to serialize.
+ * @returns Tab-indented JSON with a trailing newline.
+ */
+export function serializeJSON(value) {
     return `${JSON.stringify(value, null, '\t')}\n`;
 }
-function readBlock(manifest, field) {
+/**
+ * Reads one dependency-style block of a manifest.
+ *
+ * @param manifest - The manifest.
+ * @param field - The block's field name.
+ * @returns The block, or an empty record when the field is absent or not a record.
+ */
+export function readBlock(manifest, field) {
     const block = manifest[field];
     return isRecord(block) ? block : {};
 }
-function findDeclaration(manifest, name) {
+/**
+ * Finds the field that declares a package.
+ *
+ * @param manifest - The manifest.
+ * @param name - The package name.
+ * @returns The field and spec of the first of `dependencies` and `devDependencies` that holds a
+ * string spec for the name, or undefined when neither does.
+ */
+export function findDeclaration(manifest, name) {
     const field = FIELDS.find((candidate) => typeof readBlock(manifest, candidate)[name] === 'string');
     const spec = field === undefined ? undefined : readBlock(manifest, field)[name];
     return field === undefined || typeof spec !== 'string' ? undefined : { field, spec };
 }
-function compareKeys(left, right) {
+/**
+ * Orders two keys by their code units.
+ *
+ * @param left - One key.
+ * @param right - The other key.
+ * @returns A negative number, 0, or a positive number as the left key sorts before, equal to, or
+ * after the right.
+ */
+export function compareKeys(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
-// A block whose keys are sorted stays sorted, because oxfmt sorts a dependency or override block;
-// any other block takes the added keys last.
-function mergeEntries(kept, added) {
+/**
+ * Merges added entries into a block's kept entries.
+ *
+ * @remarks
+ * A block whose keys are sorted stays sorted, because oxfmt sorts a dependency or override block;
+ * any other block takes the added keys last.
+ *
+ * @param kept - The entries the block keeps, in order.
+ * @param added - The entries the block gains.
+ * @returns The merged entries.
+ */
+export function mergeEntries(kept, added) {
     const sorted = kept.every(([name], index) => index === 0 || compareKeys(kept[index - 1]?.[0] ?? '', name) <= 0);
     const merged = [...kept, ...added];
     return sorted ? merged.toSorted(([left], [right]) => compareKeys(left, right)) : merged;
 }
-// A created block lands before the first key oxfmt sorts after `overrides`, or last when every key
-// sorts ahead of it.
-function placeBlock(manifest, field, block) {
+/**
+ * Inserts a created block where oxfmt sorts it.
+ *
+ * @remarks
+ * A created block lands before the first key oxfmt sorts after `overrides`, or last when every key
+ * sorts ahead of it.
+ *
+ * @param manifest - The manifest.
+ * @param field - The new block's field name.
+ * @param block - The new block.
+ * @returns The manifest with the block inserted.
+ */
+export function placeBlock(manifest, field, block) {
     const entries = Object.entries(manifest);
     const follower = entries.findIndex(([key]) => !OVERRIDE_PRECEDERS.includes(key));
     const position = follower === -1 ? entries.length : follower;
@@ -208,10 +452,21 @@ function placeBlock(manifest, field, block) {
         ...entries.slice(position),
     ]);
 }
-// A changed key keeps its position, a key mapped to undefined is removed, and an `overrides` block
-// left empty is removed unless `keepEmpty` is set. A block that is absent and gains nothing is not
-// created.
-function rewriteBlock(manifest, field, changes, keepEmpty) {
+/**
+ * Rewrites one block of a manifest.
+ *
+ * @remarks
+ * A changed key keeps its position, a key mapped to undefined is removed, and an `overrides` block
+ * left empty is removed unless `keepEmpty` is set. A block that is absent and gains nothing is not
+ * created.
+ *
+ * @param manifest - The manifest.
+ * @param field - The block's field name.
+ * @param changes - The new spec for each changed key, or undefined to remove the key.
+ * @param keepEmpty - If `true`, an `overrides` block left empty stays; if `false`, it is removed.
+ * @returns The rewritten manifest.
+ */
+export function rewriteBlock(manifest, field, changes, keepEmpty) {
     const present = Object.entries(readBlock(manifest, field));
     const kept = present.flatMap(([name, value]) => {
         if (!changes.has(name))
@@ -232,12 +487,26 @@ function rewriteBlock(manifest, field, changes, keepEmpty) {
             : [[key, Object.fromEntries(next)]];
     }));
 }
-function renderValue(value) {
+/**
+ * Renders a manifest spec for a change line.
+ *
+ * @param value - The spec, or undefined for an absent entry.
+ * @returns The string itself, the JSON of any other value, or undefined for undefined.
+ */
+export function renderValue(value) {
     if (value === undefined)
         return undefined;
     return typeof value === 'string' ? value : JSON.stringify(value);
 }
-function diffManifests(before, after) {
+/**
+ * Lists the entries that differ between two manifests.
+ *
+ * @param before - The manifest before.
+ * @param after - The manifest after.
+ * @returns One change per entry of `dependencies`, `devDependencies`, and `overrides` whose rendered
+ * spec differs.
+ */
+export function diffManifests(before, after) {
     return ['dependencies', 'devDependencies', 'overrides'].flatMap((block) => {
         const from = readBlock(before, block);
         const to = readBlock(after, block);
@@ -249,24 +518,60 @@ function diffManifests(before, after) {
         });
     });
 }
-function buildTarballName(name, version, sha256) {
+/**
+ * Builds a tarball's file name.
+ *
+ * @param name - The package name.
+ * @param version - The package version.
+ * @param sha256 - The archive's SHA-256 digest.
+ * @returns The scope and name joined by a dash, the version, and the first twelve hex digits of the
+ * digest.
+ */
+export function buildTarballName(name, version, sha256) {
     return `${name.replace(/^@/u, '').replace('/', '-')}-${version}-${sha256.slice(0, 12)}.tgz`;
 }
-// npm resolves a dependency's relative file: spec against that dependency's own directory, so only an
-// absolute spec resolves inside a packed consumer installed elsewhere.
-function buildTarballSpec(consumer, file) {
+/**
+ * Builds the spec a manifest holds for a tarball.
+ *
+ * @remarks
+ * npm resolves a dependency's relative file: spec against that dependency's own directory, so only
+ * an absolute spec resolves inside a packed consumer installed elsewhere.
+ *
+ * @param consumer - The consumer directory.
+ * @param file - The tarball's file name.
+ * @returns The absolute `file:` spec with forward slashes.
+ */
+export function buildTarballSpec(consumer, file) {
     return `file:${normalizeSlashes(resolve(consumer, ...TARBALL_DIRECTORY.split('/'), file))}`;
 }
-// The relative `file:tmp/tarballs/<file>` form is what earlier pins wrote, so a re-pin over it keeps
-// the range the first pin replaced.
-function isTarballSpec(spec) {
+/**
+ * Checks whether a spec names a tarball in a tarball directory.
+ *
+ * @remarks
+ * The relative `file:tmp/tarballs/<file>` form is what earlier pins wrote, so a re-pin over it keeps
+ * the range the first pin replaced.
+ *
+ * @param spec - The manifest spec.
+ * @returns True if the spec is a `file:` spec into the relative or an absolute tarball directory;
+ * false otherwise.
+ */
+export function isTarballSpec(spec) {
     if (!spec.startsWith('file:'))
         return false;
     const path = normalizeSlashes(spec.slice('file:'.length));
     return (path.startsWith(`${TARBALL_DIRECTORY}/`) ||
         (isAbsolute(path) && path.includes(`/${TARBALL_DIRECTORY}/`)));
 }
-function buildLedgerEntry(manifest, ledger, tarball, at) {
+/**
+ * Builds the ledger row for one packed source.
+ *
+ * @param manifest - The consumer manifest before the pin.
+ * @param ledger - The ledger before the pin.
+ * @param tarball - The packed source.
+ * @param at - The time of the pin.
+ * @returns The row; a re-pin over a tarball spec keeps the range the first pin replaced.
+ */
+export function buildLedgerEntry(manifest, ledger, tarball, at) {
     const declaration = findDeclaration(manifest, tarball.source.name);
     const prior = ledger.packages[tarball.source.name];
     const repinned = prior !== undefined && declaration !== undefined && isTarballSpec(declaration.spec);
@@ -282,11 +587,23 @@ function buildLedgerEntry(manifest, ledger, tarball, at) {
         at,
     };
 }
-// The replaced range is kept from the first pin while the manifest still holds a tarball spec, and a
-// package no field declares is recorded without a field and takes effect through its override alone.
-// The first pin records whether the manifest held an overrides block, so a restore keeps one that
-// existed and removes one the pin created.
-function planPin(manifest, ledger, tarballs, overrides, at) {
+/**
+ * Plans a pin.
+ *
+ * @remarks
+ * The replaced range is kept from the first pin while the manifest still holds a tarball spec, and a
+ * package no field declares is recorded without a field and takes effect through its override alone.
+ * The first pin records whether the manifest held an overrides block, so a restore keeps one that
+ * existed and removes one the pin created.
+ *
+ * @param manifest - The consumer manifest.
+ * @param ledger - The ledger before the pin.
+ * @param tarballs - The packed or planned sources.
+ * @param overrides - The names to override.
+ * @param at - The time of the pin.
+ * @returns The manifest and ledger to write and the changes between the manifests.
+ */
+export function planPin(manifest, ledger, tarballs, overrides, at) {
     const rows = tarballs.map((tarball) => ({
         name: tarball.source.name,
         spec: tarball.spec,
@@ -322,8 +639,18 @@ function planPin(manifest, ledger, tarballs, overrides, at) {
         changes: diffManifests(manifest, next),
     };
 }
-// An empty name list restores every recorded package and override.
-function planRestore(manifest, ledger, names) {
+/**
+ * Plans a restore.
+ *
+ * @remarks
+ * An empty name list restores every recorded package and override.
+ *
+ * @param manifest - The consumer manifest.
+ * @param ledger - The ledger before the restore.
+ * @param names - The packages to restore, or none for every one.
+ * @returns The manifest and ledger to write, the restored rows, and the overrides dropped.
+ */
+export function planRestore(manifest, ledger, names) {
     const targets = names.length === 0 ? Object.keys(ledger.packages) : names;
     const selected = new Set(targets);
     const rows = targets.flatMap((name) => {
@@ -353,7 +680,17 @@ function planRestore(manifest, ledger, names) {
         dropped,
     };
 }
-function scanPinRequest(text, manifest, ledger, sources, overrides) {
+/**
+ * Lists the problems that refuse a pin request.
+ *
+ * @param text - The manifest file's text.
+ * @param manifest - The parsed manifest.
+ * @param ledger - The ledger before the pin.
+ * @param sources - The sources to pin.
+ * @param overrides - The names to override.
+ * @returns One message per problem, empty when the request is usable.
+ */
+export function scanPinRequest(text, manifest, ledger, sources, overrides) {
     const names = sources.map((source) => source.name);
     const current = readBlock(manifest, 'overrides');
     return [
@@ -386,7 +723,14 @@ function scanPinRequest(text, manifest, ledger, sources, overrides) {
         ]),
     ];
 }
-function parseVersion(text) {
+/**
+ * Parses a full semantic version.
+ *
+ * @param text - A version such as `1.2.3`, `v1.2.3-rc.1`, or `1.2.3+build`, with surrounding
+ * whitespace ignored.
+ * @returns The version, or undefined when the text is not a full version. Build metadata is dropped.
+ */
+export function parseVersion(text) {
     const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(text.trim());
     if (match === null)
         return undefined;
@@ -397,7 +741,16 @@ function parseVersion(text) {
         pre: match[4],
     };
 }
-function comparePrerelease(left, right) {
+/**
+ * Orders two prerelease identifier lists.
+ *
+ * @param left - One prerelease text, such as `rc.1`.
+ * @param right - The other.
+ * @returns A negative number, 0, or a positive number as the left sorts before, equal to, or after
+ * the right: numeric identifiers compare as numbers and sort before alphanumeric ones, and a longer
+ * list sorts after its prefix.
+ */
+export function comparePrerelease(left, right) {
     const leftParts = left.split('.');
     const rightParts = right.split('.');
     const first = leftParts
@@ -416,7 +769,15 @@ function comparePrerelease(left, right) {
         .find((order) => order !== 0);
     return first ?? leftParts.length - rightParts.length;
 }
-function compareVersions(left, right) {
+/**
+ * Orders two versions.
+ *
+ * @param left - One version.
+ * @param right - The other.
+ * @returns A negative number, 0, or a positive number as the left sorts before, equal to, or after
+ * the right; a release sorts after its prerelease.
+ */
+export function compareVersions(left, right) {
     const core = [left.major - right.major, left.minor - right.minor, left.patch - right.patch].find((order) => order !== 0);
     if (core !== undefined)
         return core;
@@ -428,9 +789,17 @@ function compareVersions(left, right) {
         return -1;
     return comparePrerelease(left.pre, right.pre);
 }
-// Reads `*`, `x`, an exact version, `^`, `~`, and the `>=`, `>`, `<=`, `<`, and `=` operators on full
-// versions; an empty list matches every version.
-function parseComparators(token) {
+/**
+ * Parses one token of a range into comparators.
+ *
+ * @remarks
+ * Reads `*`, `x`, an exact version, `^`, `~`, and the `>=`, `>`, `<=`, `<`, and `=` operators on full
+ * versions; an empty list matches every version.
+ *
+ * @param token - One whitespace-free token of a range.
+ * @returns The comparators the token means, or undefined when the token is not in the subset.
+ */
+export function parseComparators(token) {
     if (token === '*' || token === 'x' || token === 'X' || token === '')
         return [];
     const operator = /^(\^|~|>=|<=|>|<|=)?(.+)$/u.exec(token);
@@ -463,7 +832,14 @@ function parseComparators(token) {
     }
     return [{ operator: '=', version }];
 }
-function matchesComparator(version, comparator) {
+/**
+ * Checks whether a version satisfies one comparator.
+ *
+ * @param version - The version.
+ * @param comparator - The comparator.
+ * @returns True if the version stands in the comparator's relation to its bound; false otherwise.
+ */
+export function matchesComparator(version, comparator) {
     const order = compareVersions(version, comparator.version);
     if (comparator.operator === '>=')
         return order >= 0;
@@ -475,15 +851,32 @@ function matchesComparator(version, comparator) {
         return order < 0;
     return order === 0;
 }
-function supportsRange(range) {
+/**
+ * Checks whether the script reads every token of a range.
+ *
+ * @param range - A registry range.
+ * @returns True if every token of every `||` set is in the subset {@link parseComparators} reads;
+ * false otherwise.
+ */
+export function supportsRange(range) {
     return range.split('||').every((set) => set
         .trim()
         .split(/\s+/u)
         .every((token) => parseComparators(token) !== undefined));
 }
-// A prerelease satisfies a set only when one of its comparators names a prerelease of the same
-// `major.minor.patch`, and an unreadable range is satisfied by nothing.
-function matchesRange(text, range) {
+/**
+ * Checks whether a version satisfies a range.
+ *
+ * @remarks
+ * A prerelease satisfies a set only when one of its comparators names a prerelease of the same
+ * `major.minor.patch`, and an unreadable range is satisfied by nothing.
+ *
+ * @param text - The version.
+ * @param range - A registry range.
+ * @returns True if the version parses and satisfies every comparator of at least one `||` set;
+ * false otherwise.
+ */
+export function matchesRange(text, range) {
     const version = parseVersion(text);
     if (version === undefined)
         return false;
@@ -503,7 +896,26 @@ function matchesRange(text, range) {
         return admitted && comparators.every((comparator) => matchesComparator(version, comparator));
     });
 }
-function parseCommand(argv) {
+/**
+ * Parses the command line.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The command, or the reason the line is refused: no mode or two modes, a flag the mode does
+ * not read (the `--flag=value` form included), a flag with no value, no consumer, or a pin with no
+ * source.
+ */
+export function parseCommand(argv) {
+    const known = MODES.flatMap((candidate) => [
+        `--${candidate}`,
+        ...VALUE_FLAGS[candidate],
+        ...SWITCH_FLAGS[candidate],
+    ]);
+    // A bare `--` ends the arguments the script reads; nothing after it is a flag of this script.
+    const end = argv.indexOf('--');
+    const foreign = (end === -1 ? argv : argv.slice(0, end)).filter((token) => token.startsWith('--') && !known.includes(token));
+    if (foreign.length > 0) {
+        return { ok: false, message: `${foreign.join(', ')} is not a flag this script reads` };
+    }
     const given = MODES.filter((candidate) => argv.includes(`--${candidate}`));
     const mode = MODES.find((candidate) => argv.includes(`--${candidate}`));
     if (mode === undefined)
@@ -547,20 +959,47 @@ function parseCommand(argv) {
         },
     };
 }
-function computeHash(value) {
+/**
+ * Computes the SHA-256 digest of bytes.
+ *
+ * @param value - The bytes.
+ * @returns The digest as lowercase hexadecimal.
+ */
+export function computeHash(value) {
     return createHash('sha256').update(value).digest('hex');
 }
-function loadJSONRecord(path) {
+/**
+ * Loads a JSON file as a record.
+ *
+ * @param path - The file.
+ * @returns The record, or undefined when the file is absent or not a JSON object.
+ */
+export function loadJSONRecord(path) {
     return existsSync(path) ? parseJsonRecord(readFileSync(path, 'utf8')) : undefined;
 }
-function loadSource(directory) {
+/**
+ * Loads a source package's name and version.
+ *
+ * @param directory - The source directory.
+ * @returns The source, or undefined when its manifest lacks a name or a version.
+ */
+export function loadSource(directory) {
     const manifest = loadJSONRecord(join(directory, 'package.json'));
     const name = readString(manifest, 'name');
     const version = readString(manifest, 'version');
     return name === undefined || version === undefined ? undefined : { directory, name, version };
 }
-// npm 11 prints an array and npm 12 an object keyed by package name.
-function readPack(text) {
+/**
+ * Reads the archive name and file list out of `npm pack --json` output.
+ *
+ * @remarks
+ * npm 11 prints an array and npm 12 an object keyed by package name.
+ *
+ * @param text - npm's standard output.
+ * @returns The archive's file name and its sorted, forward-slash file paths.
+ * @throws Thrown when the output is not JSON or lacks a file name or a file list.
+ */
+export function readPack(text) {
     const parsed = JSON.parse(text);
     const entry = Array.isArray(parsed)
         ? parsed[0]
@@ -578,7 +1017,15 @@ function readPack(text) {
     });
     return { filename: entry.filename, files: files.toSorted() };
 }
-function invokeNpm(args, cwd) {
+/**
+ * Runs npm and returns its standard output.
+ *
+ * @param args - The npm arguments.
+ * @param cwd - The working directory.
+ * @returns npm's standard output.
+ * @throws Thrown when npm cannot start or exits nonzero, naming the command and the stderr tail.
+ */
+export function invokeNpm(args, cwd) {
     const result = runNpm(args, cwd);
     if (result.error !== undefined) {
         throw new Error(`npm ${args.join(' ')} could not start in ${cwd}: ${result.error.message}`);
@@ -588,7 +1035,13 @@ function invokeNpm(args, cwd) {
     }
     return result.stdout;
 }
-function inspectCheckout(directory) {
+/**
+ * Reads a checkout's commit and whether it is dirty.
+ *
+ * @param directory - The checkout.
+ * @returns The HEAD commit and the dirty flag, each undefined when git cannot answer.
+ */
+export function inspectCheckout(directory) {
     const head = spawnSync('git', ['rev-parse', 'HEAD'], {
         cwd: directory,
         encoding: 'utf8',
@@ -604,18 +1057,44 @@ function inspectCheckout(directory) {
         dirty: status.status === 0 ? status.stdout.trim() !== '' : undefined,
     };
 }
-function replaceFile(path, text) {
+/**
+ * Replaces a file by renaming a temporary file onto it.
+ *
+ * @param path - The file.
+ * @param text - Its new text.
+ * @returns Nothing after the rename.
+ * @throws Thrown when the write or the rename fails.
+ */
+export function replaceFile(path, text) {
     const temporary = `${path}.${String(process.pid)}.tmp`;
     writeFileSync(temporary, text);
     renameSync(temporary, path);
 }
-// Vite keys its pre-bundle on the installed version, so a same-version tarball would serve stale bytes.
-function installConsumer(consumer) {
+/**
+ * Installs a consumer's dependencies and clears the Vite pre-bundle.
+ *
+ * @remarks
+ * Vite keys its pre-bundle on the installed version, so a same-version tarball would serve stale bytes.
+ *
+ * @param consumer - The consumer directory.
+ * @returns Nothing after the install.
+ * @throws Thrown when the install fails.
+ */
+export function installConsumer(consumer) {
     invokeNpm(['install', '--ignore-scripts', '--no-audit', '--no-fund'], consumer);
     removeTree(join(consumer, 'node_modules', '.vite'));
 }
-// The package's own `node_modules` is skipped, and a link is listed as `path (link)`.
-function collectFiles(directory, prefix = '') {
+/**
+ * Lists the files of an installed package.
+ *
+ * @remarks
+ * The package's own `node_modules` is skipped, and a link is listed as `path (link)`.
+ *
+ * @param directory - The package directory.
+ * @param prefix - The path of `directory` inside the package. Default: none.
+ * @returns The sorted forward-slash paths.
+ */
+export function collectFiles(directory, prefix = '') {
     return readdirSync(directory, { withFileTypes: true })
         .flatMap((entry) => {
         const path = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
@@ -630,14 +1109,27 @@ function collectFiles(directory, prefix = '') {
     })
         .toSorted();
 }
-function computeInventory(directory) {
+/**
+ * Computes the digest of an installed package's bytes.
+ *
+ * @param directory - The package directory.
+ * @returns The SHA-256 of the sorted path and file-digest lines.
+ */
+export function computeInventory(directory) {
     const lines = collectFiles(directory).map((path) => {
         const file = join(directory, ...path.split('/'));
         return `${path}\t${existsSync(file) ? computeHash(readFileSync(file)) : 'unreadable'}`;
     });
     return computeHash(Buffer.from(lines.join('\n')));
 }
-function computeScope(consumer, excluded) {
+/**
+ * Computes the digest of every top-level `@orkestrel` package the pin does not name.
+ *
+ * @param consumer - The consumer directory.
+ * @param excluded - The package names to leave out.
+ * @returns The digest of each package by name, `link` for a link, empty when the scope is absent.
+ */
+export function computeScope(consumer, excluded) {
     const scope = join(consumer, 'node_modules', '@orkestrel');
     if (!existsSync(scope))
         return {};
@@ -649,7 +1141,14 @@ function computeScope(consumer, excluded) {
         return [[name, lstatSync(path).isSymbolicLink() ? 'link' : computeInventory(path)]];
     }));
 }
-function describeMoved(before, after) {
+/**
+ * Names the packages an install added, removed, or changed.
+ *
+ * @param before - The scope digests before the install.
+ * @param after - The scope digests after.
+ * @returns One message per package whose digest differs.
+ */
+export function describeMoved(before, after) {
     return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap((name) => {
         const was = before[name];
         const now = after[name];
@@ -659,8 +1158,17 @@ function describeMoved(before, after) {
         return [`${name} was ${verb} by the install`];
     });
 }
-// A link is reported and not entered.
-function scanModules(directory, names) {
+/**
+ * Finds every installed copy of the named packages.
+ *
+ * @remarks
+ * A link is reported and not entered.
+ *
+ * @param directory - A `node_modules` directory.
+ * @param names - The package names to find.
+ * @returns Each copy at any depth of nested `node_modules`.
+ */
+export function scanModules(directory, names) {
     if (!existsSync(directory))
         return [];
     return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
@@ -690,13 +1198,31 @@ function scanModules(directory, names) {
         });
     });
 }
-function locateInstalled(consumer, name) {
+/**
+ * Locates a package's top-level install path.
+ *
+ * @param consumer - The consumer directory.
+ * @param name - The package name.
+ * @returns The path under the consumer's `node_modules`.
+ */
+export function locateInstalled(consumer, name) {
     return join(consumer, 'node_modules', ...name.split('/'));
 }
-// A source that is itself pinned was packed with its registry ranges, so its installed manifest is
-// compared to those bytes rather than to the source's own manifest. Every pinned source must be
-// installed at the top level, so an override that selects no installed dependency fails the proof.
-function proveInstalled(consumer, tarball, declared, copies) {
+/**
+ * Lists the problems with one pinned package's install.
+ *
+ * @remarks
+ * A source that is itself pinned was packed with its registry ranges, so its installed manifest is
+ * compared to those bytes rather than to the source's own manifest. Every pinned source must be
+ * installed at the top level, so an override that selects no installed dependency fails the proof.
+ *
+ * @param consumer - The consumer directory.
+ * @param tarball - The packed source.
+ * @param declared - If `true`, the consumer declares the package; if `false`, only an override names it.
+ * @param copies - Every installed copy of the pinned packages.
+ * @returns One message per problem, empty when the install proves the pin.
+ */
+export function proveInstalled(consumer, tarball, declared, copies) {
     const name = tarball.source.name;
     const top = locateInstalled(consumer, name);
     const named = copies.filter((copy) => copy.name === name);
@@ -728,15 +1254,32 @@ function proveInstalled(consumer, tarball, declared, copies) {
         ...nested.map((copy) => `${name} has another copy at ${normalizeSlashes(relative(consumer, copy.path))} (version ${copy.version ?? 'unknown'}); add an --override`),
     ];
 }
-function loadResolved(consumer, name) {
+/**
+ * Reads the `resolved` address the lockfile records for a package.
+ *
+ * @param consumer - The consumer directory.
+ * @param name - The package name.
+ * @returns The address, or undefined when the lockfile is absent or records none.
+ */
+export function loadResolved(consumer, name) {
     const packages = loadJSONRecord(join(consumer, 'package-lock.json'))?.packages;
     const entry = isRecord(packages) ? packages[`node_modules/${name}`] : undefined;
     return readString(isRecord(entry) ? entry : undefined, 'resolved');
 }
-// A registry range needs a real directory whose version the range accepts and a lockfile `resolved`
-// that is a registry URL; a `file:` directory range needs a link to that directory or a directory of
-// its version; any other spec is reported as unproven.
-function proveRestored(consumer, name, range) {
+/**
+ * Lists the problems with one restored package's install.
+ *
+ * @remarks
+ * A registry range needs a real directory whose version the range accepts and a lockfile `resolved`
+ * that is a registry URL; a `file:` directory range needs a link to that directory or a directory of
+ * its version; any other spec is reported as unproven.
+ *
+ * @param consumer - The consumer directory.
+ * @param name - The package name.
+ * @param range - The restored range.
+ * @returns One message per problem, empty when the install proves the restore.
+ */
+export function proveRestored(consumer, name, range) {
     const installed = locateInstalled(consumer, name);
     if (!existsSync(installed))
         return [`${name} is not installed`];
@@ -763,65 +1306,152 @@ function proveRestored(consumer, name, range) {
             : []),
     ];
 }
-function locateLedger(consumer) {
+/**
+ * Locates a consumer's ledger file.
+ *
+ * @param consumer - The consumer directory.
+ * @returns The ledger's path.
+ */
+export function locateLedger(consumer) {
     return join(consumer, ...TARBALL_DIRECTORY.split('/'), LEDGER_FILE);
 }
-// An absent ledger is an empty one; a malformed ledger is undefined.
-function loadLedger(consumer) {
+/**
+ * Loads a consumer's ledger.
+ *
+ * @remarks
+ * An absent ledger is an empty one; a malformed ledger is undefined.
+ *
+ * @param consumer - The consumer directory.
+ * @returns The ledger, or undefined when the file is malformed.
+ */
+export function loadLedger(consumer) {
     const path = locateLedger(consumer);
     if (!existsSync(path))
         return { packages: {}, overrides: {} };
     return parseLedger(loadJSONRecord(path));
 }
-function readLedger(consumer) {
+/**
+ * Reads a consumer's ledger.
+ *
+ * @param consumer - The consumer directory.
+ * @returns The ledger; an absent file reads as an empty one.
+ * @throws Thrown when the ledger file is malformed.
+ */
+export function readLedger(consumer) {
     const ledger = loadLedger(consumer);
     if (ledger === undefined)
         throw new Error(`${normalizeSlashes(locateLedger(consumer))} is malformed`);
     return ledger;
 }
-function renderStamp(at) {
+/**
+ * Renders a time as a file-name stamp.
+ *
+ * @param at - An ISO time.
+ * @returns The time with each colon and dot replaced by a dash.
+ */
+export function renderStamp(at) {
     return at.replace(/[:.]/gu, '-');
 }
-function writeReceipt(consumer, at, receipt) {
+/**
+ * Writes a receipt create-only under the working directory.
+ *
+ * @param consumer - The consumer directory, whose name the file carries.
+ * @param at - The time of the run.
+ * @param receipt - The receipt record.
+ * @returns The receipt's forward-slash path.
+ * @throws Thrown when the file already exists or cannot be written.
+ */
+export function writeReceipt(consumer, at, receipt) {
     mkdirSync(RECEIPT_DIRECTORY, { recursive: true });
     const path = join(RECEIPT_DIRECTORY, `swap-${basename(consumer)}-${renderStamp(at)}.json`);
     writeFileSync(path, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx' });
     return normalizeSlashes(path);
 }
-function printReport(json, lines, report) {
+/**
+ * Prints a report.
+ *
+ * @param json - If `true`, prints the report as one JSON line; if `false`, prints the text lines.
+ * @param lines - The text lines.
+ * @param report - The JSON report.
+ * @returns Nothing after the write.
+ */
+export function printReport(json, lines, report) {
     process.stdout.write(json ? `${JSON.stringify(report)}\n` : `${lines.join('\n')}\n`);
 }
-function reportUsage(message) {
+/**
+ * Prints a usage refusal.
+ *
+ * @param message - What was refused.
+ * @returns The usage exit code.
+ */
+export function reportUsage(message) {
     process.stderr.write(`swap: ${message}\n${USAGE}\n`);
     return EXIT_USAGE;
 }
-function hasPins(ledger) {
+/**
+ * Checks whether a ledger records any pin.
+ *
+ * @param ledger - The ledger.
+ * @returns True if it holds a package or an override row; false otherwise.
+ */
+export function hasPins(ledger) {
     return Object.keys(ledger.packages).length > 0 || Object.keys(ledger.overrides).length > 0;
 }
-// The manifest a source is packed with: its own, with the ranges and overrides its ledger replaced
-// put back when it carries pins.
-function loadPackedManifest(directory) {
+/**
+ * Loads the manifest a source is packed with.
+ *
+ * @remarks
+ * It is the source's own, with the ranges and overrides its ledger replaced put back when it carries
+ * pins.
+ *
+ * @param directory - The source directory.
+ * @returns The manifest to pack.
+ * @throws Thrown when the manifest is unreadable or the ledger is malformed.
+ */
+export function loadPackedManifest(directory) {
     const manifest = loadJSONRecord(join(directory, 'package.json'));
     if (manifest === undefined)
         throw new Error(`${directory}/package.json is unreadable`);
     const ledger = readLedger(directory);
     return hasPins(ledger) ? planRestore(manifest, ledger, []).manifest : manifest;
 }
-// The text a pinned source's manifest is rewritten to for the pack; undefined when the source carries
-// no pins and packs its own manifest.
-function readPackedManifest(directory) {
+/**
+ * Reads the text a pinned source's manifest is rewritten to for the pack.
+ *
+ * @param directory - The source directory.
+ * @returns The text, or undefined when the source carries no pins and packs its own manifest.
+ */
+export function readPackedManifest(directory) {
     return hasPins(readLedger(directory)) ? serializeJSON(loadPackedManifest(directory)) : undefined;
 }
-// A source that packs a local dependency spec ships a tarball that resolves only on this host, whether
-// or not a ledger recorded the spec.
-function scanPackedSpecs(source) {
+/**
+ * Lists the local dependency specs a source would pack.
+ *
+ * @remarks
+ * A source that packs a local dependency spec ships a tarball that resolves only on this host,
+ * whether or not a ledger recorded the spec.
+ *
+ * @param source - The source.
+ * @returns One message per local spec in the manifest the source packs.
+ */
+export function scanPackedSpecs(source) {
     const manifest = loadPackedManifest(source.directory);
     return scanLocalSpecs(manifest).map(([path, spec]) => `${source.name} would pack a local dependency spec: ${path} is ${spec}`);
 }
-// A source that carries a ledger of its own has its manifest rewritten to the recorded ranges for the
-// pack and restored byte for byte whether the pack succeeds or throws, so a consumer never receives a
-// tarball spec that resolves only inside the source.
-function packSource(directory, scratch) {
+/**
+ * Packs a source.
+ *
+ * @remarks
+ * A source that carries a ledger of its own has its manifest rewritten to the recorded ranges for
+ * the pack and restored byte for byte whether the pack succeeds or throws, so a consumer never
+ * receives a tarball spec that resolves only inside the source.
+ *
+ * @param directory - The source directory.
+ * @param scratch - The directory that receives the archive.
+ * @returns npm's `pack --json` output.
+ * @throws Thrown when the pack fails.
+ */
+export function packSource(directory, scratch) {
     const args = ['pack', '--ignore-scripts', '--json', '--pack-destination', scratch];
     const packed = readPackedManifest(directory);
     if (packed === undefined)
@@ -836,7 +1466,16 @@ function packSource(directory, scratch) {
         writeFileSync(path, original);
     }
 }
-function packSources(sources, build, consumer) {
+/**
+ * Builds and packs each source into the consumer's tarball directory.
+ *
+ * @param sources - The sources.
+ * @param build - If `true`, runs `npm run build` in each source first; if `false`, packs it as is.
+ * @param consumer - The consumer directory.
+ * @returns One packed tarball per source.
+ * @throws Thrown when a build or a pack fails.
+ */
+export function packSources(sources, build, consumer) {
     const tarballs = join(consumer, ...TARBALL_DIRECTORY.split('/'));
     mkdirSync(tarballs, { recursive: true });
     const scratch = mkdtempSync(join(tarballs, '.scratch-'));
@@ -863,7 +1502,14 @@ function packSources(sources, build, consumer) {
         removeTree(scratch);
     }
 }
-function planTarballs(sources, consumer) {
+/**
+ * Plans the tarballs of a dry run without building or packing.
+ *
+ * @param sources - The sources.
+ * @param consumer - The consumer directory.
+ * @returns One planned tarball per source, with a pending hash and no files.
+ */
+export function planTarballs(sources, consumer) {
     return sources.map((source) => {
         const file = buildTarballName(source.name, source.version, '<sha256:12>');
         return {
@@ -876,11 +1522,27 @@ function planTarballs(sources, consumer) {
         };
     });
 }
-function renderChange(change) {
+/**
+ * Renders a manifest change as a text line.
+ *
+ * @param change - The change.
+ * @returns The line, naming the block, the package, and both specs.
+ */
+export function renderChange(change) {
     return `swap: ${change.block}.${change.name} ${change.from ?? '(absent)'} -> ${change.to ?? '(absent)'}`;
 }
-// A proved pin records the digest of its installed bytes, which `--status` compares the install to.
-function recordInventory(consumer, ledger, tarballs) {
+/**
+ * Records the digest of each proved install in the ledger.
+ *
+ * @remarks
+ * A proved pin records the digest of its installed bytes, which `--status` compares the install to.
+ *
+ * @param consumer - The consumer directory.
+ * @param ledger - The ledger.
+ * @param tarballs - The pinned tarballs.
+ * @returns The ledger with an inventory on each package that is installed as a real directory.
+ */
+export function recordInventory(consumer, ledger, tarballs) {
     const proved = new Map(tarballs.flatMap((tarball) => {
         const top = locateInstalled(consumer, tarball.source.name);
         return existsSync(top) && !lstatSync(top).isSymbolicLink()
@@ -895,7 +1557,14 @@ function recordInventory(consumer, ledger, tarballs) {
         })),
     };
 }
-function executePin(command) {
+/**
+ * Runs the pin mode.
+ *
+ * @param command - The parsed command.
+ * @returns 0 when the pin installed and proved, 1 when a proof failed, 64 on a usage refusal.
+ * @throws Thrown when a build, a pack, or the install fails.
+ */
+export function executePin(command) {
     const manifestPath = join(command.consumer, 'package.json');
     if (!existsSync(manifestPath))
         return reportUsage(`${command.consumer} has no package.json`);
@@ -978,9 +1647,18 @@ function executePin(command) {
     ], { ...receipt, receipt: path });
     return failures.length === 0 ? 0 : EXIT_FAILURE;
 }
-// The re-pin arguments name every source the restored rows recorded and every override they
-// dropped, so the pins can come back after a verb that needed the registry ranges.
-function buildRepin(consumer, plan) {
+/**
+ * Builds the arguments that pin again what a restore undid.
+ *
+ * @remarks
+ * The re-pin arguments name every source the restored rows recorded and every override they
+ * dropped, so the pins can come back after a verb that needed the registry ranges.
+ *
+ * @param consumer - The consumer directory.
+ * @param plan - The restore plan.
+ * @returns The `--pin` argument list.
+ */
+export function buildRepin(consumer, plan) {
     return [
         '--pin',
         '--consumer',
@@ -989,10 +1667,19 @@ function buildRepin(consumer, plan) {
         ...plan.dropped.flatMap((name) => ['--override', name]),
     ];
 }
-// npm keeps a lock entry whose version satisfies the restored range, so the tarball `resolved` of a
-// pinned package outlives the restore; removing the entry and the installed copy makes the install
-// resolve the package again from the registry.
-function removePinnedInstalls(consumer, names) {
+/**
+ * Removes the lock entries and installed copies of the named packages.
+ *
+ * @remarks
+ * npm keeps a lock entry whose version satisfies the restored range, so the tarball `resolved` of a
+ * pinned package outlives the restore; removing the entry and the installed copy makes the install
+ * resolve the package again from the registry.
+ *
+ * @param consumer - The consumer directory.
+ * @param names - The package names.
+ * @returns Nothing after the removal.
+ */
+export function removePinnedInstalls(consumer, names) {
     const path = join(consumer, 'package-lock.json');
     const text = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
     const lock = text === undefined ? undefined : parseJsonRecord(text);
@@ -1004,9 +1691,13 @@ function removePinnedInstalls(consumer, names) {
     for (const name of names)
         removeTree(locateInstalled(consumer, name));
 }
-// The packages whose lock entry and installed copy the restore removes: each restored row that
-// returns to a registry range, and each dropped override.
-function listRemovals(plan) {
+/**
+ * Lists the packages whose lock entry and installed copy a restore removes.
+ *
+ * @param plan - The restore plan.
+ * @returns Each restored row that returns to a registry range, and each dropped override.
+ */
+export function listRemovals(plan) {
     return [
         ...new Set([
             ...plan.rows.flatMap((row) => row.entry.field === undefined ||
@@ -1018,33 +1709,72 @@ function listRemovals(plan) {
         ]),
     ];
 }
-// Every ledger key becomes a manifest key, a lock key, and an install path, so each must be a package
-// name before the restore writes anything.
-function scanLedgerNames(ledger) {
+/**
+ * Lists the ledger keys that are not package names.
+ *
+ * @remarks
+ * Every ledger key becomes a manifest key, a lock key, and an install path, so each must be a package
+ * name before the restore writes anything.
+ *
+ * @param ledger - The ledger.
+ * @returns One message per package or override key that is not a package name.
+ */
+export function scanLedgerNames(ledger) {
     return [
         ...scanNames('packages', Object.keys(ledger.packages)),
         ...scanNames('overrides', Object.keys(ledger.overrides)),
     ];
 }
-function scanNames(block, names) {
+/**
+ * Lists the keys of one ledger block that are not package names.
+ *
+ * @param block - The block's name.
+ * @param names - The block's keys.
+ * @returns One message per key that is not a package name, with the key JSON-encoded.
+ */
+export function scanNames(block, names) {
     return names
         .filter((name) => !isPackageName(name))
         .map((name) => `The ledger ${block} key ${JSON.stringify(name)} is not a package name`);
 }
-// A name that passes the package-name rules still resolves outside `node_modules` when a scope
-// directory on its way is a link, so the target's real parent is compared to the real `node_modules`.
-function isContained(root, target) {
+/**
+ * Checks whether a target stays inside a root.
+ *
+ * @remarks
+ * A name that passes the package-name rules still resolves outside `node_modules` when a scope
+ * directory on its way is a link, so the target's real parent is compared to the real `node_modules`.
+ *
+ * @param root - The `node_modules` directory.
+ * @param target - The path to remove.
+ * @returns True if the target's real location is strictly inside the root's real location; false
+ * otherwise.
+ */
+export function isContained(root, target) {
     const parent = dirname(target);
     const inside = relative(existsSync(root) ? realpathSync(root) : resolve(root), join(existsSync(parent) ? realpathSync(parent) : resolve(parent), basename(target)));
     return inside !== '' && !isAbsolute(inside) && inside.split(/[\\/]/u)[0] !== '..';
 }
-function scanRemovals(consumer, names) {
+/**
+ * Lists the removals that would leave `node_modules`.
+ *
+ * @param consumer - The consumer directory.
+ * @param names - The packages to remove.
+ * @returns One message per package whose install path resolves outside `node_modules`.
+ */
+export function scanRemovals(consumer, names) {
     const root = join(consumer, 'node_modules');
     return names
         .filter((name) => !isContained(root, locateInstalled(consumer, name)))
         .map((name) => `The install of ${name} resolves outside node_modules`);
 }
-function executeRestore(command) {
+/**
+ * Runs the restore mode.
+ *
+ * @param command - The parsed command.
+ * @returns 0 when the restore installed and proved, 1 when a proof failed, 64 on a usage refusal.
+ * @throws Thrown when the ledger is malformed or the install fails.
+ */
+export function executeRestore(command) {
     const manifestPath = join(command.consumer, 'package.json');
     if (!existsSync(manifestPath))
         return reportUsage(`${command.consumer} has no package.json`);
@@ -1067,9 +1797,9 @@ function executeRestore(command) {
     const at = new Date().toISOString();
     const plan = planRestore(manifest, ledger, command.packages);
     const removals = listRemovals(plan);
-    const escaping = scanRemovals(command.consumer, removals);
-    if (escaping.length > 0)
-        return reportUsage(escaping.join('\n'));
+    const refusals = scanRemovals(command.consumer, removals);
+    if (refusals.length > 0)
+        return reportUsage(refusals.join('\n'));
     replaceFile(manifestPath, serializeJSON(plan.manifest));
     replaceFile(locateLedger(command.consumer), serializeJSON(plan.ledger));
     removePinnedInstalls(command.consumer, removals);
@@ -1111,12 +1841,31 @@ function executeRestore(command) {
     ], { ...receipt, receipt: path });
     return failures.length === 0 ? 0 : EXIT_FAILURE;
 }
-// The manifest spec of a tarball resolved to the location it names, relative specs against the
-// consumer, so a spec holds its tarball only when it names the ledger archive itself.
-function locateSpecTarget(consumer, spec) {
+/**
+ * Resolves a manifest tarball spec to the location it names.
+ *
+ * @remarks
+ * Relative specs resolve against the consumer, so a spec holds its tarball only when it names the
+ * ledger archive itself.
+ *
+ * @param consumer - The consumer directory.
+ * @param spec - A `file:` spec.
+ * @returns The location with forward slashes.
+ */
+export function locateSpecTarget(consumer, spec) {
     return normalizeSlashes(resolve(consumer, spec.slice('file:'.length)));
 }
-function describeStatus(name, entry, archive, report) {
+/**
+ * Lists the drifts one pinned package reports.
+ *
+ * @param name - The package name.
+ * @param entry - Its ledger row.
+ * @param archive - The ledger archive's forward-slash location.
+ * @param report - What the status read: whether the manifest holds the archive, whether the archive
+ * matches its recorded digest, how the package is installed, and whether its source commit moved.
+ * @returns One message per drift, empty when the pin holds.
+ */
+export function describeStatus(name, entry, archive, report) {
     return [
         ...(report.pinned ? [] : [`${name}: the manifest does not hold ${archive}`]),
         ...(report.tarball
@@ -1135,7 +1884,14 @@ function describeStatus(name, entry, archive, report) {
         ...(report.moved ? [`${name}: ${entry.source} moved from ${entry.commit ?? '?'}; re-pin`] : []),
     ];
 }
-function executeStatus(command) {
+/**
+ * Runs the status mode.
+ *
+ * @param command - The parsed command.
+ * @returns 0 when nothing drifted, 3 when something did, 64 on a usage refusal.
+ * @throws Thrown when the ledger is malformed.
+ */
+export function executeStatus(command) {
     const manifest = loadJSONRecord(join(command.consumer, 'package.json'));
     if (manifest === undefined)
         return reportUsage(`${command.consumer} has no readable package.json`);
@@ -1218,7 +1974,14 @@ function executeStatus(command) {
     });
     return problems.length === 0 ? 0 : EXIT_DRIFT;
 }
-function main(argv) {
+/**
+ * Runs the mode the arguments name.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 on success, 1 when a command or a proof failed, 3 when the status reports
+ * drift, 64 on usage.
+ */
+export function main(argv) {
     const parsed = parseCommand(argv);
     if (!parsed.ok)
         return reportUsage(parsed.message);
@@ -1234,4 +1997,6 @@ function main(argv) {
         return EXIT_FAILURE;
     }
 }
-process.exitCode = main(process.argv.slice(2));
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    process.exitCode = main(process.argv.slice(2));
+}