@williamthorsen/nmr 0.37.0 → 0.38.0

package/dist/esm/runCli.js

@@ -1,8 +1,9 @@
 import path from 'node:path';
-import { readPackageVersion, reportError } from '@williamthorsen/nmr-core';
+import { describeInvalidOutputStyle, formatGlyphLine, readPackageVersion, reportError, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
 import { resolveContext } from "./context.js";
+import { NMR_GLYPHS } from "./glyphs.js";
 import { generateHelp } from "./help.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
@@ -11,6 +12,7 @@ import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";
 import { composeTranscript } from "./helpers/transcript.js";
+import { isTerminalStream, OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG, resolveOutputStyles } from "./output-style.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
 import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
@@ -38,11 +40,17 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const { parsed } = parseResult;
-    const inherited = readPresentationEnv(env);
+    const inherited = readPresentation({
+        env,
+        flagValue: parsed.outputStyle,
+        stderrIsTty: isTerminalStream(stderr),
+        stdoutIsTty: isTerminalStream(stdout),
+    });
     if (!inherited.ok) {
         reportError(inherited.error, stderr);
         return { exitCode: 1 };
     }
+    const { styles } = inherited;
     if (parsed.version) {
         stdout.write(`${VERSION}\n`);
         return { exitCode: 0 };
@@ -72,6 +80,7 @@ export async function runCli(options) {
         monorepoRoot: context.monorepoRoot,
         passthrough: parsed.passthrough,
         stderr,
+        style: styles.stderr,
     });
     const noCache = parsed.noCache || env[NO_CACHE_ENV_VAR] === '1';
     const runId = resolveRunId(env);
@@ -82,6 +91,7 @@ export async function runCli(options) {
         passthrough: parsed.passthrough,
         runId,
         snapshot,
+        styles,
         verbosity,
     });
     const runOptions = {
@@ -114,7 +124,7 @@ export async function runCli(options) {
     const resolvedCommand = renderChain(resolved.steps);
     const noOpReason = findNoOpReason(resolvedCommand);
     if (noOpReason !== undefined && !parsed.log) {
-        reportVerdict({ command, scope, outcome: 'no-op', reason: noOpReason }, stdout, format);
+        reportVerdict({ command, scope, outcome: 'no-op', reason: noOpReason }, stdout, format, styles.stdout);
         return { exitCode: 0 };
     }
     const substitutedSteps = applyDevBinToSteps(resolved.steps, context.config.devBin, context.monorepoRoot);
@@ -137,6 +147,7 @@ export async function runCli(options) {
         registry,
         resolved,
         stderr,
+        style: styles.stderr,
         useRoot,
         workspaceRoot: parsed.workspaceRoot,
     });
@@ -163,6 +174,7 @@ export async function runCli(options) {
             snapshot,
             stderr,
             stdout,
+            styles,
         });
     }
     const { exitCode, outcome } = await runGated({
@@ -175,7 +187,7 @@ export async function runCli(options) {
         key,
         monorepoRoot: context.monorepoRoot,
         noCache,
-        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, quiet),
+        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, quiet, styles.stdout),
         ownSteps: mainSteps,
         runId,
         runOptions,
@@ -183,33 +195,49 @@ export async function runCli(options) {
         stderr,
         stdout,
     });
-    reportVerdict({ command, scope, ...outcome }, stdout, format);
+    reportVerdict({ command, scope, ...outcome }, stdout, format, styles.stdout);
     return { exitCode };
 }
+const BOOLEAN_FLAGS = new Map([
+    ['-?', 'help'],
+    ['--help', 'help'],
+    ['--json', 'json'],
+    ['--log', 'log'],
+    ['--no-cache', 'noCache'],
+    ['-q', 'quiet'],
+    ['--quiet', 'quiet'],
+    ['-R', 'recursive'],
+    ['--recursive', 'recursive'],
+    ['-V', 'version'],
+    ['--version', 'version'],
+    ['-w', 'workspaceRoot'],
+    ['--workspace-root', 'workspaceRoot'],
+]);
 function buildChildEnv(options) {
-    const { env, format, noCache, passthrough, runId, snapshot, verbosity } = options;
+    const { env, format, noCache, passthrough, runId, snapshot, styles, verbosity } = options;
     const bypassesCache = noCache || passthrough.length > 0;
     return {
         ...env,
         ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
         ...(bypassesCache && { [NO_CACHE_ENV_VAR]: '1' }),
         [COMMAND_VERBOSITY_ENV_VAR]: verbosity,
+        [OUTPUT_STYLE_ENV_VAR]: styles.stdout,
         [REPORT_FORMAT_ENV_VAR]: format,
         [RUN_ID_ENV_VAR]: runId,
     };
 }
-function acceptsArgs(step) {
-    return step.kind === 'opaque' || step.declinesArgs !== true;
+function acceptsArguments(step) {
+    return step.kind === 'opaque' || step.shouldDeclineArguments !== true;
 }
 function bindPassthrough(steps, passthrough, command) {
     if (passthrough.length === 0) {
         return { ok: true, steps };
     }
-    if (!steps.some(acceptsArgs)) {
-        return { ok: false, error: formatUnroutableArgsError(command) };
+    if (!steps.some(acceptsArguments)) {
+        return { ok: false, error: formatUnroutableArgumentsError(command) };
     }
     const boundSteps = steps.map((step) => {
-        if (!acceptsArgs(step)) {
+        if (!acceptsArguments(step)) {
             return step;
         }
         return step.kind === 'structural'
@@ -218,7 +246,7 @@ function bindPassthrough(steps, passthrough, command) {
     });
     return { ok: true, steps: boundSteps };
 }
-function formatUnroutableArgsError(command) {
+function formatUnroutableArgumentsError(command) {
     return (`\`${command}\` takes no trailing arguments: every step of its chain declines them. ` +
         'Running it unnarrowed is not what the arguments asked for, so nothing ran.');
 }
@@ -313,15 +341,16 @@ function escapeControlCharacters(text) {
 }
 function formatNmrCrossingWarning(options) {
     const { remedy, subject } = describeCrossingRemedy(options);
-    return (`⚠️ ${subject} reaches nmr through a shell (\`${escapeControlCharacters(options.crossing)}\`), ` +
-        `${CROSSING_CONSEQUENCE} ${remedy}`);
+    return (`${STATUS_GLYPHS[options.style].warning.text} ${subject} reaches nmr through a shell ` +
+        `(\`${escapeControlCharacters(options.crossing)}\`), ${CROSSING_CONSEQUENCE} ${remedy}`);
 }
-function formatOverrideNotice(resolved, registry, command, anchorDir, quiet) {
+function formatOverrideNotice(resolved, registry, command, anchorDir, quiet, style) {
     const registryEntry = Object.hasOwn(registry, command) ? registry[command] : undefined;
     if (quiet || resolved.origin.tier !== 'package' || registryEntry === undefined) {
         return undefined;
     }
-    return `📦 ${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}\n`;
+    const notice = `${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}`;
+    return `${formatGlyphLine(NMR_GLYPHS, style, 'package', notice)}\n`;
 }
 function formatSelfReferenceRemedy(options) {
     const { command, monorepoRoot, registry, script, workspaceRoot } = options;
@@ -464,12 +493,12 @@ async function lookUpRecordedPass(options) {
     };
 }
 function openGate(options) {
-    const { command, config, env, monorepoRoot, passthrough, stderr } = options;
+    const { command, config, env, monorepoRoot, passthrough, stderr, style } = options;
     if (!isCacheableCommand(config.checkCache, command)) {
         return undefined;
     }
     if (passthrough.includes('--no-cache')) {
-        stderr.write(`${formatMisplacedNoCacheWarning(command)}\n`);
+        stderr.write(`${formatMisplacedNoCacheWarning(command, style)}\n`);
     }
     if (passthrough.length > 0) {
         writeDebugNote(`gate disabled: ${command} was passed arguments`, env, stderr);
@@ -509,44 +538,19 @@ function parseArgs(args) {
             i++;
             continue;
         }
-        if (arg === '-R' || arg === '--recursive') {
-            parsed.recursive = true;
-            i++;
-            continue;
-        }
-        if (arg === '-w' || arg === '--workspace-root') {
-            parsed.workspaceRoot = true;
-            i++;
-            continue;
-        }
-        if (arg === '-?' || arg === '--help') {
-            parsed.help = true;
-            i++;
-            continue;
-        }
-        if (arg === '-V' || arg === '--version') {
-            parsed.version = true;
-            i++;
-            continue;
-        }
-        if (arg === '-q' || arg === '--quiet') {
-            parsed.quiet = true;
-            i++;
-            continue;
-        }
-        if (arg === '--json') {
-            parsed.json = true;
-            i++;
-            continue;
-        }
-        if (arg === '--log') {
-            parsed.log = true;
+        const booleanFlag = BOOLEAN_FLAGS.get(arg);
+        if (booleanFlag !== undefined) {
+            parsed[booleanFlag] = true;
             i++;
             continue;
         }
-        if (arg === '--no-cache') {
-            parsed.noCache = true;
-            i++;
+        const styleArgument = readOutputStyleArgument(args, i);
+        if (styleArgument !== undefined) {
+            if (!styleArgument.ok) {
+                return styleArgument;
+            }
+            parsed.outputStyle = styleArgument.value;
+            i += styleArgument.consumed;
             continue;
         }
         parsed.command = arg;
@@ -557,7 +561,7 @@ function parseArgs(args) {
     return error === undefined ? { ok: true, parsed } : { ok: false, error };
 }
 async function reportRecording(options) {
-    const { command, config, scope } = options;
+    const { command, config, scope, styles } = options;
     const lookup = await resolveRecording({
         anchorDir: options.anchorDir,
         command,
@@ -572,13 +576,14 @@ async function reportRecording(options) {
         monorepoRoot: options.monorepoRoot,
     });
     if (!lookup.ok) {
-        options.stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope })}\n`);
+        options.stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
         return { exitCode: options.env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
     }
-    options.stdout.write(renderRecording({ command, recording: lookup.recording, scope }));
+    options.stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
     return { exitCode: 0 };
 }
-function readPresentationEnv(env) {
+function readPresentation(options) {
+    const { env } = options;
     const verbosity = readVerbosityEnv(env);
     if (!verbosity.ok) {
         return verbosity;
@@ -587,7 +592,23 @@ function readPresentationEnv(env) {
     if (!format.ok) {
         return format;
     }
-    return { ok: true, format: format.format, verbosity: verbosity.verbosity };
+    const { invalid, styles } = resolveOutputStyles(options);
+    if (invalid !== undefined) {
+        return { ok: false, error: describeInvalidOutputStyle(invalid) };
+    }
+    return { ok: true, format: format.format, styles, verbosity: verbosity.verbosity };
+}
+function readOutputStyleArgument(args, index) {
+    const arg = args[index] ?? '';
+    const assignment = arg.startsWith(`${OUTPUT_STYLE_FLAG}=`) ? arg.slice(OUTPUT_STYLE_FLAG.length + 1) : undefined;
+    if (arg !== OUTPUT_STYLE_FLAG && assignment === undefined) {
+        return undefined;
+    }
+    const value = assignment ?? args[index + 1];
+    if (!value) {
+        return { ok: false, error: `${OUTPUT_STYLE_FLAG} requires a value argument: auto, plain, or rich` };
+    }
+    return { ok: true, value, consumed: assignment === undefined ? 2 : 1 };
 }
 function reportNmrCrossing(options) {
     const crossing = findNmrCrossing(options.resolved.steps);
@@ -599,15 +620,16 @@ function reportNmrCrossing(options) {
         monorepoRoot: options.monorepoRoot,
         origin: describeOrigin(options.resolved.origin, options.config, options.useRoot),
         registry: options.registry,
+        style: options.style,
         workspaceRoot: options.workspaceRoot,
     });
     options.stderr.write(`${warning}\n`);
 }
-function reportVerdict(verdict, stdout, format) {
+function reportVerdict(verdict, stdout, format, style) {
     if (isHookName(verdict.command)) {
         return;
     }
-    writeVerdict(verdict, stdout, format);
+    writeVerdict(verdict, stdout, format, style);
 }
 function resolveReportingVerbosity(options) {
     const { format, ...ladder } = options;

package/dist/esm/steps.d.ts

@@ -4,12 +4,12 @@
  *
  * A structural step's argv leads with the file to spawn, so the runner has one to hand `spawn` without a shell.
  *
- * `declinesArgs` travels from the composite element that composed the step to the one reader that acts on it,
+ * `shouldDeclineArguments` travels from the composite element that composed the step to the one reader that acts on it,
  * the binding of the invocation's trailing arguments. Every stage between the two -- the devBin substitution,
  * the chain rendering, the replay assembly, the runner -- passes it through and asks nothing of it.
  *
  * `shouldWithholdInput` is read by the runner alone, which gives the step's child the null device as stdin rather
- * than nmr's own. Like `declinesArgs`, it is set only where it holds and leaves the rendered chain unchanged.
+ * than nmr's own. Like `shouldDeclineArguments`, it is set only where it holds and leaves the rendered chain unchanged.
  */
 export type Step = {
     kind: 'opaque';
@@ -17,7 +17,7 @@ export type Step = {
 } | {
     kind: 'structural';
     argv: readonly [string, ...(readonly string[])];
-    declinesArgs?: boolean;
+    shouldDeclineArguments?: boolean;
     shouldWithholdInput?: boolean;
 };
 /** What a structural step asks of the nmr process it spawns. */
@@ -39,10 +39,10 @@ export type SelfReference = 'chained' | 'sole';
  * The element tokenizes on whitespace, so it may carry nmr's own flags but cannot carry a space-bearing token.
  * `-w` is prepended as its own token, so the child selects the root registry on its own.
  *
- * `declinesArgs` is set only where it holds, so a step that takes the trailing arguments renders and compares
+ * `shouldDeclineArguments` is set only where it holds, so a step that takes the trailing arguments renders and compares
  * exactly as it did before any element declared anything.
  */
-export declare function composeNmrStep(element: string, workspaceRoot: boolean, declinesArgs?: boolean): Step;
+export declare function composeNmrStep(element: string, workspaceRoot: boolean, shouldDeclineArguments?: boolean): Step;
 /**
  * Returns the text of the first opaque step that reaches nmr through a shell, or `undefined` when none does.
  *

package/dist/esm/steps.js

@@ -11,9 +11,13 @@ const QUOTES = new Set(['"', "'"]);
 const SEGMENT_SEPARATORS = new Set([';', '|', '&', '\n', '\r']);
 const SHELL_SAFE_TOKEN = /^[\w@%+=:,./-]+$/;
 const TOKEN_SEPARATORS = new Set([' ', '\t', '\n', '\r']);
-export function composeNmrStep(element, workspaceRoot, declinesArgs = false) {
+export function composeNmrStep(element, workspaceRoot, shouldDeclineArguments = false) {
     const flags = workspaceRoot ? ['-w'] : [];
-    return { kind: 'structural', argv: ['nmr', ...flags, ...tokenize(element)], ...(declinesArgs && { declinesArgs }) };
+    return {
+        kind: 'structural',
+        argv: ['nmr', ...flags, ...tokenize(element)],
+        ...(shouldDeclineArguments && { shouldDeclineArguments }),
+    };
 }
 export function findNmrCrossing(steps) {
     for (const step of steps) {

package/dist/esm/verdict.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReplayLine } from './check-cache.js';
 import type { ReportFormat } from './report-format.js';
 /**
@@ -54,8 +55,11 @@ export type VerdictOutcome = {
  * The line ends without terminal punctuation and reserves its tail for `detail`, so a later change appends to
  * the grammar rather than rewriting it. A detail carrying nothing but line breaks takes its whole clause with
  * it, rather than leaving a separator pointing at nothing.
+ *
+ * The marker takes no padding column: every plain marker a verdict reaches for is four characters, so the
+ * lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and no verdict is one.
  */
-export declare function renderVerdict(verdict: Verdict): string;
+export declare function renderVerdict(verdict: Verdict, style: OutputStyle): string;
 /**
  * Renders a verdict as the JSON object a machine consumer reads, without the newline that terminates it.
  *
@@ -71,4 +75,4 @@ export declare function serializeVerdict(verdict: Verdict): string;
  * share one descriptor. Both renderings spend the one record, so neither can come to report what the other
  * does not.
  */
-export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat): void;
+export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat, style: OutputStyle): void;

package/dist/esm/verdict.js

@@ -1,41 +1,47 @@
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { NMR_GLYPHS } from "./glyphs.js";
 import { clampToBytes, TRUNCATION_MARK } from "./helpers/clampToBytes.js";
 import { formatDuration, formatSaving } from "./helpers/duration.js";
 export const VERDICT_LINE_LIMIT = 512;
-export function renderVerdict(verdict) {
-    const { icon, phrase } = describeOutcome(verdict);
+export function renderVerdict(verdict, style) {
+    const { marker, phrase } = describeOutcome(verdict, style);
     const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? '');
     const detailClause = detail === '' ? '' : ` — ${detail}`;
-    return clampToBytes(`${icon} ${verdict.scope}: ${verdict.command}: ${phrase}${detailClause}`, LINE_BUDGET_BYTES);
+    return clampToBytes(`${marker} ${verdict.scope}: ${verdict.command}: ${phrase}${detailClause}`, LINE_BUDGET_BYTES);
 }
 export function serializeVerdict(verdict) {
     const rendered = JSON.stringify(verdict);
     return isWithinBudget(rendered) ? rendered : renderWithinBudget(verdict);
 }
-export function writeVerdict(verdict, stream, format) {
-    const line = format === 'json' ? serializeVerdict(verdict) : renderVerdict(verdict);
+export function writeVerdict(verdict, stream, format, style) {
+    const line = format === 'json' ? serializeVerdict(verdict) : renderVerdict(verdict, style);
     stream.write(`${line}\n`);
 }
 const NEWLINE_BYTES = 1;
 const LINE_BUDGET_BYTES = VERDICT_LINE_LIMIT - NEWLINE_BYTES;
 const MIN_CUT_BYTES = Buffer.byteLength(TRUNCATION_MARK);
 const REPLAY_MARKER = 'replayed:';
-function describeOutcome(verdict) {
+function describeOutcome(verdict, style) {
+    const statuses = STATUS_GLYPHS[style];
     switch (verdict.outcome) {
         case 'passed':
-            return { icon: '✅', phrase: `passed in ${formatDuration(verdict.durationMs)}` };
+            return { marker: statuses.passed.text, phrase: `passed in ${formatDuration(verdict.durationMs)}` };
         case 'failed':
             return {
-                icon: '❌',
+                marker: statuses.failed.text,
                 phrase: `failed in ${formatDuration(verdict.durationMs)} (exit ${verdict.exitCode})`,
             };
         case 'recalled': {
             const saving = formatSaving(verdict.savedMs);
             const savingClause = saving === undefined ? '' : `, ${saving}`;
-            return { icon: '⏭️', phrase: `passed ${formatDuration(verdict.ageMs)} ago on this tree${savingClause}` };
+            return {
+                marker: statuses.skipped.text,
+                phrase: `passed ${formatDuration(verdict.ageMs)} ago on this tree${savingClause}`,
+            };
         }
         case 'no-op':
             return {
-                icon: '⛔',
+                marker: NMR_GLYPHS[style].noop.text,
                 phrase: `skipped, the override is ${verdict.reason === 'empty-override' ? 'empty' : 'a no-op'}`,
             };
         default: {

package/docs/check-cache.md

@@ -77,7 +77,7 @@ $ nmr test
 # ... the suite runs ...
 
 $ nmr test
-⏭️ nmr: test: passed 2m ago on this tree, saved ~12s — replayed: Test Files 6 passed (6) Tests 41 passed (41)
+⏩ nmr: test: passed 2m ago on this tree, saved ~12s — replayed: Test Files 6 passed (6) Tests 41 passed (41)
 ```
 
 The excerpt is the last blank-line-delimited block of what the command wrote, which is the closing statement a tool separates from its progress output. It is flattened onto one line, with escape sequences stripped, table rules dropped, and a redrawn progress line reduced to what a reader was left looking at. Nothing is parsed and no figure is computed: nmr replays bytes it recorded. A block wider than a few kilobytes is cut and marked with `…`, so a command whose closing statement is one long line cannot carry its whole output into the cache.
@@ -90,7 +90,7 @@ The excerpt and the whole transcript it is drawn from are written by the same op
 
 ```console
 $ nmr check
-⏭️ nmr-core: check: passed 3m ago on this tree, saved ~48s — replayed: nmr-core: fmt:check: All matched files use Prettier code style!; nmr-core: test: Test Files 6 passed (6) Tests 41 passed (41)
+⏩ nmr-core: check: passed 3m ago on this tree, saved ~48s — replayed: nmr-core: fmt:check: All matched files use Prettier code style!; nmr-core: test: Test Files 6 passed (6) Tests 41 passed (41)
 ```
 
 The assembly is flat: a constituent that is itself a composite contributes its own leaves' lines, so a skipped `ci` replays a package's `test` rather than one opaque `check:strict` line. A delegate expands into the scopes it fans out to, and a constituent that recorded no excerpt is absent rather than inferred: `typecheck` and `lint:check` print nothing on success and contribute nothing above, and a command outside the [cacheable set](#what-is-cached) records nothing at all, so `ci` replays what `check:strict` earned and nothing for `build`.
@@ -99,7 +99,7 @@ It is assembled when the composite records its pass rather than when it skips, s
 
 **A skip certifies what it replays.** Recalling a pass proves the excerpt describes this tree, and a matching retention key proves it describes this presentation environment, so a skip restamps the recalled entry with the run replaying it. A constituent already warm when a composite ran therefore still contributes its line: `nmr check` after `nmr test` replays the test summary. The restamp touches nothing else -- the instant and the duration belong to the run that earned the pass.
 
-**A replay is held to more than the pass is.** Retention carries its own key: the [pass key](#what-the-key-is-made-of) folded with the channel each output stream ran on and with `CI`, `COLUMNS`, `FORCE_COLOR`, `NO_COLOR`, and `TERM`. A recording made under a different one is recalled as a pass all the same; its excerpt is simply not replayed, and the verdict prints alone, as it does for a pass that retained nothing.
+**A replay is held to more than the pass is.** Retention carries its own key: the [pass key](#what-the-key-is-made-of) folded with the channel each output stream ran on and with `CI`, `COLUMNS`, `FORCE_COLOR`, `NO_COLOR`, and `TERM`. `NMR_OUTPUT_STYLE` is in neither key, so a rich run and a plain one share a recorded pass and replay each other's excerpts as recorded. A recording made under a different one is recalled as a pass all the same; its excerpt is simply not replayed, and the verdict prints alone, as it does for a pass that retained nothing.
 
 The whole line, excerpt included, is held to the same [512-byte ceiling](reporting.md#what-nmr-reports) every verdict is, so one write still carries it whole under concurrent fan-out. An assembly wide enough to overrun it is cut and marked with `…` rather than spread over several lines.
 
@@ -109,7 +109,7 @@ The excerpt is a line; the run behind it is kept whole. `nmr --log <command>` pr
 
 ```console
 $ nmr --log test
-📼 nmr: test — recorded 2026-08-12T15:04:05.412Z (12m ago), ran in 12.4s
+💾 nmr: test — recorded 2026-08-12T15:04:05.412Z (12m ago), ran in 12.4s
 $ pnpm exec vitest --project unit --project tool
 
  ✓ src/__tests__/resolver.unit.test.ts (18 tests) 12ms
@@ -130,7 +130,7 @@ The header is what presents the body as a recording rather than as this invocati
 
 ```console
 $ nmr --log test
-📭 nmr: test: no recording; the last pass was 3m ago, on a tree this is not
+🟠 nmr: test: no recording; the last pass was 3m ago, on a tree this is not
 ```
 
 **`--log` reaches the scopes `-F` and `-R` select.** The flag rides the delegate, so each scope prints its own recording. There a scope with nothing to show reports its gap and exits 0: partial coverage is a survey's normal shape, and failing on the first gap would hide every scope that had something. A selection of no scope at all is the other case and fails, as it does for a run: there is no survey to be partial.

package/docs/reporting.md

@@ -57,8 +57,22 @@ The format is nmr's own reporting and not a mode the commands it runs are told a
 
 `-q` sets it for the run and outranks an inherited value. Both values are spelled out so either direction is expressible: export `NMR_COMMAND_VERBOSITY=quiet` for a quiet shell, and set `full` on one invocation to opt back out.
 
+`NMR_OUTPUT_STYLE` is nmr's own as well, and carries the style every marker nmr prints is rendered in; see [output style](#output-style) below.
+
 `NMR_REPORT_FORMAT` is nmr's own as well, and carries how nmr renders its own verdicts. Its values are `text` and `json`; any other non-empty value is reported and exits 1, and an empty value reads as unset. `--json` sets it for the run and outranks an inherited value, and both values are spelled out so either direction is expressible: export `NMR_REPORT_FORMAT=json` for a shell whose consumer parses, and set `text` on one invocation to opt back out. Two sources, then, where a verbosity has four: no repo-level default and no harness detection, since detection would hand every agent JSON in place of the prose the [shipped guidance](../README.md#agent-guidance) teaches. See [reporting for a machine](#reporting-for-a-machine) for what the objects carry.
 
+### Output style
+
+`--output-style <auto|plain|rich>` sets the style for one invocation, and `NMR_OUTPUT_STYLE` sets it for a shell: `rich` marks each verdict with an emoji, such as ✅ or ❌, and `plain` prints a word in its place, such as `PASS` or `FAIL`, which a reader of a log can search for. `auto`, the default, defers to detection. Any other value is a usage error that exits with code 1, whichever source named it. The flag outranks the variable, and both name `auto` as well as a style, so a shell exporting one style is overridable on one invocation in either direction.
+
+Detection decides stdout and stderr separately. A stream is plain when `CI` is set to anything other than an empty string or `false`, when the stream is not a terminal, or when `TERM` is `linux`; otherwise it is rich. `--json` output carries no marker in either style.
+
+**The flag belongs to `nmr`.** A standalone bin -- `nmr-clean`, `nmr-compile`, `nmr-report-catalog`, `nmr-report-overrides`, `nmr-ensure-prepublish-hooks` -- takes the variable alone, and passing it the flag gets that bin's unknown-option error. `nmr <command>` exports the style it resolved, so a bin run through nmr renders as nmr does.
+
+**A nested run follows the one that spawned it.** The resolved style, never `auto`, travels down as `NMR_OUTPUT_STYLE`, so a child whose own stdout is a pipe still renders rich where the parent resolved rich. The style exported is the one stdout resolved to, which is where the verdicts and nearly every other line go; a parent at a terminal whose stderr alone is redirected therefore hands its children `rich`.
+
+The style is out of the [pass key](check-cache.md#what-the-key-is-made-of) and the [retention key](check-cache.md#replaying-a-skipped-runs-output) alike, as the verbosity is: it changes how a run renders and never what a command concludes. Selecting it neither invalidates a recorded pass nor costs a replay, and an excerpt recorded rich replays as recorded in a plain run.
+
 ### Where a verbosity comes from
 
 Four sources, in precedence order. Each is read once, at the top of a chain: the resolved value travels down as `NMR_COMMAND_VERBOSITY`, so a nested process reads a decision already made rather than making its own.

package/docs/scripts.md

@@ -40,11 +40,11 @@ Each array element is a command name, optionally preceded by nmr's own flags, sp
 Trailing arguments reach every step of a composite, so `nmr fix --dry-run` runs `nmr lint --dry-run`, then `nmr fmt --dry-run`. A step whose work the arguments cannot narrow declines them by taking the long form of an element, and runs unnarrowed:
 
 ```ts
-// "ci": [{ run: "build", declinesArgs: true }, "check:strict"]
+// "ci": [{ run: "build", shouldDeclineArguments: true }, "check:strict"]
 // nmr ci src/foo.ts  ->  nmr build && nmr check:strict src/foo.ts
 ```
 
-`{ run }` is the bare string element with room for the declaration; `declinesArgs` defaults to `false`, and an element that accepts is written as the string. Decline where the step is a prerequisite the narrowed steps run against, or where the tool it reaches would be misled — `tsgo --noEmit foo.ts` abandons the tsconfig, which is why every default `typecheck` step declines. A leaf tool that merely ignores what it is handed is not a reason to decline: nmr forwards, and the tool decides.
+`{ run }` is the bare string element with room for the declaration; `shouldDeclineArguments` defaults to `false`, and an element that accepts is written as the string. Decline where the step is a prerequisite the narrowed steps run against, or where the tool it reaches would be misled — `tsgo --noEmit foo.ts` abandons the tsconfig, which is why every default `typecheck` step declines. A leaf tool that merely ignores what it is handed is not a reason to decline: nmr forwards, and the tool decides.
 
 Where no step of a command accepts them, nmr rejects the invocation and runs nothing, rather than running the whole command unnarrowed. That is what `nmr typecheck src/foo.ts` gets at the root, whose two steps both decline.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -77,22 +77,22 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.11.1",
-    "@williamthorsen/toolbelt.errors": "0.7.0",
+    "@williamthorsen/nmr-core": "0.12.0",
+    "@williamthorsen/toolbelt.errors": "0.8.1",
     "glob": "13.0.6",
     "prettier-plugin-sh": "0.19.0",
     "taze": "21.1.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.filesystem": "0.8.3",
-    "@williamthorsen/toolbelt.testing": "0.5.1",
-    "@williamthorsen/toolbelt.vitest": "0.9.0",
+    "@williamthorsen/toolbelt.filesystem": "0.9.1",
+    "@williamthorsen/toolbelt.testing": "0.6.1",
+    "@williamthorsen/toolbelt.vitest": "0.10.1",
     "prettier": "3.9.6",
-    "readyup": "0.36.0",
+    "readyup": "0.38.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.2.2",
+    "vite": "8.3.0",
     "vitest": "4.1.11"
   },
   "peerDependencies": {