@williamthorsen/nmr 2.0.0 → 2.0.2

package/docs/check-cache.md

@@ -65,7 +65,7 @@ The gate never wrongly skips. When it cannot be sure, it does nothing and the co
 - When the repository does not have a pnpm install to fingerprint.
 - For any invocation carrying arguments after the command name, and for every step below it: the arguments narrow what runs, and a step served from a recorded pass is a step that did not.
 
-`NMR_DEBUG=1` reports why a run did not skip and why the cache did not apply.
+`NMR_DEBUG=1` reports why a run did not skip and why the cache did not apply. [Environment switches](scripts.md#environment-switches) lists the values that `NMR_DEBUG` accepts.
 
 ## Delegated passes
 
@@ -154,12 +154,12 @@ $ nmr --log test
 
 Try these in order; the first is almost always the right one.
 
-| Step                                   | Effect                                                                       |
-| -------------------------------------- | ---------------------------------------------------------------------------- |
-| `nmr --no-cache <command>`             | Runs the command, then records the fresh result. Applies to the whole chain. |
-| `NMR_NO_CACHE=1`                       | The same, for every nmr invocation in the shell.                             |
-| `rm -rf node_modules/.cache/nmr-check` | Forgets every recorded pass, leaving build output alone.                     |
-| `nmr clean`                            | Forgets every recorded pass and removes build output, at any scope.          |
+| Step                                   | Effect                                                                                                                                     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `nmr --no-cache <command>`             | Runs the command, then records the fresh result. Applies to the whole chain.                                                               |
+| `NMR_NO_CACHE=1`                       | The same, for every nmr invocation in the shell. [Environment switches](scripts.md#environment-switches) lists the values that it accepts. |
+| `rm -rf node_modules/.cache/nmr-check` | Forgets every recorded pass, leaving build output alone.                                                                                   |
+| `nmr clean`                            | Forgets every recorded pass and removes build output, at any scope.                                                                        |
 
 `--no-cache` and `NMR_NO_CACHE=1` also bypass the Prettier cache that `nmr-fmt` keeps, because nmr exports `NMR_NO_CACHE=1` to the commands that it runs. nmr exports it too when a command is given trailing arguments, so `nmr fmt:check <pathspec>` runs uncached. See [`nmr-fmt`'s cache](utilities.md#cache).
 

package/docs/delegate.md

@@ -55,7 +55,7 @@ The first rule that applies decides where a command runs:
 - **A step and a `-F` or `-R` child run where their parent runs.** nmr gives every process that it starts an empty `NMR_DELEGATE`, which rule 6 reads as "here"; the run on a host already passes `--no-delegate`, so a host does not apply its own user config. A git hook that an agent's command starts is an agent run.
 - **A repo whose checks must run on the machine that has the tree** declares `delegate: false` in `.config/nmr.config.ts`, the only value that the repo config accepts for the key. It outranks `NMR_DELEGATE` and the user config, but not a flag.
 - **A command in a package install hook runs here unless a flag asks otherwise.** During `pnpm add`, a hook such as `postinstall` sees a manifest that its lockfile does not match yet, and the host's frozen install of that tree fails. A command in any other `package.json` script, such as `test`, delegates as usual.
-- **`NMR_DEBUG=1` names what sent a command to a host**, such as `delegating ci per ~/.config/nmr/config.ts (when: agent)`, `per NMR_DELEGATE`, or `per --delegate-to`.
+- **`NMR_DEBUG=1` names what sent a command to a host**, such as `delegating ci per ~/.config/nmr/config.ts (when: agent)`, `per NMR_DELEGATE`, or `per --delegate-to`. [Environment switches](scripts.md#environment-switches) lists the values that `NMR_DEBUG` accepts.
 
 ### Choosing among several hosts
 
@@ -92,7 +92,7 @@ $ nmr --delegate-to imac2 ci
 - **A pass earned on a host is recorded here** with that host, and a later delegation whose list includes that host recalls it as `passed 4m ago on imac2`, without asking any host whether it is free. A run here, or a delegation to other hosts, does not recall it. `nmr --log <command>` prints the output that the host sent back, under a header that names the host.
 - **A delegated composite records its constituents' passes too**, as the host reports them, so `nmr --delegate-to imac2 check` after `nmr --delegate-to imac2 ci` recalls without contacting the host, and a recall of `ci` replays its constituents' excerpts. A composite that the host itself recalled records only its own pass, and a `-F` or `-R` delegation does not record any pass; [delegated passes](check-cache.md#delegated-passes) has the rules.
 - **Only a miss reaches the host**, and it does not take the [machine lock](machine-lock.md) here.
-- **`--no-cache` and `NMR_NO_CACHE=1` skip the lookup** and reach the host, where they bypass its cache too.
+- **`--no-cache` and `NMR_NO_CACHE=1` skip the lookup** and reach the host, where they bypass its cache too. [Environment switches](scripts.md#environment-switches) lists the values that `NMR_NO_CACHE` accepts.
 - **An invocation that nmr settles while planning**, such as an unknown command or an empty override, settles here without contacting the host.
 - **A `-F` or `-R` invocation is sent whole**, without consulting this machine's cache, and the host fans it out.
 

package/docs/machine-lock.md

@@ -46,10 +46,10 @@ A holder removes the lock when its command ends, whether the command passed or f
 
 ## Bypassing the lock
 
-| Step                      | Effect                                                     |
-| ------------------------- | ---------------------------------------------------------- |
-| `nmr --no-lock <command>` | Runs without waiting. Applies to the whole chain.          |
-| `NMR_NO_LOCK=1`           | The same, for every nmr invocation that sees the variable. |
+| Step                      | Effect                                                                                                                                               |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nmr --no-lock <command>` | Runs without waiting. Applies to the whole chain.                                                                                                    |
+| `NMR_NO_LOCK=1`           | The same, for every nmr invocation that sees the variable. [Environment switches](scripts.md#environment-switches) lists the values that it accepts. |
 
 `--no-lock` belongs before the command name. After it, it is an argument to the command rather than a flag to nmr; nmr reports this rather than silently ignoring the bypass.
 

package/docs/scripts.md

@@ -132,6 +132,10 @@ All fields are optional. [Script values](#script-values) describes `ScriptValue`
 
 Each field belongs to exactly one tier, and nmr loads from a config only the fields that its tier honors: `build` in a package config, every other field in the monorepo-root config. Declaring a field at the wrong tier fails with a message naming it and where it goes, as does a key that nmr does not recognize at all: A typo cannot degrade into a setting that silently applies nowhere.
 
+### Environment switches
+
+`NMR_DEBUG`, `NMR_NO_CACHE`, `NMR_NO_LOCK`, and `NMR_RUN_IF_PRESENT` are on/off switches. Each is on when set to `1`, and off when set to `0`, set to an empty value, or unset. Any other value, such as `true`, makes nmr exit 2 before it runs a command, with a message that names the variable, its value, and the accepted values; `nmr-fmt` rejects such an `NMR_NO_CACHE` the same way. What each switch does is in [check-result cache](check-cache.md) (`NMR_DEBUG`, `NMR_NO_CACHE`) and [machine lock](machine-lock.md) (`NMR_NO_LOCK`); nmr sets `NMR_RUN_IF_PRESENT` itself, for the runs that it fans out.
+
 ### Package-level configuration
 
 A package may have its own `.config/nmr.config.ts`, which `nmr-compile` reads from the package that it is compiling. This tier honors `build` alone; declaring `workspaceScripts`, `rootScripts`, or any other root-config field there fails with a message naming them, rather than being quietly ignored: Those belong in the monorepo-root config, and a package that appeared to set them would otherwise build on settings that nothing applied. The monorepo-root config has the mirror restriction: `build` there fails the same way, since only a package's own config affects the compile.

package/docs/upgrades.md

@@ -92,10 +92,16 @@ nodejs 24.22.1 → 24.22.3 is available. Run with --write to update .tool-versio
 `--write` rewrites that version and leaves the rest of the file unchanged. A newer major line is never proposed, whatever range mode the invocation passes: Changing majors is left to an edit of `.tool-versions`.
 
 - A release is proposed once it is at least 24 hours old. The index dates a release by UTC day alone, so a release dated D is proposed from the start of D+2, UTC.
+- A release is proposed only once [node-build](https://github.com/nodenv/node-build/tree/main/share/node-build) defines it on its `main` branch, which asdf-nodejs installs from. node-build adds definitions by hand, some time after the index lists a release. When a newer release lacks a definition, the check proposes the newest release that has one and reports the newer one as held back:
+
+  ```text
+  nodejs 24.22.3 is held back: node-build does not define it yet.
+  ```
+
 - Only a plain `X.Y.Z` pin is checked, and only the first version on the `nodejs` line. Any other pin, such as `lts`, is skipped with a note.
 - A repo without `.tool-versions`, or without a `nodejs` entry in it, is skipped silently.
 - `--no-node-version`, which turns off taze's own checks of `.node-version` and `.nvmrc`, turns off this check too.
-- An unreachable index, or a file that cannot be read or written, produces a warning and does not fail the upgrade.
+- An unreachable index, node-build definitions that cannot be read, or a file that cannot be read or written produces a warning and does not fail the upgrade. The check writes nothing when it cannot read the definitions.
 - `--silent` suppresses the report but not the warnings. The report goes to stderr, so `--json` output is unaffected.
 
 ## Request timeout
@@ -130,7 +136,7 @@ These commands are available as `nmr` subcommands and as standalone `nmr-`-prefi
 
 ### `report-catalog`
 
-Report the dependencies that the current package takes from a [pnpm catalog](https://pnpm.io/catalogs), which a package-scoped `upgrade` cannot read (see [dependency upgrades](#dependency-upgrades) for why). Each line names the dependency, its `catalog:` specifier, and the monorepo root from which a covering pass runs. The workspace `upgrade` script runs it automatically, so a repo does not need to wire it up. The subcommand belongs to the workspace registry and runs from a package directory. The `nmr-report-catalog` bin reports nothing when run from the monorepo root, because a root-scoped pass reads the catalog itself.
+Report the dependencies that the current package takes from a [pnpm catalog](https://pnpm.io/catalogs), which a package-scoped `upgrade` cannot read (see [dependency upgrades](#dependency-upgrades) for why). Each line names the dependency, its `catalog:` specifier, and the monorepo root from which a covering pass runs. The workspace `upgrade` script runs it automatically, so a repo does not need to wire it up. The subcommand belongs to the workspace registry and runs from a package directory. The `nmr-report-catalog` bin reports nothing when run from the monorepo root, because a root-scoped pass reads the catalog itself. It takes no arguments: `--help` prints its usage, and any other argument is a usage error, which exits 2 without reporting.
 
 ```bash
 nmr report-catalog
@@ -152,6 +158,8 @@ Run the [taze](https://github.com/antfu-collective/taze) dependency-upgrade tool
 
 Under pnpm's isolated `node_modules`, a transitive package's binary is absent from the consuming repo's `node_modules/.bin`, so a repo that depends on nmr cannot run `taze` directly. `nmr-taze` can, because nmr is a direct dependency, and it resolves the tool from the tree that nmr controls.
 
+Its exit status is that of the first taze run that fails, or 128 plus the signal number when a signal ends that run.
+
 ```bash
 nmr-taze --recursive
 ```

package/docs/utilities.md

@@ -12,7 +12,7 @@ nmr-actionlint
 
 ## `nmr-clean`
 
-Remove a package's build output (`dist`) and its `nmr-compile` cache entries, the key and the recorded emit duration, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels.
+Remove a package's build output (`dist`) and its `nmr-compile` cache entries, the key and the recorded emit duration, so that the next build cannot skip on leftover state. Run from a package directory, it cleans that package; run from the monorepo root, it sweeps every workspace package in a single pass, running each package's resolved `clean`, so a package that overrides `clean`, in `.config/nmr.config.ts` or in its own `package.json`, gets its own command rather than the sweep. Removal is idempotent: Cleaning an unbuilt package is a silent no-op. This is the default `clean` script at both levels. It takes no arguments: `--help` prints its usage, and any other argument is a usage error, which exits 2 without removing anything.
 
 ```bash
 nmr-clean
@@ -20,7 +20,7 @@ nmr-clean
 
 ## `nmr-compile`
 
-Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` from one program and `.d.ts` from a second that reuses it. The package's own `removeComments` governs the `.js` emit; the declarations emit forces it off, so `.d.ts` files keep their doc comments either way. Because the compiler parses each source file, every relative import form (static, re-export, dynamic `import()`, and bare side-effect) is rewritten from `.ts` or `.tsx` 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 every input is unchanged 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.
+Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` from one program and `.d.ts` from a second that reuses it. The package's own `removeComments` governs the `.js` emit; the declarations emit forces it off, so `.d.ts` files keep their doc comments either way. Because the compiler parses each source file, every relative import form (static, re-export, dynamic `import()`, and bare side-effect) is rewritten from `.ts` or `.tsx` 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 every input is unchanged 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. It takes no arguments: `--help` prints its usage, and any other argument is a usage error, which exits 2 without compiling.
 
 **What it compiles.** Entry points are `src/**/*.{ts,tsx}` less the directories that contain test scaffolding rather than published code: `__fixtures__/`, `__mocks__/`, `__tests__/`, and `test-utils/`. Add to that list per package with [`build.extraIgnorePatterns`](scripts.md#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 the compiler never emits a dangling specifier in its importer. This list is deliberately not the Vitest [coverage exclusions](vitest.md#what-the-config-excludes): Helpers live in `test-utils/` precisely so that they stay covered.
 
@@ -44,10 +44,12 @@ nmr-compile
 
 Format, or check the formatting of, the files that git reports for the working directory. Exactly one of `--check` and `--write` is required; a bare invocation prints usage and exits non-zero rather than defaulting to a mutation. `--write` also lists the files that it rewrote. This is what `fmt` and `fmt:check` resolve to, in both registries.
 
-`prettier` is a dependency of nmr, but a repo's own copy takes precedence: `nmr-fmt` resolves Prettier from the working directory first and from nmr's installation second. A repository's formatter has to be the one that its editor and pre-commit hook also run, and resolution goes through the module graph rather than `PATH`, so the copy that runs is the one that the repo declares and not whichever `prettier` happens to come first. A repo that does not install Prettier, or nmr, formats with nmr's copy; when it does not have a Prettier config either, the [house config](prettier.md) applies.
+`prettier` is a dependency of nmr, but a repo's own copy takes precedence: `nmr-fmt` resolves Prettier from the working directory first and from nmr's installation second. A repository's formatter has to be the one that its editor and pre-commit hook also run, and resolution goes through the module graph rather than `PATH`, so the copy that runs is the one that the repo declares and not whichever `prettier` happens to come first. A repo that does not install Prettier, or nmr, formats with nmr's copy; when it does not have a Prettier config either, the [house config](prettier.md) applies. A repo's copy whose manifest is malformed, unreadable, or without a CLI fails the run with an error that names where it is installed, rather than giving way to nmr's copy.
 
 A repo's own copy must be Prettier 3.0.0 or later. The design requires `--ignore-path` to honour every flag rather than only the last, so that a repository-root ignore file passed alongside a package-level one is not silently dropped, and 2.x honoured only the final flag.
 
+A long file list is split into batches that Prettier runs one after another. The exit status is that of the first batch that fails, or 128 plus the signal number when a signal ends that batch.
+
 ```bash
 nmr-fmt --check
 nmr-fmt --write packages/nmr
@@ -68,7 +70,7 @@ A file that git ignores is never formatted, even when named directly. Because tr
 
 A cached entry is reused only while the Prettier version, the Node version, the resolved Prettier options, and the repository's lockfile are all unchanged. Prettier's own key covers the first three. It does not cover plugin code, so each cache file's name also contains a fingerprint of the root's lockfile, and a dependency change, a plugin upgrade included, starts a fresh cache. `nmr-fmt` deletes cache files with an outdated fingerprint, and it discards a cache file that is not valid JSON rather than letting Prettier fail on it. A failure to prepare the cache prints a warning and leaves the run uncached; it never fails the run.
 
-Pass `--no-cache`, or set `NMR_NO_CACHE=1`, to run uncached. `nmr --no-cache fmt:check` sets that variable, so it bypasses both nmr's [check cache](check-cache.md) and this one. Because the fingerprint makes a cache from an earlier lockfile harmless, CI can restore the whole `node_modules/.cache/prettier/nmr-fmt/` directory under a fallback key.
+Pass `--no-cache`, or set `NMR_NO_CACHE=1`, to run uncached; [environment switches](scripts.md#environment-switches) lists the values that the variable accepts. `nmr --no-cache fmt:check` sets that variable, so it bypasses both nmr's [check cache](check-cache.md) and this one. Because the fingerprint makes a cache from an earlier lockfile harmless, CI can restore the whole `node_modules/.cache/prettier/nmr-fmt/` directory under a fallback key.
 
 ```bash
 nmr-fmt --check --no-cache

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -81,8 +81,8 @@
   ],
   "dependencies": {
     "@williamthorsen/nmr-core": "0.16.1",
-    "@williamthorsen/toolbelt.errors": "0.9.0",
-    "@williamthorsen/toolbelt.filesystem": "0.10.0",
+    "@williamthorsen/toolbelt.errors": "0.9.1",
+    "@williamthorsen/toolbelt.filesystem": "0.10.1",
     "glob": "14.0.4",
     "prettier": "3.9.10",
     "prettier-plugin-sh": "0.20.2",
@@ -90,13 +90,13 @@
     "unconfig": "7.5.0"
   },
   "devDependencies": {
-    "@williamthorsen/toolbelt.testing": "0.8.0",
-    "@williamthorsen/toolbelt.vitest": "0.13.2",
+    "@williamthorsen/toolbelt.testing": "0.8.1",
+    "@williamthorsen/toolbelt.vitest": "0.13.3",
     "esbuild": "0.28.2",
-    "readyup": "0.45.0",
+    "readyup": "0.45.1",
     "tinyglobby": "0.2.17",
     "typescript": "6.0.3",
-    "vite": "8.3.6",
+    "vite": "8.3.7",
     "vitest": "5.1.0",
     "yaml": "2.9.1"
   },