@williamthorsen/nmr 0.34.0 → 0.35.0

package/dist/esm/help.d.ts

@@ -1,2 +1,15 @@
 import type { NmrConfig } from './types.js';
+/**
+ * Generates the help text for the `nmr` CLI. Renders only nmr commands —
+ * names from the workspace and root registries, excluding hooks (`*:pre`,
+ * `*:post`).
+ *
+ * When `packageDir` is provided, tier-3 entries from that package's
+ * `package.json:scripts` that match a registry name in the active section
+ * are inlined as overrides: the registry value is replaced with the
+ * override value and the row's command name is suffixed with `*`. The
+ * active section is the root section when `useRoot` is true (root cwd
+ * or `-w`), otherwise the workspace section. A footnote is appended once
+ * if any override marker was rendered.
+ */
 export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, useRoot: boolean): string;

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

@@ -1,2 +1,14 @@
+/** Marks a value that was cut, so a reader can tell a truncated one from a complete one. */
 export declare const TRUNCATION_MARK = "\u2026";
+/**
+ * Cuts a string that would overrun a byte budget, marking the cut. What comes back is at most `budgetBytes`
+ * long, the mark included.
+ *
+ * Cuts between code points rather than between bytes, so a multi-byte character is never left in halves.
+ * Graphemes are left unconsidered, which can separate an emoji from a modifier following it -- a cost paid
+ * only at a budget no caller here comes near.
+ *
+ * A budget too small to hold the mark yields nothing at all, rather than a return that overruns what the
+ * caller asked for.
+ */
 export declare function clampToBytes(value: string, budgetBytes: number): string;

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

@@ -3,7 +3,14 @@ export interface BoundedBufferOptions {
     tailLimitBytes?: number;
 }
 export interface BoundedBuffer {
+    /** Retains a chunk, dropping bytes from the middle once both ends are full. */
     append: (chunk: Buffer) => void;
+    /** Renders the retained bytes, with a marker naming the dropped count standing in for what was dropped. */
     toBuffer: () => Buffer;
 }
+/**
+ * Creates an accumulator that retains the first and last bytes it is fed and drops the middle.
+ * Both ends are kept because a failing command's first error and its trailing summary each carry signal
+ * that the other end does not.
+ */
 export declare function createBoundedBuffer(options?: BoundedBufferOptions): BoundedBuffer;

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

@@ -1 +1,11 @@
+/**
+ * Reduces a transcript to the one line a verdict's detail slot carries, or `undefined` when it held nothing.
+ *
+ * The excerpt is the last blank-line-delimited block: a tool that prints progress separates its closing
+ * statement with a blank line, so the blank line is the tool naming where its summary starts. A fixed count of
+ * trailing lines fits vitest's four-line summary and v8's six-line coverage summary only by coincidence.
+ *
+ * The line carries a byte bound of its own, so what a caller persists is bounded. The 512-byte ceiling a
+ * verdict line is held to is not applied here, which leaves that line's grammar with the module that owns it.
+ */
 export declare function deriveExcerpt(transcript: string): string | undefined;

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

@@ -1,2 +1,17 @@
+/**
+ * Renders a duration at the two coarsest units that say something, for a line a reader skims.
+ *
+ * Truncates at every unit rather than rounding, so a value never reads as more time than elapsed: 90 seconds is
+ * `1m 30s`, where rounding would claim `2m`. Below a minute the tenth is kept, since that is the scale at which
+ * one check's runtime differs from another's; a whole number sheds the `.0` rather than reading `12.0s`.
+ */
 export declare function formatDuration(milliseconds: number): string;
+/**
+ * Renders the clause a skip spends on the time it saved, or `undefined` when there is no saving worth naming.
+ * A skip that can say what it saved earns the clause; one that cannot says nothing, and the caller drops it
+ * rather than printing a saving of `~0s`.
+ *
+ * Guards its own input rather than trusting the caller's, because the clause is shared: a non-finite duration
+ * compares false against the threshold, and would reach a reader as `saved ~NaNs`.
+ */
 export declare function formatSaving(milliseconds: number): string | undefined;

package/dist/esm/helpers/hook-name.d.ts

@@ -1 +1,9 @@
+/**
+ * Returns true when `key` is a hook script name — that is, ends with the
+ * `:pre` or `:post` suffix preceded by at least one character.
+ *
+ * Bare `:pre` and `:post` (no parent name) return false. The predicate is
+ * purely about suffix shape; it does not consult the registry or care
+ * whether the parent command exists.
+ */
 export declare function isHookName(key: string): boolean;

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

@@ -1,3 +1,9 @@
+/**
+ * The `package.json` fields that carry a dependency's version specifier.
+ *
+ * pnpm accepts the `catalog:` protocol in all four, so a reader looking for catalogued dependencies has to
+ * sweep the whole set rather than the two that carry most of them.
+ */
 export declare const DEPENDENCY_FIELDS: readonly ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
 export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
 export type PackageJson = {
@@ -12,8 +18,27 @@ export type PackageJson = {
 } & {
     [K in DependencyField]?: Record<string, string>;
 };
+/**
+ * Reads and parses the package.json at the given directory, keeping only the fields nmr reads.
+ */
 export declare function readPackageJson(dir: string): PackageJson;
+/**
+ * Returns the `pnpm.overrides` block a package.json declares, every key it holds and each value as written.
+ */
 export declare function getPnpmOverrides(pkg: PackageJson): Record<string, unknown> | undefined;
+/**
+ * Parses a `package.json`'s text, rejecting what does not parse.
+ *
+ * A file the user wrote by hand is theirs to fix, so the failure names it rather than reporting the parser's
+ * own stack.
+ */
 export declare function parsePackageJson(raw: string, file: string): unknown;
+/**
+ * Narrows a `scripts` record to strings, rejecting any value that is not one.
+ *
+ * npm and pnpm read a script as a string too, so a value of any other type is malformed however it got there.
+ * Dropping one silently would let a caller run something else in its place and report nothing.
+ */
 export declare function readScriptRecord(dir: string, scripts: Record<string, unknown>): Record<string, string>;
+/** Resolves the `package.json` path for a directory: the file tier-3 scripts are read from. */
 export declare function resolvePackageJsonPath(dir: string): string;

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

@@ -1 +1,8 @@
+/**
+ * Keeps the entries whose value is a string, dropping the rest.
+ *
+ * A manifest reader that rejected the whole record over one bad value would report nothing about the entries
+ * beside it, which for a reporter is silence where there is something to say. YAML's implicit typing makes
+ * that easy to reach without malformed intent: an unquoted `18` parses as a number.
+ */
 export declare function readStringValues(record: Record<string, unknown>): Record<string, string>;

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

@@ -1 +1,16 @@
+/**
+ * Reports the line that closes a bin's output, separated from the items above it by a blank line.
+ *
+ * A bin that prints one line per item leaves a reader who reaches the end holding whichever item happened to
+ * be last. The convention this writes: the header says what the list is, and the closing statement says what
+ * the run came to, so the count and the remedy live here rather than in the header. The blank line is what
+ * makes the statement findable once the lines are flattened.
+ *
+ * The blank line rides in the same call as the statement, so the closer is one write and cannot be
+ * interleaved. `log` is what puts the closer on the stream its items went to: a bin reporting to stderr
+ * passes `console.warn`.
+ *
+ * A bin whose whole output is one or two statements about one subject has no items to be separated from, and
+ * closes by printing plainly rather than through here.
+ */
 export declare function reportClosing(message: string, log?: (line: string) => void): void;

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

@@ -1,5 +1,30 @@
 import type { RetainedOutput } from '../runner.js';
+/**
+ * The bound on what one recorded pass persists, and so on what `nmr --log` can print back.
+ *
+ * A quantity of its own, distinct from the two that bound the same bytes elsewhere: the in-memory copy a
+ * command's capture keeps is bounded per stream, for a failure this run may still have to report, and a
+ * verdict line is bounded at what a pipe carries atomically. This one bounds what a cache directory
+ * accumulates over every scope and command a repo records.
+ */
 export declare const TRANSCRIPT_LIMIT_BYTES = 262144;
+/**
+ * Reduces a command's raw output to the form nmr persists: escape sequences dropped, and a line the command
+ * redrew reduced to what a reader was left looking at.
+ *
+ * Applied where the bytes are stored rather than where they are captured. The copy a quiet run writes to
+ * stderr on failure is the command's own output going to a stream that may be a terminal, and stripping its
+ * color there would be a loss.
+ */
 export declare function cleanTranscript(raw: string): string;
+/**
+ * Composes what a pass persists from what its command wrote, or `undefined` where it wrote nothing worth
+ * keeping.
+ *
+ * The streams follow one another rather than interleaving, in the order a quiet run already dumps them on
+ * failure: nmr reads each through a pipe of its own, so their true interleaving is not among the facts it
+ * holds. A stream carrying nothing contributes neither content nor marker.
+ */
 export declare function composeTranscript(retained: RetainedOutput): string | undefined;
+/** Renders the line that stands in for dropped bytes, in nmr's voice so it is not mistaken for the tool's. */
 export declare function formatElisionMarker(byteCount: number): string;

package/dist/esm/helpers/type-guards.d.ts

@@ -1,2 +1,3 @@
 export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** Narrows an unknown value to a record of plain strings. */
 export declare function isStringRecord(value: unknown): value is Record<string, string>;

package/dist/esm/helpers/workspace-patterns.d.ts

@@ -1 +1,8 @@
+/**
+ * Resolves pnpm workspace patterns to absolute package directories.
+ *
+ * Applies pnpm's algorithm: every pattern is rewritten to match a manifest, `!`-prefixed patterns become
+ * exclusions, and the matcher decides the rest. Exclusions filter the entire positive match set
+ * irrespective of declaration order.
+ */
 export declare function resolvePackageDirs(monorepoRoot: string, patterns: string[]): string[];

package/dist/esm/prettier.d.ts

@@ -1,8 +1,16 @@
 import type { Config } from 'prettier';
 export interface PrettierConfigOptions extends Omit<Config, 'overrides' | 'plugins'> {
+    /** Appended to the plugins this config registers. */
     additionalPlugins?: NonNullable<Config['plugins']>;
+    /** Appended to the overrides this config declares, so a later entry wins over nmr's own. */
     additionalOverrides?: NonNullable<Config['overrides']>;
+    /** Replacing the override list is inexpressible; append through `additionalOverrides`. */
     overrides?: never;
+    /** Replacing the plugin list is inexpressible; append through `additionalPlugins`. */
     plugins?: never;
 }
+/**
+ * Builds the shared Prettier config, registering shell and Dockerfile support alongside the house options.
+ * Every option other than `plugins` and `overrides` spreads over the defaults.
+ */
 export declare function definePrettierConfig(options?: PrettierConfigOptions): Config;

package/dist/esm/recording.d.ts

@@ -1,14 +1,26 @@
-import type { CheckCacheEntry } from './check-cache.js';
+import { type CheckCacheEntry } from './check-cache.js';
+/**
+ * What this invocation would be recorded under, insofar as an entry records the same facts. A mismatch is read
+ * against these, so a refusal names the ingredient that moved rather than blaming the tree for all of them.
+ */
 export interface RunIdentity {
     commandString: string;
     nmrVersion: string;
     nodeVersion: string;
+    /** Absent where no snapshot was taken, which leaves the tree unattributable rather than assumed equal. */
     treeHash: string | undefined;
 }
+/** A recorded pass and what it left a reader: its command's own transcript, or the assembly a composite holds. */
 export interface Recording {
     entry: CheckCacheEntry;
+    /** What the command wrote, absent on a composite, which retains nothing of its own. */
     transcript?: string;
 }
+/**
+ * Which of the pass key's ingredients a recorded pass and this invocation disagree on, insofar as an entry
+ * records enough to tell: the residual covers what it does not, which is the install, the platform, and the
+ * environment variables the key folds in.
+ */
 export type KeyDifference = {
     ingredient: 'tree';
 } | {
@@ -24,6 +36,7 @@ export type KeyDifference = {
 } | {
     ingredient: 'other';
 };
+/** What `--log` found for one command at one scope. */
 export type RecordingLookup = {
     ok: true;
     recording: Recording;
@@ -31,6 +44,11 @@ export type RecordingLookup = {
     ok: false;
     refusal: RecordingRefusal;
 };
+/**
+ * Why there is nothing to print. Each is a separate answer to a reader asking for the last run's output, and
+ * each names a different next move: run the command, run it on this tree, run it through a pipe, or stop
+ * asking for a command no run records.
+ */
 export type RecordingRefusal = {
     kind: 'uncacheable';
 } | {
@@ -45,16 +63,36 @@ export type RecordingRefusal = {
     kind: 'no-output';
     ageMs: number;
 };
+/**
+ * Renders a recording as the reader sees it: a header dating what follows, the command string that produced
+ * it, and then the run's own bytes.
+ *
+ * The header is what presents the body as a recording rather than as this invocation's output, which is what
+ * lets a reader at a terminal be shown what a piped run wrote. The command string is the whole chain, hooks
+ * included, so the header names what earned the pass and not merely what was typed.
+ */
 export declare function renderRecording(options: {
     command: string;
     recording: Recording;
     scope: string;
 }): string;
+/**
+ * Renders a refusal on the one line a fan-out can attribute, in the grammar a verdict uses: the scope, the
+ * command, and what is missing.
+ */
 export declare function renderRefusal(options: {
     command: string;
     refusal: RecordingRefusal;
     scope: string;
 }): string;
+/**
+ * Resolves what one scope has to show for one command.
+ *
+ * Admitted on the pass key alone, so `--log` prints exactly what a skip would have recalled and never a
+ * recording of some other tree. The retention key is deliberately not consulted: it certifies that a recording
+ * describes this presentation environment, which is what a replayed excerpt needs and what a dated recording
+ * does not.
+ */
 export declare function resolveRecording(options: {
     anchorDir: string;
     command: string;

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

@@ -1,5 +1,21 @@
-import type { ReplayLine } from './check-cache.js';
-import type { Step } from './steps.js';
+import { type ReplayLine } from './check-cache.js';
+import { type Step } from './steps.js';
+/**
+ * Assembles what a composite's skip replays: the excerpts its constituents recorded, in the order its own
+ * steps name them.
+ *
+ * A constituent that is itself a composite holds a flat, attributed list of its own, so splicing one in keeps
+ * the assembly flat and a skipped `ci` replays a package's `test` rather than one opaque `check:strict`
+ * line. Nothing is computed and nothing is inferred: a constituent with no admissible entry is absent from
+ * the assembly.
+ *
+ * A constituent is looked up at the scope its own process anchors at: the composite's anchor, or the monorepo
+ * root for an element carrying `-w`, which is how a package-scoped composite reaches a root command.
+ *
+ * An entry is admissible where the run that certified it is this one and the tree it describes is this one.
+ * The witness is what a run stamps on an excerpt it records and on one it recalls and replays; the tree hash
+ * is what bounds an identity a process carried out of the run that issued it.
+ */
 export declare function assembleReplay(options: {
     anchorDir: string;
     monorepoRoot: string;

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

@@ -1,9 +1,32 @@
+/**
+ * Renders the rejection of a value off the format ladder, naming where it was written. Every source that
+ * accepts a format renders through this, so no two of them can come to name different ladders.
+ */
 export declare function formatReportFormatRejection(source: string, value: string): string;
+/** Narrows a raw value to a point on the format ladder. */
 export declare function isReportFormat(value: string): value is ReportFormat;
+/**
+ * Reads the format the environment names. An unrecognized value resolves to nothing at all, since falling back
+ * would pick a rendering nobody chose and hide a misspelling for the life of the shell.
+ *
+ * An unset or empty variable names no format rather than resolving to `text`, which keeps the read symmetric
+ * with the one the loudness ladder performs and leaves room for a level below the environment.
+ */
 export declare function readReportFormatEnv(env: NodeJS.ProcessEnv): ReportFormatRead;
+/**
+ * Carries the resolved format down the spawned chain, so `--json` reaches every process rather than the first.
+ * Deliberately not a keyed variable: it changes how a run reports and never what a command concludes, so
+ * folding it into the cache key would stop a machine-readable run from hitting a pass a prose one recorded.
+ */
 export declare const REPORT_FORMAT_ENV_VAR = "NMR_REPORT_FORMAT";
+/**
+ * The points on the format ladder. Both are spelled out rather than leaving `text` implicit in the variable's
+ * absence, so a format exported for a shell is overridable on one invocation in either direction.
+ */
 export declare const REPORT_FORMATS: readonly ["text", "json"];
+/** How nmr renders its own verdicts, which is never the output of the commands it runs. */
 export type ReportFormat = (typeof REPORT_FORMATS)[number];
+/** The format the environment names, if any, or the message naming why its value could not be read. */
 export type ReportFormatRead = {
     ok: true;
     format?: ReportFormat;
@@ -11,6 +34,16 @@ export type ReportFormatRead = {
     ok: false;
     error: string;
 };
+/**
+ * Resolves the format this process reports in: the flag, then the environment, then `text`.
+ *
+ * Two levels where the loudness ladder has four. A repo wanting JSON for everyone working in it is not a case
+ * anyone has, and detecting a harness would hand every agent JSON in place of the prose the shipped guidance
+ * teaches; either is additive later.
+ *
+ * Total by construction. The environment was validated as it was read, so no rejection is left for this to
+ * report and the whole ladder reads in one place.
+ */
 export declare function resolveReportFormat(options: ResolveReportFormatOptions): ReportFormat;
 export interface ResolveReportFormatOptions {
     envFormat: ReportFormat | undefined;

package/dist/esm/reportCliFailure.d.ts

@@ -1,2 +1,10 @@
 import type { Writable } from 'node:stream';
+/**
+ * Writes a failure to the CLI's error stream: as its message alone when the user's own declaration caused it,
+ * and with its stack otherwise.
+ *
+ * A stack records where nmr noticed a problem, which says nothing about the file a user has to edit; for nmr's
+ * own fault it is where a report has to start. `describeError` covers an `Error` carrying no stack and a thrown
+ * non-`Error` alike.
+ */
 export declare function reportCliFailure(error: unknown, stderr: Writable): void;

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

@@ -1,4 +1,13 @@
-import type { ScriptRegistry } from './default-scripts.js';
+import { type ScriptRegistry } from './default-scripts.js';
 export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js';
+/**
+ * Return the default workspace scripts.
+ *
+ * A function rather than the exported table itself: callers merge overrides into the result, and `generateHelp`
+ * rewrites entries in place, so each caller needs a copy the module does not share.
+ */
 export declare function getDefaultWorkspaceScripts(): ScriptRegistry;
+/**
+ * Return the default root scripts.
+ */
 export declare function getDefaultRootScripts(): ScriptRegistry;

package/dist/esm/resolver.d.ts

@@ -1,8 +1,24 @@
-import type { ScriptRegistry, ScriptValue } from './resolve-scripts.js';
-import type { Step } from './steps.js';
+import { type ScriptRegistry, type ScriptValue } from './resolve-scripts.js';
+import { type Step } from './steps.js';
 import type { NmrConfig } from './types.js';
+/**
+ * Replace the first token of a command with a `devBin` substitute.
+ * Relative paths in the replacement are resolved from `monorepoRoot`.
+ */
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
+/**
+ * Applies a `devBin` substitution to each opaque step, leaving nmr's own compositions alone.
+ *
+ * A structural step names a command nmr resolves for itself, so substituting its first token would replace the
+ * `nmr` that carries the composite rather than the leaf tool `devBin` documents replacing.
+ */
 export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
+/**
+ * Where a resolved script was read from.
+ *
+ * `registry` covers the built-in defaults and the repo-wide config together, which resolution cannot tell
+ * apart: it receives the two already merged. A caller holding the config refines the two.
+ */
 export type ScriptOrigin = {
     tier: 'registry';
     key: string;
@@ -15,11 +31,60 @@ export interface ResolvedScript {
     origin: ScriptOrigin;
     steps: readonly Step[];
 }
+/**
+ * Expands a script value into the ordered steps it runs as: a string is one opaque step, and an array is one
+ * structural step per element.
+ *
+ * A bare string element and the `{ run }` spec compose the same step. The spec's only addition is the
+ * declaration of what the step does with the invocation's trailing arguments, which position cannot carry.
+ */
 export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): readonly Step[];
+/**
+ * Returns a description of a script for help output.
+ */
 export declare function describeScript(script: ScriptValue): string;
+/**
+ * Reads a package.json's `scripts`, rejecting any value that is not a string.
+ *
+ * npm and pnpm read a script as a string too, so a value of any other type is malformed however it got there.
+ * Dropping one silently would run the registry's entry in its place, which is what an array written here after
+ * being told a step list resolves a shelled-nmr crossing would otherwise do.
+ */
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
+/**
+ * Builds the merged workspace script registry:
+ * tier 1 (defaults) + tier 2 (config overrides)
+ */
 export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistry;
+/**
+ * Builds the merged root script registry:
+ * tier 1 (defaults) + tier 2 (config overrides)
+ */
 export declare function buildRootRegistry(config: NmrConfig): ScriptRegistry;
+/**
+ * Returns a `package.json` entry that re-invokes the command it is declared under alongside other steps, or
+ * `undefined` where the entry declares no such thing.
+ *
+ * Resolution discards a self-referential entry however it reads, so an entry that chains loses the steps it
+ * chained. This is what an invocation rejects on, read where the command runs rather than raised from
+ * resolution: the same scripts are resolved speculatively, for packages nobody named.
+ */
 export declare function findChainedSelfReference(packageDir: string | undefined, commandName: string): string | undefined;
+/**
+ * Reports whether a `package.json` entry re-invokes the command it is declared under, wherever the
+ * re-invocation stands in it, e.g. `"build": "nmr build"` or `"build": "rdy compile && nmr build"`.
+ *
+ * Honouring one spawns a shell that runs the same command in the same directory, reaching the same entry
+ * again without bound, so resolution discards it.
+ */
 export declare function isSelfReferential(script: string, commandName: string, packageDir: string): boolean;
+/**
+ * Resolves a script command using the three-tier override system:
+ * 1. Package defaults (built-in registry)
+ * 2. Repo-wide config (.config/nmr.config.ts)
+ * 3. Per-package overrides (package.json scripts)
+ *
+ * Returns undefined if the command is not found in the registry. A package.json override of `""` (indicating
+ * skip) resolves to a single opaque step carrying it, which renders back to the empty string.
+ */
 export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, workspaceRoot: boolean): ResolvedScript | undefined;

package/dist/esm/resolver.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { hasErrnoCode } from '@williamthorsen/nmr-core';
 import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
 import { isObject } from "./helpers/type-guards.js";
-import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { getDefaultRootScripts, getDefaultWorkspaceScripts, } from "./resolve-scripts.js";
 import { composeNmrStep, readSelfReference } from "./steps.js";
 import { isMonorepoRoot } from "./workspace.js";
 export function applyDevBin(command, devBin, monorepoRoot) {

package/dist/esm/runCli.d.ts

@@ -1,13 +1,30 @@
 import type { Writable } from 'node:stream';
+/**
+ * Marks a run made on a delegating caller's behalf, where a command the registry does not define exits 0
+ * rather than failing.
+ */
 export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
+/** @internal */
 export interface RunCliOptions {
+    /** Post-slice CLI arguments (equivalent to `process.argv.slice(2)`). */
     args: string[];
+    /** Working directory used to resolve the nmr execution context. */
     cwd: string;
+    /** Environment for `runCli` (used for `NMR_RUN_IF_PRESENT` reads and `-R` writes). */
     env: NodeJS.ProcessEnv;
+    /** Stream for normal output (help text, override messages). */
     stdout: Writable;
+    /** Stream for error output (unknown command, parse errors). */
     stderr: Writable;
 }
+/** @internal */
 export interface RunCliResult {
     exitCode: number;
 }
+/**
+ * Executes the nmr CLI flow in-process and returns the resulting exit code.
+ * Holds no global state, reads no `process.*` globals, never calls `process.exit`.
+ *
+ * @internal
+ */
 export declare function runCli(options: RunCliOptions): Promise<RunCliResult>;

package/dist/esm/runCli.js

@@ -16,7 +16,7 @@ import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandSc
 import { resolveChannel, runSteps } from "./runner.js";
 import { composeNmrStep, findNmrCrossing, renderChain } from "./steps.js";
 import { UserError } from "./UserError.js";
-import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity } from "./verbosity.js";
+import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
 const VERSION = readPackageVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";

package/dist/esm/runner.d.ts

@@ -1,26 +1,40 @@
 import type { Writable } from 'node:stream';
 import type { Step } from './steps.js';
+/** Where one of a child's output streams goes: a descriptor the child writes to, or a pipe nmr reads. */
 export type OutputChannel = number | 'pipe';
+/** The channel each of a child's output streams runs on. */
 export interface OutputChannels {
     stderr: OutputChannel;
     stdout: OutputChannel;
 }
 export interface RunCommandOptions {
+    /** The channel each of the child's output streams runs on. */
     channels: OutputChannels;
+    /** When true, suppress output on success and write captured output to stderr on failure. */
     quiet?: boolean;
+    /** Stream that subprocess stdout flows to in non-quiet mode. Defaults to `process.stdout`. */
     stdout?: Writable;
+    /** Stream that subprocess stderr flows to (and that quiet-mode failure output is written to). Defaults to `process.stderr`. */
     stderr?: Writable;
+    /** Environment for the subprocess. Defaults to `process.env`. */
     env?: NodeJS.ProcessEnv;
 }
+/** What a step list needs to run. Each step's channels follow its kind, so the caller chooses none of them. */
 export type RunStepsOptions = Omit<RunCommandOptions, 'channels'>;
+/** A bounded copy of what a step list's own commands wrote, each stream kept apart from the other. */
 export interface RetainedOutput {
     stderr: Buffer;
     stdout: Buffer;
 }
 export interface RunStepsResult {
     exitCode: number;
+    /**
+     * What the list's opaque steps produced, absent unless every one of them was captured whole and there was
+     * at least one to capture.
+     */
     retained?: RetainedOutput;
 }
+/** How a command ended, and the exit code that carries that ending to nmr's own caller. */
 type CommandCompletion = {
     outcome: 'exited';
     exitCode: number;
@@ -34,11 +48,49 @@ type CommandCompletion = {
     error: Error;
 };
 export type RunCommandResult = CommandCompletion & {
+    /**
+     * Output retained while the command ran, elided in the middle when it overran the bound.
+     * `undefined` where the stream was handed to the child directly, or where capture stopped early
+     * and the retained copy would understate what the command produced.
+     */
     stdout: Buffer | undefined;
     stderr: Buffer | undefined;
 };
+/**
+ * Returns the channel a stream runs on: the stream's own descriptor when it is a terminal and output is not
+ * being withheld, so the child's terminal detection matches nmr's, and a pipe everywhere else.
+ */
 export declare function resolveChannel(stream: Writable, quiet: boolean): OutputChannel;
+/**
+ * Returns the channel a step running an nmr process below this one runs on: nmr's own descriptor whenever it
+ * has one, so the child writes where nmr writes and no ancestor stands between them relaying bytes. A stream
+ * carrying no descriptor, which is the one a test injects, falls back to a pipe.
+ */
 export declare function resolveInheritedChannel(stream: Writable): OutputChannel;
+/**
+ * Runs a step list in order and resolves once one fails or all have run, carrying the `&&` semantics nmr
+ * promises: the first non-zero exit ends the sequence and is the code returned.
+ *
+ * Sequencing here rather than in a spawned shell is what lets each step run on the channels its kind calls
+ * for, and what makes a signal to nmr end the run: the steps after it are never reached, where a shell would
+ * have gone on running them unsupervised.
+ *
+ * Carries back a bounded copy of what the list's own commands wrote, so a caller can retain it. Only opaque
+ * steps contribute: a structural step is another nmr process reporting for the subtree beneath it, and its
+ * output is that subtree's to account for.
+ */
 export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<RunStepsResult>;
+/**
+ * Runs a command through a shell and resolves once it has ended.
+ *
+ * The caller chooses each stream's channel. A descriptor is handed to the child and nmr sees none of what
+ * flows through it; a pipe is forwarded to the matching option stream as it arrives, with that destination's
+ * back-pressure throttling the child, and a bounded copy is retained. Quiet mode withholds the forwarding,
+ * discarding the retained copy on success and writing it to `options.stderr` on failure, so it has nothing to
+ * report unless the caller chose a pipe on both streams.
+ *
+ * Piped stdout and stderr are ordered by arrival rather than by a shared descriptor, so their interleaving
+ * is approximate.
+ */
 export declare function runCommand(command: string, cwd: string | undefined, options: RunCommandOptions): Promise<RunCommandResult>;
 export {};

package/dist/esm/scripts.d.ts

@@ -1,2 +1,3 @@
+/** Public API for inspecting nmr's built-in script registries. */
 export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js';
 export { getDefaultRootScripts, getDefaultWorkspaceScripts } from './resolve-scripts.js';