@williamthorsen/nmr 0.30.0 → 0.31.0

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,7 +22,7 @@ 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 = {
@@ -27,9 +30,9 @@ export const rootScripts = {
     'audit:dev': 'pnpm exec v11y --dev',
     'audit:prod': 'pnpm exec v11y --prod',
     build: ['-R build'],
-    check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
-    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
-    ci: ['build', 'check:strict'],
+    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',
+    '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: ['root:typecheck', '-R 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) ?? '';
+}

package/dist/esm/recording.d.ts

@@ -0,0 +1,65 @@
+import type { CheckCacheEntry } from './check-cache.js';
+export interface RunIdentity {
+    commandString: string;
+    nmrVersion: string;
+    nodeVersion: string;
+    treeHash: string | undefined;
+}
+export interface Recording {
+    entry: CheckCacheEntry;
+    transcript?: string;
+}
+export type KeyDifference = {
+    ingredient: 'tree';
+} | {
+    ingredient: 'command-string';
+} | {
+    ingredient: 'nmr-version';
+    current: string;
+    recorded: string;
+} | {
+    ingredient: 'node-version';
+    current: string;
+    recorded: string;
+} | {
+    ingredient: 'other';
+};
+export type RecordingLookup = {
+    ok: true;
+    recording: Recording;
+} | {
+    ok: false;
+    refusal: RecordingRefusal;
+};
+export type RecordingRefusal = {
+    kind: 'uncacheable';
+} | {
+    kind: 'gate-aside';
+} | {
+    kind: 'unrecorded';
+} | {
+    kind: 'mismatched';
+    ageMs: number;
+    difference: KeyDifference;
+} | {
+    kind: 'no-output';
+    ageMs: number;
+};
+export declare function renderRecording(options: {
+    command: string;
+    recording: Recording;
+    scope: string;
+}): string;
+export declare function renderRefusal(options: {
+    command: string;
+    refusal: RecordingRefusal;
+    scope: string;
+}): string;
+export declare function resolveRecording(options: {
+    anchorDir: string;
+    command: string;
+    current: RunIdentity;
+    isCacheable: boolean;
+    key: string | undefined;
+    monorepoRoot: string;
+}): Promise<RecordingLookup>;

package/dist/esm/recording.js

@@ -0,0 +1,96 @@
+import { readCheckCacheEntry, readTranscript } from "./check-cache.js";
+import { formatDuration } from "./helpers/duration.js";
+export function renderRecording(options) {
+    const { entry } = options.recording;
+    const age = formatDuration(Math.max(0, Date.now() - Date.parse(entry.recordedAt)));
+    const header = `📼 ${options.scope}: ${options.command} — recorded ${entry.recordedAt} (${age} ago), ` +
+        `ran in ${formatDuration(entry.durationMs)}\n$ ${entry.commandString}\n\n`;
+    return `${header}${appendNewline(renderBody(options.recording))}`;
+}
+export function renderRefusal(options) {
+    return `📭 ${options.scope}: ${options.command}: no recording; ${describeRefusal(options.command, options.refusal)}`;
+}
+export async function resolveRecording(options) {
+    const { anchorDir, command, monorepoRoot } = options;
+    if (!options.isCacheable) {
+        return { ok: false, refusal: { kind: 'uncacheable' } };
+    }
+    if (options.key === undefined) {
+        return { ok: false, refusal: { kind: 'gate-aside' } };
+    }
+    const entry = await readCheckCacheEntry({ anchorDir, command, monorepoRoot });
+    if (entry === undefined) {
+        return { ok: false, refusal: { kind: 'unrecorded' } };
+    }
+    const ageMs = Math.max(0, Date.now() - Date.parse(entry.recordedAt));
+    if (entry.key !== options.key) {
+        return { ok: false, refusal: { kind: 'mismatched', ageMs, difference: findKeyDifference(entry, options.current) } };
+    }
+    const transcript = await readTranscript({ anchorDir, command, monorepoRoot });
+    if (transcript === undefined && (entry.retention?.replay.length ?? 0) === 0) {
+        return { ok: false, refusal: { kind: 'no-output', ageMs } };
+    }
+    return { ok: true, recording: { entry, ...(transcript !== undefined && { transcript }) } };
+}
+function appendNewline(body) {
+    return body.endsWith('\n') ? body : `${body}\n`;
+}
+function describeDifference(difference) {
+    switch (difference.ingredient) {
+        case 'tree':
+            return 'on a tree this is not';
+        case 'command-string':
+            return 'over a command chain this is not';
+        case 'nmr-version':
+            return `under nmr ${difference.recorded}, not ${difference.current}`;
+        case 'node-version':
+            return `under Node ${difference.recorded}, not ${difference.current}`;
+        case 'other':
+            return 'under an install or environment this run does not share';
+        default: {
+            const unhandled = difference;
+            throw new Error(`Unhandled key difference: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function describeRefusal(command, refusal) {
+    switch (refusal.kind) {
+        case 'uncacheable':
+            return `\`${command}\` is outside the check-result cache, so no run of it is recorded`;
+        case 'gate-aside':
+            return 'the check-result cache is standing aside here (NMR_DEBUG=1 reports why)';
+        case 'unrecorded':
+            return 'nothing has recorded a pass for this scope';
+        case 'mismatched':
+            return `the last pass was ${formatDuration(refusal.ageMs)} ago, ${describeDifference(refusal.difference)}`;
+        case 'no-output':
+            return `the pass ${formatDuration(refusal.ageMs)} ago retained none, as a run printing nothing or writing to a terminal does`;
+        default: {
+            const unhandled = refusal;
+            throw new Error(`Unhandled refusal: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function findKeyDifference(entry, current) {
+    if (current.treeHash !== undefined && entry.treeHash !== current.treeHash) {
+        return { ingredient: 'tree' };
+    }
+    if (entry.commandString !== current.commandString) {
+        return { ingredient: 'command-string' };
+    }
+    if (entry.nmrVersion !== current.nmrVersion) {
+        return { ingredient: 'nmr-version', current: current.nmrVersion, recorded: entry.nmrVersion };
+    }
+    if (entry.nodeVersion !== current.nodeVersion) {
+        return { ingredient: 'node-version', current: current.nodeVersion, recorded: entry.nodeVersion };
+    }
+    return { ingredient: 'other' };
+}
+function renderBody(recording) {
+    if (recording.transcript !== undefined) {
+        return recording.transcript;
+    }
+    return (recording.entry.retention?.replay ?? [])
+        .map((line) => `${line.scope}: ${line.command}: ${line.excerpt}`)
+        .join('\n');
+}

package/dist/esm/replay-assembly.d.ts

@@ -0,0 +1,9 @@
+import type { ReplayLine } from './check-cache.js';
+import type { Step } from './steps.js';
+export declare function assembleReplay(options: {
+    anchorDir: string;
+    monorepoRoot: string;
+    runId: string;
+    steps: readonly Step[];
+    treeHash: string;
+}): Promise<ReplayLine[]>;

package/dist/esm/replay-assembly.js

@@ -0,0 +1,26 @@
+import { readCheckCacheEntry } from "./check-cache.js";
+import { readNmrStep } from "./steps.js";
+import { getWorkspacePackageDirs } from "./workspace.js";
+export async function assembleReplay(options) {
+    const { anchorDir, monorepoRoot, runId, steps, treeHash } = options;
+    const candidates = steps.flatMap((step) => {
+        const target = readNmrStep(step);
+        if (target === undefined) {
+            return [];
+        }
+        const scopeDirs = target.isDelegate
+            ? resolveDelegateScopes(monorepoRoot)
+            : [target.isWorkspaceRoot ? monorepoRoot : anchorDir];
+        return scopeDirs.map((scopeDir) => ({ anchorDir: scopeDir, command: target.command, monorepoRoot }));
+    });
+    const entries = await Promise.all(candidates.map((candidate) => readCheckCacheEntry(candidate)));
+    return entries.flatMap((entry) => entry?.treeHash === treeHash && entry.retention?.runId === runId ? entry.retention.replay : []);
+}
+function resolveDelegateScopes(monorepoRoot) {
+    try {
+        return getWorkspacePackageDirs(monorepoRoot);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/esm/report-format.d.ts

@@ -0,0 +1,18 @@
+export declare function formatReportFormatRejection(source: string, value: string): string;
+export declare function isReportFormat(value: string): value is ReportFormat;
+export declare function readReportFormatEnv(env: NodeJS.ProcessEnv): ReportFormatRead;
+export declare const REPORT_FORMAT_ENV_VAR = "NMR_REPORT_FORMAT";
+export declare const REPORT_FORMATS: readonly ["text", "json"];
+export type ReportFormat = (typeof REPORT_FORMATS)[number];
+export type ReportFormatRead = {
+    ok: true;
+    format?: ReportFormat;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveReportFormat(options: ResolveReportFormatOptions): ReportFormat;
+export interface ResolveReportFormatOptions {
+    envFormat: ReportFormat | undefined;
+    jsonFlag: boolean;
+}

package/dist/esm/report-format.js

@@ -0,0 +1,25 @@
+export function formatReportFormatRejection(source, value) {
+    return `${source} is \`${value}\`, which is not one of: ${REPORT_FORMATS.join(', ')}`;
+}
+export function isReportFormat(value) {
+    const names = REPORT_FORMATS;
+    return names.includes(value);
+}
+export function readReportFormatEnv(env) {
+    const raw = env[REPORT_FORMAT_ENV_VAR];
+    if (raw === undefined || raw === '') {
+        return { ok: true };
+    }
+    if (!isReportFormat(raw)) {
+        return { ok: false, error: formatReportFormatRejection(REPORT_FORMAT_ENV_VAR, raw) };
+    }
+    return { ok: true, format: raw };
+}
+export const REPORT_FORMAT_ENV_VAR = 'NMR_REPORT_FORMAT';
+export const REPORT_FORMATS = ['text', 'json'];
+export function resolveReportFormat(options) {
+    const { envFormat, jsonFlag } = options;
+    if (jsonFlag)
+        return 'json';
+    return envFormat ?? 'text';
+}