@williamthorsen/nmr 0.54.0 → 0.55.0

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

@@ -1,5 +1,4 @@
-import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { parseArgsOrExit, reportFailure } from '@williamthorsen/nmr-core';
 import { DEFAULT_HOOK, ensurePrepublishHooks, reportPrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
 import { resolveBinStyles } from "./resolveBinStyles.js";
 import { findMonorepoRoot } from "./workspace.js";
@@ -20,6 +19,6 @@ try {
     }
 }
 catch (error) {
-    reportError(describeError(error));
+    reportFailure('ensure-prepublish-hooks', error);
     process.exitCode = 1;
 }

package/dist/esm/cli-fmt.js

@@ -1,3 +1,10 @@
 import process from 'node:process';
+import { reportFailure } from '@williamthorsen/nmr-core';
 import { runFmt } from "./commands/fmt.js";
-process.exitCode = await runFmt(process.argv.slice(2), process.cwd());
+try {
+    process.exitCode = await runFmt(process.argv.slice(2), process.cwd());
+}
+catch (error) {
+    reportFailure('nmr-fmt', error);
+    process.exitCode = 1;
+}

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

@@ -1,12 +1,11 @@
 import process from 'node:process';
-import { reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { reportFailure } from '@williamthorsen/nmr-core';
 import { reportCatalog } from "./commands/report-catalog.js";
 import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
     reportCatalog(process.cwd(), resolveBinStyles().stderr);
 }
 catch (error) {
-    reportError(describeError(error));
+    reportFailure('nmr-report-catalog', error);
     process.exitCode = 1;
 }

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

@@ -1,5 +1,4 @@
-import { reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { reportFailure } from '@williamthorsen/nmr-core';
 import { reportOverrides } from "./commands/report-overrides.js";
 import { resolveBinStyles } from "./resolveBinStyles.js";
 import { findMonorepoRoot } from "./workspace.js";
@@ -8,6 +7,6 @@ try {
     reportOverrides(monorepoRoot, resolveBinStyles().stderr);
 }
 catch (error) {
-    reportError(describeError(error));
+    reportFailure('nmr-report-overrides', error);
     process.exitCode = 1;
 }

package/dist/esm/cli-shellcheck.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/cli-shellcheck.js

@@ -0,0 +1,11 @@
+import process from 'node:process';
+import { reportFailure } from '@williamthorsen/nmr-core';
+import { runShellcheck } from "./commands/shellcheck.js";
+import { findMonorepoRoot } from "./workspace.js";
+try {
+    process.exitCode = await runShellcheck(findMonorepoRoot(), process.argv.slice(2));
+}
+catch (error) {
+    reportFailure('nmr-shellcheck', error);
+    process.exitCode = 1;
+}

package/dist/esm/cli-taze.js

@@ -1,12 +1,11 @@
 import process from 'node:process';
-import { reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { reportFailure } from '@williamthorsen/nmr-core';
 import { runTaze } from "./commands/taze.js";
 import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
     process.exitCode = await runTaze(process.argv.slice(2), { stderrStyle: resolveBinStyles().stderr });
 }
 catch (error) {
-    reportError(describeError(error));
+    reportFailure('nmr-taze', error);
     process.exitCode = 1;
 }

package/dist/esm/cli-vitest.js

@@ -1,3 +1,10 @@
 import process from 'node:process';
+import { reportFailure } from '@williamthorsen/nmr-core';
 import { runNmrVitest } from "./commands/run-vitest.js";
-process.exitCode = runNmrVitest(process.argv.slice(2), process.cwd());
+try {
+    process.exitCode = runNmrVitest(process.argv.slice(2), process.cwd());
+}
+catch (error) {
+    reportFailure('nmr-vitest', error);
+    process.exitCode = 1;
+}

package/dist/esm/cli.js

@@ -1,5 +1,5 @@
 import process from 'node:process';
-import { reportCliFailure } from "./reportCliFailure.js";
+import { reportFailure } from '@williamthorsen/nmr-core';
 import { runCli } from "./runCli.js";
 try {
     const { exitCode } = await runCli({
@@ -12,6 +12,6 @@ try {
     process.exitCode = exitCode;
 }
 catch (error) {
-    reportCliFailure(error, process.stderr);
+    reportFailure('nmr', error);
     process.exitCode = 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.js

@@ -7,7 +7,7 @@ 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 * 1_000;
+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+$/;

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/shellcheck.d.ts

@@ -0,0 +1,25 @@
+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 {
+    /** Directory under which the pinned tools are cached; defaults to `node_modules/.cache/nmr-tools` at the root. */
+    cacheRoot?: string;
+    ensure?: (tool: WorkflowTool, cacheRoot: 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;
+}
+/**
+ * Lints the monorepo's tracked shell scripts with the pinned shellcheck and returns its exit status. Trailing
+ * arguments replace the file list. A repo that does not track any `*.sh` file passes without fetching the tool.
+ */
+export declare function runShellcheck(monorepoRoot: string, args: readonly string[], options?: RunShellcheckOptions): Promise<number>;
+/**
+ * Lists the `*.sh` files that git tracks under the root, relative to it. git's `*` also matches `/`, so the pathspec
+ * reaches every directory.
+ */
+export declare function listTrackedScripts(monorepoRoot: string): string[];

package/dist/esm/commands/shellcheck.js

@@ -0,0 +1,41 @@
+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";
+export async function runShellcheck(monorepoRoot, args, options = {}) {
+    const shellcheckArgs = args.length > 0 ? [...args] : listPresentScripts(monorepoRoot, options.listFiles);
+    if (shellcheckArgs.length === 0) {
+        console.info('No shell scripts to lint: the working tree does not contain any tracked *.sh file.');
+        return 0;
+    }
+    const cacheRoot = options.cacheRoot ?? path.join(monorepoRoot, 'node_modules', '.cache', 'nmr-tools');
+    const ensure = options.ensure ?? ((tool, root) => ensureTool(tool, { cacheRoot: root }));
+    const shellcheckPath = await ensure('shellcheck', cacheRoot);
+    const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, 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;
+}
+export function listTrackedScripts(monorepoRoot) {
+    const result = spawnSync('git', ['ls-files', '-z', '--', '*.sh'], { cwd: monorepoRoot, encoding: 'utf8' });
+    if (result.error !== undefined) {
+        throw new UserError(`Cannot list tracked shell scripts: ${result.error.message}`, { cause: result.error });
+    }
+    if (result.status !== 0) {
+        throw new UserError(`Cannot list tracked shell scripts: ${result.stderr.trim()}`);
+    }
+    return result.stdout.split('\0').filter((file) => file !== '');
+}
+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/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/default-scripts.js

@@ -46,6 +46,7 @@ export function buildRootScripts(workspaceGlobs) {
         'fmt:check': 'nmr-fmt --check',
         lint: 'eslint --fix .',
         'lint:check': 'eslint .',
+        'lint:shell': 'nmr-shellcheck',
         'lint:strict': 'strict-lint',
         'lint:workflows': 'nmr-actionlint',
         prepush: [{ run: 'audit', shouldDeclineArguments: true }, 'ci'],

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/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');

package/dist/esm/helpers/duration.js

@@ -17,7 +17,7 @@ export function formatSaving(durationMs) {
     return `saved ~${formatDuration(durationMs)}`;
 }
 const MILLISECONDS_PER_MINUTE = 60_000;
-const MILLISECONDS_PER_SECOND = 1_000;
+const MILLISECONDS_PER_SECOND = 1000;
 const MINUTES_PER_HOUR = 60;
 const SECONDS_PER_MINUTE = 60;
 function joinUnits(major, minor, minorUnit) {

package/dist/esm/helpers/package-json.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { UserError } from "../UserError.js";
 import { isMonorepoRoot } from "../workspace.js";
 import { CONFIG_RELATIVE_PATH } from "./config-path.js";
 import { readStringValues } from "./readStringValues.js";