@williamthorsen/nmr 2.0.1 → 2.0.2

package/dist/esm/{recording.js → check-cache/recording.js}

@@ -1,7 +1,7 @@
 import { formatGlyphLine, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { NMR_GLYPHS } from "../glyphs.js";
+import { formatDuration } from "../helpers/duration.js";
 import { readCheckCacheEntry, readTranscript } from "./check-cache-entries.js";
-import { NMR_GLYPHS } from "./glyphs.js";
-import { formatDuration } from "./helpers/duration.js";
 export function renderRecording(options) {
     const { entry } = options.recording;
     const age = formatDuration(Math.max(0, Date.now() - Date.parse(entry.recordedAt)));

package/dist/esm/{replay-assembly.d.ts → check-cache/replay-assembly.d.ts}

@@ -1,5 +1,5 @@
+import { type Step } from '../steps.js';
 import { type ReplayLine } from './check-cache-entries.js';
-import { type Step } from './steps.js';
 /**
  * Assembles what a composite's skip replays: the excerpts recorded by its constituents, in the order in which
  * its own steps name them.

package/dist/esm/{replay-assembly.js → check-cache/replay-assembly.js}

@@ -1,6 +1,6 @@
+import { readNmrStep } from "../steps.js";
+import { getWorkspacePackageDirs } from "../workspace.js";
 import { readCheckCacheEntry } from "./check-cache-entries.js";
-import { readNmrStep } from "./steps.js";
-import { getWorkspacePackageDirs } from "./workspace.js";
 export async function assembleReplay(options) {
     const { anchorDir, monorepoRoot, runId, steps, treeHash } = options;
     const candidates = steps.flatMap((step) => {

package/dist/esm/child-env.d.ts

@@ -1,5 +1,5 @@
 import type { StreamStyles } from '@williamthorsen/nmr-core';
-import { type TreeSnapshot } from './check-cache.js';
+import { type TreeSnapshot } from './check-cache/check-cache.js';
 import type { Invocation } from './invocation.js';
 import { type MachineLock } from './machine-lock.js';
 import { type ReportFormat } from './report-format.js';

package/dist/esm/child-env.js

@@ -1,8 +1,8 @@
-import { DEBUG_ENV_VAR, encodeTreeSnapshot, NO_CACHE_ENV_VAR, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, } from "./check-cache.js";
+import { DEBUG_ENV_VAR, encodeTreeSnapshot, NO_CACHE_ENV_VAR, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, } from "./check-cache/check-cache.js";
+import { DELEGATE_ENV_VAR } from "./delegation/remote-run.js";
 import { acquireMachineLock, formatMisplacedNoLockWarning, HEAVY_COMMANDS, LOCK_TOKEN_ENV_VAR, NO_LOCK_ENV_VAR, } from "./machine-lock.js";
 import { formatFlagSpelling } from "./nmr-flags.js";
 import { OUTPUT_STYLE_ENV_VAR } from "./output-style.js";
-import { DELEGATE_ENV_VAR } from "./remote-run.js";
 import { REPORT_FORMAT_ENV_VAR } from "./report-format.js";
 import { COMMAND_VERBOSITY_ENV_VAR } from "./verbosity.js";
 export function addLockEnv(env, lock) {

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

@@ -1,15 +1,10 @@
+import { type SpawnInherited } from './spawn-inherited.js';
 import { type WorkflowTool } from './workflow-tools.js';
-/** How a spawned actionlint ended. */
-export interface ActionlintOutcome {
-    error?: Error | undefined;
-    signal: NodeJS.Signals | null;
-    status: number | null;
-}
 export interface RunActionlintOptions {
     /** 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>;
-    spawn?: (file: string, args: string[], cwd: string) => ActionlintOutcome;
+    spawn?: SpawnInherited;
 }
 /**
  * Lints the monorepo's GitHub Actions workflows with the pinned actionlint, running its shellcheck pass with the

package/dist/esm/commands/actionlint.js

@@ -1,8 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { 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";
 const WORKFLOWS_DIR = path.join('.github', 'workflows');
 export async function runActionlint(monorepoRoot, args, options = {}) {
@@ -14,19 +13,14 @@ export async function runActionlint(monorepoRoot, args, options = {}) {
     const ensure = options.ensure ?? ((tool, roots) => ensureTool(tool, { cacheRoots: roots }));
     const actionlintPath = await ensure('actionlint', cacheRoots);
     const shellcheckPath = await ensure('shellcheck', cacheRoots);
-    const outcome = (options.spawn ?? spawnInherited)(actionlintPath, buildActionlintArgs(shellcheckPath, args), monorepoRoot);
+    const outcome = (options.spawn ?? spawnInherited)(actionlintPath, buildActionlintArgs(shellcheckPath, args), {
+        cwd: monorepoRoot,
+    });
     if (outcome.error !== undefined) {
         throw new UserError(`Cannot run actionlint: ${outcome.error.message}`, { cause: outcome.error });
     }
-    if (outcome.signal !== null) {
-        return describeSignalExitCode(outcome.signal);
-    }
-    return outcome.status ?? 1;
+    return resolveInheritedExitCode(outcome);
 }
 export function buildActionlintArgs(shellcheckPath, args) {
     return [`-shellcheck=${shellcheckPath}`, '-pyflakes=', ...args];
 }
-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/clean.js

@@ -4,7 +4,7 @@ import process from 'node:process';
 import { UserError } from '@williamthorsen/nmr-core';
 import { defineCommand, runCli } from '@williamthorsen/nmr-core/cli';
 import { NMR_CLEAN_BIN } from "../bins.js";
-import { removeCheckCache } from "../check-cache-entries.js";
+import { removeCheckCache } from "../check-cache/check-cache-entries.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
 import { reportClosing } from "../helpers/reportClosing.js";

package/dist/esm/commands/fmt-cache.js

@@ -2,7 +2,8 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { NO_CACHE_ENV_VAR } from "../check-cache.js";
+import { NO_CACHE_ENV_VAR } from "../check-cache/check-cache.js";
+import { isEnvSwitchOn } from "../env-switch.js";
 export const FMT_CACHE_DIRECTORY = path.join('node_modules', '.cache', 'prettier', 'nmr-fmt');
 const LOCKFILE_NAMES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lock', 'bun.lockb'];
 const NO_LOCKFILE_MARKER = 'nolock';
@@ -10,7 +11,7 @@ const HASH_LENGTH = 16;
 const CACHE_FILE_PATTERN = /^([0-9a-f]{16})\.([0-9a-f]{16}|nolock)\.json$/;
 export function prepareFmtCache(options) {
     const { cwd, env, repositoryRoot, shouldBypassCache } = options;
-    if (shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1')
+    if (shouldBypassCache || isEnvSwitchOn(env, NO_CACHE_ENV_VAR))
         return { kind: 'uncached' };
     try {
         if (statSync(path.join(repositoryRoot, 'node_modules'), { throwIfNoEntry: false })?.isDirectory() !== true) {

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

@@ -1,24 +1,17 @@
+import { type SpawnInherited } from './spawn-inherited.js';
 export type FormatMode = 'check' | 'write';
 /**
  * Runs `nmr-fmt` against `argv` and returns the exit code to report: It formats or checks the files that git
  * reports for `cwd`. A repository without a Prettier config of its own is formatted with the house config. The run
- * uses Prettier's content-keyed cache unless `--no-cache` or `NMR_NO_CACHE=1` bypasses it.
+ * uses Prettier's content-keyed cache unless `--no-cache` or `NMR_NO_CACHE=1` bypasses it, and an `NMR_NO_CACHE`
+ * that is neither on nor off is rejected as a usage error.
  *
  * Trailing arguments are git pathspecs, not Prettier flags; an unrecognized option is rejected rather
  * than passed along, since git would read it as a pathspec matching nothing and the run would report
  * success over an empty selection. Every argument after `--` is a pathspec, even one that starts
  * with `-`.
  */
-export declare function runFmt(argv: string[], cwd?: string): Promise<number>;
-/**
- * How a spawned Prettier process ended.
- *
- * @internal
- */
-export interface PrettierOutcome {
-    error?: Error | undefined;
-    status: number | null;
-}
+export declare function runFmt(argv: string[], cwd?: string, env?: NodeJS.ProcessEnv): Promise<number>;
 /** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
@@ -32,8 +25,8 @@ export interface RunPrettierOptions {
     cwd: string;
     /** Overridable so that the multi-batch path is reachable without a fixture that hits the real ceiling. */
     budgetBytes?: number;
-    /** Runs the Prettier CLI as `file` with `args` in `cwd`. */
-    spawn?: (file: string, args: string[], cwd: string) => PrettierOutcome;
+    /** Runs the Prettier CLI on the caller's stdio. */
+    spawn?: SpawnInherited;
 }
 /**
  * Runs Prettier over the selection, returning the first non-zero exit code. Every batch runs even after

package/dist/esm/commands/fmt.js

@@ -1,6 +1,4 @@
 import { Buffer } from 'node:buffer';
-import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import process from 'node:process';
@@ -9,8 +7,12 @@ import { isRecord, reportError } from '@williamthorsen/nmr-core';
 import { defineCommand, runCli, UsageError } from '@williamthorsen/nmr-core/cli';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { NMR_FMT_BIN } from "../bins.js";
+import { NO_CACHE_ENV_VAR } from "../check-cache/check-cache.js";
+import { readEnvSwitch } from "../env-switch.js";
 import { prepareFmtCache } from "./fmt-cache.js";
 import { resolveFormatTargets } from "./format-targets.js";
+import { BROKEN_MANIFEST_FIX, findPackageManifest, resolveDeclaredCli, } from "./package-manifest.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 const PRETTIER_PACKAGE = 'prettier';
 const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default.config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 const ARGUMENT_BUDGET_BYTES = 100_000;
@@ -18,7 +20,7 @@ const MODE_ARGS = {
     check: ['--check'],
     write: ['--list-different', '--write'],
 };
-export async function runFmt(argv, cwd = process.cwd()) {
+export async function runFmt(argv, cwd = process.cwd(), env = process.env) {
     const command = defineCommand({
         summary: 'Format or check the files that git lists',
         flags: {
@@ -31,12 +33,20 @@ export async function runFmt(argv, cwd = process.cwd()) {
             if (flags.check === flags.write) {
                 throw new UsageError(flags.check ? 'Pass --check or --write, not both.' : 'Pass --check or --write.');
             }
-            return formatFiles({ mode: flags.check ? 'check' : 'write', pathspecs: operands.pathspec, shouldBypassCache: flags.noCache }, cwd);
+            const noCache = readEnvSwitch(env, NO_CACHE_ENV_VAR);
+            if (!noCache.ok) {
+                throw new UsageError(noCache.error);
+            }
+            return formatFiles({
+                mode: flags.check ? 'check' : 'write',
+                pathspecs: operands.pathspec,
+                shouldBypassCache: flags.noCache || noCache.isOn,
+            }, cwd, env);
         },
     });
     return runCli(argv, command, { name: NMR_FMT_BIN, stdout: process.stdout, stderr: process.stderr, baseDir: cwd });
 }
-async function formatFiles(request, cwd) {
+async function formatFiles(request, cwd, env) {
     const resolvedTargets = resolveFormatTargets(cwd, request.pathspecs);
     if (!resolvedTargets.ok) {
         reportError(NMR_FMT_BIN, resolvedTargets.error);
@@ -70,7 +80,7 @@ async function formatFiles(request, cwd) {
     }
     const cache = prepareFmtCache({
         cwd,
-        env: process.env,
+        env,
         repositoryRoot,
         shouldBypassCache: request.shouldBypassCache,
     });
@@ -92,17 +102,36 @@ function resolvePrettierCli(cwd) {
         ok: false,
         error: `\`${PRETTIER_PACKAGE}\` could not be resolved from this repository or from nmr's own installation, which declares it as a dependency. Reinstall \`@williamthorsen/nmr\`.`,
     };
-    const manifestPath = resolveFrom(path.join(cwd, 'package.json'), `${PRETTIER_PACKAGE}/package.json`) ??
-        resolveFrom(import.meta.url, `${PRETTIER_PACKAGE}/package.json`);
-    if (manifestPath === undefined)
-        return missingResult;
-    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-    if (!isRecord(manifest))
-        return missingResult;
-    const bin = isRecord(manifest['bin']) ? manifest['bin'][PRETTIER_PACKAGE] : manifest['bin'];
-    if (typeof bin !== 'string')
+    const repositoryLookup = findPackageManifest(path.join(cwd, 'package.json'), PRETTIER_PACKAGE);
+    const copy = repositoryLookup.kind === 'absent'
+        ? {
+            lookup: findPackageManifest(import.meta.url, PRETTIER_PACKAGE),
+            origin: "nmr's installation",
+            reinstallStep: 'Reinstall `@williamthorsen/nmr`.',
+        }
+        : {
+            lookup: repositoryLookup,
+            origin: 'this repository',
+            reinstallStep: `Reinstall this repository's \`${PRETTIER_PACKAGE}\` dependency.`,
+        };
+    const { lookup } = copy;
+    if (lookup.kind === 'absent')
         return missingResult;
-    return { ok: true, cliPath: path.resolve(path.dirname(manifestPath), bin), manifestPath };
+    if (lookup.kind === 'broken') {
+        return {
+            ok: false,
+            error: `\`${PRETTIER_PACKAGE}\` could not be loaded from ${copy.origin}: ${lookup.cause}. ${BROKEN_MANIFEST_FIX}`,
+        };
+    }
+    const { manifest, manifestPath } = lookup;
+    const cliPath = resolveDeclaredCli(manifest, manifestPath, PRETTIER_PACKAGE);
+    if (cliPath === undefined) {
+        return {
+            ok: false,
+            error: `\`${PRETTIER_PACKAGE}\` at ${path.dirname(manifestPath)} does not declare a CLI. ${copy.reinstallStep}`,
+        };
+    }
+    return { ok: true, cliPath, manifestPath };
 }
 async function findRepositoryConfig(manifestPath, cwd) {
     try {
@@ -136,12 +165,12 @@ export function runPrettier(options) {
     ];
     let firstFailureStatus = 0;
     for (const batch of batchWithinBudget(files, budgetBytes)) {
-        const result = spawn(process.execPath, [...prettierArgs, ...batch], cwd);
+        const result = spawn(process.execPath, [...prettierArgs, ...batch], { cwd });
         if (result.error) {
             reportError(NMR_FMT_BIN, `could not run \`${PRETTIER_PACKAGE}\` (${result.error.message}).`);
             return 1;
         }
-        const status = result.status ?? 1;
+        const status = resolveInheritedExitCode(result);
         if (status !== 0 && firstFailureStatus === 0) {
             firstFailureStatus = status;
         }
@@ -166,15 +195,3 @@ function batchWithinBudget(files, budgetBytes) {
         batches.push(batch);
     return batches;
 }
-function resolveFrom(parent, specifier) {
-    try {
-        return createRequire(parent).resolve(specifier);
-    }
-    catch {
-        return undefined;
-    }
-}
-function spawnInherited(file, args, cwd) {
-    const { error, status } = spawnSync(file, args, { cwd, stdio: 'inherit' });
-    return { error, status };
-}

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/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 };
-}