@williamthorsen/nmr 2.0.1 → 2.0.3

package/dist/esm/runCli.js

@@ -2,25 +2,28 @@ import { reportError } from '@williamthorsen/nmr-core';
 import { runCli as runRouter } from '@williamthorsen/nmr-core/cli';
 import { prependBinDirs } from "./bin-path.js";
 import { NMR_BIN } from "./bins.js";
-import { NO_CACHE_ENV_VAR, resolveRunId, RUN_ID_ENV_VAR } from "./check-cache.js";
-import { openGate, runGated } from "./check-cache-gate.js";
-import { reportRecording } from "./check-cache-record.js";
+import { GIT_TREE_READER, NO_CACHE_ENV_VAR, resolveRunId, RUN_ID_ENV_VAR, } from "./check-cache/check-cache.js";
+import { openGate, runGated } from "./check-cache/check-cache-gate.js";
+import { reportRecording } from "./check-cache/check-cache-record.js";
 import { addLockEnv, buildChildEnv, takeMachineLock } from "./child-env.js";
 import { resolveContext } from "./context.js";
 import { assertNoSelfReference } from "./crossing-diagnostics.js";
-import { resolveExecutionTarget, runInvocationOnHost } from "./delegate-host.js";
+import { resolveExecutionTarget, runInvocationOnHost } from "./delegation/delegate-host.js";
+import { DELEGATE_TO_FLAG } from "./delegation/remote-run.js";
 import { enterChain } from "./entry-chain.js";
+import { isEnvSwitchOn } from "./env-switch.js";
 import { composeDelegation, runDelegation } from "./fan-out.js";
+import { readFilterSelection as readFilterSelectionDefault, } from "./helpers/filter-selection.js";
 import { RUN_IF_PRESENT_ENV_VAR, USAGE_EXIT_CODE, VERSION, } from "./invocation.js";
 import { formatMisplacedFlagHint } from "./invocation-args.js";
 import { readInvocationFlags } from "./nmr-flags.js";
 import { reportVerdict } from "./presentation.js";
-import { DELEGATE_TO_FLAG } from "./remote-run.js";
 import { buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
 import { buildRoot, buildVersionRoot } from "./route.js";
 import { assembleChain, formatOverrideNotice } from "./run-chain.js";
+import { runSteps as runStepsDefault } from "./runner.js";
 export async function runCli(options) {
-    const { args, cwd, env, stdout, stderr } = options;
+    const { args, cwd, env, readFilterSelection = readFilterSelectionDefault, readTree = GIT_TREE_READER, runSteps = runStepsDefault, stdout, stderr, } = options;
     const reading = readInvocationFlags(args);
     const firstPass = reading.ok ? reading.parsedArgs : undefined;
     const routerOptions = { name: NMR_BIN, context: undefined, stdout, stderr, baseDir: cwd, version: () => VERSION };
@@ -33,7 +36,10 @@ export async function runCli(options) {
         cwd,
         env,
         firstPass,
+        readFilterSelection,
+        readTree,
         runInvocation: (invocation) => runInvocation(invocation, options),
+        runSteps,
         stderr,
         stdout,
     });
@@ -74,10 +80,11 @@ async function planRun(invocation, target) {
         env,
         monorepoRoot: context.monorepoRoot,
         passthrough: parsedArgs.passthrough,
+        readTree: invocation.readTree,
         stderr,
         style: styles.stderr,
     });
-    const shouldBypassCache = parsedArgs.shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1';
+    const shouldBypassCache = parsedArgs.shouldBypassCache || isEnvSwitchOn(env, NO_CACHE_ENV_VAR);
     const runId = resolveRunId(env);
     const childEnv = buildChildEnv({
         env,
@@ -103,7 +110,15 @@ async function planRun(invocation, target) {
         let result;
         try {
             const heldDelegation = { ...delegation, env: addLockEnv(delegation.env, lock) };
-            result = await runDelegation({ context, delegation: heldDelegation, parsedArgs, runOptions, stderr });
+            result = await runDelegation({
+                context,
+                delegation: heldDelegation,
+                parsedArgs,
+                readFilterSelection: invocation.readFilterSelection,
+                runOptions,
+                runSteps: invocation.runSteps,
+                stderr,
+            });
         }
         finally {
             await lock?.release();
@@ -123,7 +138,7 @@ async function planRun(invocation, target) {
     });
     const resolvedScript = resolveScript(command, registry, anchorDir, parsedArgs.isWorkspaceRoot);
     if (!resolvedScript) {
-        if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
+        if (isEnvSwitchOn(env, RUN_IF_PRESENT_ENV_VAR)) {
             return { settled: true, result: { exitCode: 0 } };
         }
         const delegateToHint = parsedArgs.shouldDelegate && parsedArgs.delegateHosts === undefined

package/dist/esm/runner.d.ts

@@ -18,6 +18,8 @@ export interface RunStepsResult {
     /** The outcome that each foreground opaque step stated, absent unless a step that exited 0 stated one. */
     statedOutcomes?: Map<Step, StatedOutcome>;
 }
+/** Runs a step list, as `runSteps` does: the form in which a caller receives it. */
+export type RunSteps = typeof runSteps;
 /**
  * Runs a step list in order and resolves once one fails or all have run, implementing the `&&` semantics that
  * nmr promises: The first non-zero exit ends the sequence and is the code returned.

package/dist/esm/runner.js

@@ -2,7 +2,7 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { writeDebugNote } from "./check-cache.js";
+import { writeDebugNote } from "./check-cache/check-cache.js";
 import { describeSignalExitCode, startSpawned, } from "./child-process.js";
 import { createOutputRecorder } from "./helpers/createOutputRecorder.js";
 import { isTerminal, resolveChannel, resolveInheritedChannel } from "./output-channel.js";

package/dist/esm/verdict.d.ts

@@ -1,6 +1,6 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-import type { ReplayLine } from './check-cache-entries.js';
+import type { ReplayLine } from './check-cache/check-cache-entries.js';
 import type { ReportFormat } from './report-format.js';
 import type { StatedOutcome } from './stated-outcome.js';
 /**

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
@@ -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

@@ -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.1",
+  "version": "2.0.3",
   "private": false,
   "description": "Context-aware script runner for pnpm monorepos",
   "keywords": [
@@ -80,7 +80,7 @@
     "!docs/*.v*.md"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.16.1",
+    "@williamthorsen/nmr-core": "0.16.2",
     "@williamthorsen/toolbelt.errors": "0.9.1",
     "@williamthorsen/toolbelt.filesystem": "0.10.1",
     "glob": "14.0.4",