@williamthorsen/nmr 2.0.0 → 2.0.2

package/dist/esm/commands/node-pin.d.ts

@@ -1,10 +1,20 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
+/**
+ * Prefix of node-build's definition files on the branch from which asdf-nodejs updates node-build before an install.
+ * A version is installable through asdf once a file named for it exists here.
+ */
+export declare const NODE_BUILD_DEFINITION_URL = "https://raw.githubusercontent.com/nodenv/node-build/main/share/node-build/";
 /** Node's release index, which lists every release with its version and its UTC release day. */
 export declare const NODE_RELEASE_INDEX_URL = "https://nodejs.org/dist/index.json";
 export interface CheckNodePinOptions {
     /** Returns the parsed release index. Injected by tests; defaults to fetching `NODE_RELEASE_INDEX_URL`. */
     fetchReleases?: () => Promise<unknown>;
+    /**
+     * Reports whether node-build defines a version. Injected by tests; defaults to requesting the version's file under
+     * `NODE_BUILD_DEFINITION_URL`.
+     */
+    isNodeBuildDefined?: (version: string) => Promise<boolean>;
     /** Suppresses the report, but not the warnings. */
     isSilent: boolean;
     /** The current time, against which the soak is measured. Injected by tests. */
@@ -16,15 +26,15 @@ export interface CheckNodePinOptions {
 }
 /**
  * Reports the newest release in the major line of the `nodejs` pin in `dir`'s `.tool-versions` that is newer than
- * the pin and at least 24 hours old, and rewrites the pin to it when `shouldWrite` is set.
+ * the pin, at least 24 hours old, and defined by node-build, and rewrites the pin to it when `shouldWrite` is set.
+ * Reports the newest newer release that node-build does not define yet as held back.
  *
  * Reports nothing when the file or its `nodejs` entry is absent, or when the pin is current. Every failure is a
  * warning, so that the check never fails the upgrade that runs it.
  */
 export declare function checkNodePin(dir: string, options: CheckNodePinOptions): Promise<void>;
 /**
- * Returns the newest plain `X.Y.Z` release in `pin`'s major line that is newer than `pin` and whose UTC release day
- * began at least two days before `now`, or `undefined` when none is. Ignores an entry that lacks a plain version or
- * a `YYYY-MM-DD` date.
+ * Returns every plain `X.Y.Z` release in `pin`'s major line that is newer than `pin` and whose UTC release day began
+ * at least two days before `now`, newest first. Ignores an entry that lacks a plain version or a `YYYY-MM-DD` date.
  */
-export declare function selectNodeUpgrade(pin: string, releases: readonly unknown[], now: Date): string | undefined;
+export declare function selectNodeUpgradeCandidates(pin: string, releases: readonly unknown[], now: Date): string[];

package/dist/esm/commands/node-pin.js

@@ -4,6 +4,7 @@ import process from 'node:process';
 import { formatGlyphLine, isRecord } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { NMR_GLYPHS } from "../glyphs.js";
+export const NODE_BUILD_DEFINITION_URL = 'https://raw.githubusercontent.com/nodenv/node-build/main/share/node-build/';
 export const NODE_RELEASE_INDEX_URL = 'https://nodejs.org/dist/index.json';
 const TOOL_VERSIONS_FILE = '.tool-versions';
 const SOAK_MS = 2 * 24 * 60 * 60 * 1000;
@@ -51,13 +52,30 @@ export async function checkNodePin(dir, options) {
         warn(`${NODE_RELEASE_INDEX_URL} did not return a list of releases`);
         return;
     }
-    const target = selectNodeUpgrade(pin.version, releases, options.now ?? new Date());
-    if (target === undefined)
+    const candidates = selectNodeUpgradeCandidates(pin.version, releases, options.now ?? new Date());
+    let target;
+    try {
+        target = await findNewestDefined(candidates, options.isNodeBuildDefined ?? requestNodeBuildDefinition);
+    }
+    catch (error) {
+        warn(`${NODE_BUILD_DEFINITION_URL} is unreachable (${describeError(error)})`);
+        return;
+    }
+    const heldBack = candidates[0] === target ? undefined : candidates[0];
+    function reportHeldBack() {
+        if (heldBack !== undefined && !options.isSilent) {
+            report(`nodejs ${heldBack} is held back: node-build does not define it yet.`);
+        }
+    }
+    if (target === undefined) {
+        reportHeldBack();
         return;
+    }
     if (!options.shouldWrite) {
         if (!options.isSilent) {
             report(`nodejs ${pin.version} → ${target} is available. Run with --write to update ${TOOL_VERSIONS_FILE}.`);
         }
+        reportHeldBack();
         return;
     }
     const updated = content.slice(0, pin.start) + target + content.slice(pin.start + pin.version.length);
@@ -70,11 +88,11 @@ export async function checkNodePin(dir, options) {
     }
     if (!options.isSilent)
         report(`Updated nodejs ${pin.version} → ${target} in ${TOOL_VERSIONS_FILE}.`);
+    reportHeldBack();
 }
-export function selectNodeUpgrade(pin, releases, now) {
+export function selectNodeUpgradeCandidates(pin, releases, now) {
     const pinParts = parseVersion(pin);
-    let best;
-    let bestVersion;
+    const candidates = [];
     for (const release of releases) {
         if (!isRecord(release))
             continue;
@@ -89,12 +107,9 @@ export function selectNodeUpgrade(pin, releases, now) {
             continue;
         if (Date.parse(`${date}T00:00:00Z`) + SOAK_MS > now.getTime())
             continue;
-        if (best !== undefined && compareVersions(parts, best) <= 0)
-            continue;
-        best = parts;
-        bestVersion = bareVersion;
+        candidates.push({ parts, version: bareVersion });
     }
-    return bestVersion;
+    return candidates.toSorted((a, b) => compareVersions(b.parts, a.parts)).map((candidate) => candidate.version);
 }
 function compareVersions(a, b) {
     for (let index = 0; index < 3; index++) {
@@ -111,6 +126,13 @@ async function fetchNodeReleaseIndex() {
     const body = await response.json();
     return body;
 }
+async function findNewestDefined(candidates, isDefined) {
+    for (const candidate of candidates) {
+        if (await isDefined(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 function findNodePin(content) {
     const match = NODEJS_ENTRY_PATTERN.exec(content);
     const version = match?.[1];
@@ -121,6 +143,17 @@ function findNodePin(content) {
 function isMissingFileError(error) {
     return isRecord(error) && error['code'] === 'ENOENT';
 }
+async function requestNodeBuildDefinition(version) {
+    const response = await fetch(`${NODE_BUILD_DEFINITION_URL}${version}`, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (response.status === 404)
+        return false;
+    if (response.status !== 200)
+        throw new Error(`HTTP ${response.status}`);
+    return true;
+}
 function parseVersion(version) {
     return version.split('.').map(Number);
 }

package/dist/esm/commands/package-manifest.d.ts

@@ -0,0 +1,28 @@
+/** The fix for a broken lookup, whose cause can name the manifest of the resolving package as well as the tool's. */
+export declare const BROKEN_MANIFEST_FIX = "Repair that manifest, or reinstall the package that contains it.";
+/**
+ * Looks up the manifest of `packageName` as `require` from `parent` resolves it, a file path or a file URL.
+ *
+ * Only `MODULE_NOT_FOUND` means that the package is absent: Node rejects an installed package whose manifest is
+ * malformed or unreadable with another code, and the message of that error, which `cause` repeats, names the
+ * manifest at fault. A failure to read or parse the manifest after resolution prefixes `cause` with its path.
+ * `cause` does not end with a period, so that a caller can end the sentence that it composes around it.
+ */
+export declare function findPackageManifest(parent: string, packageName: string): ManifestLookup;
+/** What a lookup of a package's manifest found: the parsed manifest, no installed package, or a broken one. */
+export type ManifestLookup = {
+    kind: 'found';
+    manifestPath: string;
+    manifest: unknown;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'broken';
+    cause: string;
+};
+/**
+ * Returns the absolute path of the CLI that the manifest at `manifestPath` declares for `packageName`, or `undefined`
+ * when it does not declare one. `bin` may be a bare path, which names the package's lone CLI, or a map keyed by
+ * command name.
+ */
+export declare function resolveDeclaredCli(manifest: unknown, manifestPath: string, packageName: string): string | undefined;

package/dist/esm/commands/package-manifest.js

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { hasErrnoCode, isRecord } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+export const BROKEN_MANIFEST_FIX = 'Repair that manifest, or reinstall the package that contains it.';
+export function findPackageManifest(parent, packageName) {
+    let manifestPath;
+    try {
+        manifestPath = createRequire(parent).resolve(`${packageName}/package.json`);
+    }
+    catch (error) {
+        if (hasErrnoCode(error, 'MODULE_NOT_FOUND'))
+            return { kind: 'absent' };
+        return { kind: 'broken', cause: describeCause(error) };
+    }
+    try {
+        const source = readFileSync(manifestPath, 'utf8').replace(/^\u{FEFF}/u, '');
+        return { kind: 'found', manifestPath, manifest: JSON.parse(source) };
+    }
+    catch (error) {
+        return { kind: 'broken', cause: `${manifestPath}: ${describeCause(error)}` };
+    }
+}
+export function resolveDeclaredCli(manifest, manifestPath, packageName) {
+    const declaredBin = isRecord(manifest) ? manifest['bin'] : undefined;
+    const bin = isRecord(declaredBin) ? declaredBin[packageName] : declaredBin;
+    return typeof bin === 'string' ? path.resolve(path.dirname(manifestPath), bin) : undefined;
+}
+function describeCause(error) {
+    return describeError(error).replace(/\.$/, '');
+}

package/dist/esm/commands/publish-output.d.ts

@@ -0,0 +1,40 @@
+/** The pair of directories through which a build publishes, both siblings of the emit directory. */
+export interface ScratchDirs {
+    previousDir: string;
+    stagingDir: string;
+}
+/** One file emitted by the compiler, kept in memory until the whole emit is ready to publish. */
+export interface StagedFile {
+    text: string;
+    writeByteOrderMark: boolean;
+}
+/**
+ * Removes both scratch directories of `emitDir` without failing the caller. `force` suppresses only a missing
+ * top-level path and `rm` does not retry, so a removal racing another build's leaves `ENOTEMPTY`, `EBUSY`, and
+ * `EPERM` live.
+ */
+export declare function discardScratchDirs(emitDir: string): Promise<void>;
+/**
+ * Publishes the staged emit to `emitDir` atomically: It writes the files to a staging directory and swaps that
+ * into place by rename. Returns how many files it published.
+ *
+ * An emit that produces nothing removes `emitDir` instead, because swapping an empty directory into place would
+ * leave a `dist` behind for a package whose entry points do not emit any output.
+ *
+ * A failure while staging precedes the first rename, so it leaves the previous output exactly as it was.
+ */
+export declare function publishOutput(emitDir: string, stagedFiles: Map<string, StagedFile>): Promise<number>;
+/** Removes both scratch directories of `emitDir`, tolerating their absence. */
+export declare function removeScratchDirs(emitDir: string): Promise<void>;
+/**
+ * Resolves the two scratch directories through which a build publishes: `staging`, which the emit is written to,
+ * and `previous`, which the outgoing output is renamed aside to. Both are siblings of the emit directory, so a
+ * rename between them never crosses a filesystem, and both are dot-prefixed so that a leftover stays out of the
+ * globs that select sources.
+ *
+ * The names are fixed rather than unique because the build removes both before use. A unique name would need a
+ * sweep to accomplish that removal, and a sweep cannot tell a directory orphaned by a killed run from one that a
+ * concurrent build is still writing. Because a directory left behind by a failed build is cleared the same way,
+ * the failure path does not need any cleanup of its own.
+ */
+export declare function resolveScratchDirs(emitDir: string): ScratchDirs;

package/dist/esm/commands/publish-output.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { getCompiler } from "./compiler.js";
+import { isWithin } from "./rewrite-specifiers.js";
+export async function discardScratchDirs(emitDir) {
+    try {
+        await removeScratchDirs(emitDir);
+    }
+    catch {
+    }
+}
+export async function publishOutput(emitDir, stagedFiles) {
+    if (stagedFiles.size === 0) {
+        await rm(emitDir, { force: true, recursive: true });
+        return 0;
+    }
+    writeStagedOutput(stagedFiles, emitDir);
+    await swapIntoPlace(emitDir);
+    return stagedFiles.size;
+}
+export async function removeScratchDirs(emitDir) {
+    const { previousDir, stagingDir } = resolveScratchDirs(emitDir);
+    await rm(previousDir, { force: true, recursive: true });
+    await rm(stagingDir, { force: true, recursive: true });
+}
+export function resolveScratchDirs(emitDir) {
+    const parent = path.dirname(emitDir);
+    const name = path.basename(emitDir);
+    return {
+        previousDir: path.join(parent, `.${name}.previous`),
+        stagingDir: path.join(parent, `.${name}.staging`),
+    };
+}
+async function swapIntoPlace(emitDir) {
+    const { previousDir, stagingDir } = resolveScratchDirs(emitDir);
+    const hadPreviousOutput = existsSync(emitDir);
+    if (hadPreviousOutput) {
+        await rename(emitDir, previousDir);
+    }
+    try {
+        await rename(stagingDir, emitDir);
+    }
+    catch (error) {
+        if (hadPreviousOutput && !existsSync(emitDir)) {
+            await rename(previousDir, emitDir);
+        }
+        throw new UserError(`failed to move the built output into ${emitDir}: ${describeError(error)}`, {
+            cause: error,
+        });
+    }
+    await discardScratchDirs(emitDir);
+}
+function writeStagedOutput(stagedFiles, emitDir) {
+    const ts = getCompiler();
+    const { stagingDir } = resolveScratchDirs(emitDir);
+    for (const [fileName, file] of stagedFiles) {
+        if (!isWithin(emitDir, fileName)) {
+            throw new Error(`the compiler emitted ${fileName}, which is outside the output directory ${emitDir}. ` +
+                "Verify the resolved tsconfig's 'outDir' and 'declarationDir'.");
+        }
+        ts.sys.writeFile(path.join(stagingDir, path.relative(emitDir, fileName)), file.text, file.writeByteOrderMark);
+    }
+}

package/dist/esm/commands/report-catalog.d.ts

@@ -8,3 +8,8 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
  * pass runs, to keep the reader from taking that result to mean that every dependency is up to date.
  */
 export declare function reportCatalog(cwd: string, style: OutputStyle): void;
+/**
+ * Runs `nmr-report-catalog` against `argv` from `cwd` and returns the exit code to report. The command takes neither
+ * an option nor an operand, so anything but `--help` is a usage error and reports nothing.
+ */
+export declare function runReportCatalog(argv: string[], cwd: string): Promise<number>;

package/dist/esm/commands/report-catalog.js

@@ -1,8 +1,12 @@
+import process from 'node:process';
 import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
+import { NMR_REPORT_CATALOG_BIN } from "../bins.js";
 import { findContainingPackageDir } from "../context.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 const CATALOG_PROTOCOL = 'catalog:';
 export function reportCatalog(cwd, style) {
@@ -21,6 +25,21 @@ export function reportCatalog(cwd, style) {
     }
     reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'catalog', describeCatalog(dependencies.length, monorepoRoot)), console.warn);
 }
+export async function runReportCatalog(argv, cwd) {
+    const command = defineCommand({
+        summary: 'Report the catalogued dependencies that a package-scoped upgrade does not read',
+        run: () => {
+            reportCatalog(cwd, resolveBinStyles().stderr);
+            return 0;
+        },
+    });
+    return runCli(argv, command, {
+        name: NMR_REPORT_CATALOG_BIN,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        baseDir: cwd,
+    });
+}
 function describeCatalog(count, monorepoRoot) {
     const subject = count === 1 ? '1 catalogued dependency went' : `${count} catalogued dependencies went`;
     const object = count === 1 ? 'it' : 'them';

package/dist/esm/commands/report-overrides.d.ts

@@ -4,3 +4,8 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
  * `pnpm.overrides` block left behind in the root `package.json`.
  */
 export declare function reportOverrides(monorepoRoot: string, style: OutputStyle): void;
+/**
+ * Runs `nmr-report-overrides` against `argv` for the monorepo containing `cwd` and returns the exit code to report.
+ * The command takes neither an option nor an operand, so anything but `--help` is a usage error and reports nothing.
+ */
+export declare function runReportOverrides(argv: string[], cwd: string): Promise<number>;

package/dist/esm/commands/report-overrides.js

@@ -1,8 +1,12 @@
+import process from 'node:process';
 import { formatGlyphLine, UserError } from '@williamthorsen/nmr-core';
+import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
+import { NMR_REPORT_OVERRIDES_BIN } from "../bins.js";
 import { NMR_GLYPHS } from "../glyphs.js";
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
-import { readWorkspaceOverrides } from "../workspace.js";
+import { resolveBinStyles } from "../resolveBinStyles.js";
+import { findMonorepoRoot, readWorkspaceOverrides } from "../workspace.js";
 export function reportOverrides(monorepoRoot, style) {
     const declaredOverrides = listEntries(readWorkspaceOverrides(monorepoRoot));
     if (declaredOverrides.length > 0) {
@@ -14,6 +18,21 @@ export function reportOverrides(monorepoRoot, style) {
     }
     rejectLegacyOverrides(monorepoRoot);
 }
+export async function runReportOverrides(argv, cwd) {
+    const command = defineCommand({
+        summary: 'Report the pnpm overrides that the monorepo declares',
+        run: () => {
+            reportOverrides(findMonorepoRoot(cwd), resolveBinStyles().stderr);
+            return 0;
+        },
+    });
+    return runCli(argv, command, {
+        name: NMR_REPORT_OVERRIDES_BIN,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        baseDir: cwd,
+    });
+}
 function describeOverrides(count) {
     return count === 1
         ? '1 override is active. Check whether it is still needed.'

package/dist/esm/commands/run-vitest.js

@@ -1,13 +1,12 @@
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { isRecord, reportError } from '@williamthorsen/nmr-core';
+import { reportError } from '@williamthorsen/nmr-core';
 import { findMonorepoRoot as findMonorepoRootOrNothing } from '@williamthorsen/nmr-core/workspace';
 import { NMR_VITEST_BIN } from "../bins.js";
-import { describeSignalExitCode } from "../child-process.js";
 import { omitOutcomeFile } from "../stated-outcome.js";
+import { BROKEN_MANIFEST_FIX, findPackageManifest, resolveDeclaredCli } from "./package-manifest.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 const VITEST_PACKAGE = 'vitest';
 const SUPPORTED_VITEST_RANGE = '>=4.0.0 <6';
 const CONFIG_EXTENSIONS = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'];
@@ -17,18 +16,15 @@ export function runNmrVitest(argv, cwd = process.cwd()) {
         reportError(NMR_VITEST_BIN, cli.error);
         return 1;
     }
-    const result = spawnSync(process.execPath, [cli.cliPath, ...chooseVitestConfigArgs(argv, cwd)], {
+    const result = spawnInherited(process.execPath, [cli.cliPath, ...chooseVitestConfigArgs(argv, cwd)], {
         cwd,
         env: omitOutcomeFile(process.env),
-        stdio: 'inherit',
     });
     if (result.error) {
         reportError(NMR_VITEST_BIN, `could not run \`${VITEST_PACKAGE}\` (${result.error.message}).`);
         return 1;
     }
-    if (result.signal !== null)
-        return describeSignalExitCode(result.signal);
-    return result.status ?? 1;
+    return resolveInheritedExitCode(result);
 }
 export function chooseVitestConfigArgs(argv, cwd) {
     if (namesConfig(argv))
@@ -65,17 +61,22 @@ function resolveVitestCli(cwd) {
         ok: false,
         error: `requires Vitest ${SUPPORTED_VITEST_RANGE}, but \`${VITEST_PACKAGE}\` could not be resolved from ${cwd}. Install a version in that range as the \`${VITEST_PACKAGE}\` peer dependency.`,
     };
-    let manifestPath;
-    try {
-        manifestPath = createRequire(path.join(cwd, 'package.json')).resolve(`${VITEST_PACKAGE}/package.json`);
-    }
-    catch {
+    const lookup = findPackageManifest(path.join(cwd, 'package.json'), VITEST_PACKAGE);
+    if (lookup.kind === 'absent')
         return missingResult;
+    if (lookup.kind === 'broken') {
+        return {
+            ok: false,
+            error: `\`${VITEST_PACKAGE}\` could not be loaded from ${cwd}: ${lookup.cause}. ${BROKEN_MANIFEST_FIX}`,
+        };
     }
-    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    const bin = isRecord(manifest) && isRecord(manifest['bin']) ? manifest['bin'][VITEST_PACKAGE] : undefined;
-    if (typeof bin !== 'string') {
-        return { ok: false, error: `\`${VITEST_PACKAGE}\` at ${path.dirname(manifestPath)} does not declare a CLI.` };
+    const { manifest, manifestPath } = lookup;
+    const cliPath = resolveDeclaredCli(manifest, manifestPath, VITEST_PACKAGE);
+    if (cliPath === undefined) {
+        return {
+            ok: false,
+            error: `\`${VITEST_PACKAGE}\` at ${path.dirname(manifestPath)} does not declare a CLI. Reinstall the \`${VITEST_PACKAGE}\` peer dependency.`,
+        };
     }
-    return { ok: true, cliPath: path.resolve(path.dirname(manifestPath), bin) };
+    return { ok: true, cliPath };
 }

package/dist/esm/commands/shellcheck.d.ts

@@ -1,17 +1,12 @@
+import { type SpawnInherited } from './spawn-inherited.js';
 import { type WorkflowTool } from './workflow-tools.js';
-/** How a spawned shellcheck ended. */
-export interface ShellcheckOutcome {
-    error?: Error | undefined;
-    signal: NodeJS.Signals | null;
-    status: number | null;
-}
 export interface RunShellcheckOptions {
     /** Directories under which the pinned tools are cached, in lookup order; defaults to `resolveToolCacheRoots`. */
     cacheRoots?: readonly [string, ...string[]];
     ensure?: (tool: WorkflowTool, cacheRoots: readonly [string, ...string[]]) => Promise<string>;
     /** Lists the tracked `*.sh` files under the root, relative to it. */
     listFiles?: (monorepoRoot: string) => string[];
-    spawn?: (file: string, args: string[], cwd: string) => ShellcheckOutcome;
+    spawn?: SpawnInherited;
 }
 /**
  * Lints the monorepo's tracked shell scripts with the pinned shellcheck and returns its exit status. Trailing

package/dist/esm/commands/shellcheck.js

@@ -1,8 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { runGit, UserError } from '@williamthorsen/nmr-core';
-import { describeSignalExitCode } from "../child-process.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { ensureTool, resolveToolCacheRoots } from "./workflow-tools.js";
 export async function runShellcheck(monorepoRoot, args, options = {}) {
     const shellcheckArgs = args.length > 0 ? [...args] : listPresentScripts(monorepoRoot, options.listFiles);
@@ -13,14 +12,11 @@ export async function runShellcheck(monorepoRoot, args, options = {}) {
     const cacheRoots = options.cacheRoots ?? resolveToolCacheRoots(monorepoRoot);
     const ensure = options.ensure ?? ((tool, roots) => ensureTool(tool, { cacheRoots: roots }));
     const shellcheckPath = await ensure('shellcheck', cacheRoots);
-    const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, monorepoRoot);
+    const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, { cwd: monorepoRoot });
     if (outcome.error !== undefined) {
         throw new UserError(`Cannot run shellcheck: ${outcome.error.message}`, { cause: outcome.error });
     }
-    if (outcome.signal !== null) {
-        return describeSignalExitCode(outcome.signal);
-    }
-    return outcome.status ?? 1;
+    return resolveInheritedExitCode(outcome);
 }
 export function listTrackedScripts(monorepoRoot) {
     const result = runGit(['ls-files', '-z', '--', '*.sh'], monorepoRoot);
@@ -32,7 +28,3 @@ export function listTrackedScripts(monorepoRoot) {
 function listPresentScripts(monorepoRoot, listFiles = listTrackedScripts) {
     return listFiles(monorepoRoot).filter((file) => fs.existsSync(path.join(monorepoRoot, file)));
 }
-function spawnInherited(file, args, cwd) {
-    const result = spawnSync(file, args, { cwd, stdio: 'inherit' });
-    return { error: result.error, signal: result.signal, status: result.status };
-}

package/dist/esm/commands/spawn-inherited.d.ts

@@ -0,0 +1,21 @@
+/** How a program spawned on the caller's stdio ended. */
+export interface InheritedOutcome {
+    error?: Error | undefined;
+    signal: NodeJS.Signals | null;
+    status: number | null;
+}
+export interface SpawnInheritedOptions {
+    /** Directory in which the program runs. Defaults to the current one. */
+    cwd?: string;
+    /** Environment for the program. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/** A function that runs a program on the caller's stdio, the shape of each command's injectable spawn. */
+export type SpawnInherited = typeof spawnInherited;
+/** Returns the exit code that reports how the program ended: the shell's code for a death by signal, else its status. */
+export declare function resolveInheritedExitCode({ signal, status }: Pick<InheritedOutcome, 'signal' | 'status'>): number;
+/**
+ * Runs a program on the caller's stdio, so that it sees the caller's terminal: It colors its output, renders
+ * progress, and reads input as it would when run directly.
+ */
+export declare function spawnInherited(file: string, args: readonly string[], options?: SpawnInheritedOptions): InheritedOutcome;

package/dist/esm/commands/spawn-inherited.js

@@ -0,0 +1,11 @@
+import { spawnSync } from 'node:child_process';
+import { describeSignalExitCode } from "../child-process.js";
+export function resolveInheritedExitCode({ signal, status }) {
+    if (signal !== null)
+        return describeSignalExitCode(signal);
+    return status ?? 1;
+}
+export function spawnInherited(file, args, options = {}) {
+    const result = spawnSync(file, args, { cwd: options.cwd, env: options.env, stdio: 'inherit' });
+    return { error: result.error, signal: result.signal, status: result.status };
+}

package/dist/esm/commands/taze.d.ts

@@ -1,10 +1,7 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import { type CheckNodePinOptions } from './node-pin.js';
-export interface SpawnOutcome {
-    status: number | null;
-    error?: Error | undefined;
-}
+import { type SpawnInherited } from './spawn-inherited.js';
 export interface RunTazeOptions {
     /** Checks the `.tool-versions` Node pin in a directory. Injected by tests. */
     checkNodePin?: (dir: string, options: CheckNodePinOptions) => Promise<void>;
@@ -12,8 +9,11 @@ export interface RunTazeOptions {
     loadConfig?: (cwd: string) => Promise<unknown>;
     /** Resolves the absolute path of taze's CLI entry. Injected by tests. */
     resolveCliPath?: () => string;
-    /** Runs the CLI and reports how it exited. Injected by tests. */
-    spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
+    /**
+     * Runs the CLI on the caller's stdio, so that taze's progress rendering, cursor restore, and `--interactive` mode
+     * see the caller's TTY. Injected by tests.
+     */
+    spawn?: SpawnInherited;
     /** Stream that error output and pass headings are written to. Defaults to `process.stderr`. */
     stderr?: Writable;
     /** Style of `stderr`, in which the Node pin check reports. Defaults to `'plain'`. */

package/dist/esm/commands/taze.js

@@ -1,4 +1,3 @@
-import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -7,6 +6,7 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { NMR_TAZE_BIN } from "../bins.js";
 import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
 import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { isSilent, readFlag } from "./taze-args.js";
 import { planTazePasses } from "./taze-passes.js";
 const TAZE_CLI_SPECIFIER = 'taze/cli';
@@ -17,7 +17,7 @@ const NODE_PIN_SKIP_FLAGS = ['--no-node-version', '--help', '-h', '--version', '
 export async function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
     const resolveCliPath = options.resolveCliPath ?? resolveTazeCliPath;
-    const spawn = options.spawn ?? spawnNode;
+    const spawn = options.spawn ?? spawnInherited;
     const loadConfig = options.loadConfig ?? loadPackageMaturityPeriod;
     let cliPath;
     try {
@@ -59,7 +59,7 @@ export async function runTaze(args, options = {}) {
             reportError(NMR_TAZE_BIN, `Failed to run taze: ${outcome.error.message}`, stderr);
             return 1;
         }
-        const status = outcome.status ?? 1;
+        const status = resolveInheritedExitCode(outcome);
         if (exitCode === 0)
             exitCode = status;
     }
@@ -74,7 +74,3 @@ function composeRequestTimeoutArgs(args) {
 function resolveConfigDir(args) {
     return path.resolve(readFlag(args, ['--cwd', '-C'])?.value ?? '.');
 }
-function spawnNode(nodePath, argv) {
-    const result = spawnSync(nodePath, argv, { stdio: 'inherit' });
-    return { status: result.status, error: result.error };
-}

package/dist/esm/config-validation.js

@@ -1,5 +1,5 @@
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
-import { assertResolvableCheckCacheCommands } from "./config-check-cache.js";
+import { assertResolvableCheckCacheCommands } from "./check-cache/config-check-cache.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {