@williamthorsen/nmr 0.53.1 → 0.54.1

package/dist/esm/commands/actionlint.js

@@ -1,6 +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 { ensureTool } from "./workflow-tools.js";
 const WORKFLOWS_DIR = path.join('.github', 'workflows');
@@ -15,7 +16,7 @@ export async function runActionlint(monorepoRoot, args, options = {}) {
     const shellcheckPath = await ensure('shellcheck', cacheRoot);
     const outcome = (options.spawn ?? spawnInherited)(actionlintPath, buildActionlintArgs(shellcheckPath, args), monorepoRoot);
     if (outcome.error !== undefined) {
-        throw new Error(`Cannot run actionlint: ${outcome.error.message}`, { cause: outcome.error });
+        throw new UserError(`Cannot run actionlint: ${outcome.error.message}`, { cause: outcome.error });
     }
     if (outcome.signal !== null) {
         return describeSignalExitCode(outcome.signal);

package/dist/esm/commands/build.js

@@ -2,7 +2,8 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine, readCacheEntry, startTimer, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, readCacheEntry, startTimer, STATUS_GLYPHS, UserError, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { glob } from 'glob';
 import { NMR_GLYPHS } from "../glyphs.js";
 import { resolveConfigPath } from "../helpers/config-path.js";
@@ -91,7 +92,7 @@ async function emitPackage(packageDir, entryPoints, outdir) {
 }
 function assertEmitSucceeded(result) {
     if (result.emitSkipped) {
-        throw new Error(`nmr-compile: emit failed.\n${formatDiagnostics(result.diagnostics)}`);
+        throw new UserError(`nmr-compile: emit failed.\n${formatDiagnostics(result.diagnostics)}`);
     }
 }
 function createCachingCompilerHost(compilerOptions) {
@@ -126,7 +127,7 @@ function resolveEmitDir(packageDir, outdir) {
     if (relativePathFromPackage === '' ||
         relativePathFromPackage.startsWith('..') ||
         path.isAbsolute(relativePathFromPackage)) {
-        throw new Error(`nmr-compile: refusing to build into '${outdir}', which does not resolve inside the package. ` +
+        throw new UserError(`nmr-compile: refusing to build into '${outdir}', which does not resolve inside the package. ` +
             'The build replaces its output directory on each emit, so the directory must be below the package root.');
     }
     return resolvedDir;
@@ -143,7 +144,9 @@ async function swapIntoPlace(emitDir, scratchDirs) {
         if (hadPreviousOutput && !existsSync(emitDir)) {
             await rename(scratchDirs.previousDir, emitDir);
         }
-        throw error;
+        throw new UserError(`nmr-compile: failed to move the built output into ${emitDir}: ${describeError(error)}`, {
+            cause: error,
+        });
     }
     await discardScratchDirs(scratchDirs);
 }
@@ -152,11 +155,11 @@ function synthesizeCompilerOptions(packageDir, outdir) {
     const configPath = path.join(packageDir, 'tsconfig.json');
     const configFile = ts.readConfigFile(configPath, (fileName) => ts.sys.readFile(fileName));
     if (configFile.error) {
-        throw new Error(`nmr-compile: failed to read ${configPath}.\n${formatDiagnostics([configFile.error])}`);
+        throw new UserError(`nmr-compile: failed to read ${configPath}.\n${formatDiagnostics([configFile.error])}`);
     }
     const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, packageDir);
     if (parsedConfig.errors.length > 0) {
-        throw new Error(`nmr-compile: failed to parse ${configPath}.\n${formatDiagnostics(parsedConfig.errors)}`);
+        throw new UserError(`nmr-compile: failed to parse ${configPath}.\n${formatDiagnostics(parsedConfig.errors)}`);
     }
     const resolvedOutDir = path.resolve(packageDir, outdir);
     return {

package/dist/esm/commands/clean.js

@@ -1,6 +1,6 @@
 import { rm } from 'node:fs/promises';
 import path from 'node:path';
-import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, UserError } from '@williamthorsen/nmr-core';
 import { removeCheckCache } from "../check-cache-entries.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
@@ -71,7 +71,7 @@ async function sweepWorkspace(monorepoRoot, workspacePackageDirs, style) {
             channels: { stderr: resolveChannel(process.stderr, false), stdout: resolveChannel(process.stdout, false) },
         });
         if (exitCode !== 0) {
-            throw new Error(`nmr-clean: \`${command}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
+            throw new UserError(`nmr-clean: \`${command}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
         }
         cleanedCount++;
     }

package/dist/esm/commands/compiler.js

@@ -1,4 +1,4 @@
-import { hasErrnoCode } from '@williamthorsen/nmr-core';
+import { hasErrnoCode, UserError } from '@williamthorsen/nmr-core';
 const MINIMUM_TYPESCRIPT_MAJOR = 5;
 const MINIMUM_TYPESCRIPT_MINOR = 7;
 const UNSUPPORTED_TYPESCRIPT_MAJOR = 7;
@@ -14,7 +14,7 @@ export function assertSupportedTypeScript() {
     const minor = minorPart === undefined ? 0 : Number(minorPart);
     const tooOld = major < MINIMUM_TYPESCRIPT_MAJOR || (major === MINIMUM_TYPESCRIPT_MAJOR && minor < MINIMUM_TYPESCRIPT_MINOR);
     if (tooOld || major >= UNSUPPORTED_TYPESCRIPT_MAJOR) {
-        throw new Error(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but found ` +
+        throw new UserError(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but found ` +
             `${typeof version === 'string' ? version : 'a version without the compiler API'}. ${INSTALL_TYPESCRIPT_GUIDANCE}`);
     }
 }
@@ -38,7 +38,7 @@ export async function loadCompiler(loadTypeScript = importTypeScript) {
     }
     catch (error) {
         if (hasErrnoCode(error, 'ERR_MODULE_NOT_FOUND') && error.message.includes("'typescript'")) {
-            throw new Error(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but 'typescript' could not be resolved. ` +
+            throw new UserError(`nmr-compile requires TypeScript ${SUPPORTED_TYPESCRIPT_RANGE}, but 'typescript' could not be resolved. ` +
                 INSTALL_TYPESCRIPT_GUIDANCE, { cause: error });
         }
         throw error;

package/dist/esm/commands/ensure-prepublish-hooks.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { STATUS_GLYPHS, UserError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
 import { isObject } from "../helpers/type-guards.js";
@@ -75,9 +76,15 @@ export function reportPrepublishHooks(result, hookCommand, style) {
 function addPrepublishOnly(packageDir, command) {
     const filePath = path.join(packageDir, 'package.json');
     const rawText = readFileSync(filePath, 'utf8');
-    const parsedManifest = JSON.parse(rawText);
+    let parsedManifest;
+    try {
+        parsedManifest = JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new UserError(`Invalid package.json in ${packageDir}: ${describeError(error)}`, { cause: error });
+    }
     if (!isObject(parsedManifest)) {
-        throw new TypeError(`Invalid package.json in ${packageDir}: expected an object`);
+        throw new UserError(`Invalid package.json in ${packageDir}: expected an object`);
     }
     const scripts = isObject(parsedManifest['scripts']) ? parsedManifest['scripts'] : {};
     scripts['prepublishOnly'] = command;

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

@@ -0,0 +1,30 @@
+import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+/** 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>;
+    /** Suppresses the report, but not the warnings. */
+    isSilent: boolean;
+    /** The current time, against which the soak is measured. Injected by tests. */
+    now?: Date;
+    shouldWrite: boolean;
+    /** Stream that the report and the warnings are written to. Defaults to `process.stderr`. */
+    stderr?: Writable;
+    style: OutputStyle;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function selectNodeUpgrade(pin: string, releases: readonly unknown[], now: Date): string | undefined;

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

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { NMR_GLYPHS } from "../glyphs.js";
+import { isObject } from "../helpers/type-guards.js";
+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;
+const FETCH_TIMEOUT_MS = 10_000;
+const NODEJS_ENTRY_PATTERN = /^[ \t]*nodejs[ \t]+([^\s#]+)/m;
+const PLAIN_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const RELEASE_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+export async function checkNodePin(dir, options) {
+    const stderr = options.stderr ?? process.stderr;
+    function report(message) {
+        stderr.write(`${formatGlyphLine(NMR_GLYPHS, options.style, 'pin', message)}\n`);
+    }
+    function warn(detail) {
+        report(`WARN: Could not check the nodejs pin: ${detail}`);
+    }
+    const filePath = path.join(dir, TOOL_VERSIONS_FILE);
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return;
+        warn(describeError(error));
+        return;
+    }
+    const pin = findNodePin(content);
+    if (pin === undefined)
+        return;
+    if (!PLAIN_VERSION_PATTERN.test(pin.version)) {
+        if (!options.isSilent) {
+            report(`Skipped the nodejs pin '${pin.version}' in ${TOOL_VERSIONS_FILE}: Only an X.Y.Z version is checked.`);
+        }
+        return;
+    }
+    let releases;
+    try {
+        releases = await (options.fetchReleases ?? fetchNodeReleaseIndex)();
+    }
+    catch (error) {
+        warn(`${NODE_RELEASE_INDEX_URL} is unreachable (${describeError(error)})`);
+        return;
+    }
+    if (!Array.isArray(releases)) {
+        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)
+        return;
+    if (!options.shouldWrite) {
+        if (!options.isSilent) {
+            report(`nodejs ${pin.version} → ${target} is available. Run with --write to update ${TOOL_VERSIONS_FILE}.`);
+        }
+        return;
+    }
+    const updated = content.slice(0, pin.start) + target + content.slice(pin.start + pin.version.length);
+    try {
+        fs.writeFileSync(filePath, updated);
+    }
+    catch (error) {
+        warn(describeError(error));
+        return;
+    }
+    if (!options.isSilent)
+        report(`Updated nodejs ${pin.version} → ${target} in ${TOOL_VERSIONS_FILE}.`);
+}
+export function selectNodeUpgrade(pin, releases, now) {
+    const pinParts = parseVersion(pin);
+    let best;
+    let bestVersion;
+    for (const release of releases) {
+        if (!isObject(release))
+            continue;
+        const { date, version } = release;
+        if (typeof version !== 'string' || typeof date !== 'string' || !RELEASE_DATE_PATTERN.test(date))
+            continue;
+        const bareVersion = version.replace(/^v/, '');
+        if (!PLAIN_VERSION_PATTERN.test(bareVersion))
+            continue;
+        const parts = parseVersion(bareVersion);
+        if (parts[0] !== pinParts[0] || compareVersions(parts, pinParts) <= 0)
+            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;
+    }
+    return bestVersion;
+}
+function compareVersions(a, b) {
+    for (let index = 0; index < 3; index++) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+async function fetchNodeReleaseIndex() {
+    const response = await fetch(NODE_RELEASE_INDEX_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    const body = await response.json();
+    return body;
+}
+function findNodePin(content) {
+    const match = NODEJS_ENTRY_PATTERN.exec(content);
+    const version = match?.[1];
+    if (match === null || version === undefined)
+        return undefined;
+    return { start: match.index + match[0].length - version.length, version };
+}
+function isMissingFileError(error) {
+    return isObject(error) && error['code'] === 'ENOENT';
+}
+function parseVersion(version) {
+    return version.split('.').map(Number);
+}

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

@@ -1,8 +1,7 @@
-import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, UserError } from '@williamthorsen/nmr-core';
 import { NMR_GLYPHS } from "../glyphs.js";
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
-import { UserError } from "../UserError.js";
 import { readWorkspaceOverrides } from "../workspace.js";
 export function reportOverrides(monorepoRoot, style) {
     const declaredOverrides = listEntries(readWorkspaceOverrides(monorepoRoot));

package/dist/esm/commands/rewrite-specifiers.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
 import { getCompiler } from "./compiler.js";
 const TS_EXTENSIONS = ['.ts', '.tsx'];
 const JS_EXTENSION = '.js';
@@ -88,7 +89,7 @@ function resolveSpecifierReplacement(specifier, sourceContainingFile, compilerOp
     const ts = getCompiler();
     const resolvedModule = ts.resolveModuleName(specifier, sourceContainingFile, compilerOptions, ts.sys).resolvedModule;
     if (!resolvedModule) {
-        throw new Error(`nmr-compile: could not resolve aliased import '${specifier}' from ${sourceContainingFile}. ` +
+        throw new UserError(`nmr-compile: could not resolve aliased import '${specifier}' from ${sourceContainingFile}. ` +
             `Verify the tsconfig 'paths' mapping and that the target file exists.`);
     }
     if (!isWithin(sourceRoot, resolvedModule.resolvedFileName)) {
@@ -97,7 +98,7 @@ function resolveSpecifierReplacement(specifier, sourceContainingFile, compilerOp
         if (bareResolvedModule) {
             return undefined;
         }
-        throw new Error(`nmr-compile: aliased import '${specifier}' from ${sourceContainingFile} resolves to ` +
+        throw new UserError(`nmr-compile: aliased import '${specifier}' from ${sourceContainingFile} resolves to ` +
             `${resolvedModule.resolvedFileName}, outside the package source root ${sourceRoot}, and does not resolve ` +
             `the way Node will at runtime, which ignores tsconfig 'paths', 'baseUrl', and 'rootDirs'. The ` +
             `emitted specifier would fail at runtime; re-anchor the alias inside the package.`);

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

@@ -1,9 +1,13 @@
 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;
 }
 export interface RunTazeOptions {
+    /** Checks the `.tool-versions` Node pin in a directory. Injected by tests. */
+    checkNodePin?: (dir: string, options: CheckNodePinOptions) => Promise<void>;
     /** Returns the `packageMaturityPeriod` that the taze config governing a directory declares. Injected by tests. */
     loadConfig?: (cwd: string) => Promise<unknown>;
     /** Resolves the absolute path of taze's CLI entry. Injected by tests. */
@@ -12,6 +16,8 @@ export interface RunTazeOptions {
     spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
     /** 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'`. */
+    stderrStyle?: OutputStyle;
 }
 /**
  * Runs taze from nmr's own dependency tree, forwarding `args`, and returns its exit code.
@@ -24,6 +30,10 @@ export interface RunTazeOptions {
  * root `node_modules/.bin`. This launcher runs taze without that bin: pnpm links nmr's own bins into the
  * consumer root, and nmr resolves taze from the tree that it does control.
  *
+ * Before the passes, checks the `nodejs` pin in the `.tool-versions` of the directory from which taze resolves its
+ * config, reporting a newer release in the pin's major line and rewriting the pin under `--write`. The check only
+ * warns on failure, so it does not affect the exit code.
+ *
  * Every pass also receives a request timeout, unless `args` sets one. Neither other site can declare it: Because
  * an invocation's trailing arguments are appended to the resolved command string, the same flag in the `upgrade`
  * script would be doubled by `nmr upgrade --request-timeout ...`, and taze's parser collects the pair into an

package/dist/esm/commands/taze.js

@@ -5,12 +5,14 @@ import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
+import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
 import { isSilent, readFlag } from "./taze-args.js";
 import { planTazePasses } from "./taze-passes.js";
 const TAZE_CLI_SPECIFIER = 'taze/cli';
 const REQUEST_TIMEOUT_FLAG = '--request-timeout';
 const REQUEST_TIMEOUT_FLAGS = [REQUEST_TIMEOUT_FLAG, '--requestTimeout'];
 const REQUEST_TIMEOUT_MS = 30_000;
+const NODE_PIN_SKIP_FLAGS = ['--no-node-version', '--help', '-h', '--version', '-v'];
 export async function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
     const resolveCliPath = options.resolveCliPath ?? resolveTazeCliPath;
@@ -33,6 +35,19 @@ export async function runTaze(args, options = {}) {
         reportError(`Could not read the taze config: ${describeError(error)}`, stderr);
         return 1;
     }
+    if (readFlag(args, NODE_PIN_SKIP_FLAGS) === undefined) {
+        try {
+            await (options.checkNodePin ?? checkNodePinDefault)(resolveConfigDir(args), {
+                isSilent: isSilent(args),
+                shouldWrite: readFlag(args, ['--write', '-w']) !== undefined,
+                stderr,
+                style: options.stderrStyle ?? 'plain',
+            });
+        }
+        catch (error) {
+            reportError(`Could not check the nodejs pin: ${describeError(error)}`, stderr);
+        }
+    }
     const showHeadings = !isSilent(args);
     let exitCode = 0;
     for (const pass of passes) {

package/dist/esm/commands/tsconfig-chain.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
 import { formatDiagnostics, getCompiler } from "./compiler.js";
 import { isRelativeSpecifier } from "./rewrite-specifiers.js";
 export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json') {
@@ -14,7 +15,7 @@ export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json
         resolvedChain.push(normalizedPath);
         const configFile = ts.readConfigFile(normalizedPath, (fileName) => ts.sys.readFile(fileName));
         if (configFile.error) {
-            throw new Error(`nmr-compile: failed to read ${normalizedPath}.\n${formatDiagnostics([configFile.error])}`);
+            throw new UserError(`nmr-compile: failed to read ${normalizedPath}.\n${formatDiagnostics([configFile.error])}`);
         }
         for (const entry of normalizeExtendsField(configFile.config)) {
             walk(resolveExtendsTarget(entry, normalizedPath));
@@ -47,12 +48,12 @@ function resolveExtendsTarget(extendsEntry, fromConfigPath) {
         if (ts.sys.fileExists(withJsonExtension)) {
             return withJsonExtension;
         }
-        throw new Error(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not exist.`);
+        throw new UserError(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not exist.`);
     }
     const resolvedPath = resolvePackageSpecifier(extendsEntry, fromConfigPath) ??
         resolvePackageSpecifier(`${extendsEntry}/tsconfig.json`, fromConfigPath);
     if (resolvedPath === undefined) {
-        throw new Error(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not resolve to a file.`);
+        throw new UserError(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not resolve to a file.`);
     }
     return resolvedPath;
 }

package/dist/esm/commands/workflow-tools.js

@@ -3,8 +3,8 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { UserError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { UserError } from "../UserError.js";
 const SUPPORTED_PLATFORMS = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64'];
 const DOWNLOAD_TIMEOUT_MS = 60_000;
 const ACTIONLINT_RELEASE = 'https://github.com/rhysd/actionlint/releases/download/v1.7.12';
@@ -71,7 +71,7 @@ export async function ensureTool(tool, options) {
         const archive = await download(asset.url, options.fetch ?? globalThis.fetch);
         const actualSha256 = createHash('sha256').update(archive).digest('hex');
         if (actualSha256 !== asset.sha256) {
-            throw new Error(`Checksum mismatch for ${asset.url}: expected sha256 ${asset.sha256}, got ${actualSha256}`);
+            throw new UserError(`Checksum mismatch for ${asset.url}: expected sha256 ${asset.sha256}, got ${actualSha256}`);
         }
         const archivePath = path.join(scratchDir, 'archive.tar.gz');
         fs.writeFileSync(archivePath, archive);
@@ -103,7 +103,7 @@ function createCacheRoot(cacheRoot) {
         fs.mkdirSync(cacheRoot, { recursive: true });
     }
     catch (error) {
-        throw new Error(`Cannot create the tool cache at ${cacheRoot}`, { cause: error });
+        throw new UserError(`Cannot create the tool cache at ${cacheRoot}: ${describeError(error)}`, { cause: error });
     }
 }
 async function download(url, fetchImpl) {
@@ -112,20 +112,20 @@ async function download(url, fetchImpl) {
         response = await fetchImpl(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
     }
     catch (error) {
-        throw new Error(`Cannot download ${url}: ${describeError(error)}`, { cause: error });
+        throw new UserError(`Cannot download ${url}: ${describeError(error)}`, { cause: error });
     }
     if (!response.ok) {
-        throw new Error(`Cannot download ${url}: HTTP ${response.status}`);
+        throw new UserError(`Cannot download ${url}: HTTP ${response.status}`);
     }
     return Buffer.from(await response.arrayBuffer());
 }
 function extractMember(archivePath, extractDir, member) {
     const result = spawnSync('tar', ['-xzf', archivePath, '-C', extractDir, member], { encoding: 'utf8' });
     if (result.error !== undefined) {
-        throw new Error(`Cannot run tar to extract ${member}: ${result.error.message}`, { cause: result.error });
+        throw new UserError(`Cannot run tar to extract ${member}: ${result.error.message}`, { cause: result.error });
     }
     if (result.status !== 0) {
-        throw new Error(`tar could not extract ${member} from ${archivePath}: ${result.stderr.trim()}`);
+        throw new UserError(`tar could not extract ${member} from ${archivePath}: ${result.stderr.trim()}`);
     }
 }
 function publishStage(stageDir, targetDir, binaryPath) {
@@ -134,7 +134,9 @@ function publishStage(stageDir, targetDir, binaryPath) {
     }
     catch (error) {
         if (!fs.existsSync(binaryPath)) {
-            throw error;
+            throw new UserError(`Cannot move the downloaded tool into ${targetDir}: ${describeError(error)}`, {
+                cause: error,
+            });
         }
     }
 }

package/dist/esm/config-check-cache.js

@@ -1,7 +1,7 @@
+import { UserError } from '@williamthorsen/nmr-core';
 import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
-import { UserError } from "./UserError.js";
 import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
 export function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     const { checkCache } = config;

package/dist/esm/config-validation.js

@@ -1,7 +1,7 @@
+import { UserError } from '@williamthorsen/nmr-core';
 import { assertResolvableCheckCacheCommands } from "./config-check-cache.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
 import { findUnexpressibleToken } from "./steps.js";
-import { UserError } from "./UserError.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {
     root: {

package/dist/esm/config.js

@@ -8,6 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { UserError } from '@williamthorsen/nmr-core';
 import { CONFIG_TIERS, validateConfig } from "./config-validation.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
@@ -16,7 +17,6 @@ import { isObject } from "./helpers/type-guards.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { describeScript } from "./resolver.js";
 import { readSelfReference, readStepListSelfReference } from "./steps.js";
-import { UserError } from "./UserError.js";
 const SCRIPT_FIELDS = [
     { field: 'rootScripts', scope: 'root' },
     { field: 'workspaceScripts', scope: 'workspaceRegistry' },

package/dist/esm/crossing-diagnostics.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { STATUS_GLYPHS, UserError } from '@williamthorsen/nmr-core';
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { isHookName } from "./helpers/hook-name.js";
@@ -7,7 +7,6 @@ import { resolvePackageJsonPath } from "./helpers/package-json.js";
 import { hasRunnableHook } from "./hooks.js";
 import { expandScript, findChainedSelfReference, readPackageJsonScripts, } from "./resolver.js";
 import { findNmrCrossing, readSoleNmrCommand, renderChain } from "./steps.js";
-import { UserError } from "./UserError.js";
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
 export function assertNoSelfReference(options) {
     const { anchorDir, command, isReading, isWorkspaceRoot, monorepoRoot, registry } = options;

package/dist/esm/delegation-target.d.ts

@@ -27,10 +27,11 @@ export type DelegationTarget = {
  * 2. `--delegate-to` runs it on the hosts that it names, and `--delegate` on `NMR_DELEGATE`'s, or else the user
  *    config's.
  * 3. A repo config declaring `delegate: false` runs it here.
- * 4. `NMR_DELEGATE` naming hosts runs it on them.
- * 5. `NMR_DELEGATE` set without a host runs it here, which is how a step keeps to where its parent runs.
- * 6. The user config's `when` matching runs it on the config's hosts, unless `CI` is set or the invocation fans out.
- * 7. Otherwise, it runs here.
+ * 4. A package install hook, which `npm_lifecycle_event` names, runs it here.
+ * 5. `NMR_DELEGATE` naming hosts runs it on them.
+ * 6. `NMR_DELEGATE` set without a host runs it here, which is how a step keeps to where its parent runs.
+ * 7. The user config's `when` matching runs it on the config's hosts, unless `CI` is set or the invocation fans out.
+ * 8. Otherwise, it runs here.
  *
  * A command that rewrites the tree, or that runs until it is stopped, cannot be delegated, and neither can `--log`,
  * which reads this machine's recordings. Asked for by a flag, such an invocation is refused; asked for by the

package/dist/esm/delegation-target.js

@@ -16,6 +16,9 @@ export async function resolveDelegationTarget(options) {
     if (isRepoOptedOut) {
         return { kind: 'local' };
     }
+    if (isInstallHook(env)) {
+        return { kind: 'local' };
+    }
     if (envHosts !== undefined) {
         return isDelegable ? { kind: 'remote', hosts: envHosts, source: 'env' } : { kind: 'local' };
     }
@@ -33,6 +36,15 @@ export async function resolveDelegationTarget(options) {
     return { kind: 'remote', hosts: delegate.hosts, source: 'config', configPath: loaded.path, when: delegate.when };
 }
 const DEFAULT_USER_CONFIG_PATH = '~/.config/nmr/config.ts';
+const INSTALL_HOOKS = new Set([
+    'dependencies',
+    'install',
+    'postinstall',
+    'postprepare',
+    'preinstall',
+    'prepare',
+    'preprepare',
+]);
 const NON_DELEGABLE_BASE_COMMANDS = ['build', 'clean', 'compile', 'fix', 'fmt', 'lint', 'test:watch', 'upgrade'];
 const NON_DELEGABLE_COMMANDS = new Set([
     ...NON_DELEGABLE_BASE_COMMANDS,
@@ -41,6 +53,9 @@ const NON_DELEGABLE_COMMANDS = new Set([
 function hasValue(value) {
     return value !== undefined && value !== '';
 }
+function isInstallHook(env) {
+    return INSTALL_HOOKS.has(env['npm_lifecycle_event'] ?? '');
+}
 function parseHostList(value) {
     const names = value.split(',').map((host) => host.trim());
     const [first, ...rest] = new Set(names.filter((host) => host !== ''));

package/dist/esm/entry-chain.js

@@ -1,7 +1,7 @@
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
 import { isObject } from "./helpers/type-guards.js";
-import { UserError } from "./UserError.js";
 export const ENTRY_CHAIN_ENV_VAR = 'NMR_ENTRY_CHAIN';
 export function enterChain(options) {
     const { anchorDir, command, env, monorepoRoot } = options;

package/dist/esm/glyphs.d.ts

@@ -5,5 +5,5 @@
  * `noop` is a neutral circle: Nothing ran because the repo asked for nothing to run, which is neither a
  * failure nor a block.
  */
-export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "host" | "catalog" | "noop" | "package" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "host" | "catalog" | "noop" | "package" | "pin" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type NmrGlyphName = keyof (typeof NMR_GLYPHS)['rich'];

package/dist/esm/glyphs.js

@@ -6,5 +6,6 @@ export const NMR_GLYPHS = defineGlyphSet({
     noop: { plain: 'NOOP', rich: '\u{26AA}' },
     overrides: { plain: '', rich: '\u{1F512}' },
     package: { plain: '', rich: '\u{1F4E6}' },
+    pin: { plain: '', rich: '\u{1F4CC}' },
     recording: { plain: '', rich: '\u{1F4BE}' },
 });

package/dist/esm/helpers/deriveExcerpt.js

@@ -1,7 +1,7 @@
 import { clampToBytes } from "./clampToBytes.js";
 import { cleanTranscript } from "./transcript.js";
 const MAX_BLOCK_LINES = 8;
-export const MAX_EXCERPT_BYTES = 2_048;
+export const MAX_EXCERPT_BYTES = 2048;
 const NON_RULE_CHARACTER = /[^-=_~*+.|:#]/u;
 export function deriveExcerpt(transcript) {
     const lines = cleanTranscript(transcript).split('\n');