@williamthorsen/nmr 0.31.0 → 0.32.1

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat — @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.27.0";
+export const __readyupVersion = "0.29.0";
 
 
 // .readyup/kits/default.ts
@@ -179,6 +179,13 @@ var default_default = defineRdyKit({
           check: toolVersionsHasNoPnpm,
           fix: "Remove pnpm from .tool-versions \u2014 manage via packageManager field and corepack"
         },
+        {
+          name: "no package.json declares a pnpm field",
+          severity: "error",
+          quiet: true,
+          check: () => noPnpmFieldInPackageJson(),
+          fix: "Move these settings into pnpm-workspace.yaml, quoting each version under `overrides`, or run `pnpx codemod run pnpm-v10-to-v11`. pnpm 11 reads no key from the `pnpm` field, so an override left there pins nothing while an upgrade run with `--write` goes on rewriting it"
+        },
         {
           name: ".config/nmr.config.ts uses defineConfig",
           severity: "recommend",
@@ -387,7 +394,7 @@ function formatPaths(paths) {
 ${paths.map((path2) => `      ${path2}`).join("\n")}`;
 }
 function getMinVersion() {
-  const picked = { "version": "0.31.0" };
+  const picked = { "version": "0.32.1" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }
@@ -413,6 +420,15 @@ function isReExportOnly(content) {
   const statements = content.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "").split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
   return statements.length > 0 && statements.every((line) => RE_EXPORT_LINE_PATTERN.test(line));
 }
+function noPnpmFieldInPackageJson(cwd = process.cwd()) {
+  const declaring = findFiles(["**/package.json"], cwd).flatMap((relativePath) => {
+    const keys = readPnpmFieldKeys(readFileIn(cwd, relativePath));
+    if (keys === void 0) return [];
+    return [keys.length > 0 ? `${relativePath} (${keys.join(", ")})` : relativePath];
+  });
+  if (declaring.length === 0) return true;
+  return { ok: false, detail: formatPaths(declaring) };
+}
 function noReExportOnlyVitestConfigs(cwd = process.cwd()) {
   const nonRootConfigs = findFiles([`**/vitest.config.${CONFIG_EXTENSIONS}`], cwd).filter((path2) => path2.includes("/"));
   const reExports = nonRootConfigs.filter((path2) => isReExportOnly(readFileIn(cwd, path2)));
@@ -464,6 +480,18 @@ function readFileIn(cwd, relativePath) {
     return void 0;
   }
 }
+function readPnpmFieldKeys(content) {
+  if (content === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return void 0;
+  }
+  if (!isRecord(parsed)) return void 0;
+  const pnpm = parsed["pnpm"];
+  return isRecord(pnpm) ? Object.keys(pnpm).toSorted() : void 0;
+}
 function resolvesVersionViaWorkspace(range) {
   return WORKSPACE_VERSION_MARKERS.some((marker) => range.startsWith(marker));
 }
@@ -483,6 +511,7 @@ export {
   everyTestFileNamesItsTier,
   hasSupportedEslintVersion,
   hasSupportedStrictLintVersion,
+  noPnpmFieldInPackageJson,
   noReExportOnlyVitestConfigs,
   noRetiredVitestConfigs,
   prettierConfigBuildsOnSharedConfig,

package/.readyup/manifest.json

@@ -5,12 +5,43 @@
       "checklists": [
         "nmr"
       ],
+      "esbuildVersion": "0.28.1",
+      "inputs": [
+        {
+          "hash": "67afdcb4",
+          "kind": "module",
+          "path": "kits/default.ts"
+        },
+        {
+          "hash": "01e1f853",
+          "kind": "inline",
+          "path": "../package.json",
+          "paths": [
+            "version"
+          ]
+        },
+        {
+          "hash": "3dfc2ee7",
+          "kind": "module",
+          "path": "../src/default-scripts.ts"
+        },
+        {
+          "hash": "b42c7523",
+          "kind": "module",
+          "path": "../src/resolve-scripts.ts"
+        },
+        {
+          "hash": "c2d21075",
+          "kind": "module",
+          "path": "../src/tiers.ts"
+        }
+      ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.27.0",
+      "readyupVersion": "0.29.0",
       "source": "kits/default.ts",
-      "sourceHash": "7b2a223f",
-      "targetHash": "aaf561e4"
+      "sourceHash": "67afdcb4",
+      "targetHash": "1fad8728"
     }
   ]
 }

package/README.md

@@ -3,69 +3,15 @@
 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.31.0 (2026-08-13)
-
-### 🎉 Features
-
-- Report a verdict for every command nmr runs (#659)
-
-  `nmr` now reports one line for every command it runs, naming the scope, command, outcome, and timing. The lines print in every verbosity, which makes `-q` the low-noise way to run rather than a silent one: a passing quiet run reports its verdicts and nothing else, so a pass, a cached skip, and a no-op override stay distinguishable.
-
-  Verdicts nest. A composite reports alongside every command it expands into, while a `:pre`/`:post` hook leaf and a `--filter`/`--recursive` delegate report nothing, since each is already covered by the levels around it.
-
-- Resolve a run's verbosity from repo config and agent-harness detection (#660)
-
-  A verbosity preference for `nmr` can now be set in the repo's root config, and `nmr` now automatically switches to quiet mode when it detects a known agent harness. This makes four ways to set verbosity: the `-q` option, the `NMR_COMMAND_VERBOSITY` env var, config, and harness detection, consulted in that order and defaulting to `full` when none applies.
-
-- 🚨 **Breaking:** Refine nmr upgrade to support catalogs (#661)
-
-  Adds `nmr-report-catalog`, which names the dependencies a package takes from a pnpm catalog, their `catalog:` specifiers, and the monorepo root a covering pass runs from. The workspace `upgrade` default chains it ahead of the upgrade tool, and `nmr report-catalog` runs it alone. Because taze reads `pnpm-workspace.yaml` only when that file sits at its working directory, changes to the catalog are not attempted during a package-scoped upgrade.
-
-  Separately, `nmr-report-overrides` now reports the `overrides` block in `pnpm-workspace.yaml` and fails on a `pnpm.overrides` block in the root `package.json`. Both `upgrade` and `root:upgrade` run the reporter ahead of taze. This avoids a scenario where taze would meaninglessly write to the latter block.
-
-  Migration: Move the block to `overrides` in `pnpm-workspace.yaml`, quoting each version, or run `pnpx codemod run pnpm-v10-to-v11`. `engines` declares `pnpm: ">=11"`.
-
-- Replay an excerpt of the run a skip recalls (#667)
-
-  `nmr` can now show the result of the previous check when a check is skipped. When `nmr` runs a command, it stores the result, keyed by presentation environment. The result is deemed to be the last blank-line-delimited block written by the command. If the command is run again in the same presentation environment, the stored result is shown, labeled "replayed:" for clarity.
-
-- Assemble a skipped composite's replay from its constituents' excerpts (#668)
-
-  A skipped composite now replays what its constituents recorded, with each line attributed to the scope and command that produced it:
-
-  ```console
-  ⏭️ nmr: check: passed 35.7s ago on this tree, saved ~10s — replayed: nmr: fmt:check: All matched files use Prettier code style!; nmr: test: Test Files 52 passed (52) Tests 987 passed (987)
-  ```
-
-  Nesting collapses. A constituent that fans out across packages contributes a line from every package that recorded one; a constituent that recorded nothing is omitted.
-
-  A new reserved variable, `NMR_RUN_ID`, carries a run's identity to every process below it. Every recorded excerpt names the run that last certified it. A composite summary includes saved results with the same status as a fresh result.
-
-- Print a retained run with nmr --log (#669)
-
-  Adds `nmr --log <command>`, which prints what the last recorded pass wrote instead of running the command again. The whole transcript, up to a limit of 256 KiB, is now saved for any passing command that is not writing straight to a terminal; `--log` prints it under a header giving the instant, the duration, and the command chain that succeeded. The log of a composite is the sum of its constituents' excerpts. If a change disqualifies the recording, `--log` instead reports the change.
-
-- Emit one JSON object per command for machine consumers (#672)
-
-  Adds `--json` to `nmr`, allowing the caller to request output in JSON format instead of prose. An env var carries the choice of `json` or `text` down a spawned chain. When the output is JSON, the consumer receives one JSON object per command; each object carries the command, scope, and outcome, and a recalled pass carries the recorded excerpts.
-
-  The mode implies quiet. Stdout carries the objects alone (with no prose verdict line and no override notice); a failing command still displays its output on stderr.
-
-- 🚨 **Breaking:** Bind trailing arguments to every step that accepts them (#675)
-
-  Routes an argument passed to an `nmr` command to every step of that command that accepts it, in place of the last step alone. Thus, `nmr test <file>` therefore runs only that file's tests; previously, the root suite ran in full alongside the narrowed package runs. Steps by default accept passed arguments, but can be configured to ignore them. If no step of a command accepts the argument, `nmr` names the command and runs nothing.
-
-  A command carrying an argument also reads the check-result cache nowhere in its chain, so it no longer skips part of its work from a pass recorded for an unnarrowed run.
-
-  Migration: Existing configs need no change, since a bare string element keeps its present meaning. Two behaviors differ: A composite passes its arguments to every accepting step rather than to its final step alone; and `nmr typecheck <file>` at the repo root is refused, where it previously checked that file under default compiler options at the root and hunted for it in every package.
+## Release notes — v0.32.1 (2026-08-18)
 
 ### 🐛 Bug fixes
 
-- Derive the shelled-nmr remedy from the declaration site and reject a malformed package.json (#658)
+- Reject a `package.json` entry that chains steps onto a self-reference (#707)
 
-  Fixes a shelled-nmr warning that named `.config/nmr.config.ts` as the remedy for every step it reported, including the `package.json` entries that tier cannot resolve. The line now names the relevant declaration and remedy. Shelled nmr can now be detected not only in a step's first token but anywhere in the step.
-  
-  Separately, a configuration mistake now reports as a plain message rather than a Node stack trace.
+  Fixes an issue where a `package.json` script re-invoking its own command alongside other steps (such as `"build": "nmr build && rdy compile"`) silently lost those steps: nmr discarded the entry and ran its own `build` in its place, so `rdy compile` never ran. nmr now refuses to run the entry and reports the error.
+
+  Separately, fixes an issue where the same chain written the other way round (e.g., `"build": "rdy compile && nmr build"`) was honored as an ordinary override, causing infinite recursion.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -153,6 +99,10 @@ If no per-package override exists, the highest-tier value that is set wins. Set
 
 > **Tip:** If your repo uses `eslint-plugin-package-json/valid-scripts`, empty strings are flagged as invalid. Use `":"` (the POSIX null command) instead — nmr treats it as a regular override that exits successfully and does nothing.
 
+A `package.json` entry that re-invokes the command it is declared under is never honored. Honoring `"build": "nmr build"` would spawn a shell running `nmr build` in the same directory, reaching the same entry again without bound, so nmr discards the entry and resolves the command from the tier below. An entry that carries only the self-reference, trailing arguments included, is discarded in silence: it declares no step to lose. An entry that chains anything else onto it — `"build": "nmr build && rdy compile"`, or `"build": "rdy compile && nmr build"` — would lose those steps, so nmr rejects the invocation instead, naming the file, the key, and where the steps belong. For an ordinary command that is a `<command>:pre` or `<command>:post` script: `"build:pre": "rdy verify"` and `"build:post": "rdy compile"` wrap nmr's own `build` rather than replacing it. For a hook entry it is the entry itself, since nmr wraps a `:pre` or `:post` script in no hooks of its own — `"build:post": "nmr build:post && rdy compile"` becomes `"build:post": "rdy compile"`.
+
+The re-invocation is recognized wherever it stands in the entry, on the grammar [the shelled-nmr line](#script-values) uses, and a segment carrying `-F` or `-R` is not one — it hands the command to other scopes rather than back to this one. Nor is `-w` from inside a package, which reaches the root's registry and the root's `package.json`. A filter that selects the declaring package is the hole in that exemption: `nmr -F own-pkg build` in `own-pkg`'s own `build` re-enters without bound, and nmr does not recognize it.
+
 ### Script values
 
 A script value is a string or an array of steps. Only the built-in defaults and `.config/nmr.config.ts` carry an array; a `package.json` script must be a string, and any other value is rejected when the scripts are read. Arrays expand to chained `nmr` sub-invocations:
@@ -183,9 +133,11 @@ An invocation carrying trailing arguments also serves no part of its work from t
 
 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 reaching nmr through a shell.
 
-The line names the declaration it is an edit to — the file, the field, and the key — and its remedy follows from that site. A `.config/nmr.config.ts` entry keeps its nmr steps as a step list and moves anything else to a `<command>:pre` or `<command>:post` script: a step-list element is composed into `nmr <element>`, so it can name only an nmr command. A `package.json` entry has to go, since `package.json` holds no step list: delete it outright when it restates what nmr already runs for that command, and move the steps it adds to a `<command>:pre` or `<command>:post` script when they are the package's own. Where the registry defines no such command, both apply: name the command in `.config/nmr.config.ts`, and put the package-specific steps in a hook. The pair is named rather than `:post` alone because an entry's extra steps may run on either side of the chain: `rdy verify && nmr compile` puts them first.
+The line names the declaration it is an edit to — the file, the field, and the key — and its remedy follows from that site. A `.config/nmr.config.ts` entry keeps its nmr steps as a step list and moves anything else to a `<command>:pre` or `<command>:post` script: a step-list element is composed into `nmr <element>`, so it can name only an nmr command. A `package.json` entry has to go, since `package.json` holds no step list: delete it outright when it restates what nmr already runs for that command, and move the steps it adds to a `<command>:pre` or `<command>:post` script when they are the package's own. Where the registry defines no such command, both apply: name the command in `.config/nmr.config.ts`, and put the package-specific steps in a hook. The pair is named rather than `:post` alone because an entry's extra steps may run on either side of the chain: `rdy verify && nmr compile` puts them first. A hook is the exception at both tiers: nmr wraps a `:pre` or `:post` script in no hooks of its own, so a hook's other steps become a script of their own that the step list names.
+
+nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, `|`, or a newline, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. This line reports a boundary rather than enforcing a rule — it covers a step nmr runs as written, and only the reporting of the nested run is degraded — and it stays partial in stated ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), a launcher outside that set goes unreported, and a `devBin` substitution that introduces `nmr` itself is not reported, the line being an edit to a declaration rather than to a substitution.
 
-nmr recognizes `nmr` in command position: at the start of a step, after an unquoted `&&`, `||`, `;`, or `|`, and behind `npx`, `bunx`, or an `exec`, `dlx`, or `x` subcommand of `npm`, `pnpm`, `yarn`, or `bun`. The line reports a boundary rather than enforcing a rule, and it stays partial in stated ways: a value-taking flag standing immediately before the program name hides it (`npx -p foo nmr`), a launcher outside that set goes unreported, and a `devBin` substitution that introduces `nmr` itself is not reported, the line being an edit to a declaration rather than to a substitution.
+A [self-referential `package.json` entry](#three-tier-override-system) is the shape nmr cannot run as written, and it is rejected rather than reported. The same recognition finds it, so the same residuals apply — what goes unrecognized there re-enters nmr without bound, which hangs rather than passing quietly.
 
 ## Configuration
 
@@ -883,7 +835,7 @@ nmr-clean
 
 ### `nmr-compile`
 
-Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. An aliased import whose target resolves outside the package's `src/` and is not resolvable without the alias mapping fails the build with a diagnostic, rather than being emitted verbatim to produce output that fails at runtime. The build is skipped when no input has changed and the previous output is still on disk (a content-and-path hash is cached under `node_modules/.cache/nmr-compile/`, outside the published output). Deleting the output by any means — `nmr clean`, `rm -rf dist`, `git clean` — therefore forces a rebuild rather than a skip. This is the default `compile` script — run it from a package directory.
+Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. An aliased import whose target resolves outside the package's `src/` and is not resolvable without the alias mapping fails the build with a diagnostic, rather than being emitted verbatim to produce output that fails at runtime. The build is skipped when no input has changed and the previous output is still on disk (the key is cached under `node_modules/.cache/nmr-compile/`, outside the published output). Deleting the output by any means — `nmr clean`, `rm -rf dist`, `git clean` — therefore forces a rebuild rather than a skip. This is the default `compile` script — run it from a package directory.
 
 **What it compiles.** Entry points are `src/**/*.ts` less the directories that hold test scaffolding rather than shipped code: `__fixtures__/`, `__mocks__/`, `__tests__/`, and `test-utils/`. Add to that list per package with [`build.extraIgnorePatterns`](#package-level-configuration). Ignoring a directory drops it as an _entry point_, not from the emit: the compiler still emits whatever the surviving entry points import, so a helper that production code uses is still compiled and its importer never emits a dangling specifier. This list is deliberately not the Vitest [coverage exclusions](#what-the-config-excludes) — helpers live in `test-utils/` precisely so they stay covered.
 
@@ -891,6 +843,8 @@ Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler
 
 **The replacement is atomic.** The emit is buffered in memory, written to a staging directory beside the output directory, and swapped into place by rename. A build that fails for any reason -- a malformed tsconfig, an unresolvable alias, a full disk -- therefore leaves the previous output exactly as it was. `dist/esm` is never observed mid-write: it holds the previous build or the new one, and is absent only between the two renames. This matters most when the package being rebuilt supplies a binary that other packages in the same recursive build invoke.
 
+**What busts the cache.** The key folds each input's content and path, the emit options, the resolved TypeScript version, and a fingerprint of the nmr running the build -- its own build digest in a workspace checkout, its package version otherwise. Upgrading nmr in a consuming repo therefore rebuilds every package nmr compiles, and an edit to nmr's own build sources rebuilds each sibling once nmr itself has been rebuilt. A build of nmr's own package folds the version rather than the digest, which is the cache entry that build is about to write.
+
 `typescript` is a peer dependency (`>=5.7.0 <7`); the consuming repo provides it. The floor is what `rewriteRelativeImportExtensions` requires; the ceiling is because TypeScript 7 ships no compiler API — its root export is a version constant, so `nmr-compile` cannot run on it. Relative imports in source must carry explicit `.ts` extensions for them to be rewritten.
 
 ```bash
@@ -940,7 +894,7 @@ ensure-prepublish-hooks
 
 ## Conformance checks
 
-nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, and the [test-tier convention](#test-tiers). The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade.
+nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the [test-tier convention](#test-tiers), and that no `package.json` in the tree declares a `pnpm` field, which pnpm 11 reads no key from. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves them. The kit ships inside the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr reaches the repo on upgrade.
 
 Add `readyup` as a devDependency, then name nmr in its config:
 

package/agents/guidance/rulebooks/nmr.md

@@ -13,4 +13,5 @@ delivery: ambient
 - A check that already passed on the current working tree skips, printing `⏭️ <scope>: <command>: passed …` and, where the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it, so read the replayed excerpt rather than paying for the answer again: 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`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling where there are too many to fit. A skip carrying no excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
 - `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it -- so output you need in full is a recording to read rather than a run to pay for again. It runs nothing, and it is held to the tree rather than to the terminal: a recording a piped run made prints for a reader at one. A composite prints its constituents' excerpts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. Nothing to show is said on one line and exits non-zero, naming which it is.
 - Every command nmr runs reports one line -- `✅ <scope>: <command>: passed in 12.4s`, `❌ … failed in 1.2s (exit 1)`, `⏭️ … passed 4m ago on this tree`, or `⛔ … skipped, the override is empty` -- and a composite reports alongside every command it expands into. The lines print in every verbosity, so `-q` is the low-noise way to run rather than a silent one: it withholds the output of the commands nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. Expect a run to be quiet already without the flag: nmr recognizes a known agent harness in the environment and takes quiet from that, as it does from `NMR_COMMAND_VERBOSITY` or the repo's `output.commandVerbosity`. A command whose output you need in full is one to run with `NMR_COMMAND_VERBOSITY=full`, which outranks both.
-- 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, the retention key a replayed excerpt is additionally held to, the retention ceiling `--log` prints within, its `checkCache` config, and every condition that disables it.
+- Every test file lives under a `__tests__` directory and names its isolation tier last: `<subject>[.<aspect>].<tier>.test.ts`, where any earlier segment is free-form documentation. A tier is the furthest thing the test reaches -- `tool` (a program the environment supplies), `localhost` (a service on this machine), `remote` (a machine that isn't this one), or `unit`, the residual claiming everything else. Neither a file outside `__tests__` nor one whose tier segment is missing or misspelt fails anything: the first is collected by nothing and the second runs under `unit`, and no test run distinguishes either from a conformant file. `rdy run --packages` reports the misspelt tier, and nothing reports the misplaced file.
+- 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), the test tiers' timeout budgets and the `tiers` seam that raises one, which script reaches which tier, and the check-result cache's key, the retention key a replayed excerpt is additionally held to, the retention ceiling `--log` prints within, its `checkCache` config, and every condition that disables it.

package/dist/esm/cli-ensure-prepublish-hooks.js

@@ -1,6 +1,6 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { DEFAULT_HOOK, ensurePrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
+import { DEFAULT_HOOK, ensurePrepublishHooks, reportPrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
 import { findMonorepoRoot } from "./workspace.js";
 const flagSchema = {
     fix: { long: '--fix', type: 'boolean' },
@@ -10,31 +10,10 @@ const flagSchema = {
 const { fix, dryRun, command } = parseArgsOrExit(process.argv.slice(2), flagSchema).flags;
 try {
     const monorepoRoot = findMonorepoRoot();
-    const hookCommand = command ?? DEFAULT_HOOK;
     const options = command ? { fix, dryRun, command } : { fix, dryRun };
     const result = ensurePrepublishHooks(monorepoRoot, options);
-    for (const pkg of result.packages) {
-        if (pkg.isPrivate) {
-            continue;
-        }
-        switch (pkg.action) {
-            case 'ok':
-                console.info(`✓ ${pkg.packageName}: prepublishOnly = "${pkg.prepublishOnly}"`);
-                break;
-            case 'missing':
-                console.warn(`✗ ${pkg.packageName}: missing prepublishOnly`);
-                break;
-            case 'fixed':
-                console.info(`✓ ${pkg.packageName}: added prepublishOnly = "${hookCommand}"`);
-                break;
-            case 'would-fix':
-                console.info(`~ ${pkg.packageName}: would add prepublishOnly = "${hookCommand}"`);
-                break;
-        }
-    }
+    reportPrepublishHooks(result, command ?? DEFAULT_HOOK);
     if (result.hasFailures) {
-        const missing = result.packages.filter((p) => p.action === 'missing').length;
-        process.stderr.write(`\n${missing} package(s) missing prepublishOnly. Use --fix to add it.\n`);
         process.exitCode = 1;
     }
 }

package/dist/esm/commands/build-output.d.ts

@@ -16,3 +16,4 @@ export declare function hasExpectedBuildOutput(packageDir: string, outdir: strin
 export declare function readBuildDigest(packageDir: string): Promise<string | undefined>;
 export declare function resolveBuildCachePath(packageDir: string): string;
 export declare function resolveScratchDirs(emitDir: string): ScratchDirs;
+export declare function resolveToolchainFingerprint(packageDir: string, selfDir?: string): Promise<string>;

package/dist/esm/commands/build-output.js

@@ -1,11 +1,13 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
-import { readCacheEntry, resolveCacheEntryPath } from '@williamthorsen/nmr-core';
+import { findPackageRoot, readCacheEntry, resolveCacheEntryPath } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
+import { readPackageJson } from "../helpers/package-json.js";
 export const DEFAULT_ENTRY_GLOBS = ['src/**/*.ts'];
 export const DEFAULT_IGNORE_PATTERNS = ['**/__fixtures__/**', '**/__mocks__/**', '**/__tests__/**', '**/test-utils/**'];
 export const DEFAULT_OUTDIR = 'dist/esm/';
 const BUILD_CACHE_TOOL = 'nmr-compile';
+const SELF_DIR = findPackageRoot(import.meta.url);
 export async function hasBuildOutput(packageDir, options = {}) {
     const outdir = options.outdir ?? DEFAULT_OUTDIR;
     const entryPoints = await glob(options.entryGlobs ?? DEFAULT_ENTRY_GLOBS, {
@@ -42,3 +44,24 @@ export function resolveScratchDirs(emitDir) {
         staging: path.join(parent, `.${name}.staging`),
     };
 }
+export async function resolveToolchainFingerprint(packageDir, selfDir = SELF_DIR) {
+    if (!isSameDir(packageDir, selfDir)) {
+        const digest = await readBuildDigest(selfDir);
+        if (digest !== undefined) {
+            return digest;
+        }
+    }
+    return readPackageJson(selfDir).version ?? '';
+}
+function isSameDir(left, right) {
+    return toRealPath(left) === toRealPath(right);
+}
+function toRealPath(dir) {
+    const absolute = path.resolve(dir);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}

package/dist/esm/commands/build.d.ts

@@ -1,4 +1,8 @@
 import type { BuildOptions } from './build-output.js';
+export interface BuildToolchain {
+    compilerVersion: string;
+    fingerprint: string;
+}
 export declare function buildPackage(packageDir: string, options?: BuildOptions): Promise<void>;
-export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, compilerVersion: string): Promise<string>;
+export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object, toolchain: BuildToolchain): Promise<string>;
 export declare function resolveTsconfigChain(packageDir: string, configFileName?: string): string[];

package/dist/esm/commands/build.js

@@ -6,7 +6,7 @@ import { readCacheEntry, writeCacheEntry } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import * as ts from 'typescript';
 import { resolveConfigPath } from "../config.js";
-import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, resolveBuildCachePath, resolveScratchDirs, } from "./build-output.js";
+import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, } from "./build-output.js";
 const PACKAGE_ICON = '📦';
 const SKIPPED_ICON = '⏭️';
 const SOURCE_ROOT = 'src';
@@ -30,15 +30,20 @@ export async function buildPackage(packageDir, options = {}) {
         ...(existsSync(configPath) ? [path.relative(packageDir, configPath)] : []),
         ...resolveTsconfigChain(packageDir),
     ];
-    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, ts.version, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints));
+    const toolchain = {
+        compilerVersion: ts.version,
+        fingerprint: await resolveToolchainFingerprint(packageDir),
+    };
+    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, toolchain, cachePath, hasExpectedBuildOutput(packageDir, outdir, entryPoints));
     if (!changed) {
         await discardScratchDirs(resolveScratchDirs(emitDir));
         return;
     }
-    await emitPackage(packageDir, entryPoints, outdir);
+    const emittedFileCount = await emitPackage(packageDir, entryPoints, outdir);
     await writeCacheEntry(cachePath, currentHash);
+    console.info(`${PACKAGE_ICON} ${path.basename(packageDir)}: ${describeEmit(emittedFileCount, outdir)}`);
 }
-export async function computeBuildHash(packageDir, files, emitConfig, compilerVersion) {
+export async function computeBuildHash(packageDir, files, emitConfig, toolchain) {
     const hash = createHash('sha256');
     for (const file of files.toSorted()) {
         hash.update(file);
@@ -47,7 +52,9 @@ export async function computeBuildHash(packageDir, files, emitConfig, compilerVe
     }
     hash.update(JSON.stringify(emitConfig));
     hash.update('\0');
-    hash.update(compilerVersion);
+    hash.update(toolchain.compilerVersion);
+    hash.update('\0');
+    hash.update(toolchain.fingerprint);
     return hash.digest('hex');
 }
 export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json') {
@@ -92,10 +99,11 @@ async function emitPackage(packageDir, entryPoints, outdir) {
     }
     if (staged.size === 0) {
         await rm(emitDir, { force: true, recursive: true });
-        return;
+        return 0;
     }
     writeStagedOutput(staged, emitDir, scratchDirs.staging);
     await swapIntoPlace(emitDir, scratchDirs);
+    return staged.size;
 }
 async function discardScratchDirs(scratchDirs) {
     try {
@@ -247,10 +255,10 @@ function getModuleSpecifier(node) {
     }
     return undefined;
 }
-async function detectBuildChanges(packageDir, files, emitConfig, compilerVersion, cachePath, outputPresent) {
+async function detectBuildChanges(packageDir, files, emitConfig, toolchain, cachePath, outputPresent) {
     const packageName = path.basename(packageDir);
     const previousHash = await readCacheEntry(cachePath);
-    const currentHash = await computeBuildHash(packageDir, files, emitConfig, compilerVersion);
+    const currentHash = await computeBuildHash(packageDir, files, emitConfig, toolchain);
     if (previousHash === currentHash) {
         if (outputPresent) {
             console.info(`${SKIPPED_ICON} ${packageName}: No changes detected. Skipping build.`);
@@ -278,6 +286,12 @@ function collectAliasPrefixes(compilerOptions) {
     }
     return Object.keys(compilerOptions.paths).map((pattern) => pattern.replace(/\*$/, ''));
 }
+function describeEmit(fileCount, outdir) {
+    if (fileCount === 0) {
+        return 'Emitted no output.';
+    }
+    return `Compiled ${fileCount} files to ${outdir.replace(/\/+$/u, '')}.`;
+}
 function formatDiagnostics(diagnostics) {
     return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
         getCurrentDirectory: () => process.cwd(),

package/dist/esm/commands/clean.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { removeCheckCache } from "../check-cache.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
+import { reportClosing } from "../helpers/reportClosing.js";
 import { applyDevBin, buildWorkspaceRegistry, resolveScript } from "../resolver.js";
 import { resolveChannel, runCommand } from "../runner.js";
 import { renderChain } from "../steps.js";
@@ -40,17 +41,26 @@ async function clearCheckCache(scopeDir) {
     await removeCheckCache(scopeDir);
     console.info(`${CLEAN_ICON} Removed all recorded check results.`);
 }
+function describeSweep(cleaned, skipped) {
+    const packages = cleaned === 1 ? '1 package' : `${cleaned} packages`;
+    const skipClause = skipped === 0 ? '' : `, skipping ${skipped} with an empty clean override`;
+    return `Cleaned ${packages}${skipClause}.`;
+}
 async function sweepWorkspace(monorepoRoot, workspacePackageDirs) {
     const config = await loadRootConfig(monorepoRoot);
     const registry = buildWorkspaceRegistry(config);
+    let cleaned = 0;
+    let skipped = 0;
     for (const packageDir of workspacePackageDirs) {
         const resolved = resolveScript(CLEAN_COMMAND, registry, packageDir, false);
         const resolvedCommand = resolved === undefined ? undefined : renderChain(resolved.steps);
         if (resolvedCommand === undefined || resolvedCommand === '') {
+            skipped++;
             continue;
         }
         if (resolvedCommand === BUILT_IN_CLEAN) {
             await cleanPackage(packageDir);
+            cleaned++;
             continue;
         }
         const command = applyDevBin(resolvedCommand, config.devBin, monorepoRoot);
@@ -60,5 +70,7 @@ async function sweepWorkspace(monorepoRoot, workspacePackageDirs) {
         if (exitCode !== 0) {
             throw new Error(`nmr-clean: \`${command}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
         }
+        cleaned++;
     }
+    reportClosing(`${CLEAN_ICON} ${describeSweep(cleaned, skipped)}`);
 }

package/dist/esm/commands/ensure-prepublish-hooks.d.ts

@@ -15,3 +15,4 @@ export declare function ensurePrepublishHooks(monorepoRoot: string, options: {
     dryRun: boolean;
     command?: string;
 }): EnsurePrepublishHooksResult;
+export declare function reportPrepublishHooks(result: EnsurePrepublishHooksResult, hookCommand: string): void;

package/dist/esm/commands/ensure-prepublish-hooks.js

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { readPackageJson } from "../helpers/package-json.js";
+import { reportClosing } from "../helpers/reportClosing.js";
 import { isObject } from "../helpers/type-guards.js";
 import { getWorkspacePackageDirs } from "../workspace.js";
 export const DEFAULT_HOOK = 'npm run build';
@@ -59,6 +60,17 @@ export function ensurePrepublishHooks(monorepoRoot, options) {
     const hasFailures = packages.some((p) => p.action === 'missing');
     return { packages, hasFailures };
 }
+export function reportPrepublishHooks(result, hookCommand) {
+    const publishable = result.packages.filter((pkg) => !pkg.isPrivate);
+    if (publishable.length === 0) {
+        console.info('No publishable packages found.');
+        return;
+    }
+    for (const pkg of publishable) {
+        console.info(renderHookStatus(pkg, hookCommand));
+    }
+    reportClosing(describeHookRun(publishable));
+}
 function addPrepublishOnly(packageDir, command) {
     const filePath = path.join(packageDir, 'package.json');
     const raw = readFileSync(filePath, 'utf8');
@@ -71,3 +83,34 @@ function addPrepublishOnly(packageDir, command) {
     parsed['scripts'] = scripts;
     writeFileSync(filePath, JSON.stringify(parsed, null, 2) + '\n', 'utf8');
 }
+function countAction(publishable, action) {
+    return publishable.filter((pkg) => pkg.action === action).length;
+}
+function describeHookRun(publishable) {
+    const packages = publishable.length === 1 ? '1 publishable package' : `${publishable.length} publishable packages`;
+    const missing = countAction(publishable, 'missing');
+    if (missing > 0) {
+        return `${missing} of ${packages} ${missing === 1 ? 'is' : 'are'} missing prepublishOnly. Run with --fix to add it.`;
+    }
+    const fixed = countAction(publishable, 'fixed');
+    if (fixed > 0) {
+        return `Added prepublishOnly to ${fixed} of ${packages}.`;
+    }
+    const wouldFix = countAction(publishable, 'would-fix');
+    if (wouldFix > 0) {
+        return `Would add prepublishOnly to ${wouldFix} of ${packages}.`;
+    }
+    return `${packages} ${publishable.length === 1 ? 'has' : 'have'} prepublishOnly.`;
+}
+function renderHookStatus(pkg, hookCommand) {
+    switch (pkg.action) {
+        case 'ok':
+            return `✓ ${pkg.packageName}: prepublishOnly = "${pkg.prepublishOnly}"`;
+        case 'missing':
+            return `✗ ${pkg.packageName}: missing prepublishOnly`;
+        case 'fixed':
+            return `✓ ${pkg.packageName}: added prepublishOnly = "${hookCommand}"`;
+        case 'would-fix':
+            return `~ ${pkg.packageName}: would add prepublishOnly = "${hookCommand}"`;
+    }
+}

package/dist/esm/commands/report-catalog.js

@@ -1,6 +1,8 @@
 import { findContainingPackageDir } from "../context.js";
 import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
+import { reportClosing } from "../helpers/reportClosing.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
+const CATALOG_ICON = '📚';
 const CATALOG_PROTOCOL = 'catalog:';
 export function reportCatalog(cwd) {
     const monorepoRoot = findMonorepoRoot(cwd);
@@ -12,12 +14,16 @@ export function reportCatalog(cwd) {
     if (dependencies.length === 0) {
         return;
     }
-    const subject = dependencies.length === 1 ? '1 dependency comes' : `${dependencies.length} dependencies come`;
-    console.warn(`📚 WARN: ${subject} from a catalog, which a package-scoped upgrade does not read:`);
+    console.warn(`${CATALOG_ICON} WARN: A package-scoped upgrade does not read the catalogs these come from:`);
     for (const { name, specifier } of dependencies) {
         console.warn(`- ${name} → ${specifier}`);
     }
-    console.warn(`Run \`nmr upgrade\` from ${monorepoRoot} to include them.`);
+    reportClosing(`${CATALOG_ICON} ${describeCatalog(dependencies.length, monorepoRoot)}`, console.warn);
+}
+function describeCatalog(count, monorepoRoot) {
+    const subject = count === 1 ? '1 catalogued dependency went' : `${count} catalogued dependencies went`;
+    const object = count === 1 ? 'it' : 'them';
+    return `${subject} unread. Run \`nmr upgrade\` from ${monorepoRoot} to include ${object}.`;
 }
 function findCataloguedDependencies(packageDir) {
     const pkg = readPackageJson(packageDir);

package/dist/esm/commands/report-overrides.js

@@ -1,16 +1,24 @@
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
+import { reportClosing } from "../helpers/reportClosing.js";
 import { UserError } from "../UserError.js";
 import { readWorkspaceOverrides } from "../workspace.js";
+const OVERRIDES_ICON = '🔒';
 export function reportOverrides(monorepoRoot) {
     const declared = listEntries(readWorkspaceOverrides(monorepoRoot));
     if (declared.length > 0) {
-        console.warn('🔒 WARN: pnpm overrides are active! Check whether these are still needed:');
+        console.warn(`${OVERRIDES_ICON} WARN: pnpm overrides are active:`);
         for (const [name, version] of declared) {
             console.warn(`- ${name} → ${version}`);
         }
+        reportClosing(`${OVERRIDES_ICON} ${describeOverrides(declared.length)}`, console.warn);
     }
     rejectLegacyOverrides(monorepoRoot);
 }
+function describeOverrides(count) {
+    return count === 1
+        ? '1 override is active. Check whether it is still needed.'
+        : `${count} overrides are active. Check whether they are still needed.`;
+}
 function listEntries(overrides) {
     return Object.entries(overrides ?? {}).toSorted(([a], [b]) => a.localeCompare(b));
 }

package/dist/esm/help.js

@@ -43,7 +43,7 @@ function collectOverrides(packageDir) {
     for (const [name, value] of Object.entries(scripts)) {
         if (isHookName(name))
             continue;
-        if (isSelfReferential(value, name))
+        if (isSelfReferential(value, name, packageDir))
             continue;
         filtered[name] = value;
     }

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

@@ -0,0 +1 @@
+export declare function reportClosing(message: string, log?: (line: string) => void): void;

package/dist/esm/helpers/reportClosing.js

@@ -0,0 +1,3 @@
+export function reportClosing(message, log = console.info) {
+    log(`\n${message}`);
+}

package/dist/esm/reportCliFailure.js

@@ -1,11 +1,11 @@
 import { reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { describeError, isError } from '@williamthorsen/toolbelt.errors';
 import { UserError } from "./UserError.js";
 export function reportCliFailure(error, stderr) {
     if (error instanceof UserError) {
         reportError(error.message, stderr);
         return;
     }
-    const detail = error instanceof Error && error.stack !== undefined ? error.stack : describeError(error);
+    const detail = isError(error) && error.stack !== undefined ? error.stack : describeError(error);
     stderr.write(`${detail}\n`);
 }

package/dist/esm/resolver.d.ts

@@ -20,5 +20,6 @@ export declare function describeScript(script: ScriptValue): string;
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
 export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistry;
 export declare function buildRootRegistry(config: NmrConfig): ScriptRegistry;
-export declare function isSelfReferential(script: string, commandName: string): boolean;
+export declare function findChainedSelfReference(packageDir: string | undefined, commandName: string): string | undefined;
+export declare function isSelfReferential(script: string, commandName: string, packageDir: string): boolean;
 export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, workspaceRoot: boolean): ResolvedScript | undefined;

package/dist/esm/resolver.js

@@ -1,9 +1,11 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { hasErrnoCode } from '@williamthorsen/nmr-core';
 import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
 import { isObject } from "./helpers/type-guards.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
-import { composeNmrStep } from "./steps.js";
+import { composeNmrStep, readSelfReference } from "./steps.js";
+import { isMonorepoRoot } from "./workspace.js";
 export function applyDevBin(command, devBin, monorepoRoot) {
     if (!devBin) {
         return command;
@@ -62,7 +64,7 @@ export function readPackageJsonScripts(packageDir) {
         raw = readFileSync(file, 'utf8');
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (hasErrnoCode(error, 'ENOENT')) {
             return undefined;
         }
         throw error;
@@ -87,16 +89,31 @@ export function buildRootRegistry(config) {
         ...config.rootScripts,
     };
 }
-export function isSelfReferential(script, commandName) {
-    const prefix = `nmr ${commandName}`;
-    return script === prefix || script.startsWith(`${prefix} `);
+export function findChainedSelfReference(packageDir, commandName) {
+    if (packageDir === undefined) {
+        return undefined;
+    }
+    const scripts = readPackageJsonScripts(packageDir);
+    if (scripts === undefined || !Object.hasOwn(scripts, commandName)) {
+        return undefined;
+    }
+    const script = scripts[commandName];
+    if (script === undefined) {
+        return undefined;
+    }
+    return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) === 'chained'
+        ? script
+        : undefined;
+}
+export function isSelfReferential(script, commandName, packageDir) {
+    return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) !== undefined;
 }
 export function resolveScript(commandName, registry, packageDir, workspaceRoot) {
     if (packageDir) {
         const pkgScripts = readPackageJsonScripts(packageDir);
         if (pkgScripts && Object.hasOwn(pkgScripts, commandName)) {
             const override = pkgScripts[commandName];
-            if (override !== undefined && !isSelfReferential(override, commandName)) {
+            if (override !== undefined && !isSelfReferential(override, commandName, packageDir)) {
                 return {
                     origin: { tier: 'package', file: resolvePackageJsonPath(packageDir), key: commandName },
                     steps: [{ kind: 'opaque', command: override }],

package/dist/esm/runCli.js

@@ -7,17 +7,24 @@ import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
 import { isHookName } from "./helpers/hook-name.js";
+import { resolvePackageJsonPath } from "./helpers/package-json.js";
 import { composeTranscript } from "./helpers/transcript.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
 import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
-import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, resolveScript, } from "./resolver.js";
+import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, resolveScript, } from "./resolver.js";
 import { resolveChannel, runSteps } from "./runner.js";
 import { composeNmrStep, findNmrCrossing, renderChain } from "./steps.js";
+import { UserError } from "./UserError.js";
 import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
 const VERSION = readPackageVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
+const NAMED_ESCAPES = new Map([
+    ['\n', String.raw `\n`],
+    ['\r', String.raw `\r`],
+    ['\t', String.raw `\t`],
+]);
 export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
     const { args, cwd, env, stdout, stderr } = options;
@@ -84,6 +91,14 @@ export async function runCli(options) {
         return runSteps([delegation.step], context.monorepoRoot, { ...runOptions, env: delegation.env });
     }
     const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
+    assertNoSelfReference({
+        anchorDir,
+        command,
+        isReading: parsed.log,
+        monorepoRoot: context.monorepoRoot,
+        registry,
+        workspaceRoot: parsed.workspaceRoot,
+    });
     const resolved = resolveScript(command, registry, anchorDir, parsed.workspaceRoot);
     if (!resolved) {
         if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
@@ -255,8 +270,7 @@ function describeCrossingRemedy(options) {
             };
         case 'config':
             return {
-                remedy: `Write the nmr steps as a step list, and move any others to a \`${origin.key}:pre\` or ` +
-                    `\`${origin.key}:post\` script.`,
+                remedy: `Write the nmr steps as a step list, and move any others to ${describeStepDestination(origin.key)}.`,
                 subject: `${configSite}: \`${origin.field}.${origin.key}\``,
             };
         case 'package':
@@ -270,6 +284,12 @@ function describeCrossingRemedy(options) {
         }
     }
 }
+function describeStepDestination(key) {
+    if (isHookName(key)) {
+        return 'a script of their own that the step list names, because a hook has no `:pre` or `:post` of its own';
+    }
+    return `a \`${key}:pre\` or \`${key}:post\` script`;
+}
 function describeOrigin(origin, config, useRoot) {
     if (origin.tier === 'package') {
         return origin;
@@ -280,9 +300,17 @@ function describeOrigin(origin, config, useRoot) {
         ? { tier: 'config', field, key: origin.key }
         : { tier: 'default', key: origin.key };
 }
+function escapeControlCharacters(text) {
+    let escaped = text;
+    for (const [char, escape] of NAMED_ESCAPES) {
+        escaped = escaped.split(char).join(escape);
+    }
+    return escaped;
+}
 function formatNmrCrossingWarning(options) {
     const { remedy, subject } = describeCrossingRemedy(options);
-    return `⚠️ ${subject} reaches nmr through a shell (\`${options.crossing}\`), ${CROSSING_CONSEQUENCE} ${remedy}`;
+    return (`⚠️ ${subject} reaches nmr through a shell (\`${escapeControlCharacters(options.crossing)}\`), ` +
+        `${CROSSING_CONSEQUENCE} ${remedy}`);
 }
 function formatOverrideNotice(resolved, registry, command, anchorDir, quiet) {
     const registryEntry = Object.hasOwn(registry, command) ? registry[command] : undefined;
@@ -291,18 +319,26 @@ function formatOverrideNotice(resolved, registry, command, anchorDir, quiet) {
     }
     return `📦 ${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}\n`;
 }
+function formatSelfReferenceRemedy(options) {
+    const { command, monorepoRoot, registry, script, workspaceRoot } = options;
+    if (isHookName(command)) {
+        return `Delete the re-invocation: \`${command}\` runs the steps standing beside it.`;
+    }
+    const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
+    return formatPackageRemedy({ configSite, crossing: script, key: command, registry, workspaceRoot });
+}
 function formatPackageRemedy(options) {
     const { configSite, crossing, key, registry, workspaceRoot } = options;
     const registryEntry = Object.hasOwn(registry, key) ? registry[key] : undefined;
     if (registryEntry === undefined) {
         return (`A \`package.json\` script holds no step list: define \`${key}\` in \`${configSite}\` and move the ` +
-            `package-specific steps to a \`${key}:pre\` or \`${key}:post\` script.`);
+            `package-specific steps to ${describeStepDestination(key)}.`);
     }
     const registryChain = renderChain(expandScript(registryEntry, workspaceRoot));
     if (registryChain === crossing) {
-        return `Delete the entry: nmr's own \`${key}\` already runs \`${registryChain}\`.`;
+        return `Delete the entry: nmr's own \`${key}\` already runs \`${escapeControlCharacters(registryChain)}\`.`;
     }
-    return `Delete the entry and move the steps it adds to a \`${key}:pre\` or \`${key}:post\` script.`;
+    return `Delete the entry and move the steps it adds to ${describeStepDestination(key)}.`;
 }
 function findArgError(parsed) {
     if (parsed.log && parsed.command === undefined && !parsed.help && !parsed.version) {
@@ -319,7 +355,24 @@ function findNoOpReason(resolvedCommand) {
     }
     return undefined;
 }
+function assertNoSelfReference(options) {
+    const { anchorDir, command, isReading, monorepoRoot, registry, workspaceRoot } = options;
+    if (isReading) {
+        return;
+    }
+    const script = findChainedSelfReference(anchorDir, command);
+    if (script === undefined) {
+        return;
+    }
+    const remedy = formatSelfReferenceRemedy({ command, monorepoRoot, registry, script, workspaceRoot });
+    const site = path.relative(monorepoRoot, resolvePackageJsonPath(anchorDir));
+    throw new UserError(`${site}: \`scripts.${command}\` re-invokes \`nmr ${command}\` (\`${escapeControlCharacters(script)}\`), ` +
+        `so nmr cannot run the steps it chains. ${remedy}`);
+}
 function hasRunnableHook(hookName, registry, anchorDir, workspaceRoot) {
+    if (findChainedSelfReference(anchorDir, hookName) !== undefined) {
+        return true;
+    }
     const resolved = resolveScript(hookName, registry, anchorDir, workspaceRoot);
     if (!resolved)
         return false;

package/dist/esm/steps.d.ts

@@ -11,8 +11,14 @@ export interface NmrStepTarget {
     isDelegate: boolean;
     isWorkspaceRoot: boolean;
 }
+export type SelfReference = 'chained' | 'sole';
 export declare function composeNmrStep(element: string, workspaceRoot: boolean, declinesArgs?: boolean): Step;
 export declare function findNmrCrossing(steps: readonly Step[]): string | undefined;
 export declare function findUnexpressibleToken(element: string): string | undefined;
 export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
+export declare function readSelfReference(options: {
+    anchoredAtRoot: boolean;
+    commandName: string;
+    script: string;
+}): SelfReference | undefined;
 export declare function renderChain(steps: readonly Step[]): string;

package/dist/esm/steps.js

@@ -8,7 +8,7 @@ const LAUNCHERS = new Map([
     ['yarn', new Set(['dlx', 'exec'])],
 ]);
 const QUOTES = new Set(['"', "'"]);
-const SEGMENT_SEPARATORS = new Set([';', '|', '&']);
+const SEGMENT_SEPARATORS = new Set([';', '|', '&', '\n', '\r']);
 const SHELL_SAFE_TOKEN = /^[\w@%+=:,./-]+$/;
 export function composeNmrStep(element, workspaceRoot, declinesArgs = false) {
     const flags = workspaceRoot ? ['-w'] : [];
@@ -16,7 +16,7 @@ export function composeNmrStep(element, workspaceRoot, declinesArgs = false) {
 }
 export function findNmrCrossing(steps) {
     for (const step of steps) {
-        if (step.kind === 'opaque' && splitSegments(step.command).some(reachesNmr)) {
+        if (step.kind === 'opaque' && splitSegments(step.command).some((segment) => readNmrTail(segment) !== undefined)) {
             return step.command;
         }
     }
@@ -30,14 +30,65 @@ export function readNmrStep(step) {
         return undefined;
     }
     const [file, ...rest] = step.argv;
-    if (file !== 'nmr') {
+    return file === 'nmr' ? readNmrTarget(rest) : undefined;
+}
+export function readSelfReference(options) {
+    const { anchoredAtRoot, commandName, script } = options;
+    const segments = splitSegments(script).filter((segment) => segment.trim() !== '');
+    const reenters = segments.some((segment) => {
+        const tail = readNmrTail(segment);
+        const target = tail === undefined ? undefined : readNmrTarget(tail);
+        return target?.command === commandName && !target.isDelegate && (anchoredAtRoot || !target.isWorkspaceRoot);
+    });
+    if (!reenters) {
         return undefined;
     }
+    return segments.length === 1 ? 'sole' : 'chained';
+}
+export function renderChain(steps) {
+    return steps.map(renderStep).join(' && ');
+}
+function dropLeadingAssignments(tokens) {
+    const start = tokens.findIndex((token) => !ENV_ASSIGNMENT.test(token));
+    return start === -1 ? [] : tokens.slice(start);
+}
+function isRedirectionOperator(char, precedingText, nextChar) {
+    if (char !== '&' && char !== '|') {
+        return false;
+    }
+    return (char === '&' && nextChar === '>') || /[<>]\s*$/.test(precedingText);
+}
+function quoteToken(token) {
+    if (SHELL_SAFE_TOKEN.test(token)) {
+        return token;
+    }
+    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
+}
+function readNmrTail(segment) {
+    const [head, ...rest] = dropLeadingAssignments(tokenize(segment));
+    if (head === undefined) {
+        return undefined;
+    }
+    if (head === 'nmr') {
+        return rest;
+    }
+    const subcommands = LAUNCHERS.get(head);
+    if (subcommands === undefined) {
+        return undefined;
+    }
+    if (subcommands.size === 0) {
+        const nameIndex = rest.findIndex((token) => !token.startsWith('-'));
+        return nameIndex !== -1 && rest[nameIndex] === 'nmr' ? rest.slice(nameIndex + 1) : undefined;
+    }
+    const subcommandIndex = rest.findIndex((token) => subcommands.has(token));
+    return subcommandIndex !== -1 && rest[subcommandIndex + 1] === 'nmr' ? rest.slice(subcommandIndex + 2) : undefined;
+}
+function readNmrTarget(tokens) {
     let isDelegate = false;
     let isWorkspaceRoot = false;
     let index = 0;
-    while (index < rest.length) {
-        const token = rest[index] ?? '';
+    while (index < tokens.length) {
+        const token = tokens[index] ?? '';
         switch (token) {
             case '-F':
             case '--filter':
@@ -63,37 +114,6 @@ export function readNmrStep(step) {
     }
     return undefined;
 }
-export function renderChain(steps) {
-    return steps.map(renderStep).join(' && ');
-}
-function dropLeadingAssignments(tokens) {
-    const start = tokens.findIndex((token) => !ENV_ASSIGNMENT.test(token));
-    return start === -1 ? [] : tokens.slice(start);
-}
-function quoteToken(token) {
-    if (SHELL_SAFE_TOKEN.test(token)) {
-        return token;
-    }
-    return "'" + token.replaceAll("'", String.raw `'\''`) + "'";
-}
-function reachesNmr(segment) {
-    const [head, ...rest] = dropLeadingAssignments(tokenize(segment));
-    if (head === undefined) {
-        return false;
-    }
-    if (head === 'nmr') {
-        return true;
-    }
-    const subcommands = LAUNCHERS.get(head);
-    if (subcommands === undefined) {
-        return false;
-    }
-    if (subcommands.size === 0) {
-        return rest.find((token) => !token.startsWith('-')) === 'nmr';
-    }
-    const subcommandIndex = rest.findIndex((token) => subcommands.has(token));
-    return subcommandIndex !== -1 && rest[subcommandIndex + 1] === 'nmr';
-}
 function renderStep(step) {
     return step.kind === 'opaque' ? step.command : step.argv.map(quoteToken).join(' ');
 }
@@ -128,6 +148,11 @@ function splitSegments(command) {
             continue;
         }
         if (SEGMENT_SEPARATORS.has(char)) {
+            if (isRedirectionOperator(char, current, command[index + 1])) {
+                current += char;
+                index += 1;
+                continue;
+            }
             index += command[index + 1] === char ? 2 : 1;
             segments.push(current);
             current = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -68,16 +68,18 @@
     "dist"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.4.0",
+    "@williamthorsen/toolbelt.errors": "0.5.0",
     "glob": "13.0.6",
     "prettier-plugin-sh": "0.19.0",
-    "taze": "20.0.0",
+    "taze": "20.0.1",
     "yaml": "2.9.0",
-    "@williamthorsen/nmr-core": "0.10.0"
+    "@williamthorsen/nmr-core": "0.10.1"
   },
   "devDependencies": {
+    "@williamthorsen/toolbelt.testing": "0.3.0",
+    "@williamthorsen/toolbelt.vitest": "0.4.0",
     "prettier": "3.9.6",
-    "readyup": "0.27.0",
+    "readyup": "0.29.0",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
     "vitest": "4.1.10"