@orkestrel/scaffold 0.0.107 → 0.0.109

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

@@ -1,38 +1,216 @@
-// Compare the rebuilt dist/ against the published tarball on material content. Run from the
-// publishing package's root after its build:
-//   node .agents/skills/orkestrel-publish/scripts/compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]
-// The package defaults to the manifest's name and the version to what the registry serves; --tarball
-// compares against a local .tgz instead of fetching. Sourcemaps are excluded, a text file differs
-// only when it differs with all whitespace removed, and a binary file differs on any byte. The
-// summary lists the paths added, removed, and changed. Exit 0 when nothing material differs, 3 when
-// something does, 2 when the tarball cannot be read, 64 on usage.
-import { existsSync, readFileSync } from 'node:fs';
-import { relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 import { gunzipSync } from 'node:zlib';
-import { listFiles, readMissingFlags, readOption, parseJsonRecord, readString, runNpm, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const BLOCK = 512;
-const PACKAGE_PREFIX = 'package/';
-function readManifest() {
-    if (!existsSync('package.json'))
+/** Holds the byte size of one tar block. */
+export const BLOCK = 512;
+/** Names the directory every npm tarball entry sits under. */
+export const PACKAGE_PREFIX = 'package/';
+/** Names the directories every tree walk skips by default. */
+export const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'tmp',
+    '.orkestrel',
+    '.idea',
+]);
+/** Holds the empty skip set, because a dist tree holds nothing a walk skips, so every emitted file counts. */
+export const NOTHING_SKIPPED = new Set();
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = ['--package', '--version', '--tarball', '--dist', '--json'];
+/** Holds the usage line the script prints on a usage refusal. */
+export const USAGE = 'usage: compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]';
+/**
+ * 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 `--package`.
+ * @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));
+}
+/**
+ * Lists every regular file beneath a directory, skipping the directories named.
+ *
+ * @remarks
+ * A skipped name matches a directory at any depth, exactly and case-sensitively.
+ *
+ * @param directory - The directory to walk.
+ * @param skipped - The directory names to skip. Default: {@link SKIPPED_DIRECTORIES}.
+ * @returns Each file's forward-slash path and modification time, in walk order.
+ * @throws Thrown when `directory` does not exist or cannot be read; check `existsSync` first.
+ */
+export function listFiles(directory, skipped = SKIPPED_DIRECTORIES) {
+    const files = [];
+    const pending = [directory];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (skipped.has(entry.name))
+                continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (entry.isFile()) {
+                files.push({ path: normalizeSlashes(path), modified: statSync(path).mtimeMs });
+            }
+        }
+    }
+    return files;
+}
+/**
+ * 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 `['view', '@orkestrel/scaffold', 'version']`.
+ * @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 the name and version a directory's package manifest declares.
+ *
+ * @param directory - The directory that holds `package.json`.
+ * @returns The name and version, each undefined when the manifest is absent, unreadable, or lacks it.
+ */
+export function readManifest(directory) {
+    const path = join(directory, 'package.json');
+    if (!existsSync(path))
         return { name: undefined, version: undefined };
     try {
-        const record = parseJsonRecord(readFileSync('package.json', 'utf8'));
+        const record = parseJsonRecord(readFileSync(path, 'utf8'));
         return { name: readString(record, 'name'), version: readString(record, 'version') };
     }
     catch {
         return { name: undefined, version: undefined };
     }
 }
-function readField(text) {
+/**
+ * Reads one value npm printed as JSON.
+ *
+ * @param text - npm's output with the surrounding whitespace removed.
+ * @returns The text without its enclosing quotes, or undefined when nothing remains.
+ */
+export function readField(text) {
     const stripped = text.replace(/^"|"$/gu, '');
     return stripped === '' ? undefined : stripped;
 }
-function readHeaderText(header, start, length) {
+/**
+ * Reads a NUL-terminated text field out of a tar header block.
+ *
+ * @param header - The header block.
+ * @param start - The field's first byte.
+ * @param length - The field's byte length.
+ * @returns The field's text up to its first NUL.
+ */
+export function readHeaderText(header, start, length) {
     const slice = header.subarray(start, start + length);
     const end = slice.indexOf(0);
     return slice.subarray(0, end === -1 ? slice.length : end).toString('utf8');
 }
-function readPaxPath(data, offset = 0) {
+/**
+ * Reads the `path` record out of a pax extended header.
+ *
+ * @param data - The header's data blocks, each record written as `LENGTH KEY=VALUE` and a line feed.
+ * @param offset - The byte where the search starts. Default: 0.
+ * @returns The path the first `path=` record names, or undefined when no record does or one is malformed.
+ */
+export function readPaxPath(data, offset = 0) {
     if (offset >= data.length)
         return undefined;
     const space = data.indexOf(0x20, offset);
@@ -46,9 +224,20 @@ function readPaxPath(data, offset = 0) {
         ? record.slice('path='.length)
         : readPaxPath(data, offset + length);
 }
-// A tar entry occupies a header block and the data blocks its size names, so a step ignores every
-// block offset an earlier entry already consumed.
-function stepTar(archive, state, offset) {
+/**
+ * Advances a tar reader by the block at one offset.
+ *
+ * @remarks
+ * A tar entry occupies a header block and the data blocks its size names, so a step ignores every
+ * block offset an earlier entry already consumed.
+ *
+ * @param archive - The uncompressed archive.
+ * @param state - The reader's state before this block.
+ * @param offset - The block's first byte.
+ * @returns The state after the block: a regular file added, a pax or GNU long name remembered for the
+ * next entry, or the reader done at the first all-zero block.
+ */
+export function stepTar(archive, state, offset) {
     if (state.done || offset < state.next)
         return state;
     const header = archive.subarray(offset, offset + BLOCK);
@@ -73,9 +262,15 @@ function stepTar(archive, state, offset) {
         done: !Number.isFinite(next),
     };
 }
-function readTar(archive) {
+/**
+ * Reads the regular files out of an uncompressed tar archive.
+ *
+ * @param archive - The uncompressed archive.
+ * @returns Each file's path and bytes; a later entry of the same name replaces an earlier one at the
+ * earlier position, as a map write does.
+ */
+export function readTar(archive) {
     const offsets = Array.from({ length: Math.floor(archive.length / BLOCK) }, (_, index) => index * BLOCK);
-    // A later entry of the same name replaces an earlier one at the earlier position, as a map write does.
     return new Map(offsets.reduce((state, offset) => stepTar(archive, state, offset), {
         next: 0,
         name: undefined,
@@ -83,7 +278,13 @@ function readTar(archive) {
         done: false,
     }).files);
 }
-function unpackTar(archive) {
+/**
+ * Unpacks a gzip-compressed tar archive.
+ *
+ * @param archive - The compressed archive.
+ * @returns The regular files it holds, or the error that stopped the unpacking.
+ */
+export function unpackTar(archive) {
     try {
         return readTar(gunzipSync(archive));
     }
@@ -91,7 +292,42 @@ function unpackTar(archive) {
         return error instanceof Error ? error : new Error(String(error));
     }
 }
-async function readSource(name, requested, tarball) {
+/**
+ * Reads one value from npm's view of the registry.
+ *
+ * @param args - The npm arguments, such as `['view', 'name', 'version', '--json']`.
+ * @returns The value npm printed, or undefined when npm exited nonzero or printed nothing.
+ */
+export function readNpmValue(args) {
+    const result = runNpm(args);
+    return result.status === 0 ? readField(result.stdout.trim()) : undefined;
+}
+/**
+ * Fetches a tarball over HTTP.
+ *
+ * @param url - The tarball's address.
+ * @returns The response body, or undefined when the request failed or answered a non-success status.
+ */
+export async function fetchTarball(url) {
+    try {
+        const response = await fetch(url);
+        if (!response.ok)
+            return undefined;
+        return Buffer.from(await response.arrayBuffer());
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reads the tarball a run compares against.
+ *
+ * @param name - The package name to look up when no tarball file is given.
+ * @param requested - The version to compare, or undefined for the one the registry serves.
+ * @param tarball - A local `.tgz` path, or undefined to fetch from the registry.
+ * @returns The archive with its version, or the reason none could be read.
+ */
+export async function readSource(name, requested, tarball) {
     if (tarball !== undefined) {
         return existsSync(tarball)
             ? { archive: readFileSync(tarball), version: requested, failure: undefined }
@@ -113,34 +349,54 @@ async function readSource(name, requested, tarball) {
         ? { archive: undefined, version, failure: `fetching ${url} failed` }
         : { archive: fetched, version, failure: undefined };
 }
-// A dist tree holds nothing a walk skips, so every emitted file counts.
-const NOTHING_SKIPPED = new Set();
-function readNpmValue(args) {
-    const result = runNpm(args);
-    return result.status === 0 ? readField(result.stdout.trim()) : undefined;
-}
-function isMaterial(path) {
+/**
+ * Checks whether a published path counts in the comparison.
+ *
+ * @param path - A path inside the tarball or the dist tree.
+ * @returns True if the path is not a sourcemap; false otherwise.
+ */
+export function isMaterial(path) {
     return !path.endsWith('.map');
 }
-function differs(left, right) {
+/**
+ * Checks whether two versions of one file differ materially.
+ *
+ * @param left - One version's bytes.
+ * @param right - The other version's bytes.
+ * @returns True if a file holding a NUL byte differs on any byte, or a text file differs with all
+ * whitespace removed; false otherwise.
+ */
+export function differs(left, right) {
     if (left.includes(0) || right.includes(0))
         return !left.equals(right);
     return left.toString('utf8').replace(/\s+/gu, '') !== right.toString('utf8').replace(/\s+/gu, '');
 }
-async function main(argv) {
+/**
+ * Runs the comparison and prints its summary.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when nothing material differs, 3 when something does, 2 when the tarball
+ * cannot be read, 64 on usage.
+ */
+export async function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`compare: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
+        return 64;
+    }
     const missing = readMissingFlags(argv, ['--package', '--version', '--tarball', '--dist']);
     if (missing.length > 0) {
         console.error(`compare: ${missing.join(', ')} given with no value`);
         return 64;
     }
-    const manifest = readManifest();
+    const manifest = readManifest('.');
     const name = readOption(argv, '--package') ?? manifest.name;
     const dist = readOption(argv, '--dist') ?? 'dist';
     const tarball = readOption(argv, '--tarball');
     if (name === undefined ||
         !existsSync(dist) ||
         (argv.includes('--tarball') && tarball === undefined)) {
-        console.error('usage: compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]');
+        console.error(USAGE);
         return 64;
     }
     const source = await readSource(name, readOption(argv, '--version'), tarball);
@@ -159,7 +415,7 @@ async function main(argv) {
         ? [[path.slice(prefixed.length), content]]
         : []));
     const local = new Map(listFiles(dist, NOTHING_SKIPPED).flatMap(({ path }) => {
-        const key = relative(dist, path).split('\\').join('/');
+        const key = normalizeSlashes(relative(dist, path));
         return isMaterial(key) ? [[key, readFileSync(path)]] : [];
     }));
     const added = [...local.keys()].filter((key) => !published.has(key)).sort();
@@ -196,17 +452,8 @@ async function main(argv) {
     }
     return material ? 3 : 0;
 }
-async function fetchTarball(url) {
-    try {
-        const response = await fetch(url);
-        if (!response.ok)
-            return undefined;
-        return Buffer.from(await response.arrayBuffer());
-    }
-    catch {
-        return undefined;
-    }
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
 }
-main(process.argv.slice(2)).then((code) => {
-    process.exitCode = code;
-});

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

@@ -8,21 +8,158 @@
 // range (`>=1.2.0 <2.0.0`, `8.x`) hits its literal bounded the same way and not preceded by another
 // range operator. Each matching line prints once as path:line: text, naming the first requested
 // literal that matched in the order --version then each --range, so the operator rules on it.
-// Exit 0 with no hits, 3 with hits, 64 on usage.
-import { readFileSync, statSync } from 'node:fs';
-import { listFiles, readMissingFlags, readOptions, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u;
-const COMPARATOR = /^(?:\^|~|>=|>|<=|<|=)?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)$/u;
-function escapePattern(literal) {
+// Exit 0 with no hits, 3 with hits, 64 on usage, including a flag the script does not read and the
+// `--flag=value` form.
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Matches the file extensions the sweep skips as binary. */
+export const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u;
+/** Matches a range that is one comparator over one full version and captures the version. */
+export const COMPARATOR = /^(?:\^|~|>=|>|<=|<|=)?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)$/u;
+/** Names the directories every tree walk skips. */
+export const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'tmp',
+    '.orkestrel',
+    '.idea',
+]);
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = ['--version', '--range', '--paths', '--json'];
+/** Holds the usage line the script prints on a usage refusal. */
+export const USAGE = 'usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests] [--json]';
+/**
+ * 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 `--paths`.
+ * @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 every value that follows a repeatable flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--range`.
+ * @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] : [];
+    });
+}
+/**
+ * Lists every regular file beneath a directory, skipping the directories the sweep never reads.
+ *
+ * @remarks
+ * A skipped name matches a directory at any depth, exactly and case-sensitively, so a
+ * `src/dist/` directory is skipped with the build output and a `Node_Modules/` directory is not.
+ *
+ * @param directory - The directory to walk.
+ * @param skipped - The directory names to skip. Default: {@link SKIPPED_DIRECTORIES}.
+ * @returns Each file's forward-slash path and modification time, in walk order.
+ * @throws Thrown when `directory` does not exist or cannot be read; check `statSync` first.
+ */
+export function listFiles(directory, skipped = SKIPPED_DIRECTORIES) {
+    const files = [];
+    const pending = [directory];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (skipped.has(entry.name))
+                continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (entry.isFile()) {
+                files.push({ path: normalizeSlashes(path), modified: statSync(path).mtimeMs });
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Escapes a literal for use inside a regular expression.
+ *
+ * @param literal - The text to match exactly.
+ * @returns The text with every regular expression metacharacter backslash-escaped.
+ */
+export function escapePattern(literal) {
     return literal.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
 }
-function buildVersionPattern(version) {
+/**
+ * Builds the pattern that finds a version bounded by characters other than digits and dots.
+ *
+ * @param version - The version literal.
+ * @returns The pattern.
+ */
+export function buildVersionPattern(version) {
     return new RegExp(`(?<![0-9.])${escapePattern(version)}(?![0-9.])`, 'u');
 }
-function buildVersionLiteral(literal) {
+/**
+ * Builds the literal for a requested version.
+ *
+ * @param literal - The version as the operator wrote it.
+ * @returns The literal with its bounded pattern.
+ */
+export function buildVersionLiteral(literal) {
     return { literal, pattern: buildVersionPattern(literal) };
 }
-function buildRangeLiteral(literal) {
+/**
+ * Builds the literal for a requested range.
+ *
+ * @param literal - The range as the operator wrote it.
+ * @returns A one-comparator range matched by its bare version in any form, any other range matched as
+ * its own text not preceded by a range operator.
+ */
+export function buildRangeLiteral(literal) {
     const version = COMPARATOR.exec(literal)?.[1];
     if (version !== undefined)
         return { literal, pattern: buildVersionPattern(version) };
@@ -31,7 +168,14 @@ function buildRangeLiteral(literal) {
         pattern: new RegExp(`(?<![0-9.^~<>=])${escapePattern(literal)}(?![0-9.])`, 'u'),
     };
 }
-function sweepFile(path, literals) {
+/**
+ * Finds the lines of one file that carry a requested literal.
+ *
+ * @param path - The file to read.
+ * @param literals - The literals to look for, in the order that names a line's literal.
+ * @returns One hit per matching line, naming the first literal that matched; none for a binary file.
+ */
+export function sweepFile(path, literals) {
     const content = readFileSync(path);
     if (content.includes(0))
         return [];
@@ -45,7 +189,18 @@ function sweepFile(path, literals) {
             : [{ path, line: index + 1, literal: match.literal, text: text.trim() }];
     });
 }
-function main(argv) {
+/**
+ * Runs the sweep and prints its hits.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 with no hits, 3 with hits, 64 on usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`pins: unknown flag ${unknown.join(', ')}; give each flag and its value as separate arguments\n${USAGE}`);
+        return 64;
+    }
     const missing = readMissingFlags(argv, ['--version', '--range', '--paths']);
     if (missing.length > 0) {
         console.error(`pins: ${missing.join(', ')} given with no value`);
@@ -55,7 +210,7 @@ function main(argv) {
     const ranges = readOptions(argv, '--range');
     const paths = (readOptions(argv, '--paths')[0] ?? 'src,tests').split(',');
     if (version === undefined && ranges.length === 0) {
-        console.error('usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests] [--json]');
+        console.error(USAGE);
         return 64;
     }
     const literals = [
@@ -88,4 +243,6 @@ function main(argv) {
     }
     return hits.length === 0 ? 0 : 3;
 }
-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));
+}