@williamthorsen/nmr 0.37.0 → 0.39.0

package/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.39.0 — 2026-09-22
+
+### 🎉 Features
+
+- Report why a workspace selects no package, and no-op nmr's own -R steps (#841)
+
+  - Drops a `-R` step that nmr composed into a script where the workspace holds no package, so `typecheck` and the five `test` scripts run there instead of failing the run.
+  - Adds a no-op verdict for a command that the drop leaves with no step at all.
+  - Replaces the single refusal for a workspace that selects no package with one message per cause.
+
+  Migration: In a repo that declares a workspace package pattern and deliberately holds no package, delete the `.config/nmr.config.ts` entries added to work around the `-R` refusal, the `build: ':'` override included.
+
+- 🚨 **Breaking:** Prefix the booleans and reject unrecognized Vitest option keys (#849)
+
+  - Renames two boolean options of `defineVitestConfig` and `defineRootVitestConfig`, the factories that build a repo's Vitest config: `isolateGit` becomes `shouldIsolateGit`, and `resolveFromSource` becomes `shouldResolveFromSource`.
+  - Makes both factories reject an option key outside the recognized set, naming the offending keys and the recognized ones, rather than ignoring a misspelled or retired key and letting its option fall back to the default with nothing in the run reporting it.
+  - Adds a retired-key check that runs ahead of the unrecognized-key check, reporting the new name for a config that still sets `isolateGit` or `resolveFromSource`.
+
+  Migration: In each options object passed to `defineVitestConfig` or `defineRootVitestConfig`, rename `isolateGit` to `shouldIsolateGit` and `resolveFromSource` to `shouldResolveFromSource`, and correct any other key that the factory now rejects. `defineRootVitestConfig` recognizes `monorepoRoot` on the last layer alone, so a config that sets it on an earlier layer now throws where the old code ignored it.
+
+- 🚨 **Breaking:** End nmr's source value names with the kind of the value (#850)
+
+  - Renames two fields of `TestFileConventionsReport`, `misplaced` and `untiered`, to `misplacedFiles` and `untieredFiles`, and renames `TestFileConventionsOptions`'s `exclude` to `excludedBasenames`, in the `@williamthorsen/nmr/tests` entry point.
+  - Adds a guard to `checkTestFileConventions` and `reportTestFileConventions` that throws a `TypeError` naming `excludedBasenames` when a call still sets `exclude`.
+
+  Migration: Read `report.misplacedFiles` and `report.untieredFiles` in place of `report.misplaced` and `report.untiered`, and pass `excludedBasenames` in place of `exclude`. A call that still sets `exclude` throws rather than running with no exclusions, so the failure surfaces where Vitest loads the call site.
+
+- 🚨 **Breaking:** Hoist the pnpm-workspace resolver into nmr-core as a total API (#864)
+
+  - Adds a `./workspace` subpath export to `@williamthorsen/nmr-core`, whose `resolveWorkspace` returns a pnpm workspace's package directories, or the cause of an empty result, as a value rather than as a thrown error.
+  - Reports a `pnpm-workspace.yaml` that the YAML parser rejects under a cause of its own, `unreadable-manifest`, so `nmr -R build` names the syntax error and its remedy in place of failing with the parser's own error.
+  - Removes `diagnoseEmptyWorkspace` and `EmptyWorkspaceDiagnosis` from `@williamthorsen/nmr/workspace`, since `resolveWorkspace` reports the same cause in one call.
+
+  Migration: Replace each `diagnoseEmptyWorkspace` call with `resolveWorkspace`, which reports the cause on the empty result it already returns, and rename the `no-manifest` cause to `no-package`. `EmptyWorkspaceCause` also gains `unreadable-manifest`, so an exhaustive switch over it stops compiling until it handles the new member; every other export of `@williamthorsen/nmr/workspace` keeps its signature and its `UserError` throws.
+
+- 🚨 **Breaking:** Adopt the shared workspace resolver in release-kit, honoring exclusions (#865)
+
+  - 🚨 **Breaking:** Narrows `no-pattern` in `@williamthorsen/nmr-core`'s `EmptyWorkspaceCause`, moving an absent or empty `packages` list onto `no-packages-list` and a value that is not a list of strings onto `unreadable-packages`.
+  - Stops `release-kit` from tagging, publishing, and label-syncing a package that a `!` entry in `pnpm-workspace.yaml` excludes, which its previous `glob`-based resolution could not remove from the match.
+  - Replaces the release of the root package alone with a failure naming the condition that emptied the workspace, when `pnpm-workspace.yaml` does not hold valid YAML or declares a workspace that does not resolve to a package.
+  - Replaces the `no-pattern` remedy that `nmr` printed for a `pnpm-workspace.yaml` declaring no `packages` list, and for one declaring a `packages` value that is not a list of strings.
+  - Raises `engines.node` to `>=24.16.0` in `@williamthorsen/nmr-core` and `@williamthorsen/release-kit`, because Node 24.0 through 24.15 ignores the `followSymlinks` option that the workspace matcher passes to `globSync` and drops a symlinked package directory from the resolution without reporting it.
+
+  Migration: Add a `no-packages-list` arm and an `unreadable-packages` arm to any `switch` that covers `EmptyWorkspaceCause` exhaustively. `no-pattern` now names only a list that the resolver read in full and whose entries all failed to become a positive pattern, so move the handling of an absent `packages` key, an empty list, and a value that is not a list of strings out of the `no-pattern` arm into the two new ones. Route `no-packages-list` to single-package behavior rather than to a failure path: pnpm resolves such a manifest to the root package alone.
+
+### ♻️ Refactoring
+
+- Align nmr's function names with naming conventions (#852)
+
+  - Renames the functions in `packages/nmr` to align with naming conventions.
+
+- Suffix nmr's unit-measuring numbers and expand its abbreviations (#854)
+
+  - Renames every unit-measuring number and abbreviated identifier under `packages/nmr/src`, adding `Ms`, `Bytes`, and `Offset` suffixes to the quantities and expanding `pkg`, `Len`, and `Idx` to `package`, `Length`, and `Index`. The renames are not part of any public API.
+
+### 🧪 Tests
+
+- End nmr's test value names with the kind of the value (#851)
+
+  - Aligns the name of every non-boolean value in `packages/nmr/src/**/__tests__` with naming conventions.
+  - Renames `inline` to `inlineBody` in the repo-root `__tests__/reusable-workflow-runtime.app.unit.test.ts`.
+
+### 👷 CI
+
+- Make the release workflow Corepack-agnostic (#842)
+
+  - Removes the `Disable Corepack` step from `release.reusable.yaml`, which Node 25's removal of Corepack from the distribution would make fail with `command not found` once `actions/setup-node` moves past Node 24, and keeps `COREPACK_ENABLE_STRICT: '0'`, which guards the source-build path where the pnpm `packageManager` pin survives.
+  - Adds a case to `reusable-workflow-runtime.app.unit.test.ts` that fails the test run on any reusable workflow whose `run:` commands invoke `corepack`, enumerated from `.github/workflows` so that a workflow added later is covered without editing a list.
+  - Drops the Corepack recommendation from the README's pnpm prerequisite, which now points at pnpm's installation page, and from the fix text of the `.tool-versions does not list pnpm` check in nmr's readyup kit, which now names the `packageManager` field.
+
+## 0.38.0 — 2026-09-18
+
+### 🎉 Features
+
+- Give nmr plain output in pipes and CI logs (#838)
+
+  - Stops `nmr` from printing emoji to a pipe or a CI log: When the output stream is not a terminal or `CI` is set, a verdict reads `PASS`, `FAIL`, `SKIP`, or `NOOP` and a command icon is omitted, so that a log can be searched for a verdict.
+  - Adds `--output-style <auto|plain|rich>` to `nmr` and the `NMR_OUTPUT_STYLE` variable, each forcing either style; the flag outranks the variable, a value that names no style exits 1 with a usage error, and neither enters a check-cache key: A rich run and a plain run share a recorded pass.
+  - Replaces several rich glyphs, taking the status markers from the set that release-kit and v11y-check print so that one status has one glyph across the three tools: a recalled pass shows ⏩ in place of ⏭️, a skipped empty override shows ⚪ in place of ⛔, a warning and the `--log` refusal show 🟠 in place of ⚠️ and 📭, the `--log` header shows 💾 in place of 📼, and `nmr-ensure-prepublish-hooks` reports ✅ and ❌ in place of ✓ and ✗.
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Rename the declinesArgs step declaration to shouldDeclineArguments (#822)
+
+  - Makes a `.config/nmr.config.ts` that still declares `declinesArgs` on a composite script's `{ run, declinesArgs }` step fail to load, with an error that names `shouldDeclineArguments` as the replacement.
+  - Renames the matching field of the `StepSpec` type exported by `@williamthorsen/nmr/config` and `@williamthorsen/nmr/scripts`.
+
+  Migration: Rename `declinesArgs` to `shouldDeclineArguments` in each composite script step of `.config/nmr.config.ts`, and in any code that sets or reads the field on a `StepSpec`.
+
 ## 0.37.0 — 2026-09-15
 
 ### 🎉 Features

package/README.md

@@ -5,43 +5,50 @@
 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.37.0 (2026-09-15)
+## Release notes — v0.39.0 (2026-09-22)
 
 ### 🎉 Features
 
-- Guard lefthook install in root prepare and report unguarded installs (#798)
+- Report why a workspace selects no package, and no-op nmr's own -R steps (#841)
 
-  - Adds a `warn` check to the readyup kit of `@williamthorsen/nmr` that reports a root script run by `pnpm install`, such as `prepare` or `postinstall`, whose command calls `lefthook install` without `lefthook check-install`.
-  - Includes in the check's suggested fix the guarded form `lefthook check-install || lefthook install`, which skips rewriting `.git/hooks` while `lefthook.yml` is unchanged since the last install, so that a repo using that form can run `pnpm install` without write access to `.git/hooks`, as inside the Claude Code sandbox, and under pnpm's default `verifyDepsBeforeRun` avoids a reinstall before every `pnpm exec`.
+  - Drops a `-R` step that nmr composed into a script where the workspace holds no package, so `typecheck` and the five `test` scripts run there instead of failing the run.
+  - Adds a no-op verdict for a command that the drop leaves with no step at all.
+  - Replaces the single refusal for a workspace that selects no package with one message per cause.
 
-- Report misplaced test files and a missing guard from the readyup kit (#804)
+  Migration: In a repo that declares a workspace package pattern and deliberately holds no package, delete the `.config/nmr.config.ts` entries added to work around the `-R` refusal, the `build: ':'` override included.
 
-  - Adds an `error` check to the `@williamthorsen/nmr` readyup kit that reports each `*.test.ts` or `*.test.tsx` file outside a `__tests__` directory, which no Vitest project collects and which therefore runs nowhere.
-  - Adds a `warn` check that passes once a test file under `__tests__` imports `checkTestFileConventions` from `@williamthorsen/nmr/tests`, and whose fix shows the one-line guard test to add.
-  - Makes the kit skip both test-file checks once it finds that guard, because the guard reports the same files and applies the repo's `exclude` list, which the kit cannot read.
+- 🚨 **Breaking:** Prefix the booleans and reject unrecognized Vitest option keys (#849)
 
-### 🐛 Bug fixes
+  - Renames two boolean options of `defineVitestConfig` and `defineRootVitestConfig`, the factories that build a repo's Vitest config: `isolateGit` becomes `shouldIsolateGit`, and `resolveFromSource` becomes `shouldResolveFromSource`.
+  - Makes both factories reject an option key outside the recognized set, naming the offending keys and the recognized ones, rather than ignoring a misspelled or retired key and letting its option fall back to the default with nothing in the run reporting it.
+  - Adds a retired-key check that runs ahead of the unrecognized-key check, reporting the new name for a config that still sets `isolateGit` or `resolveFromSource`.
 
-- Fail when a -F pattern selects no workspace (#785)
+  Migration: In each options object passed to `defineVitestConfig` or `defineRootVitestConfig`, rename `isolateGit` to `shouldIsolateGit` and `resolveFromSource` to `shouldResolveFromSource`, and correct any other key that the factory now rejects. `defineRootVitestConfig` recognizes `monorepoRoot` on the last layer alone, so a config that sets it on an earlier layer now throws where the old code ignored it.
 
-  - Fixes a run that reported success without doing anything. `nmr -F <pattern> <command>` printed nothing and exited 0 when the pattern matched no package. It now exits 1, names the rejected pattern, and explains the likely cause.
-  - Covers three further selections that ran nothing and exited 0: an exclusion that leaves only the workspace root, such as `nmr -F '!./packages/*'`; `-R` in a workspace that declares no package; and an empty `-F ''`.
+- 🚨 **Breaking:** End nmr's source value names with the kind of the value (#850)
 
-  Migration: Replace any `-F` pattern that names a directory with the package's manifest `name`. A filter that selects nothing now fails the run instead of passing in silence.
+  - Renames two fields of `TestFileConventionsReport`, `misplaced` and `untiered`, to `misplacedFiles` and `untieredFiles`, and renames `TestFileConventionsOptions`'s `exclude` to `excludedBasenames`, in the `@williamthorsen/nmr/tests` entry point.
+  - Adds a guard to `checkTestFileConventions` and `reportTestFileConventions` that throws a `TypeError` naming `excludedBasenames` when a call still sets `exclude`.
 
-- Fix test runs failing on a dependency with a TypeScript source export (#793)
+  Migration: Read `report.misplacedFiles` and `report.untieredFiles` in place of `report.misplaced` and `report.untiered`, and pass `excludedBasenames` in place of `exclude`. A call that still sets `exclude` throws rather than running with no exclusions, so the failure surfaces where Vitest loads the call site.
 
-  - Fixes the issue that, with `resolveFromSource` at its default of `true`, every test in a file failed with `Stripping types is currently unsupported for files under node_modules` when the file's imports reached a dependency whose `exports` map declares a `source` condition pointing at TypeScript.
-  - Limits the source resolution enabled by `resolveFromSource` to packages whose real path lies outside every `node_modules`, which covers workspace packages and packages linked into the repo from elsewhere.
-  - Makes an import of a workspace package fail when that package's `source` condition names a missing file, instead of resolving to the build output without warning.
-  - Makes conditions that a config adds to `resolve.conditions` or `ssr.resolve.conditions` extend Vite's defaults when `resolveFromSource` is `false`, instead of replacing them.
+- 🚨 **Breaking:** Hoist the pnpm-workspace resolver into nmr-core as a total API (#864)
 
-  Migration: Point each workspace package's `source` condition at a file that exists, or remove the condition. Build a workspace package before running a test that reaches it through an externalized dependency (one that Vitest loads through Node instead of transforming): Node resolves that import without the `source` condition, so it loads the package's build output.
+  - Adds a `./workspace` subpath export to `@williamthorsen/nmr-core`, whose `resolveWorkspace` returns a pnpm workspace's package directories, or the cause of an empty result, as a value rather than as a thrown error.
+  - Reports a `pnpm-workspace.yaml` that the YAML parser rejects under a cause of its own, `unreadable-manifest`, so `nmr -R build` names the syntax error and its remedy in place of failing with the parser's own error.
+  - Removes `diagnoseEmptyWorkspace` and `EmptyWorkspaceDiagnosis` from `@williamthorsen/nmr/workspace`, since `resolveWorkspace` reports the same cause in one call.
 
-- Prevent a recursive or multi-package run from hanging under pnpm 12 (#814)
+  Migration: Replace each `diagnoseEmptyWorkspace` call with `resolveWorkspace`, which reports the cause on the empty result it already returns, and rename the `no-manifest` cause to `no-package`. `EmptyWorkspaceCause` also gains `unreadable-manifest`, so an exhaustive switch over it stops compiling until it handles the new member; every other export of `@williamthorsen/nmr/workspace` keeps its signature and its `UserError` throws.
 
-  - Fixes a hang under pnpm 12: In a terminal, `nmr -R <command>`, a root command that runs in every package such as `nmr build`, and a `-F` pattern that selects several packages printed nothing and waited until Ctrl+C when a package command read keyboard input or changed the terminal's mode, as the spinner in `next build` does.
-  - Gives no terminal input to each package of a `-R` run or a multi-package `-F` run, including a dependency-chain filter such as `-F 'app...'`, and keeps it for a `-F` filter that selects one package, which an interactive command such as `nmr -F <pkg> test:watch` needs.
+- 🚨 **Breaking:** Adopt the shared workspace resolver in release-kit, honoring exclusions (#865)
+
+  - 🚨 **Breaking:** Narrows `no-pattern` in `@williamthorsen/nmr-core`'s `EmptyWorkspaceCause`, moving an absent or empty `packages` list onto `no-packages-list` and a value that is not a list of strings onto `unreadable-packages`.
+  - Stops `release-kit` from tagging, publishing, and label-syncing a package that a `!` entry in `pnpm-workspace.yaml` excludes, which its previous `glob`-based resolution could not remove from the match.
+  - Replaces the release of the root package alone with a failure naming the condition that emptied the workspace, when `pnpm-workspace.yaml` does not hold valid YAML or declares a workspace that does not resolve to a package.
+  - Replaces the `no-pattern` remedy that `nmr` printed for a `pnpm-workspace.yaml` declaring no `packages` list, and for one declaring a `packages` value that is not a list of strings.
+  - Raises `engines.node` to `>=24.16.0` in `@williamthorsen/nmr-core` and `@williamthorsen/release-kit`, because Node 24.0 through 24.15 ignores the `followSymlinks` option that the workspace matcher passes to `globSync` and drops a symlinked package directory from the resolution without reporting it.
+
+  Migration: Add a `no-packages-list` arm and an `unreadable-packages` arm to any `switch` that covers `EmptyWorkspaceCause` exhaustively. `no-pattern` now names only a list that the resolver read in full and whose entries all failed to become a positive pattern, so move the handling of an absent `packages` key, an empty list, and a value that is not a list of strings out of the `no-pattern` arm into the two new ones. Route `no-packages-list` to single-package behavior rather than to a failure path: pnpm resolves such a manifest to the root package alone.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -176,13 +183,15 @@ Every command nmr runs reports one line naming the scope it ran at, the command,
 ```console
 ✅ nmr-core: test: passed in 12.4s
 ❌ nmr: build: failed in 1.2s (exit 1)
-⏭️ nmr-core: test: passed 4m ago on this tree, saved ~12s
-⛔ nmr-core: lint: skipped, the override is empty
+⏩ nmr-core: test: passed 4m ago on this tree, saved ~12s
+⚪ nmr-core: lint: skipped, the override is empty
 ```
 
-**Verdicts print in every verbosity.** `-q` withholds the output of the commands nmr runs, never nmr's own words: a passing quiet run reports its verdicts and nothing else. A command whose override resolved to `""` or `":"` reports the skip rather than exiting 0 in silence, which is what separates it from a command that passed. An `NMR_RUN_IF_PRESENT` miss reports nothing, having no command to report on.
+**A pipe and a CI log get words rather than emoji.** The same four lines read `PASS`, `FAIL`, `SKIP`, and `NOOP` there, which `grep FAIL` finds. `--output-style` and `NMR_OUTPUT_STYLE` each force either style.
+
+**Verdicts print in every verbosity.** `-q` withholds the output of the commands nmr runs, never nmr's own words: a passing quiet run reports its verdicts and nothing else. A command that ran nothing reports the skip rather than exiting 0 in silence, which is what separates it from a command that passed: an override resolving to `""` or `":"`, and a fan-out step that a package-free workspace left nothing to do. An `NMR_RUN_IF_PRESENT` miss reports nothing, having no command to report on.
 
-[What nmr reports](docs/reporting.md) covers how verdicts nest, the `--json` format, and where the verbosity of a run comes from.
+[What nmr reports](docs/reporting.md) covers how verdicts nest, the `--json` format, the output style, and where the verbosity of a run comes from.
 
 ## Check-result cache
 
@@ -193,7 +202,7 @@ $ nmr ci
 # ... four minutes of build, typecheck, lint, and tests ...
 
 $ nmr ci
-⏭️ node-monorepo-tools: ci: passed 2m ago on this tree, saved ~4m
+⏩ node-monorepo-tools: ci: passed 2m ago on this tree, saved ~4m
 ```
 
 [Check-result cache](docs/check-cache.md) covers what is cached, what a hit requires, replaying and reading a recorded run, and bypassing or configuring the cache.
@@ -297,7 +306,7 @@ rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 ## Documentation
 
 - [Scripts and configuration](docs/scripts.md): override tiers, script values, hooks, `defineConfig` fields, `devBin`, and the default commands
-- [What nmr reports](docs/reporting.md): verdicts, `--json`, and verbosity
+- [What nmr reports](docs/reporting.md): verdicts, `--json`, output style, and verbosity
 - [Check-result cache](docs/check-cache.md): what is skipped, what a hit requires, and replaying, reading, and bypassing recorded runs
 - [Dependency upgrades](docs/upgrades.md): `nmr upgrade`, the upgrade policy, `report-catalog`, `report-overrides`, and `nmr-taze`
 - [Standalone utilities](docs/utilities.md): `nmr-clean`, `nmr-compile`, `nmr-fmt`, and `ensure-prepublish-hooks`

package/agents/guidance/rulebooks/nmr.md

@@ -10,8 +10,8 @@ delivery: ambient
 - Scope follows cwd, and bare `nmr` lists both registries: from the repo root a command covers root files and every workspace; from inside a package, that package alone. `nmr -F <pkg> <command>` targets one package from anywhere; `nmr root:<command>` targets root files alone, which isolates a failure to root code.
 - Never `npx nmr`: inside a git worktree it can resolve a different nmr from outside the tree. Fall back to `pnpm exec nmr`.
 - `nmr ci` runs what a code-quality workflow runs (build, then strict checks) and not the dependency audit, which belongs to a workflow of its own; `nmr prepush` runs the audit first, then `ci`, so a vulnerability stops the run before the long gate. Neither installs or binds a git hook.
-- A check that already passed on the current working tree skips, printing `⏭️ <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.
+- A check that already passed on the current working tree skips, printing `SKIP <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.
+- Every command nmr runs reports one line -- `PASS <scope>: <command>: passed in 12.4s`, `FAIL … failed in 1.2s (exit 1)`, `SKIP … passed 4m ago on this tree`, or `NOOP … skipped, the override is empty` -- and a composite reports alongside every command it expands into. Those are the words a pipe and a CI log get; a terminal gets ✅, ❌, ⏩, and ⚪ in their place, and `--output-style rich` or `NMR_OUTPUT_STYLE=rich` forces the emoji on any stream. 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.
 - 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. A file outside `__tests__`, or one whose tier segment is missing or misspelt, fails the test run in a repo that declares nmr's exported conventions check, which reports both. In a repo that has not, neither fails anything -- the first is collected by nothing and the second runs under `unit` -- and `rdy run --packages` reports both and warns that the check is missing.
 - The rest is in `node_modules/@williamthorsen/nmr/docs/`: `scripts.md` for pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`) and script overrides and their `""`/`":"` skip values; `upgrades.md` for `nmr upgrade` ceilings (report-only until `nmr upgrade --write`); `utilities.md` for the `nmr-compile` build (there is no repo-local build script); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; and `check-cache.md` for 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/check-cache.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { OutputChannels } from './runner.js';
 import type { CheckCacheConfig, NmrConfig } from './types.js';
 /** A recorded pass: what ran, on which tree, and what it cost. */
@@ -52,7 +53,7 @@ export interface Retention {
 /** What nmr's own build has left on disk across the workspace. */
 export interface BuildOutputState {
     /** Covered packages whose output is absent. */
-    missing: string[];
+    missingPackages: string[];
     /** The digest of the inputs each covered package's output was built from, keyed by package name. */
     digests: Record<string, string>;
 }
@@ -153,13 +154,13 @@ export declare function encodeTreeSnapshot(snapshot: TreeSnapshot): string;
  * package agrees. A package that has appeared or disappeared between them counts as a disagreement, because
  * the output the earlier observation describes is not the output the later one found.
  */
-export declare function findStaleBuildOutput(earlier: Record<string, string>, later: Record<string, string>): string | undefined;
+export declare function findStaleBuildOutput(earlierDigests: Record<string, string>, laterDigests: Record<string, string>): string | undefined;
 /**
  * Renders the warning for a `--no-cache` that landed after the command name, where it is an argument to the
  * command rather than a flag to nmr. Passing it on unchanged is the honest thing to do with an argument, so
  * the warning is all that separates this from a silently un-bypassed run.
  */
-export declare function formatMisplacedNoCacheWarning(command: string): string;
+export declare function formatMisplacedNoCacheWarning(command: string, style: OutputStyle): string;
 /**
  * Reports whether a command's passes are recorded at all, which is what separates a command with no recording
  * from one that could never have had one.

package/dist/esm/check-cache.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { hashWorkingTree, readCacheEntry, readHeadSha, readJsonCacheEntry, removeCacheDir, removeCacheEntry, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { hashWorkingTree, readCacheEntry, readHeadSha, readJsonCacheEntry, removeCacheDir, removeCacheEntry, resolveCacheEntryPath, STATUS_GLYPHS, writeCacheEntry, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { hasBuildOutput, readBuildDigest } from "./commands/build-output.js";
 import { loadWorkspaceConfig } from "./config.js";
@@ -103,19 +103,19 @@ export function computeRetentionKey(options) {
 export function encodeTreeSnapshot(snapshot) {
     return `${snapshot.hash} ${snapshot.headSha}`;
 }
-export function findStaleBuildOutput(earlier, later) {
-    const names = [...new Set([...Object.keys(earlier), ...Object.keys(later)])].toSorted();
-    return names.find((name) => earlier[name] !== later[name]);
+export function findStaleBuildOutput(earlierDigests, laterDigests) {
+    const names = [...new Set([...Object.keys(earlierDigests), ...Object.keys(laterDigests)])].toSorted();
+    return names.find((name) => earlierDigests[name] !== laterDigests[name]);
 }
-export function formatMisplacedNoCacheWarning(command) {
-    return (`⚠️ --no-cache after the command name is passed to \`${command}\`, not read by nmr. ` +
-        `Did you mean \`nmr --no-cache ${command}\`?`);
+export function formatMisplacedNoCacheWarning(command, style) {
+    return (`${STATUS_GLYPHS[style].warning.text} --no-cache after the command name is passed to \`${command}\`, ` +
+        `not read by nmr. Did you mean \`nmr --no-cache ${command}\`?`);
 }
 export function isCacheableCommand(checkCache, command) {
     return !isHookName(command) && checkCache?.enabled !== false && resolveCacheableCommands(checkCache).has(command);
 }
 export async function readBuildOutputState(monorepoRoot, config) {
-    const state = { missing: [], digests: {} };
+    const state = { missingPackages: [], digests: {} };
     let packageDirs;
     try {
         packageDirs = getWorkspacePackageDirs(monorepoRoot);
@@ -138,17 +138,17 @@ export async function readBuildOutputState(monorepoRoot, config) {
             state.digests[name] = (await readBuildDigest(packageDir)) ?? '';
         }
         else {
-            state.missing.push(name);
+            state.missingPackages.push(name);
         }
     }
     return state;
 }
 export async function readCheckCacheEntry(options) {
-    const parsed = await readJsonCacheEntry(resolveEntryPath(options), isParsedCheckCacheEntry);
-    if (parsed === undefined) {
+    const parsedEntry = await readJsonCacheEntry(resolveEntryPath(options), isParsedCheckCacheEntry);
+    if (parsedEntry === undefined) {
         return undefined;
     }
-    const { retention, ...pass } = parsed;
+    const { retention, ...pass } = parsedEntry;
     return isRetention(retention) ? { ...pass, retention } : pass;
 }
 export async function readTranscript(ref) {
@@ -168,23 +168,23 @@ export async function removeCheckCache(scopeDir) {
 export function resolveCacheableCommands(checkCache) {
     const commands = new Set([...DEFAULT_CACHEABLE_COMMANDS, ...(checkCache?.extraCommands ?? [])]);
     const excludedCommands = checkCache?.excludeCommands ?? [];
-    for (const excluded of excludedCommands) {
-        commands.delete(excluded);
+    for (const excludedCommand of excludedCommands) {
+        commands.delete(excludedCommand);
     }
     return commands;
 }
 export function resolveRunId(env) {
-    const inherited = env[RUN_ID_ENV_VAR];
-    return inherited === undefined || inherited === '' ? randomUUID() : inherited;
+    const inheritedRunId = env[RUN_ID_ENV_VAR];
+    return inheritedRunId === undefined || inheritedRunId === '' ? randomUUID() : inheritedRunId;
 }
 export function resolveTreeSnapshot(options) {
-    const inherited = decodeTreeSnapshot(options.env[TREE_SNAPSHOT_ENV_VAR]);
-    if (inherited !== undefined && readHeadSha(options.monorepoRoot) === inherited.headSha) {
-        return { ok: true, snapshot: inherited };
+    const inheritedSnapshot = decodeTreeSnapshot(options.env[TREE_SNAPSHOT_ENV_VAR]);
+    if (inheritedSnapshot !== undefined && readHeadSha(options.monorepoRoot) === inheritedSnapshot.headSha) {
+        return { ok: true, snapshot: inheritedSnapshot };
     }
-    const hashed = hashWorkingTree(options.monorepoRoot);
-    if (!hashed.ok) {
-        return hashed;
+    const hashedTree = hashWorkingTree(options.monorepoRoot);
+    if (!hashedTree.ok) {
+        return hashedTree;
     }
     let physicalRoot;
     try {
@@ -193,10 +193,10 @@ export function resolveTreeSnapshot(options) {
     catch {
         return { ok: false, reason: `could not resolve ${options.monorepoRoot}` };
     }
-    if (hashed.toplevel !== physicalRoot) {
-        return { ok: false, reason: `the monorepo root is not the git toplevel (${hashed.toplevel})` };
+    if (hashedTree.toplevel !== physicalRoot) {
+        return { ok: false, reason: `the monorepo root is not the git toplevel (${hashedTree.toplevel})` };
     }
-    return { ok: true, snapshot: { hash: hashed.hash, headSha: hashed.headSha } };
+    return { ok: true, snapshot: { hash: hashedTree.hash, headSha: hashedTree.headSha } };
 }
 export async function writeCheckCacheEntry(options) {
     await writeCacheEntry(resolveEntryPath(options), JSON.stringify(options.entry, undefined, 2));
@@ -212,11 +212,11 @@ function composeEnvParts(names, env) {
         return [name, value === undefined ? 'unset' : 'set', value ?? ''];
     });
 }
-function decodeTreeSnapshot(encoded) {
-    if (encoded === undefined) {
+function decodeTreeSnapshot(encodedSnapshot) {
+    if (encodedSnapshot === undefined) {
         return undefined;
     }
-    const [hash, headSha] = encoded.split(' ', 2);
+    const [hash, headSha] = encodedSnapshot.split(' ', 2);
     if (hash === undefined || headSha === undefined || hash === '' || headSha === '') {
         return undefined;
     }

package/dist/esm/cli-build.js

@@ -2,10 +2,13 @@ import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildPackage } from "./commands/build.js";
 import { loadWorkspaceConfig } from "./config.js";
+import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
+    const { stdout } = resolveBinStyles();
     const packageDir = process.cwd();
     const { build } = await loadWorkspaceConfig(packageDir);
     await buildPackage(packageDir, {
+        style: stdout,
         ...(build?.extraIgnorePatterns !== undefined && { extraIgnorePatterns: build.extraIgnorePatterns }),
     });
 }

package/dist/esm/cli-clean.js

@@ -1,8 +1,10 @@
+import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { runClean } from "./commands/clean.js";
+import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
-    await runClean(process.cwd());
+    await runClean(process.cwd(), resolveBinStyles().stdout);
 }
 catch (error) {
     reportError(describeError(error));

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

@@ -1,18 +1,20 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { DEFAULT_HOOK, ensurePrepublishHooks, reportPrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
+import { resolveBinStyles } from "./resolveBinStyles.js";
 import { findMonorepoRoot } from "./workspace.js";
 const flagSchema = {
-    fix: { long: '--fix', type: 'boolean' },
-    dryRun: { long: '--dry-run', type: 'boolean' },
+    shouldFix: { long: '--fix', type: 'boolean' },
+    isDryRun: { long: '--dry-run', type: 'boolean' },
     command: { long: '--command', type: 'string' },
 };
-const { fix, dryRun, command } = parseArgsOrExit(process.argv.slice(2), flagSchema).flags;
+const { shouldFix, isDryRun, command } = parseArgsOrExit(process.argv.slice(2), flagSchema).flags;
 try {
+    const { stdout } = resolveBinStyles();
     const monorepoRoot = findMonorepoRoot();
-    const options = command ? { fix, dryRun, command } : { fix, dryRun };
+    const options = command ? { shouldFix, isDryRun, command } : { shouldFix, isDryRun };
     const result = ensurePrepublishHooks(monorepoRoot, options);
-    reportPrepublishHooks(result, command ?? DEFAULT_HOOK);
+    reportPrepublishHooks(result, command ?? DEFAULT_HOOK, stdout);
     if (result.hasFailures) {
         process.exitCode = 1;
     }

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

@@ -2,8 +2,9 @@ import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { reportCatalog } from "./commands/report-catalog.js";
+import { resolveBinStyles } from "./resolveBinStyles.js";
 try {
-    reportCatalog(process.cwd());
+    reportCatalog(process.cwd(), resolveBinStyles().stderr);
 }
 catch (error) {
     reportError(describeError(error));

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

@@ -1,10 +1,11 @@
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { reportOverrides } from "./commands/report-overrides.js";
+import { resolveBinStyles } from "./resolveBinStyles.js";
 import { findMonorepoRoot } from "./workspace.js";
 try {
     const monorepoRoot = findMonorepoRoot();
-    reportOverrides(monorepoRoot);
+    reportOverrides(monorepoRoot, resolveBinStyles().stderr);
 }
 catch (error) {
     reportError(describeError(error));

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

@@ -8,8 +8,8 @@ export interface BuildOptions {
 }
 /** The pair of directories a build publishes through, both siblings of the emit directory. */
 export interface ScratchDirs {
-    previous: string;
-    staging: string;
+    previousDir: string;
+    stagingDir: string;
 }
 export declare const DEFAULT_ENTRY_GLOBS: string[];
 /**

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

@@ -17,8 +17,8 @@ export async function hasBuildOutput(packageDir, options = {}) {
     return hasExpectedBuildOutput(packageDir, outdir, entryPoints);
 }
 export function hasExpectedBuildOutput(packageDir, outdir, entryPoints) {
-    const emitsOutput = entryPoints.some((entry) => !entry.endsWith('.d.ts'));
-    if (!emitsOutput) {
+    const doesEmitOutput = entryPoints.some((entry) => !entry.endsWith('.d.ts'));
+    if (!doesEmitOutput) {
         return true;
     }
     const outputDir = path.resolve(packageDir, outdir);
@@ -40,8 +40,8 @@ export function resolveScratchDirs(emitDir) {
     const parent = path.dirname(emitDir);
     const name = path.basename(emitDir);
     return {
-        previous: path.join(parent, `.${name}.previous`),
-        staging: path.join(parent, `.${name}.staging`),
+        previousDir: path.join(parent, `.${name}.previous`),
+        stagingDir: path.join(parent, `.${name}.staging`),
     };
 }
 export async function resolveToolchainFingerprint(packageDir, selfDir = SELF_DIR) {
@@ -54,14 +54,14 @@ export async function resolveToolchainFingerprint(packageDir, selfDir = SELF_DIR
     return readPackageJson(selfDir).version ?? '';
 }
 function isSameDir(left, right) {
-    return toRealPath(left) === toRealPath(right);
+    return resolveRealPath(left) === resolveRealPath(right);
 }
-function toRealPath(dir) {
-    const absolute = path.resolve(dir);
+function resolveRealPath(dir) {
+    const absoluteDir = path.resolve(dir);
     try {
-        return realpathSync(absolute);
+        return realpathSync(absoluteDir);
     }
     catch {
-        return absolute;
+        return absoluteDir;
     }
 }

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

@@ -1,3 +1,4 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 import { type BuildOptions } from './build-output.js';
 /**
  * The toolchain a build's emit comes from: the resolved compiler and the nmr running it. Both join the build
@@ -7,6 +8,10 @@ export interface BuildToolchain {
     compilerVersion: string;
     fingerprint: string;
 }
+/** What a build needs beyond its sources: the options shaping the emit, and the style it reports in. */
+export interface BuildPackageOptions extends BuildOptions {
+    style: OutputStyle;
+}
 /**
  * Compiles a package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and
  * `.d.ts` from two programs and rewriting relative `.ts` specifiers and tsconfig `paths` aliases to
@@ -17,7 +22,7 @@ export interface BuildToolchain {
  * current inputs rather than an accumulation of every build that ever ran. Assets belong outside it, or in a
  * `build:post` hook, which runs after the output is published.
  */
-export declare function buildPackage(packageDir: string, options?: BuildOptions): Promise<void>;
+export declare function buildPackage(packageDir: string, options: BuildPackageOptions): Promise<void>;
 /**
  * Produces a digest of the given files (paths and contents), the emit config, and the toolchain.
  * The file list is sorted so the digest is order-invariant, and each path is folded in so renames are detected.