@williamthorsen/nmr 0.28.0 → 0.30.0

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat — @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.24.0";
+export const __readyupVersion = "0.26.0";
 
 
 // .readyup/kits/default.ts
@@ -48,7 +48,7 @@ var rootScripts = {
   audit: ["audit:prod", "audit:dev"],
   "audit:dev": "pnpm exec v11y --dev",
   "audit:prod": "pnpm exec v11y --prod",
-  build: "pnpm --recursive exec nmr build",
+  build: ["-R build"],
   check: ["typecheck", "fmt:check", "lint:check", "test"],
   "check:strict": ["typecheck", "fmt:check", "lint:strict", "test:coverage"],
   // Excludes the audit, which in CI has a workflow of its own.
@@ -61,7 +61,8 @@ var rootScripts = {
   lint: "eslint --fix .",
   "lint:check": "eslint .",
   "lint:strict": "strict-lint",
-  prepush: ["ci", "audit"],
+  // The audit costs seconds and `ci` costs minutes, so the cheap gate fails first.
+  prepush: ["audit", "ci"],
   "report-overrides": "nmr-report-overrides",
   "root:check": ["root:typecheck", "fmt:check", "root:lint:check", "root:test"],
   "root:lint": "eslint --fix --ignore-pattern 'packages/**' .",
@@ -73,13 +74,13 @@ var rootScripts = {
   "root:test:unit": "vitest --config ./vitest.root.config.ts --project unit",
   "root:typecheck": "tsgo --noEmit",
   "root:upgrade": "nmr-taze --include-locked",
-  test: "nmr root:test && pnpm --recursive exec nmr test",
-  "test:all": "nmr root:test:all && pnpm --recursive exec nmr test:all",
-  "test:coverage": "nmr root:test && pnpm --recursive exec nmr test:coverage",
-  "test:tool": "nmr root:test:tool && pnpm --recursive exec nmr test:tool",
-  "test:unit": "nmr root:test:unit && pnpm --recursive exec nmr test:unit",
+  test: ["root:test", "-R test"],
+  "test:all": ["root:test:all", "-R test:all"],
+  "test:coverage": ["root:test", "-R test:coverage"],
+  "test:tool": ["root:test:tool", "-R test:tool"],
+  "test:unit": ["root:test:unit", "-R test:unit"],
   "test:watch": `vitest ${GATE_PROJECTS} --watch`,
-  typecheck: "nmr root:typecheck && pnpm --recursive exec nmr typecheck",
+  typecheck: ["root:typecheck", "-R typecheck"],
   // The command must be a string rather than a composite: Passthrough args attach to the chain's last command.
   upgrade: "nmr-report-overrides && nmr-taze --include-locked --recursive"
 };
@@ -375,7 +376,7 @@ function formatPaths(paths) {
 ${paths.map((path2) => `      ${path2}`).join("\n")}`;
 }
 function getMinVersion() {
-  const picked = { "version": "0.28.0" };
+  const picked = { "version": "0.30.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -7,10 +7,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.24.0",
+      "readyupVersion": "0.26.0",
       "source": "kits/default.ts",
       "sourceHash": "7b2a223f",
-      "targetHash": "b7abeb12"
+      "targetHash": "bdca19db"
     }
   ]
 }

package/README.md

@@ -3,29 +3,25 @@
 Context-aware script runner for pnpm monorepos. Ships an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v0.28.0 (2026-08-08)
+## Release notes — v0.30.0 (2026-08-10)
 
 ### 🎉 Features
 
-- Stop reporting absence checks that pass (#610)
+- 🚨 **Breaking:** Resolve a command to a step list and reject a script element carrying shell syntax (#648)
 
-  A ReadyUp check that checks for a problem (such as an unwanted file or a stale config reference) now stays silent unless it finds one. The `nmr`, `release-kit`, and `v11y-check` ReadyUp kits previously printed a line for every such check on every run.
+  A script defined in `.config/nmr.config.ts` as a list of nmr commands now holds one command name per entry, optionally preceded by nmr's own flags. An entry that carries a quoted argument or any other shell syntax previously ran as written and is now rejected when the config loads. Before upgrading, a repo relying on such an entry should define that command as a script of its own and reference it by name from the list.
 
-- Stop reporting non-issues in the readyup kits (#613)
+- 🚨 **Breaking:** Sequence a command's steps in nmr rather than in a shell (#649)
 
-  Modifies the `release-kit` and `nmr` ReadyUp kits to avoid verbose reporting when an initial check determines that further checks aren't applicable. In particular, a repo with no `release-kit` config file gets a single line in the `release-kit` report, and a repo that publishes nothing now bypasses the `npm-auto-publish` kit instead of failing it.
+  When a run in quiet mode fails, it now shows only the output of the command that failed instead of everything the run had produced up to that point. Quiet mode can now be set for a whole shell session with the `NMR_COMMAND_VERBOSITY` environment variable, which accepts `full` or `quiet`; `-q` still takes precedence for a single run, and an unrecognized value is reported as an error. Interrupting a run now stops the commands that would have followed it.
 
-### 🐛 Bug fixes
+  Breaking: a `devBin` entry that maps `nmr` itself no longer takes effect inside a command that runs other nmr commands. Mapping any other tool (the documented use) is unaffected.
 
-- Fix prototype-key hole in nmr command runner (#624)
+- 🚨 **Breaking:** Express the seven root defaults as steps (#650)
 
-  Fixes an issue where running `nmr` with a command named for property inherited by JS objects (such as `constructor` or `toString`) failed with a type error instead of reporting the command as unknown.
+  Running `nmr build`, `nmr test`, `nmr test:all`, `nmr test:coverage`, `nmr test:tool`, `nmr test:unit`, or `nmr typecheck` from a monorepo root now passes over a package that does not define the command, instead of failing there. The first run of `test`, `test:coverage`, `test:tool`, `test:unit`, or `typecheck` after the upgrade no longer skips as already passed; skipping resumes on the run after.
 
-  Also fixes all lint issues in the `nmr` package.
-
-- Publish build output atomically so a failed build cannot destroy it (#631)
-
-  Fixes an issue where a failed or still-running `nmr build` could leave a package with no build output at all, breaking the tooling that a subsequent build depends on. Separately, the error reported when a package's build output is missing now names the correct recovery command.
+  `nmr` now also warns when a command it is about to run invokes `nmr` again through a shell, where a failure reports the whole inner run's output instead of the failing command's. The warning catches only a direct `nmr` call, so a command that reaches `nmr` through another program goes unreported.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -73,9 +69,9 @@ nmr's key feature is that the same command runs different scripts depending on w
 
 | Where you run `nmr`               | Registry used     | Working directory | `nmr test` runs                                                      |
 | --------------------------------- | ----------------- | ----------------- | -------------------------------------------------------------------- |
-| Monorepo root                     | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                        |
+| Monorepo root                     | Root scripts      | Monorepo root     | `root:test`, then `-R test`                                          |
 | Inside a workspace package        | Workspace scripts | The package root  | `pnpm exec vitest --project unit --project tool` (that package only) |
-| Anywhere, with `--workspace-root` | Root scripts      | Monorepo root     | Root tests + `pnpm --recursive exec nmr test`                        |
+| Anywhere, with `--workspace-root` | Root scripts      | Monorepo root     | `root:test`, then `-R test`                                          |
 
 Relative paths in a script resolve against that working directory, not the invocation directory.
 
@@ -122,7 +118,13 @@ Script values can be `string` or `string[]`. Arrays expand to chained `nmr` sub-
 // expands to: nmr lint && nmr fmt
 ```
 
-Passthrough arguments attach to the final step alone, because the expansion is a single shell chain: `nmr fix --dry-run` runs `nmr lint && nmr fmt --dry-run`.
+Each array element is a command name, optionally preceded by nmr's own flags, split on whitespace — `-R test` runs the element in every package, the way `nmr -R test` does. An element carrying a quoted argument or shell syntax is rejected when the config loads: name that command as a script of its own and reference the name.
+
+Passthrough arguments attach to the final step alone: `nmr fix --dry-run` runs `nmr lint`, then `nmr fmt --dry-run`.
+
+A string value is spawned through a shell as one command, so an `nmr` invocation inside it is invisible to the process above: a quiet failure surrenders the whole nested subtree rather than the failing step, and a loud run relays the nested tree through a forwarding pipe. nmr writes one line to stderr, in every verbosity, when a command resolves to a step whose first token is `nmr`.
+
+That line reports a boundary rather than enforcing a rule, and it is partial: a step reaching nmr through another program, such as `pnpm --recursive exec nmr build`, goes unreported. Only the built-in defaults and `.config/nmr.config.ts` carry arrays, so a `package.json` script embedding nmr has nowhere to move but up a tier.
 
 ## Configuration
 
@@ -192,7 +194,7 @@ For example, if a workspace script resolves to `my-cli --verbose`, nmr rewrites
 
 ## Pre and post hooks
 
-Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: nested invocations from composite expansion get their own hook treatment. Hook failure short-circuits the chain via shell `&&` semantics, propagating the failing exit code.
+Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: nested invocations from composite expansion get their own hook treatment. A failing hook ends the sequence, and its exit code propagates.
 
 Behaviors worth knowing:
 
@@ -277,7 +279,7 @@ A hit requires all of these to match the run that recorded the pass:
 
 A hit additionally requires the build output of every package nmr's own build covers to be present, and to have been built from this tree. Output is git-ignored, so neither its removal nor its replacement moves the hash: restoring a tree with `git stash` or `git checkout` restores none of the output that tree was built with. nmr compares each covered package's recorded build digest against the one on disk, so a `dist` compiled from another tree is a miss the following run repairs. A package that overrides `build` or `compile` emits on terms nmr does not know and is exempt.
 
-A pass is recorded only when the command exits 0, only when the tree still matches the one the run started against, only when every covered package's output is present, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss).
+A pass is recorded only when the command exits 0, only when the tree still matches the one the run started against, only when every covered package's output is present and unchanged since the run started, and never for a run that executed nothing (a `""`/`":"` skip override, or an `NMR_RUN_IF_PRESENT` miss). Output that moves mid-run leaves no answer to which output the pass was earned over, whether another process rebuilt it or the chain built it itself: `nmr ci` is the one default command whose chain does, and it records nothing on a run whose build did work. The `nmr check:strict` inside that chain still records, because its own window opens after the build.
 
 ### Out of contract
 
@@ -321,6 +323,10 @@ Reach for these in order; the first is almost always the right one.
 
 `NMR_TREE_SNAPSHOT` is nmr's own: it carries one observation of the tree from a top-level invocation down to the processes it spawns, so a chain hashes the tree once rather than at every link. nmr trusts an inherited value only while `HEAD` still stands where it did when the observation was taken, which bounds a process that outlives the run that spawned it. That bound does not extend to a tree edited without committing, so **a process that survives its run and later invokes nmr should clear `NMR_TREE_SNAPSHOT`** — a test suite that shells out to `nmr` is the case worth checking.
 
+`NMR_COMMAND_VERBOSITY` is nmr's own as well, and carries how loudly a run reports the output of the commands it runs. Its values are `full` and `quiet`; any other non-empty value is reported and exits 1, rather than falling back to a mode nobody chose, and an empty value reads as unset. Each process in a chain suppresses the output of the command it runs rather than of everything below it, so a failure still surrenders the failing command's output. nmr's own messages — the skip line, the override notice, and the `""`/`":"` skip notices — keep the suppression `-q` has always given them.
+
+`-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.
+
 ### Configuring
 
 ```ts
@@ -433,14 +439,16 @@ A run that collects no test files passes. That is what lets `nmr test:tool` fan
 
 #### Build and CI
 
-| Command   | Runs                              |
-| --------- | --------------------------------- |
-| `build`   | `pnpm --recursive exec nmr build` |
-| `ci`      | `build`, `check:strict`           |
-| `clean`   | `nmr-clean`                       |
-| `prepush` | `ci`, `audit`                     |
+| Command   | Runs                    |
+| --------- | ----------------------- |
+| `build`   | `-R build`              |
+| `ci`      | `build`, `check:strict` |
+| `clean`   | `nmr-clean`             |
+| `prepush` | `audit`, `ci`           |
+
+`ci` is what a code-quality workflow runs; it leaves out the audit, which belongs in a workflow of its own. `prepush` is what a developer runs before pushing: both gates, audit first. The audit takes seconds and `ci` takes minutes, so a vulnerability surfaces before the long gate runs. It composes `ci` rather than restating its stages, so a stage added to `ci` joins the pre-push run too.
 
-`ci` is what a code-quality workflow runs; it leaves out the audit, which belongs in a workflow of its own. `prepush` is what a developer runs before pushing: both gates. It composes `ci` rather than restating its stages, so a stage added to `ci` joins the pre-push run too.
+The audit reaches the network. With no network, `ci` is the gate that still runs.
 
 Neither is bound to a git hook. `prepush` is named for when you run it, not for a hook nmr installs.
 
@@ -461,14 +469,14 @@ Neither is bound to a git hook. `prepush` is named for when you run it, not for
 
 The same six names the workspace registry carries, so a command means the same thing from the monorepo root as from inside a package. Each fans out to root-level files and every workspace package.
 
-| Command         | Runs                                                        |
-| --------------- | ----------------------------------------------------------- |
-| `test`          | `nmr root:test && pnpm --recursive exec nmr test`           |
-| `test:all`      | `nmr root:test:all && pnpm --recursive exec nmr test:all`   |
-| `test:coverage` | `nmr root:test && pnpm --recursive exec nmr test:coverage`  |
-| `test:tool`     | `nmr root:test:tool && pnpm --recursive exec nmr test:tool` |
-| `test:unit`     | `nmr root:test:unit && pnpm --recursive exec nmr test:unit` |
-| `test:watch`    | `vitest --project unit --project tool --watch`              |
+| Command         | Runs                                           |
+| --------------- | ---------------------------------------------- |
+| `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 --project unit --project tool --watch` |
 
 `test:coverage` chains `root:test` rather than a `root:test:coverage`, because the root config reports no coverage of its own; packages cover their own sources.
 
@@ -476,9 +484,9 @@ The same six names the workspace registry carries, so a command means the same t
 
 #### Typecheck
 
-| Command     | Runs                                                        |
-| ----------- | ----------------------------------------------------------- |
-| `typecheck` | `nmr root:typecheck && pnpm --recursive exec nmr typecheck` |
+| Command     | Runs                             |
+| ----------- | -------------------------------- |
+| `typecheck` | `root:typecheck`, `-R typecheck` |
 
 #### Lint
 
@@ -576,7 +584,7 @@ nmr build # Compile to .js and .d.ts in one pass
 # From the monorepo root
 nmr test    # Root tests + recursive workspace tests
 nmr ci      # build + check:strict
-nmr prepush # ci + audit
+nmr prepush # audit + ci
 
 # Target specific packages
 nmr --filter core test # Test only the core package

package/agents/guidance/rulebooks/nmr.md

@@ -9,6 +9,6 @@ delivery: ambient
 - Use `nmr <command>`, not `pnpm run <command>`, for anything nmr provides. Run bare `nmr` to list every command and the shell command it resolves to; a wrong guess reports only `Unknown command`, with no list.
 - Scope follows cwd, and bare `nmr` lists both registries: from the repo root a command covers root files and every workspace; from inside a package, that package alone. `nmr -F <pkg> <command>` targets one package from anywhere; `nmr root:<command>` targets root files alone, which isolates a failure to root code.
 - Never `npx nmr`: inside a git worktree it can resolve a different nmr from outside the tree. Fall back to `pnpm exec nmr`.
-- `nmr ci` runs what a code-quality workflow runs (build, then strict checks) and not the dependency audit, which belongs to a workflow of its own; `nmr prepush` runs both. Neither installs or binds a git hook.
+- `nmr ci` runs what a code-quality workflow runs (build, then strict checks) and not the dependency audit, which belongs to a workflow of its own; `nmr prepush` runs the audit first, then `ci`, so a vulnerability stops the run before the long gate. Neither installs or binds a git hook.
 - A check that already passed on the current working tree skips, printing `⏭️ <command>: passed …`. Any edit, addition, or deletion re-runs it, so a skip is a real pass and needs no confirming: never pass `--no-cache` to get a "real" run, which costs the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`.
 - The rest is in `node_modules/@williamthorsen/nmr/README.md`: pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`), script overrides and their `""`/`":"` skip values, `nmr upgrade` ceilings (report-only until `nmr upgrade --write`), the `nmr-compile` build (there is no repo-local build script), and the check-result cache's key, its `checkCache` config, and every condition that disables it.

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

@@ -46,7 +46,7 @@ export declare function computeCacheKey(options: {
     reason: string;
 };
 export declare function encodeTreeSnapshot(snapshot: TreeSnapshot): string;
-export declare function findStaleBuildOutput(recorded: Record<string, string>, current: Record<string, string>): string | undefined;
+export declare function findStaleBuildOutput(earlier: Record<string, string>, later: Record<string, string>): string | undefined;
 export declare function formatMisplacedNoCacheWarning(command: string): string;
 export declare function formatSkipLine(command: string, entry: CheckCacheEntry, now: number): string;
 export declare function readBuildOutputState(monorepoRoot: string, config: NmrConfig): Promise<BuildOutputState>;

package/dist/esm/check-cache.js

@@ -9,6 +9,7 @@ import { formatDuration, formatSaving } from "./helpers/duration.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
 import { getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { renderChain } from "./steps.js";
 import { getWorkspacePackageDirs } from "./workspace.js";
 export const CURRENT_RUNTIME = {
     arch: process.arch,
@@ -81,9 +82,9 @@ export function computeCacheKey(options) {
 export function encodeTreeSnapshot(snapshot) {
     return `${snapshot.hash} ${snapshot.headSha}`;
 }
-export function findStaleBuildOutput(recorded, current) {
-    const names = [...new Set([...Object.keys(recorded), ...Object.keys(current)])].toSorted();
-    return names.find((name) => recorded[name] !== current[name]);
+export function findStaleBuildOutput(earlier, later) {
+    const names = [...new Set([...Object.keys(earlier), ...Object.keys(later)])].toSorted();
+    return names.find((name) => earlier[name] !== later[name]);
 }
 export function formatMisplacedNoCacheWarning(command) {
     return (`⚠️ --no-cache after the command name is passed to \`${command}\`, not read by nmr. ` +
@@ -196,7 +197,7 @@ function isProbeSubject(packageDir, registry) {
         return false;
     }
     const compile = resolveScript('compile', registry, packageDir, false);
-    return compile !== undefined && compile.command === BUILT_IN_COMPILE;
+    return compile !== undefined && renderChain(compile.steps) === BUILT_IN_COMPILE;
 }
 function resolveEntryPath(options) {
     const anchorDir = path.resolve(options.anchorDir);

package/dist/esm/commands/clean.js

@@ -4,7 +4,8 @@ import { removeCheckCache } from "../check-cache.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
 import { applyDevBin, buildWorkspaceRegistry, resolveScript } from "../resolver.js";
-import { runCommand } from "../runner.js";
+import { resolveChannel, runCommand } from "../runner.js";
+import { renderChain } from "../steps.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 import { resolveBuildCachePath } from "./build-output.js";
 const CLEAN_ICON = '🧹';
@@ -44,15 +45,18 @@ async function sweepWorkspace(monorepoRoot, workspacePackageDirs) {
     const registry = buildWorkspaceRegistry(config);
     for (const packageDir of workspacePackageDirs) {
         const resolved = resolveScript(CLEAN_COMMAND, registry, packageDir, false);
-        if (resolved === undefined || resolved.command === '') {
+        const resolvedCommand = resolved === undefined ? undefined : renderChain(resolved.steps);
+        if (resolvedCommand === undefined || resolvedCommand === '') {
             continue;
         }
-        if (resolved.command === BUILT_IN_CLEAN) {
+        if (resolvedCommand === BUILT_IN_CLEAN) {
             await cleanPackage(packageDir);
             continue;
         }
-        const command = applyDevBin(resolved.command, config.devBin, monorepoRoot);
-        const exitCode = runCommand(command, packageDir);
+        const command = applyDevBin(resolvedCommand, config.devBin, monorepoRoot);
+        const { exitCode } = await runCommand(command, packageDir, {
+            channels: { stderr: resolveChannel(process.stderr, false), stdout: resolveChannel(process.stdout, false) },
+        });
         if (exitCode !== 0) {
             throw new Error(`nmr-clean: \`${command}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
         }

package/dist/esm/config.js

@@ -10,6 +10,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
+import { findUnexpressibleToken } from "./steps.js";
 const CONFIG_FILENAME = 'nmr.config.ts';
 const CONFIG_DIR = '.config';
 const CONFIG_TIERS = {
@@ -45,10 +46,26 @@ function validateScriptField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
         return undefined;
     }
-    if (!isScriptRecord(value[fieldName])) {
+    const scripts = value[fieldName];
+    if (!isScriptRecord(scripts)) {
         throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | string[]>`);
     }
-    return value[fieldName];
+    assertExpressibleElements(scripts, fieldName, configPath);
+    return scripts;
+}
+function assertExpressibleElements(scripts, fieldName, configPath) {
+    for (const [command, script] of Object.entries(scripts)) {
+        if (typeof script === 'string')
+            continue;
+        for (const element of script) {
+            const token = findUnexpressibleToken(element);
+            if (token === undefined)
+                continue;
+            throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
+                `\`${token}\`, which is neither a command name nor an nmr flag. Name it as a script of its own and ` +
+                `reference that name here.`);
+        }
+    }
 }
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');

package/dist/esm/default-scripts.js

@@ -26,7 +26,7 @@ export const rootScripts = {
     audit: ['audit:prod', 'audit:dev'],
     'audit:dev': 'pnpm exec v11y --dev',
     'audit:prod': 'pnpm exec v11y --prod',
-    build: 'pnpm --recursive exec nmr build',
+    build: ['-R build'],
     check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
     'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
     ci: ['build', 'check:strict'],
@@ -38,7 +38,7 @@ export const rootScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
-    prepush: ['ci', 'audit'],
+    prepush: ['audit', 'ci'],
     'report-overrides': 'nmr-report-overrides',
     'root:check': ['root:typecheck', 'fmt:check', 'root:lint:check', 'root:test'],
     'root:lint': "eslint --fix --ignore-pattern 'packages/**' .",
@@ -50,12 +50,12 @@ export const rootScripts = {
     'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
     'root:typecheck': 'tsgo --noEmit',
     'root:upgrade': 'nmr-taze --include-locked',
-    test: 'nmr root:test && pnpm --recursive exec nmr test',
-    'test:all': 'nmr root:test:all && pnpm --recursive exec nmr test:all',
-    'test:coverage': 'nmr root:test && pnpm --recursive exec nmr test:coverage',
-    'test:tool': 'nmr root:test:tool && pnpm --recursive exec nmr test:tool',
-    'test:unit': 'nmr root:test:unit && pnpm --recursive exec nmr test:unit',
+    test: ['root:test', '-R test'],
+    'test:all': ['root:test:all', '-R test:all'],
+    'test:coverage': ['root:test', '-R test:coverage'],
+    'test:tool': ['root:test:tool', '-R test:tool'],
+    'test:unit': ['root:test:unit', '-R test:unit'],
     'test:watch': `vitest ${GATE_PROJECTS} --watch`,
-    typecheck: 'nmr root:typecheck && pnpm --recursive exec nmr typecheck',
+    typecheck: ['root:typecheck', '-R typecheck'],
     upgrade: 'nmr-report-overrides && nmr-taze --include-locked --recursive',
 };

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

@@ -0,0 +1,9 @@
+export interface BoundedBufferOptions {
+    headLimitBytes?: number;
+    tailLimitBytes?: number;
+}
+export interface BoundedBuffer {
+    append: (chunk: Buffer) => void;
+    toBuffer: () => Buffer;
+}
+export declare function createBoundedBuffer(options?: BoundedBufferOptions): BoundedBuffer;

package/dist/esm/helpers/createBoundedBuffer.js

@@ -0,0 +1,60 @@
+const DEFAULT_HEAD_LIMIT_BYTES = 1_048_576;
+const DEFAULT_TAIL_LIMIT_BYTES = 1_048_576;
+export function createBoundedBuffer(options = {}) {
+    const headLimitBytes = options.headLimitBytes ?? DEFAULT_HEAD_LIMIT_BYTES;
+    const tailLimitBytes = options.tailLimitBytes ?? DEFAULT_TAIL_LIMIT_BYTES;
+    const headChunks = [];
+    let headBytes = 0;
+    let tailRing;
+    let tailOffset = 0;
+    let tailBytes = 0;
+    let elidedBytes = 0;
+    function append(chunk) {
+        let remainder = chunk;
+        if (headBytes < headLimitBytes) {
+            const takenBytes = Math.min(headLimitBytes - headBytes, remainder.length);
+            headChunks.push(remainder.subarray(0, takenBytes));
+            headBytes += takenBytes;
+            remainder = remainder.subarray(takenBytes);
+        }
+        if (remainder.length > 0) {
+            appendToTail(remainder);
+        }
+    }
+    function appendToTail(chunk) {
+        const ring = (tailRing ??= Buffer.alloc(tailLimitBytes));
+        if (chunk.length >= tailLimitBytes) {
+            elidedBytes += tailBytes + chunk.length - tailLimitBytes;
+            chunk.copy(ring, 0, chunk.length - tailLimitBytes);
+            tailOffset = 0;
+            tailBytes = tailLimitBytes;
+            return;
+        }
+        elidedBytes += Math.max(0, tailBytes + chunk.length - tailLimitBytes);
+        const untilWrapBytes = Math.min(chunk.length, tailLimitBytes - tailOffset);
+        chunk.copy(ring, tailOffset, 0, untilWrapBytes);
+        if (untilWrapBytes < chunk.length) {
+            chunk.copy(ring, 0, untilWrapBytes);
+        }
+        tailOffset = (tailOffset + chunk.length) % tailLimitBytes;
+        tailBytes = Math.min(tailLimitBytes, tailBytes + chunk.length);
+    }
+    function toBuffer() {
+        const headBuffer = Buffer.concat(headChunks);
+        if (tailRing === undefined) {
+            return headBuffer;
+        }
+        const tailBuffer = tailBytes < tailLimitBytes
+            ? tailRing.subarray(0, tailBytes)
+            : Buffer.concat([tailRing.subarray(tailOffset), tailRing.subarray(0, tailOffset)]);
+        if (elidedBytes === 0) {
+            return Buffer.concat([headBuffer, tailBuffer]);
+        }
+        return Buffer.concat([headBuffer, Buffer.from(formatElisionMarker(elidedBytes)), tailBuffer]);
+    }
+    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/resolver.d.ts

@@ -1,11 +1,13 @@
 import type { ScriptRegistry, ScriptValue } from './resolve-scripts.js';
+import type { Step } from './steps.js';
 import type { NmrConfig } from './types.js';
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
+export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
 export interface ResolvedScript {
-    command: string;
     source: 'default' | 'package';
+    steps: readonly Step[];
 }
-export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): string;
+export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): readonly Step[];
 export declare function describeScript(script: ScriptValue): string;
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
 export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistry;

package/dist/esm/resolver.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { isObject } from "./helpers/type-guards.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { composeNmrStep } from "./steps.js";
 export function applyDevBin(command, devBin, monorepoRoot) {
     if (!devBin) {
         return command;
@@ -16,6 +17,12 @@ export function applyDevBin(command, devBin, monorepoRoot) {
     const resolvedReplacement = resolveReplacementPaths(replacement, monorepoRoot);
     return resolvedReplacement + rest;
 }
+export function applyDevBinToSteps(steps, devBin, monorepoRoot) {
+    if (!devBin) {
+        return steps;
+    }
+    return steps.map((step) => step.kind === 'opaque' ? { kind: 'opaque', command: applyDevBin(step.command, devBin, monorepoRoot) } : step);
+}
 function resolveReplacementPaths(replacement, monorepoRoot) {
     const tokens = replacement.split(' ');
     return tokens
@@ -32,10 +39,9 @@ function resolveReplacementPaths(replacement, monorepoRoot) {
 }
 export function expandScript(script, workspaceRoot) {
     if (typeof script === 'string') {
-        return script;
+        return [{ kind: 'opaque', command: script }];
     }
-    const flag = workspaceRoot ? '-w ' : '';
-    return script.map((s) => `nmr ${flag}${s}`).join(' && ');
+    return script.map((element) => composeNmrStep(element, workspaceRoot));
 }
 export function describeScript(script) {
     return typeof script === 'string' ? script : `[${script.join(', ')}]`;
@@ -85,7 +91,7 @@ export function resolveScript(commandName, registry, packageDir, workspaceRoot)
         if (pkgScripts && Object.hasOwn(pkgScripts, commandName)) {
             const override = pkgScripts[commandName];
             if (override !== undefined && !isSelfReferential(override, commandName)) {
-                return { command: override, source: 'package' };
+                return { source: 'package', steps: [{ kind: 'opaque', command: override }] };
             }
         }
     }
@@ -96,5 +102,5 @@ export function resolveScript(commandName, registry, packageDir, workspaceRoot)
     if (registryEntry === undefined) {
         return undefined;
     }
-    return { command: expandScript(registryEntry, workspaceRoot), source: 'default' };
+    return { source: 'default', steps: expandScript(registryEntry, workspaceRoot) };
 }

package/dist/esm/runCli.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
 export interface RunCliOptions {
     args: string[];
     cwd: string;

package/dist/esm/runCli.js

@@ -4,9 +4,12 @@ import { computeCacheKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOut
 import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
 import { isHookName } from "./helpers/hook-name.js";
-import { applyDevBin, buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
-import { runCommand } from "./runner.js";
+import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { runSteps } from "./runner.js";
+import { composeNmrStep, findShelledNmrStep, renderChain } from "./steps.js";
+import { COMMAND_VERBOSITY_ENV_VAR, resolveVerbosity } from "./verbosity.js";
 const VERSION = readPackageVersion(import.meta.url);
+export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
     const { args, cwd, env, stdout, stderr } = options;
     const parseResult = parseArgs(args);
@@ -15,10 +18,16 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const { parsed } = parseResult;
+    const verbosity = resolveVerbosity(env, parsed.quiet);
+    if (!verbosity.ok) {
+        reportError(verbosity.error, stderr);
+        return { exitCode: 1 };
+    }
     if (parsed.version) {
         stdout.write(`${VERSION}\n`);
         return { exitCode: 0 };
     }
+    const quiet = verbosity.verbosity === 'quiet';
     const context = await resolveContext(cwd);
     const useRoot = parsed.workspaceRoot || context.isRoot;
     const anchorDir = useRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
@@ -27,7 +36,6 @@ export async function runCli(options) {
         return { exitCode: 0 };
     }
     const { command } = parsed;
-    const passthrough = parsed.passthrough.length > 0 ? ' ' + parsed.passthrough.map(shellQuote).join(' ') : '';
     const snapshot = openGate({
         command,
         config: context.config,
@@ -37,38 +45,48 @@ export async function runCli(options) {
         stderr,
     });
     const noCache = parsed.noCache || env[NO_CACHE_ENV_VAR] === '1';
-    const childEnv = buildChildEnv(env, snapshot, noCache);
-    const runOptions = { quiet: parsed.quiet, stdout, stderr, env: childEnv };
+    const childEnv = buildChildEnv(env, snapshot, noCache, verbosity.verbosity);
+    const runOptions = {
+        quiet,
+        stdout,
+        stderr,
+        env: childEnv,
+    };
     if (parsed.filter) {
-        const delegateCmd = `pnpm --filter ${shellQuote(parsed.filter)} exec nmr ${command}${passthrough}`;
-        const exitCode = runCommand(delegateCmd, context.monorepoRoot, runOptions);
-        return { exitCode };
+        const delegate = composeDelegate(['--filter', parsed.filter], command, parsed.passthrough);
+        return runSteps([delegate], context.monorepoRoot, runOptions);
     }
     if (parsed.recursive) {
-        const delegateEnv = { ...childEnv, NMR_RUN_IF_PRESENT: '1' };
-        const delegateCmd = `pnpm --recursive exec nmr ${command}${passthrough}`;
-        const exitCode = runCommand(delegateCmd, context.monorepoRoot, { ...runOptions, env: delegateEnv });
-        return { exitCode };
+        const delegateEnv = { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' };
+        const delegate = composeDelegate(['--recursive'], command, parsed.passthrough);
+        return runSteps([delegate], context.monorepoRoot, { ...runOptions, env: delegateEnv });
     }
     const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
     const resolved = resolveScript(command, registry, anchorDir, parsed.workspaceRoot);
     if (!resolved) {
-        if (env['NMR_RUN_IF_PRESENT'] === '1') {
+        if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
             return { exitCode: 0 };
         }
         reportError(`Unknown command: ${command}`, stderr);
         return { exitCode: 1 };
     }
-    const skipExitCode = handleSkipMessage(resolved.command, anchorDir, parsed.quiet, stdout);
+    const resolvedCommand = renderChain(resolved.steps);
+    const skipExitCode = handleSkipMessage(resolvedCommand, anchorDir, quiet, stdout);
     if (skipExitCode !== undefined) {
         return { exitCode: skipExitCode };
     }
-    const substitutedCommand = applyDevBin(resolved.command, context.config.devBin, context.monorepoRoot);
-    const mainCommand = substitutedCommand + passthrough;
+    const substitutedSteps = applyDevBinToSteps(resolved.steps, context.config.devBin, context.monorepoRoot);
+    const substitutedCommand = renderChain(substitutedSteps);
+    const mainSteps = appendPassthrough(substitutedSteps, parsed.passthrough);
     const isHookInvocation = isHookName(command);
-    const fullCommand = isHookInvocation
-        ? mainCommand
-        : wrapWithHooks(command, mainCommand, registry, anchorDir, parsed.workspaceRoot);
+    const fullSteps = isHookInvocation
+        ? mainSteps
+        : wrapWithHooks(command, mainSteps, registry, anchorDir, parsed.workspaceRoot);
+    const fullCommand = renderChain(fullSteps);
+    const shelledStep = findShelledNmrStep(fullSteps);
+    if (shelledStep !== undefined) {
+        stderr.write(`${formatShelledNmrWarning(command, shelledStep)}\n`);
+    }
     const key = resolveCacheKey({
         anchorDir,
         command,
@@ -77,19 +95,20 @@ export async function runCli(options) {
         monorepoRoot: context.monorepoRoot,
         snapshot,
         stderr,
-        substitution: substitutedCommand === resolved.command ? undefined : substitutedCommand,
+        substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
     const exitCode = await runGated({
         anchorDir,
         command,
         commandString: fullCommand,
         config: context.config,
+        steps: fullSteps,
         env,
         key,
         monorepoRoot: context.monorepoRoot,
         noCache,
-        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, parsed.quiet),
-        quiet: parsed.quiet,
+        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, quiet),
+        quiet,
         runOptions,
         snapshot,
         stderr,
@@ -97,19 +116,37 @@ export async function runCli(options) {
     });
     return { exitCode };
 }
-function buildChildEnv(env, snapshot, noCache) {
+function buildChildEnv(env, snapshot, noCache, verbosity) {
     return {
         ...env,
         ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
         ...(noCache && { [NO_CACHE_ENV_VAR]: '1' }),
+        [COMMAND_VERBOSITY_ENV_VAR]: verbosity,
     };
 }
+function appendPassthrough(steps, passthrough) {
+    const last = steps.at(-1);
+    if (passthrough.length === 0 || last === undefined) {
+        return steps;
+    }
+    const bound = last.kind === 'structural'
+        ? { kind: 'structural', argv: [...last.argv, ...passthrough] }
+        : { kind: 'opaque', command: `${last.command} ${passthrough.map(shellQuote).join(' ')}` };
+    return [...steps.slice(0, -1), bound];
+}
+function composeDelegate(scope, command, passthrough) {
+    return { kind: 'structural', argv: ['pnpm', ...scope, 'exec', 'nmr', command, ...passthrough] };
+}
 function formatOverrideNotice(resolved, registry, command, anchorDir, quiet) {
     const registryEntry = Object.hasOwn(registry, command) ? registry[command] : undefined;
     if (quiet || resolved.source !== 'package' || registryEntry === undefined) {
         return undefined;
     }
-    return `📦 ${path.basename(anchorDir)}: Using override script: ${resolved.command}\n`;
+    return `📦 ${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}\n`;
+}
+function formatShelledNmrWarning(command, step) {
+    return (`⚠️ ${command}: \`${step}\` runs nmr behind a shell, so nmr handles its output as a tool's rather than a ` +
+        `nested run's. A step list in \`.config/nmr.config.ts\` avoids it.`);
 }
 function handleSkipMessage(resolvedCommand, anchorDir, quiet, stdout) {
     if (resolvedCommand === '') {
@@ -130,10 +167,11 @@ function hasRunnableHook(hookName, registry, anchorDir, workspaceRoot) {
     const resolved = resolveScript(hookName, registry, anchorDir, workspaceRoot);
     if (!resolved)
         return false;
-    return resolved.command !== '' && resolved.command !== ':';
+    const chain = renderChain(resolved.steps);
+    return chain !== '' && chain !== ':';
 }
 async function lookUpRecordedPass(options) {
-    const { anchorDir, command, env, key, monorepoRoot, stderr } = options;
+    const { anchorDir, buildOutput, command, env, key, monorepoRoot, stderr } = options;
     const entry = await readCheckCacheEntry({ anchorDir, command, monorepoRoot });
     if (entry === undefined) {
         writeDebugNote(`running ${command}: no pass recorded for this scope`, env, stderr);
@@ -143,13 +181,12 @@ async function lookUpRecordedPass(options) {
         writeDebugNote(`running ${command}: the tree or its inputs changed since the last pass`, env, stderr);
         return undefined;
     }
-    const output = await readBuildOutputState(monorepoRoot, options.config);
-    const [missing] = output.missing;
+    const [missing] = buildOutput.missing;
     if (missing !== undefined) {
         writeDebugNote(`running ${command}: ${missing} has no build output`, env, stderr);
         return undefined;
     }
-    const stale = findStaleBuildOutput(entry.buildDigests, output.digests);
+    const stale = findStaleBuildOutput(entry.buildDigests, buildOutput.digests);
     if (stale !== undefined) {
         writeDebugNote(`running ${command}: ${stale}'s build output came from a different tree`, env, stderr);
         return undefined;
@@ -255,6 +292,11 @@ async function recordPass(options) {
         writeDebugNote(`not recording ${command}: ${missing} has no build output`, env, stderr);
         return;
     }
+    const changed = findStaleBuildOutput(options.buildOutputBefore.digests, output.digests);
+    if (changed !== undefined) {
+        writeDebugNote(`not recording ${command}: ${changed}'s build output changed while it ran`, env, stderr);
+        return;
+    }
     try {
         await writeCheckCacheEntry({
             anchorDir,
@@ -304,14 +346,16 @@ function resolveCacheKey(options) {
 }
 async function runGated(options) {
     const { anchorDir, command, commandString, env, key, monorepoRoot, snapshot, stderr, stdout } = options;
-    const gated = key !== undefined && snapshot !== undefined;
-    if (gated && !options.noCache) {
+    const gate = key !== undefined && snapshot !== undefined
+        ? { buildOutputBefore: await readBuildOutputState(monorepoRoot, options.config), key, snapshot }
+        : undefined;
+    if (gate !== undefined && !options.noCache) {
         const skipLine = await lookUpRecordedPass({
             anchorDir,
+            buildOutput: gate.buildOutputBefore,
             command,
-            config: options.config,
             env,
-            key,
+            key: gate.key,
             monorepoRoot,
             stderr,
         });
@@ -326,18 +370,19 @@ async function runGated(options) {
         stdout.write(options.overrideNotice);
     }
     const startedAt = Date.now();
-    const exitCode = runCommand(commandString, anchorDir, options.runOptions);
-    if (exitCode === 0 && gated) {
+    const { exitCode } = await runSteps(options.steps, anchorDir, options.runOptions);
+    if (exitCode === 0 && gate !== undefined) {
         await recordPass({
             anchorDir,
+            buildOutputBefore: gate.buildOutputBefore,
             command,
             commandString,
             config: options.config,
             durationMs: Date.now() - startedAt,
             env,
-            key,
+            key: gate.key,
             monorepoRoot,
-            snapshot,
+            snapshot: gate.snapshot,
             stderr,
         });
     }
@@ -346,15 +391,14 @@ async function runGated(options) {
 function shellQuote(arg) {
     return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";
 }
-function wrapWithHooks(command, mainCommand, registry, anchorDir, workspaceRoot) {
-    const segments = [];
-    const flag = workspaceRoot ? '-w ' : '';
+function wrapWithHooks(command, mainSteps, registry, anchorDir, workspaceRoot) {
+    const steps = [];
     if (hasRunnableHook(`${command}:pre`, registry, anchorDir, workspaceRoot)) {
-        segments.push(`nmr ${flag}${command}:pre`);
+        steps.push(composeNmrStep(`${command}:pre`, workspaceRoot));
     }
-    segments.push(mainCommand);
+    steps.push(...mainSteps);
     if (hasRunnableHook(`${command}:post`, registry, anchorDir, workspaceRoot)) {
-        segments.push(`nmr ${flag}${command}:post`);
+        steps.push(composeNmrStep(`${command}:post`, workspaceRoot));
     }
-    return segments.join(' && ');
+    return steps;
 }

package/dist/esm/runner.d.ts

@@ -1,8 +1,38 @@
 import type { Writable } from 'node:stream';
+import type { Step } from './steps.js';
+export type OutputChannel = number | 'pipe';
+export interface OutputChannels {
+    stderr: OutputChannel;
+    stdout: OutputChannel;
+}
 export interface RunCommandOptions {
+    channels: OutputChannels;
     quiet?: boolean;
     stdout?: Writable;
     stderr?: Writable;
     env?: NodeJS.ProcessEnv;
 }
-export declare function runCommand(command: string, cwd?: string, options?: RunCommandOptions): number;
+export type RunStepsOptions = Omit<RunCommandOptions, 'channels'>;
+type CommandCompletion = {
+    outcome: 'exited';
+    exitCode: number;
+} | {
+    outcome: 'signaled';
+    exitCode: number;
+    signal: NodeJS.Signals;
+} | {
+    outcome: 'spawn-failed';
+    exitCode: number;
+    error: Error;
+};
+export type RunCommandResult = CommandCompletion & {
+    stdout: Buffer | undefined;
+    stderr: Buffer | undefined;
+};
+export declare function resolveChannel(stream: Writable, quiet: boolean): OutputChannel;
+export declare function resolveInheritedChannel(stream: Writable): OutputChannel;
+export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<{
+    exitCode: number;
+}>;
+export declare function runCommand(command: string, cwd: string | undefined, options: RunCommandOptions): Promise<RunCommandResult>;
+export {};

package/dist/esm/runner.js

@@ -1,41 +1,153 @@
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import os from 'node:os';
 import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
-export function runCommand(command, cwd, options) {
-    const quiet = options?.quiet === true;
-    const stdout = options?.stdout ?? process.stdout;
-    const stderr = options?.stderr ?? process.stderr;
-    const env = options?.env ?? process.env;
-    const stdoutChannel = quiet ? 'pipe' : streamFdOrPipe(stdout);
-    const stderrChannel = quiet ? 'pipe' : streamFdOrPipe(stderr);
-    const result = spawnSync(command, [], {
-        shell: true,
-        stdio: ['inherit', stdoutChannel, stderrChannel],
+import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+const SIGNAL_EXIT_BASE = 128;
+const PIPE_DRAIN_GRACE_MS = 2_000;
+export function resolveChannel(stream, quiet) {
+    if (quiet)
+        return 'pipe';
+    return isTerminal(stream) ? stream.fd : 'pipe';
+}
+export function resolveInheritedChannel(stream) {
+    return hasDescriptor(stream) ? stream.fd : 'pipe';
+}
+export async function runSteps(steps, cwd, options) {
+    const resolved = {
+        ...options,
+        quiet: options.quiet === true,
+        stdout: options.stdout ?? process.stdout,
+        stderr: options.stderr ?? process.stderr,
+    };
+    for (const step of steps) {
+        const { exitCode } = await runStep(step, cwd, resolved);
+        if (exitCode !== 0) {
+            return { exitCode };
+        }
+    }
+    return { exitCode: 0 };
+}
+export async function runCommand(command, cwd, options) {
+    return runSpawned({ args: [], file: command, useShell: true }, cwd, options);
+}
+async function runSpawned({ args, file, useShell }, cwd, options) {
+    const quiet = options.quiet === true;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const env = options.env ?? process.env;
+    const child = spawn(file, args, {
+        shell: useShell,
+        stdio: ['inherit', options.channels.stdout, options.channels.stderr],
         cwd,
         env,
     });
-    if (result.error) {
+    const stdoutCapture = child.stdout === null ? undefined : captureStream(child.stdout, quiet ? undefined : stdout);
+    const stderrCapture = child.stderr === null ? undefined : captureStream(child.stderr, quiet ? undefined : stderr);
+    const completion = await awaitCompletion(child, () => {
+        stdoutCapture?.stopReading();
+        stderrCapture?.stopReading();
+    });
+    stdoutCapture?.detach();
+    stderrCapture?.detach();
+    const result = {
+        ...completion,
+        stdout: stdoutCapture?.toBuffer(),
+        stderr: stderrCapture?.toBuffer(),
+    };
+    if (result.outcome === 'spawn-failed') {
         reportError(result.error.message, stderr);
-        return 1;
+        return result;
     }
-    if (quiet) {
-        if (result.status !== 0) {
-            writeBuffer(result.stdout, stderr);
-            writeBuffer(result.stderr, stderr);
-        }
+    if (quiet && result.exitCode !== 0) {
+        writeBuffer(result.stdout, stderr);
+        writeBuffer(result.stderr, stderr);
+    }
+    return result;
+}
+function runStep(step, cwd, options) {
+    const { quiet, stderr, stdout } = options;
+    if (step.kind === 'opaque') {
+        return runSpawned({ args: [], file: step.command, useShell: true }, cwd, {
+            ...options,
+            channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
+        });
     }
-    else {
-        if (stdoutChannel === 'pipe')
-            writeBuffer(result.stdout, stdout);
-        if (stderrChannel === 'pipe')
-            writeBuffer(result.stderr, stderr);
+    const [file, ...args] = step.argv;
+    return runSpawned({ args, file, useShell: false }, cwd, {
+        ...options,
+        quiet: false,
+        channels: { stderr: resolveInheritedChannel(stderr), stdout: resolveInheritedChannel(stdout) },
+    });
+}
+function captureStream(source, destination) {
+    const retained = createBoundedBuffer();
+    let isComplete = true;
+    function stopReading() {
+        if (destination !== undefined)
+            source.unpipe(destination);
+        source.destroy();
+    }
+    function abandon() {
+        isComplete = false;
+        stopReading();
+    }
+    source.on('error', abandon);
+    if (destination !== undefined) {
+        destination.on('error', abandon);
+        source.pipe(destination, { end: false });
+    }
+    source.on('data', (chunk) => retained.append(chunk));
+    return {
+        toBuffer: () => (isComplete ? retained.toBuffer() : undefined),
+        detach: () => {
+            destination?.off('error', abandon);
+        },
+        stopReading,
+    };
+}
+function awaitCompletion(child, stopReading) {
+    return new Promise((resolve) => {
+        let exitCompletion;
+        let graceTimer;
+        let isSettled = false;
+        function settle(completion) {
+            if (isSettled)
+                return;
+            isSettled = true;
+            if (graceTimer !== undefined)
+                clearTimeout(graceTimer);
+            resolve(completion);
+        }
+        child.on('error', (error) => {
+            settle({ outcome: 'spawn-failed', exitCode: 1, error });
+        });
+        child.on('exit', (code, signal) => {
+            const completion = describeExit(code, signal);
+            exitCompletion = completion;
+            graceTimer = setTimeout(() => {
+                stopReading();
+                settle(completion);
+            }, PIPE_DRAIN_GRACE_MS);
+        });
+        child.on('close', () => {
+            settle(exitCompletion ?? { outcome: 'exited', exitCode: 1 });
+        });
+    });
+}
+function describeExit(code, signal) {
+    if (signal !== null) {
+        return { outcome: 'signaled', exitCode: SIGNAL_EXIT_BASE + os.constants.signals[signal], signal };
     }
-    return result.status ?? 1;
+    return { outcome: 'exited', exitCode: code ?? 1 };
+}
+function hasDescriptor(stream) {
+    return 'fd' in stream && typeof stream.fd === 'number';
 }
-function streamFdOrPipe(stream) {
-    return 'fd' in stream && typeof stream.fd === 'number' ? stream.fd : 'pipe';
+function isTerminal(stream) {
+    return 'isTTY' in stream && stream.isTTY === true && hasDescriptor(stream);
 }
-function writeBuffer(buffer, dest) {
-    if (buffer.length > 0)
-        dest.write(buffer);
+function writeBuffer(buffer, destination) {
+    if (buffer !== undefined && buffer.length > 0)
+        destination.write(buffer);
 }

package/dist/esm/steps.d.ts

@@ -0,0 +1,11 @@
+export type Step = {
+    kind: 'opaque';
+    command: string;
+} | {
+    kind: 'structural';
+    argv: readonly [string, ...(readonly string[])];
+};
+export declare function composeNmrStep(element: string, workspaceRoot: boolean): Step;
+export declare function findShelledNmrStep(steps: readonly Step[]): string | undefined;
+export declare function findUnexpressibleToken(element: string): string | undefined;
+export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/steps.js

@@ -0,0 +1,31 @@
+const SHELL_SAFE_TOKEN = /^[\w@%+=:,./-]+$/;
+export function composeNmrStep(element, workspaceRoot) {
+    const flags = workspaceRoot ? ['-w'] : [];
+    return { kind: 'structural', argv: ['nmr', ...flags, ...tokenize(element)] };
+}
+export function findShelledNmrStep(steps) {
+    for (const step of steps) {
+        if (step.kind === 'opaque' && tokenize(step.command)[0] === 'nmr') {
+            return step.command;
+        }
+    }
+    return undefined;
+}
+export function findUnexpressibleToken(element) {
+    return tokenize(element).find((token) => !SHELL_SAFE_TOKEN.test(token));
+}
+export function renderChain(steps) {
+    return steps.map(renderStep).join(' && ');
+}
+function quoteToken(token) {
+    if (SHELL_SAFE_TOKEN.test(token)) {
+        return token;
+    }
+    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
+}
+function renderStep(step) {
+    return step.kind === 'opaque' ? step.command : step.argv.map(quoteToken).join(' ');
+}
+function tokenize(element) {
+    return element.split(/\s+/).filter((token) => token.length > 0);
+}

package/dist/esm/verbosity.d.ts

@@ -0,0 +1,11 @@
+export declare const COMMAND_VERBOSITY_ENV_VAR = "NMR_COMMAND_VERBOSITY";
+export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
+export type CommandVerbosity = (typeof COMMAND_VERBOSITIES)[number];
+export type VerbosityResolution = {
+    ok: true;
+    verbosity: CommandVerbosity;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveVerbosity(env: NodeJS.ProcessEnv, quietFlag: boolean): VerbosityResolution;

package/dist/esm/verbosity.js

@@ -0,0 +1,17 @@
+export const COMMAND_VERBOSITY_ENV_VAR = 'NMR_COMMAND_VERBOSITY';
+export const COMMAND_VERBOSITIES = ['full', 'quiet'];
+export function resolveVerbosity(env, quietFlag) {
+    const raw = env[COMMAND_VERBOSITY_ENV_VAR];
+    const inherited = raw === undefined || raw === '' ? 'full' : raw;
+    if (!isCommandVerbosity(inherited)) {
+        return {
+            ok: false,
+            error: `${COMMAND_VERBOSITY_ENV_VAR} is \`${inherited}\`, which is not one of: ${COMMAND_VERBOSITIES.join(', ')}`,
+        };
+    }
+    return { ok: true, verbosity: quietFlag ? 'quiet' : inherited };
+}
+function isCommandVerbosity(value) {
+    const names = COMMAND_VERBOSITIES;
+    return names.includes(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -66,13 +66,13 @@
   "dependencies": {
     "glob": "13.0.6",
     "prettier-plugin-sh": "0.19.0",
-    "taze": "19.16.0",
+    "taze": "19.17.1",
     "yaml": "2.9.0",
     "@williamthorsen/nmr-core": "0.9.3"
   },
   "devDependencies": {
     "prettier": "3.9.6",
-    "readyup": "0.24.0",
+    "readyup": "0.26.0",
     "tinyglobby": "0.2.17",
     "vitest": "4.1.10"
   },