@williamthorsen/nmr 0.30.0 → 0.31.0

package/dist/esm/check-cache.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+import type { OutputChannels } from './runner.js';
 import type { CheckCacheConfig, NmrConfig } from './types.js';
 export interface CheckCacheEntry {
     key: string;
@@ -10,6 +11,22 @@ export interface CheckCacheEntry {
     durationMs: number;
     recordedAt: string;
     buildDigests: Record<string, string>;
+    retention?: Retention;
+}
+export interface EntryRef {
+    anchorDir: string;
+    command: string;
+    monorepoRoot: string;
+}
+export interface ReplayLine {
+    command: string;
+    excerpt: string;
+    scope: string;
+}
+export interface Retention {
+    key: string;
+    replay: ReplayLine[];
+    runId: string;
 }
 export interface BuildOutputState {
     missing: string[];
@@ -28,7 +45,17 @@ export declare const CURRENT_RUNTIME: RuntimeIdentity;
 export declare const DEBUG_ENV_VAR = "NMR_DEBUG";
 export declare const DEFAULT_CACHEABLE_COMMANDS: string[];
 export declare const NO_CACHE_ENV_VAR = "NMR_NO_CACHE";
+export declare const RUN_ID_ENV_VAR = "NMR_RUN_ID";
 export declare const TREE_SNAPSHOT_ENV_VAR = "NMR_TREE_SNAPSHOT";
+export declare function certifyRetention(options: {
+    anchorDir: string;
+    command: string;
+    entry: CheckCacheEntry;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+    runId: string;
+    stderr: Writable;
+}): Promise<void>;
 export declare function computeCacheKey(options: {
     anchorDir: string;
     command: string;
@@ -45,18 +72,26 @@ export declare function computeCacheKey(options: {
     ok: false;
     reason: string;
 };
+export declare function computeRetentionKey(options: {
+    channels: OutputChannels;
+    env: NodeJS.ProcessEnv;
+    passKey: string;
+}): string;
 export declare function encodeTreeSnapshot(snapshot: TreeSnapshot): string;
 export declare function findStaleBuildOutput(earlier: Record<string, string>, later: Record<string, string>): string | undefined;
 export declare function formatMisplacedNoCacheWarning(command: string): string;
-export declare function formatSkipLine(command: string, entry: CheckCacheEntry, now: number): string;
+export declare function isCacheableCommand(checkCache: CheckCacheConfig | undefined, command: string): boolean;
 export declare function readBuildOutputState(monorepoRoot: string, config: NmrConfig): Promise<BuildOutputState>;
 export declare function readCheckCacheEntry(options: {
     anchorDir: string;
     command: string;
     monorepoRoot: string;
 }): Promise<CheckCacheEntry | undefined>;
+export declare function readTranscript(ref: EntryRef): Promise<string | undefined>;
+export declare function recordTranscript(ref: EntryRef, transcript: string | undefined): Promise<void>;
 export declare function removeCheckCache(scopeDir: string): Promise<void>;
 export declare function resolveCacheableCommands(checkCache: CheckCacheConfig | undefined): Set<string>;
+export declare function resolveRunId(env: NodeJS.ProcessEnv): string;
 export declare function resolveTreeSnapshot(options: {
     monorepoRoot: string;
     env: NodeJS.ProcessEnv;

package/dist/esm/check-cache.js

@@ -1,11 +1,12 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { hashWorkingTree, readHeadSha, readJsonCacheEntry, removeCacheDir, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { hashWorkingTree, readCacheEntry, readHeadSha, readJsonCacheEntry, removeCacheDir, removeCacheEntry, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { hasBuildOutput, readBuildDigest } from "./commands/build-output.js";
 import { loadWorkspaceConfig } from "./config.js";
-import { formatDuration, formatSaving } from "./helpers/duration.js";
+import { isHookName } from "./helpers/hook-name.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
 import { getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { buildWorkspaceRegistry, resolveScript } from "./resolver.js";
@@ -39,6 +40,7 @@ export const DEFAULT_CACHEABLE_COMMANDS = [
     'typecheck',
 ];
 export const NO_CACHE_ENV_VAR = 'NMR_NO_CACHE';
+export const RUN_ID_ENV_VAR = 'NMR_RUN_ID';
 export const TREE_SNAPSHOT_ENV_VAR = 'NMR_TREE_SNAPSHOT';
 const BUILT_IN_COMPILE = 'nmr-compile';
 const CACHE_TOOL = 'nmr-check';
@@ -48,7 +50,26 @@ const INSTALL_FINGERPRINT_FILES = [
 ];
 const KEY_FORMAT = 'nmr-check-cache-v1';
 const KEYED_ENV_VARS = ['LANG', 'LC_ALL', 'NODE_OPTIONS', 'TZ'];
+const RETENTION_KEY_FORMAT = 'nmr-retention-v1';
+const RETENTION_KEYED_ENV_VARS = ['CI', 'COLUMNS', 'FORCE_COLOR', 'NO_COLOR', 'TERM'];
 const UNSAFE_SLUG_CHARACTERS = /[^\w.-]+/g;
+export async function certifyRetention(options) {
+    const { entry, runId } = options;
+    if (entry.retention === undefined || entry.retention.runId === runId) {
+        return;
+    }
+    try {
+        await writeCheckCacheEntry({
+            anchorDir: options.anchorDir,
+            command: options.command,
+            monorepoRoot: options.monorepoRoot,
+            entry: { ...entry, retention: { ...entry.retention, runId } },
+        });
+    }
+    catch (error) {
+        writeDebugNote(`could not certify ${options.command}: ${describeError(error)}`, options.env, options.stderr);
+    }
+}
 export function computeCacheKey(options) {
     const fingerprint = resolveInstallFingerprint(options.monorepoRoot);
     if (!fingerprint.ok) {
@@ -68,16 +89,16 @@ export function computeCacheKey(options) {
         runtime.arch,
         fingerprint.fingerprint,
     ];
-    for (const name of KEYED_ENV_VARS) {
-        const value = options.env[name];
-        parts.push(name, value === undefined ? 'unset' : 'set', value ?? '');
-    }
-    const hash = createHash('sha256');
-    for (const part of parts) {
-        hash.update(part);
-        hash.update('\0');
-    }
-    return { ok: true, key: hash.digest('hex') };
+    return { ok: true, key: digestParts([...parts, ...composeEnvParts(KEYED_ENV_VARS, options.env)]) };
+}
+export function computeRetentionKey(options) {
+    const parts = [
+        RETENTION_KEY_FORMAT,
+        options.passKey,
+        describeChannel(options.channels.stdout),
+        describeChannel(options.channels.stderr),
+    ];
+    return digestParts([...parts, ...composeEnvParts(RETENTION_KEYED_ENV_VARS, options.env)]);
 }
 export function encodeTreeSnapshot(snapshot) {
     return `${snapshot.hash} ${snapshot.headSha}`;
@@ -90,11 +111,8 @@ export function formatMisplacedNoCacheWarning(command) {
     return (`⚠️ --no-cache after the command name is passed to \`${command}\`, not read by nmr. ` +
         `Did you mean \`nmr --no-cache ${command}\`?`);
 }
-export function formatSkipLine(command, entry, now) {
-    const age = formatDuration(Math.max(0, now - Date.parse(entry.recordedAt)));
-    const saving = formatSaving(entry.durationMs);
-    const savingClause = saving === undefined ? '' : ` (${saving})`;
-    return `⏭️ ${command}: passed ${age} ago on this tree${savingClause}.`;
+export function isCacheableCommand(checkCache, command) {
+    return !isHookName(command) && checkCache?.enabled !== false && resolveCacheableCommands(checkCache).has(command);
 }
 export async function readBuildOutputState(monorepoRoot, config) {
     const state = { missing: [], digests: {} };
@@ -126,7 +144,23 @@ export async function readBuildOutputState(monorepoRoot, config) {
     return state;
 }
 export async function readCheckCacheEntry(options) {
-    return readJsonCacheEntry(resolveEntryPath(options), isCheckCacheEntry);
+    const parsed = await readJsonCacheEntry(resolveEntryPath(options), isParsedCheckCacheEntry);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    const { retention, ...pass } = parsed;
+    return isRetention(retention) ? { ...pass, retention } : pass;
+}
+export async function readTranscript(ref) {
+    return readCacheEntry(resolveEntryPath(ref, '.log'));
+}
+export async function recordTranscript(ref, transcript) {
+    const entryPath = resolveEntryPath(ref, '.log');
+    if (transcript === undefined) {
+        await removeCacheEntry(entryPath);
+        return;
+    }
+    await writeCacheEntry(entryPath, transcript);
 }
 export async function removeCheckCache(scopeDir) {
     await removeCacheDir({ tool: CACHE_TOOL, scopeDir });
@@ -139,6 +173,10 @@ export function resolveCacheableCommands(checkCache) {
     }
     return commands;
 }
+export function resolveRunId(env) {
+    const inherited = env[RUN_ID_ENV_VAR];
+    return inherited === undefined || inherited === '' ? randomUUID() : inherited;
+}
 export function resolveTreeSnapshot(options) {
     const inherited = decodeTreeSnapshot(options.env[TREE_SNAPSHOT_ENV_VAR]);
     if (inherited !== undefined && readHeadSha(options.monorepoRoot) === inherited.headSha) {
@@ -168,6 +206,12 @@ export function writeDebugNote(message, env, stderr) {
         stderr.write(`nmr check-cache: ${message}\n`);
     }
 }
+function composeEnvParts(names, env) {
+    return names.flatMap((name) => {
+        const value = env[name];
+        return [name, value === undefined ? 'unset' : 'set', value ?? ''];
+    });
+}
 function decodeTreeSnapshot(encoded) {
     if (encoded === undefined) {
         return undefined;
@@ -178,7 +222,18 @@ function decodeTreeSnapshot(encoded) {
     }
     return { hash, headSha };
 }
-function isCheckCacheEntry(value) {
+function describeChannel(channel) {
+    return channel === 'pipe' ? 'pipe' : 'descriptor';
+}
+function digestParts(parts) {
+    const hash = createHash('sha256');
+    for (const part of parts) {
+        hash.update(part);
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function isParsedCheckCacheEntry(value) {
     if (!isObject(value)) {
         return false;
     }
@@ -193,19 +248,32 @@ function isCheckCacheEntry(value) {
 }
 function isProbeSubject(packageDir, registry) {
     const build = resolveScript('build', registry, packageDir, false);
-    if (build === undefined || build.source === 'package') {
+    if (build === undefined || build.origin.tier === 'package') {
         return false;
     }
     const compile = resolveScript('compile', registry, packageDir, false);
     return compile !== undefined && renderChain(compile.steps) === BUILT_IN_COMPILE;
 }
-function resolveEntryPath(options) {
+function isReplayLine(value) {
+    return (isObject(value) &&
+        typeof value['command'] === 'string' &&
+        typeof value['excerpt'] === 'string' &&
+        typeof value['scope'] === 'string');
+}
+function isRetention(value) {
+    return (isObject(value) &&
+        typeof value['key'] === 'string' &&
+        typeof value['runId'] === 'string' &&
+        Array.isArray(value['replay']) &&
+        value['replay'].every((line) => isReplayLine(line)));
+}
+function resolveEntryPath(options, extension = '.json') {
     const anchorDir = path.resolve(options.anchorDir);
     const ref = {
         tool: CACHE_TOOL,
         scopeDir: options.monorepoRoot,
         slug: `${path.basename(anchorDir)}-${options.command.replaceAll(UNSAFE_SLUG_CHARACTERS, '-')}`,
-        extension: '.json',
+        extension,
         discriminators: [anchorDir, options.command],
     };
     return resolveCacheEntryPath(ref);

package/dist/esm/cli-build.js

@@ -1,4 +1,5 @@
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildPackage } from "./commands/build.js";
 import { loadWorkspaceConfig } from "./config.js";
 try {
@@ -9,6 +10,6 @@ try {
     });
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

package/dist/esm/cli-clean.js

@@ -1,9 +1,10 @@
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { runClean } from "./commands/clean.js";
 try {
     await runClean(process.cwd());
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

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

@@ -1,4 +1,5 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { DEFAULT_HOOK, ensurePrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
 import { findMonorepoRoot } from "./workspace.js";
 const flagSchema = {
@@ -38,6 +39,6 @@ try {
     }
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

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

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

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

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

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

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

package/dist/esm/cli-taze.js

@@ -1,10 +1,11 @@
 import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { runTaze } from "./commands/taze.js";
 try {
     process.exitCode = runTaze(process.argv.slice(2));
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

package/dist/esm/cli.js

@@ -1,4 +1,5 @@
 import process from 'node:process';
+import { reportCliFailure } from "./reportCliFailure.js";
 import { runCli } from "./runCli.js";
 try {
     const { exitCode } = await runCli({
@@ -11,6 +12,6 @@ try {
     process.exitCode = exitCode;
 }
 catch (error) {
-    process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    reportCliFailure(error, process.stderr);
     process.exitCode = 1;
 }

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

@@ -0,0 +1 @@
+export declare function reportCatalog(cwd: string): void;

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

@@ -0,0 +1,34 @@
+import { findContainingPackageDir } from "../context.js";
+import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
+import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
+const CATALOG_PROTOCOL = 'catalog:';
+export function reportCatalog(cwd) {
+    const monorepoRoot = findMonorepoRoot(cwd);
+    const packageDir = findContainingPackageDir(cwd, getWorkspacePackageDirs(monorepoRoot));
+    if (packageDir === undefined) {
+        return;
+    }
+    const dependencies = findCataloguedDependencies(packageDir);
+    if (dependencies.length === 0) {
+        return;
+    }
+    const subject = dependencies.length === 1 ? '1 dependency comes' : `${dependencies.length} dependencies come`;
+    console.warn(`📚 WARN: ${subject} from a catalog, which a package-scoped upgrade does not read:`);
+    for (const { name, specifier } of dependencies) {
+        console.warn(`- ${name} → ${specifier}`);
+    }
+    console.warn(`Run \`nmr upgrade\` from ${monorepoRoot} to include them.`);
+}
+function findCataloguedDependencies(packageDir) {
+    const pkg = readPackageJson(packageDir);
+    const found = new Map();
+    for (const field of DEPENDENCY_FIELDS) {
+        const declared = Object.entries(pkg[field] ?? {});
+        for (const [name, specifier] of declared) {
+            if (specifier.startsWith(CATALOG_PROTOCOL) && !found.has(name)) {
+                found.set(name, specifier);
+            }
+        }
+    }
+    return [...found].map(([name, specifier]) => ({ name, specifier })).toSorted((a, b) => a.name.localeCompare(b.name));
+}

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

@@ -1,12 +1,27 @@
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
+import { UserError } from "../UserError.js";
+import { readWorkspaceOverrides } from "../workspace.js";
 export function reportOverrides(monorepoRoot) {
-    const pkg = readPackageJson(monorepoRoot);
-    const overrides = getPnpmOverrides(pkg);
-    if (!overrides || Object.keys(overrides).length === 0) {
-        return;
+    const declared = listEntries(readWorkspaceOverrides(monorepoRoot));
+    if (declared.length > 0) {
+        console.warn('🔒 WARN: pnpm overrides are active! Check whether these are still needed:');
+        for (const [name, version] of declared) {
+            console.warn(`- ${name} → ${version}`);
+        }
     }
-    console.warn('🔒 WARN: pnpm overrides are active! Check whether these are still needed:');
-    for (const [name, version] of Object.entries(overrides)) {
-        console.warn(`- ${name} → ${version}`);
+    rejectLegacyOverrides(monorepoRoot);
+}
+function listEntries(overrides) {
+    return Object.entries(overrides ?? {}).toSorted(([a], [b]) => a.localeCompare(b));
+}
+function rejectLegacyOverrides(monorepoRoot) {
+    const legacy = listEntries(getPnpmOverrides(readPackageJson(monorepoRoot)));
+    if (legacy.length === 0) {
+        return;
     }
+    throw new UserError([
+        'pnpm 11 reads no `pnpm.overrides` from package.json, so these pin nothing while an upgrade run with `--write` goes on rewriting them:',
+        ...legacy.map(([name, version]) => `- ${name} → ${String(version)}`),
+        'Move them to the `overrides` block in pnpm-workspace.yaml, quoting each version, or run `pnpx codemod run pnpm-v10-to-v11`.',
+    ].join('\n'));
 }

package/dist/esm/commands/taze.js

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 const TAZE_CLI_SPECIFIER = 'taze/cli';
 export function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
@@ -12,7 +13,7 @@ export function runTaze(args, options = {}) {
         cliPath = resolveCliPath();
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = describeError(error);
         reportError(`Could not resolve '${TAZE_CLI_SPECIFIER}' from nmr's dependencies. Reinstall the workspace to restore it. (${detail})`, stderr);
         return 1;
     }

package/dist/esm/config.d.ts

@@ -1,4 +1,5 @@
 import type { NmrConfig } from './types.js';
+export declare const CONFIG_RELATIVE_PATH: string;
 export declare function resolveConfigPath(baseDir: string): string;
 export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
 export declare function loadRootConfig(monorepoRoot: string): Promise<NmrConfig>;

package/dist/esm/config.js

@@ -11,12 +11,15 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
 import { findUnexpressibleToken } from "./steps.js";
+import { UserError } from "./UserError.js";
+import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 const CONFIG_FILENAME = 'nmr.config.ts';
 const CONFIG_DIR = '.config';
+export const CONFIG_RELATIVE_PATH = path.join(CONFIG_DIR, CONFIG_FILENAME);
 const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'devBin', 'rootScripts', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'devBin', 'output', 'rootScripts', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -28,6 +31,8 @@ const CONFIG_TIERS = {
 const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.workspace.honoredKeys];
 const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
+const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
+const RECOGNIZED_STEP_KEYS = ['declinesArgs', 'run'];
 export function resolveConfigPath(baseDir) {
     return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
 }
@@ -35,33 +40,46 @@ function isScriptRecord(value) {
     if (!isObject(value))
         return false;
     for (const v of Object.values(value)) {
-        if (typeof v !== 'string' && !Array.isArray(v))
-            return false;
-        if (Array.isArray(v) && v.some((item) => typeof item !== 'string'))
+        if (typeof v === 'string')
+            continue;
+        if (!Array.isArray(v) || !v.every(isScriptElement))
             return false;
     }
     return true;
 }
+function isScriptElement(value) {
+    if (typeof value === 'string')
+        return true;
+    if (!isObject(value) || typeof value['run'] !== 'string')
+        return false;
+    const declinesArgs = value['declinesArgs'];
+    return declinesArgs === undefined || typeof declinesArgs === 'boolean';
+}
 function validateScriptField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
         return undefined;
     }
     const scripts = value[fieldName];
     if (!isScriptRecord(scripts)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | string[]>`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | element[]>, ` +
+            'where an element is a command string or `{ run: string, declinesArgs?: boolean }`');
     }
-    assertExpressibleElements(scripts, fieldName, configPath);
+    assertValidElements(scripts, fieldName, configPath);
     return scripts;
 }
-function assertExpressibleElements(scripts, fieldName, configPath) {
+function assertValidElements(scripts, fieldName, configPath) {
     for (const [command, script] of Object.entries(scripts)) {
         if (typeof script === 'string')
             continue;
-        for (const element of script) {
+        for (const spec of script) {
+            if (typeof spec !== 'string') {
+                assertRecognizedKeys(spec, RECOGNIZED_STEP_KEYS, configPath, `${fieldName}.${command}.`);
+            }
+            const element = typeof spec === 'string' ? spec : spec.run;
             const token = findUnexpressibleToken(element);
             if (token === undefined)
                 continue;
-            throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
+            throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
                 `\`${token}\`, which is neither a command name nor an nmr flag. Name it as a script of its own and ` +
                 `reference that name here.`);
         }
@@ -76,12 +94,12 @@ function validateBuildField(value, configPath) {
         return undefined;
     }
     if (!isObject(build)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`build\` must be an object`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`build\` must be an object`);
     }
     assertRecognizedKeys(build, RECOGNIZED_BUILD_KEYS, configPath, 'build.');
     const extraIgnorePatterns = build['extraIgnorePatterns'];
     if (extraIgnorePatterns !== undefined && !isStringArray(extraIgnorePatterns)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`build.extraIgnorePatterns\` must be a string[]`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`build.extraIgnorePatterns\` must be a string[]`);
     }
     return extraIgnorePatterns === undefined ? {} : { extraIgnorePatterns };
 }
@@ -91,14 +109,14 @@ function validateCheckCacheField(value, configPath) {
         return undefined;
     }
     if (!isObject(checkCache)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`checkCache\` must be an object`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache\` must be an object`);
     }
     assertRecognizedKeys(checkCache, RECOGNIZED_CHECK_CACHE_KEYS, configPath, 'checkCache.');
     const config = {};
     const enabled = checkCache['enabled'];
     if (enabled !== undefined) {
         if (typeof enabled !== 'boolean') {
-            throw new TypeError(`Invalid nmr config at ${configPath}: \`checkCache.enabled\` must be a boolean`);
+            throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.enabled\` must be a boolean`);
         }
         config.enabled = enabled;
     }
@@ -108,24 +126,51 @@ function validateCheckCacheField(value, configPath) {
             continue;
         }
         if (!isStringArray(commands)) {
-            throw new Error(`Invalid nmr config at ${configPath}: \`checkCache.${field}\` must be a string[]`);
+            throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${field}\` must be a string[]`);
         }
         config[field] = commands;
     }
     return config;
 }
+function validateOutputField(value, configPath) {
+    const output = value['output'];
+    if (output === undefined) {
+        return undefined;
+    }
+    if (!isObject(output)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`output\` must be an object`);
+    }
+    assertRecognizedKeys(output, RECOGNIZED_OUTPUT_KEYS, configPath, 'output.');
+    const config = {};
+    const commandVerbosity = output['commandVerbosity'];
+    if (commandVerbosity !== undefined) {
+        if (typeof commandVerbosity !== 'string' || !isCommandVerbosity(commandVerbosity)) {
+            const rendered = typeof commandVerbosity === 'string' ? commandVerbosity : JSON.stringify(commandVerbosity);
+            throw new UserError(`Invalid nmr config at ${configPath}: ${formatVerbosityRejection('`output.commandVerbosity`', rendered)}`);
+        }
+        config.commandVerbosity = commandVerbosity;
+    }
+    const extraAgentEnvVars = output['extraAgentEnvVars'];
+    if (extraAgentEnvVars !== undefined) {
+        if (!isStringArray(extraAgentEnvVars)) {
+            throw new UserError(`Invalid nmr config at ${configPath}: \`output.extraAgentEnvVars\` must be a string[]`);
+        }
+        config.extraAgentEnvVars = extraAgentEnvVars;
+    }
+    return config;
+}
 function validateStringRecordField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
         return undefined;
     }
     if (!isStringRecord(value[fieldName])) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
     }
     return value[fieldName];
 }
 function validateConfig(value, configPath) {
     if (!isObject(value)) {
-        throw new Error(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
+        throw new UserError(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
     }
     assertRecognizedKeys(value, RECOGNIZED_KEYS, configPath);
     const config = {};
@@ -138,6 +183,9 @@ function validateConfig(value, configPath) {
     const devBin = validateStringRecordField(value, 'devBin', configPath);
     if (devBin)
         config.devBin = devBin;
+    const output = validateOutputField(value, configPath);
+    if (output)
+        config.output = output;
     const workspaceScripts = validateScriptField(value, 'workspaceScripts', configPath);
     if (workspaceScripts)
         config.workspaceScripts = workspaceScripts;
@@ -170,7 +218,7 @@ function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
     if (unrecognized.length === 0) {
         return;
     }
-    throw new Error(`Invalid nmr config at ${configPath}: unrecognized ${unrecognized.length === 1 ? 'key' : 'keys'} ` +
+    throw new UserError(`Invalid nmr config at ${configPath}: unrecognized ${unrecognized.length === 1 ? 'key' : 'keys'} ` +
         `${formatKeyList(unrecognized, prefix)}. Recognized: ${formatKeyList(recognizedKeys, prefix)}.`);
 }
 function assertTierKeys(config, tier, configPath) {
@@ -178,7 +226,7 @@ function assertTierKeys(config, tier, configPath) {
     if (unsupported.length === 0) {
         return;
     }
-    throw new Error(`Invalid nmr config at ${configPath}: ${tier.label} honors ${tier.honoredKeys.toSorted().join(', ')} alone, ` +
+    throw new UserError(`Invalid nmr config at ${configPath}: ${tier.label} honors ${tier.honoredKeys.toSorted().join(', ')} alone, ` +
         `not ${unsupported.toSorted().join(', ')}. Move those keys to ${tier.elsewhere}.`);
 }
 function formatKeyList(keys, prefix) {