@williamthorsen/nmr 0.29.0 → 0.31.0

package/dist/esm/config.js

@@ -10,12 +10,16 @@ import { existsSync } from 'node:fs';
 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: {
@@ -27,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);
 }
@@ -34,21 +40,50 @@ 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;
     }
-    if (!isScriptRecord(value[fieldName])) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | string[]>`);
+    const scripts = value[fieldName];
+    if (!isScriptRecord(scripts)) {
+        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 }`');
+    }
+    assertValidElements(scripts, fieldName, configPath);
+    return scripts;
+}
+function assertValidElements(scripts, fieldName, configPath) {
+    for (const [command, script] of Object.entries(scripts)) {
+        if (typeof script === 'string')
+            continue;
+        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 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.`);
+        }
     }
-    return value[fieldName];
 }
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
@@ -59,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 };
 }
@@ -74,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;
     }
@@ -91,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 = {};
@@ -121,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;
@@ -153,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) {
@@ -161,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) {

package/dist/esm/default-scripts.d.ts

@@ -1,4 +1,8 @@
-export type ScriptValue = string | string[];
+export interface StepSpec {
+    run: string;
+    declinesArgs?: boolean;
+}
+export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;
 export declare const workspaceScripts: ScriptRegistry;
 export declare const rootScripts: ScriptRegistry;

package/dist/esm/default-scripts.js

@@ -1,8 +1,10 @@
 const GATE_PROJECTS = '--project unit --project tool';
+const TYPECHECK_STEP = { run: 'typecheck', declinesArgs: true };
+const ROOT_TYPECHECK_STEP = { run: 'root:typecheck', declinesArgs: true };
 export const workspaceScripts = {
     build: ['compile'],
-    check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
-    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
+    check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
+    'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test:coverage'],
     clean: 'nmr-clean',
     compile: 'nmr-compile',
     fix: ['lint', 'fmt'],
@@ -12,6 +14,7 @@ export const workspaceScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
+    'report-catalog': 'nmr-report-catalog',
     test: `pnpm exec vitest ${GATE_PROJECTS}`,
     'test:all': 'pnpm exec vitest',
     'test:coverage': `pnpm exec vitest ${GATE_PROJECTS} --coverage`,
@@ -19,17 +22,17 @@ export const workspaceScripts = {
     'test:unit': 'pnpm exec vitest --project unit',
     'test:watch': `pnpm exec vitest ${GATE_PROJECTS} --watch`,
     typecheck: 'tsgo --noEmit',
-    upgrade: 'nmr-taze --include-locked',
+    upgrade: 'nmr-report-catalog && nmr-taze --include-locked',
     'view-coverage': 'open coverage/index.html',
 };
 export const rootScripts = {
     audit: ['audit:prod', 'audit:dev'],
     'audit:dev': 'pnpm exec v11y --dev',
     'audit:prod': 'pnpm exec v11y --prod',
-    build: 'pnpm --recursive exec nmr build',
-    check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
-    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
-    ci: ['build', 'check:strict'],
+    build: ['-R build'],
+    check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
+    'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test:coverage'],
+    ci: [{ run: 'build', declinesArgs: true }, 'check:strict'],
     clean: 'nmr-clean',
     fix: ['lint', 'fmt'],
     'fix:check': ['fmt:check', 'lint:check'],
@@ -38,9 +41,9 @@ export const rootScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
-    prepush: ['audit', 'ci'],
+    prepush: [{ run: 'audit', declinesArgs: true }, 'ci'],
     'report-overrides': 'nmr-report-overrides',
-    'root:check': ['root:typecheck', 'fmt:check', 'root:lint:check', 'root:test'],
+    'root:check': [ROOT_TYPECHECK_STEP, 'fmt:check', 'root:lint:check', 'root:test'],
     'root:lint': "eslint --fix --ignore-pattern 'packages/**' .",
     'root:lint:check': "eslint --ignore-pattern 'packages/**' .",
     'root:lint:strict': "strict-lint --ignore-pattern 'packages/**' .",
@@ -49,13 +52,13 @@ export const rootScripts = {
     'root:test:tool': 'vitest --config ./vitest.root.config.ts --project tool',
     'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
     'root:typecheck': 'tsgo --noEmit',
-    'root:upgrade': 'nmr-taze --include-locked',
-    test: 'nmr root:test && pnpm --recursive exec nmr test',
-    'test:all': 'nmr root:test:all && pnpm --recursive exec nmr test:all',
-    'test:coverage': 'nmr root:test && pnpm --recursive exec nmr test:coverage',
-    'test:tool': 'nmr root:test:tool && pnpm --recursive exec nmr test:tool',
-    'test:unit': 'nmr root:test:unit && pnpm --recursive exec nmr test:unit',
+    'root:upgrade': 'nmr-report-overrides && nmr-taze --include-locked',
+    test: ['root:test', '-R test'],
+    'test:all': ['root:test:all', '-R test:all'],
+    'test:coverage': ['root:test', '-R test:coverage'],
+    'test:tool': ['root:test:tool', '-R test:tool'],
+    'test:unit': ['root:test:unit', '-R test:unit'],
     'test:watch': `vitest ${GATE_PROJECTS} --watch`,
-    typecheck: 'nmr root:typecheck && pnpm --recursive exec nmr typecheck',
+    typecheck: [ROOT_TYPECHECK_STEP, { run: '-R typecheck', declinesArgs: true }],
     upgrade: 'nmr-report-overrides && nmr-taze --include-locked --recursive',
 };

package/dist/esm/defineConfig.d.ts

@@ -1,3 +1,3 @@
 import type { NmrConfig } from './types.js';
-export type { BuildConfig, CheckCacheConfig, NmrConfig } from './types.js';
+export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, StepSpec, } from './types.js';
 export declare function defineConfig(config: NmrConfig): NmrConfig;

package/dist/esm/help.js

@@ -8,7 +8,9 @@ export function generateHelp(config, packageDir, useRoot) {
         '  -F, --filter <pattern>   Run command in matching packages',
         '  -R, --recursive          Run command in all packages',
         '  -w, --workspace-root     Use root scripts, running at the monorepo root',
-        '  -q, --quiet              Suppress output on success; show full output on failure',
+        "  -q, --quiet              Suppress command output, keeping nmr's verdicts",
+        '      --json               Report one JSON object per command, withholding command output',
+        '      --log                Print the recorded run instead of running (up to 256 KiB)',
         '      --no-cache           Run even if this tree already passed; record the result',
         '  -?, --help               Show this help',
         '  -V, --version            Show version number',

package/dist/esm/helpers/clampToBytes.d.ts

@@ -0,0 +1,2 @@
+export declare const TRUNCATION_MARK = "\u2026";
+export declare function clampToBytes(value: string, budgetBytes: number): string;

package/dist/esm/helpers/clampToBytes.js

@@ -0,0 +1,20 @@
+export const TRUNCATION_MARK = '…';
+export function clampToBytes(value, budgetBytes) {
+    if (Buffer.byteLength(value) <= budgetBytes) {
+        return value;
+    }
+    const budget = budgetBytes - Buffer.byteLength(TRUNCATION_MARK);
+    if (budget < 0) {
+        return '';
+    }
+    let kept = '';
+    let bytes = 0;
+    for (const character of value) {
+        const size = Buffer.byteLength(character);
+        if (bytes + size > budget)
+            break;
+        kept += character;
+        bytes += size;
+    }
+    return `${kept}${TRUNCATION_MARK}`;
+}

package/dist/esm/helpers/createBoundedBuffer.js

@@ -1,3 +1,4 @@
+import { formatElisionMarker } from "./transcript.js";
 const DEFAULT_HEAD_LIMIT_BYTES = 1_048_576;
 const DEFAULT_TAIL_LIMIT_BYTES = 1_048_576;
 export function createBoundedBuffer(options = {}) {
@@ -54,7 +55,3 @@ export function createBoundedBuffer(options = {}) {
     }
     return { append, toBuffer };
 }
-function formatElisionMarker(byteCount) {
-    const unit = byteCount === 1 ? 'byte' : 'bytes';
-    return `\n… nmr elided ${byteCount.toLocaleString('en-US')} ${unit} …\n`;
-}

package/dist/esm/helpers/deriveExcerpt.d.ts

@@ -0,0 +1 @@
+export declare function deriveExcerpt(transcript: string): string | undefined;

package/dist/esm/helpers/deriveExcerpt.js

@@ -0,0 +1,30 @@
+import { clampToBytes } from "./clampToBytes.js";
+import { cleanTranscript } from "./transcript.js";
+const MAX_BLOCK_LINES = 8;
+const MAX_EXCERPT_BYTES = 2_048;
+const NON_RULE_CHARACTER = /[^-=_~*+.|:#]/u;
+export function deriveExcerpt(transcript) {
+    const lines = cleanTranscript(transcript).split('\n');
+    let end = lines.length;
+    while (end > 0 && isBlank(lines[end - 1])) {
+        end--;
+    }
+    let start = end;
+    while (start > 0 && !isBlank(lines[start - 1])) {
+        start--;
+    }
+    const excerpt = lines
+        .slice(Math.max(start, end - MAX_BLOCK_LINES), end)
+        .filter((line) => !isRuleOnly(line))
+        .join(' ')
+        .replaceAll(/\s+/gu, ' ')
+        .trim();
+    return excerpt === '' ? undefined : clampToBytes(excerpt, MAX_EXCERPT_BYTES);
+}
+function isBlank(line) {
+    return line === undefined || line.trim() === '';
+}
+function isRuleOnly(line) {
+    const content = line.replaceAll(/\s/gu, '');
+    return content !== '' && !NON_RULE_CHARACTER.test(content);
+}

package/dist/esm/helpers/duration.js

@@ -1,21 +1,28 @@
 export function formatDuration(milliseconds) {
-    const seconds = Math.round(milliseconds / MILLISECONDS_PER_SECOND);
-    if (seconds < SECONDS_PER_MINUTE) {
-        return `${seconds}s`;
+    const total = Math.max(0, milliseconds);
+    if (total < MILLISECONDS_PER_MINUTE) {
+        return `${truncateToTenth(total)}s`;
     }
-    const minutes = Math.round(seconds / SECONDS_PER_MINUTE);
-    if (minutes < MINUTES_PER_HOUR) {
-        return `${minutes}m`;
+    const totalMinutes = Math.floor(total / MILLISECONDS_PER_MINUTE);
+    if (totalMinutes < MINUTES_PER_HOUR) {
+        const seconds = Math.floor(total / MILLISECONDS_PER_SECOND) % SECONDS_PER_MINUTE;
+        return joinUnits(`${totalMinutes}m`, seconds, 's');
     }
-    return `${Math.round(minutes / MINUTES_PER_HOUR)}h`;
+    return joinUnits(`${Math.floor(totalMinutes / MINUTES_PER_HOUR)}h`, totalMinutes % MINUTES_PER_HOUR, 'm');
 }
 export function formatSaving(milliseconds) {
     if (!Number.isFinite(milliseconds) || milliseconds < MILLISECONDS_PER_SECOND) {
         return undefined;
     }
-    return `${SPEED_BOOST_ICON} saved ~${formatDuration(milliseconds)}`;
+    return `saved ~${formatDuration(milliseconds)}`;
 }
+const MILLISECONDS_PER_MINUTE = 60_000;
 const MILLISECONDS_PER_SECOND = 1_000;
 const MINUTES_PER_HOUR = 60;
 const SECONDS_PER_MINUTE = 60;
-const SPEED_BOOST_ICON = '🚀';
+function joinUnits(major, minor, minorUnit) {
+    return minor === 0 ? major : `${major} ${minor}${minorUnit}`;
+}
+function truncateToTenth(milliseconds) {
+    return Math.floor(milliseconds / 100) / 10;
+}

package/dist/esm/helpers/package-json.d.ts

@@ -1,12 +1,19 @@
-export interface PackageJson {
+export declare const DEPENDENCY_FIELDS: readonly ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
+export type PackageJson = {
     name?: string;
     private?: boolean;
     version?: string;
     packageManager?: string;
     scripts?: Record<string, string>;
     pnpm?: {
-        overrides?: Record<string, string>;
+        overrides?: Record<string, unknown>;
     };
-}
+} & {
+    [K in DependencyField]?: Record<string, string>;
+};
 export declare function readPackageJson(dir: string): PackageJson;
-export declare function getPnpmOverrides(pkg: PackageJson): Record<string, string> | undefined;
+export declare function getPnpmOverrides(pkg: PackageJson): Record<string, unknown> | undefined;
+export declare function parsePackageJson(raw: string, file: string): unknown;
+export declare function readScriptRecord(dir: string, scripts: Record<string, unknown>): Record<string, string>;
+export declare function resolvePackageJsonPath(dir: string): string;

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

@@ -1,10 +1,22 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { CONFIG_RELATIVE_PATH } from "../config.js";
+import { UserError } from "../UserError.js";
+import { isMonorepoRoot } from "../workspace.js";
+import { readStringValues } from "./readStringValues.js";
 import { isObject } from "./type-guards.js";
+export const DEPENDENCY_FIELDS = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+];
 export function readPackageJson(dir) {
-    const parsed = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const file = resolvePackageJsonPath(dir);
+    const parsed = parsePackageJson(readFileSync(file, 'utf8'), file);
     if (!isObject(parsed)) {
-        throw new TypeError(`Invalid package.json in ${dir}: expected an object`);
+        throw new UserError(`Invalid package.json in ${dir}: expected an object`);
     }
     const pkg = {};
     if (typeof parsed['name'] === 'string')
@@ -16,24 +28,18 @@ export function readPackageJson(dir) {
     if (typeof parsed['packageManager'] === 'string')
         pkg.packageManager = parsed['packageManager'];
     if (isObject(parsed['scripts'])) {
-        const scripts = {};
-        const scriptEntries = Object.entries(parsed['scripts']);
-        for (const [key, val] of scriptEntries) {
-            if (typeof val === 'string')
-                scripts[key] = val;
-        }
-        pkg.scripts = scripts;
+        pkg.scripts = readScriptRecord(dir, parsed['scripts']);
     }
     if (isObject(parsed['pnpm'])) {
         const pnpm = parsed['pnpm'];
         if (isObject(pnpm['overrides'])) {
-            const overrides = {};
-            const overrideEntries = Object.entries(pnpm['overrides']);
-            for (const [key, val] of overrideEntries) {
-                if (typeof val === 'string')
-                    overrides[key] = val;
-            }
-            pkg.pnpm = { overrides };
+            pkg.pnpm = { overrides: pnpm['overrides'] };
+        }
+    }
+    for (const field of DEPENDENCY_FIELDS) {
+        const declared = parsed[field];
+        if (isObject(declared)) {
+            pkg[field] = readStringValues(declared);
         }
     }
     return pkg;
@@ -42,11 +48,34 @@ export function getPnpmOverrides(pkg) {
     if (!isObject(pkg.pnpm))
         return undefined;
     const overrides = pkg.pnpm.overrides;
-    if (!isObject(overrides))
-        return undefined;
-    for (const value of Object.values(overrides)) {
-        if (typeof value !== 'string')
-            return undefined;
+    return isObject(overrides) ? overrides : undefined;
+}
+export function parsePackageJson(raw, file) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new UserError(`Invalid package.json at ${file}: ${describeError(error)}`);
+    }
+}
+export function readScriptRecord(dir, scripts) {
+    const result = {};
+    for (const [key, value] of Object.entries(scripts)) {
+        if (typeof value !== 'string') {
+            throw new UserError(formatMalformedScript(dir, key, value));
+        }
+        result[key] = value;
+    }
+    return result;
+}
+export function resolvePackageJsonPath(dir) {
+    return path.join(dir, 'package.json');
+}
+function formatMalformedScript(dir, key, value) {
+    const rejection = `Invalid package.json at ${resolvePackageJsonPath(dir)}: \`scripts.${key}\` must be a string.`;
+    if (!Array.isArray(value)) {
+        return rejection;
     }
-    return overrides;
+    const field = isMonorepoRoot(dir) ? 'rootScripts' : 'workspaceScripts';
+    return `${rejection} A step list belongs in \`${CONFIG_RELATIVE_PATH}\` under \`${field}\`.`;
 }

package/dist/esm/helpers/readStringValues.d.ts

@@ -0,0 +1 @@
+export declare function readStringValues(record: Record<string, unknown>): Record<string, string>;

package/dist/esm/helpers/readStringValues.js

@@ -0,0 +1,8 @@
+export function readStringValues(record) {
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === 'string')
+            result[key] = value;
+    }
+    return result;
+}

package/dist/esm/helpers/transcript.d.ts

@@ -0,0 +1,5 @@
+import type { RetainedOutput } from '../runner.js';
+export declare const TRANSCRIPT_LIMIT_BYTES = 262144;
+export declare function cleanTranscript(raw: string): string;
+export declare function composeTranscript(retained: RetainedOutput): string | undefined;
+export declare function formatElisionMarker(byteCount: number): string;

package/dist/esm/helpers/transcript.js

@@ -0,0 +1,59 @@
+export const TRANSCRIPT_LIMIT_BYTES = 262_144;
+const ANSI_PATTERN = /\u{1B}(?:\[[\u{30}-\u{3F}]*[\u{20}-\u{2F}]*[\u{40}-\u{7E}]|\][^\u{7}\u{1B}]*(?:\u{7}|\u{1B}\\))/gu;
+const END_LIMIT_BYTES = TRANSCRIPT_LIMIT_BYTES / 2;
+const STREAM_MARKER = '\n… nmr: stderr …\n';
+export function cleanTranscript(raw) {
+    return raw
+        .replaceAll(ANSI_PATTERN, '')
+        .split('\n')
+        .map((line) => renderCarriageReturns(line))
+        .join('\n');
+}
+export function composeTranscript(retained) {
+    const streams = [retained.stdout, retained.stderr]
+        .map((stream) => cleanTranscript(stream.toString('utf8')))
+        .filter((stream) => stream.trim() !== '');
+    if (streams.length === 0) {
+        return undefined;
+    }
+    return clampTranscript(streams.join(STREAM_MARKER));
+}
+export function formatElisionMarker(byteCount) {
+    const unit = byteCount === 1 ? 'byte' : 'bytes';
+    return `\n… nmr elided ${byteCount.toLocaleString('en-US')} ${unit} …\n`;
+}
+function alignEnd(buffer, end) {
+    let aligned = Math.min(buffer.length, end);
+    while (aligned > 0 && isContinuationByte(buffer[aligned])) {
+        aligned--;
+    }
+    return aligned;
+}
+function alignStart(buffer, start) {
+    let aligned = Math.max(0, start);
+    while (aligned < buffer.length && isContinuationByte(buffer[aligned])) {
+        aligned++;
+    }
+    return aligned;
+}
+function clampTranscript(transcript) {
+    const buffer = Buffer.from(transcript, 'utf8');
+    if (buffer.length <= TRANSCRIPT_LIMIT_BYTES) {
+        return transcript;
+    }
+    const headEnd = alignEnd(buffer, END_LIMIT_BYTES);
+    const tailStart = alignStart(buffer, buffer.length - END_LIMIT_BYTES);
+    const head = buffer.subarray(0, headEnd).toString('utf8');
+    const tail = buffer.subarray(tailStart).toString('utf8');
+    return `${head}${formatElisionMarker(tailStart - headEnd)}${tail}`;
+}
+function isContinuationByte(byte) {
+    return byte !== undefined && (byte & 0b1100_0000) === 0b1000_0000;
+}
+function renderCarriageReturns(line) {
+    if (!line.includes('\r')) {
+        return line;
+    }
+    const segments = line.split('\r').filter((segment) => segment.trim() !== '');
+    return segments.at(-1) ?? '';
+}