@williamthorsen/nmr 0.29.0 → 0.30.0

package/.readyup/kits/default.js

@@ -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.
@@ -74,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"
 };
@@ -376,7 +376,7 @@ function formatPaths(paths) {
 ${paths.map((path2) => `      ${path2}`).join("\n")}`;
 }
 function getMinVersion() {
-  const picked = { "version": "0.29.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

@@ -10,7 +10,7 @@
       "readyupVersion": "0.26.0",
       "source": "kits/default.ts",
       "sourceHash": "7b2a223f",
-      "targetHash": "26c3d9eb"
+      "targetHash": "bdca19db"
     }
   ]
 }

package/README.md

@@ -3,23 +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.29.0 (2026-08-09)
+## Release notes — v0.30.0 (2026-08-10)
 
 ### 🎉 Features
 
-- Run the dependency audit before ci in prepush (#634)
+- 🚨 **Breaking:** Resolve a command to a step list and reject a script element carrying shell syntax (#648)
 
-  `nmr prepush` now runs the dependency audit before the code-quality gate, so a vulnerability surfaces within seconds instead of after a full build-and-check pass. A failing audit now stops the run before the code-quality gate.
+  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.
 
-### 🐛 Bug fixes
+- 🚨 **Breaking:** Sequence a command's steps in nmr rather than in a shell (#649)
 
-- Record no pass when build output changes while a check runs (#641)
+  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.
 
-  Fixes an issue where rebuilding a package in one terminal while `nmr prepush` ran in another could mark a check as passed against build output it never saw, causing a later run on the same tree to skip it. Because `nmr ci` builds during its own run, it now needs one further run before it can skip, and that run repeats only the build phase.
+  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.
 
-- Stream command output so a large writer is no longer killed (#642)
+- 🚨 **Breaking:** Express the seven root defaults as steps (#650)
 
-  Fixes an issue where a command that wrote more than a mebibyte of output under `nmr -q` was cut off and reported as failed while the tool itself kept running. When `nmr`'s output is piped or redirected to a file, a command's output now appears as it is produced instead of arriving all at once when the command exits. Piping `nmr` into a reader that stops early, such as `head`, now ends the run cleanly. A command killed by a signal now reports 128 plus the signal number rather than a bare 1.
+  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.
+
+  `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
@@ -67,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.
 
@@ -116,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
 
@@ -186,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:
 
@@ -315,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
@@ -427,12 +439,12 @@ 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` | `audit`, `ci`                     |
+| 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.
 
@@ -457,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.
 
@@ -472,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
 

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,
@@ -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 } = await 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'],
@@ -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/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 } = await 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 } = await 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,7 +167,8 @@ 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, buildOutput, command, env, key, monorepoRoot, stderr } = options;
@@ -332,7 +370,7 @@ async function runGated(options) {
         stdout.write(options.overrideNotice);
     }
     const startedAt = Date.now();
-    const { exitCode } = await runCommand(commandString, anchorDir, options.runOptions);
+    const { exitCode } = await runSteps(options.steps, anchorDir, options.runOptions);
     if (exitCode === 0 && gate !== undefined) {
         await recordPass({
             anchorDir,
@@ -353,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,10 +1,18 @@
 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 type RunStepsOptions = Omit<RunCommandOptions, 'channels'>;
 type CommandCompletion = {
     outcome: 'exited';
     exitCode: number;
@@ -21,5 +29,10 @@ export type RunCommandResult = CommandCompletion & {
     stdout: Buffer | undefined;
     stderr: Buffer | undefined;
 };
-export declare function runCommand(command: string, cwd?: string, options?: RunCommandOptions): Promise<RunCommandResult>;
+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

@@ -5,14 +5,40 @@ import { reportError } from '@williamthorsen/nmr-core';
 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) {
-    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(command, [], {
-        shell: true,
-        stdio: ['inherit', resolveChannel(stdout, quiet), resolveChannel(stderr, quiet)],
+    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,
     });
@@ -39,6 +65,21 @@ export async function runCommand(command, cwd, options) {
     }
     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) },
+        });
+    }
+    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;
@@ -100,13 +141,11 @@ function describeExit(code, signal) {
     }
     return { outcome: 'exited', exitCode: code ?? 1 };
 }
-function resolveChannel(stream, quiet) {
-    if (quiet)
-        return 'pipe';
-    return isTerminal(stream) ? stream.fd : 'pipe';
+function hasDescriptor(stream) {
+    return 'fd' in stream && typeof stream.fd === 'number';
 }
 function isTerminal(stream) {
-    return 'isTTY' in stream && stream.isTTY === true && 'fd' in stream && typeof stream.fd === 'number';
+    return 'isTTY' in stream && stream.isTTY === true && hasDescriptor(stream);
 }
 function writeBuffer(buffer, destination) {
     if (buffer !== undefined && buffer.length > 0)

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.29.0",
+  "version": "0.30.0",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -66,7 +66,7 @@
   "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"
   },