@williamthorsen/nmr 2.0.1 → 2.0.2

package/.meta/changelog.json

@@ -1,4 +1,94 @@
 [
+  {
+    "version": "2.0.2",
+    "date": "2026-11-12",
+    "sections": [
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that `nmr-fmt` and `nmr-taze` exited with 1 when a signal ended Prettier or taze, and makes each exit with 128 plus the signal number, as the other commands that nmr runs already did. (#1281)",
+            "hash": "9999694c843db32f1fc2851617402b61794abd3d",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that `nmr-fmt` formatted with nmr's own copy of Prettier when the repository's copy had a malformed or unreadable manifest, and makes `nmr-fmt` fail with an error that names that manifest instead. (#1282)",
+            "hash": "73319582559a85130ba65e810483acb24954e0ac",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that `nmr-vitest` reported a Vitest whose manifest is malformed or unreadable as not installed, and makes `nmr-vitest` name that manifest and the repair instead. (#1282)",
+            "hash": "73319582559a85130ba65e810483acb24954e0ac",
+            "entry": 2
+          },
+          {
+            "description": "Fixes the issue that `nmr-fmt` and `nmr-vitest` crashed on a Prettier or Vitest manifest that starts with a byte-order mark, which Node accepts. (#1282)",
+            "hash": "73319582559a85130ba65e810483acb24954e0ac",
+            "entry": 3
+          },
+          {
+            "description": "Fixes the issue that a `.config/nmr.config.ts` or `~/.config/nmr/config.ts` that failed to parse or threw while loading crashed `nmr` with an internal error that did not name the file, and makes `nmr` report an error that names the config and, for a syntax error, the file and line that Node reports, including those of a module that the config imports. (#1296)",
+            "hash": "3d120c5ce21b5cae276030dee7db1b63514fbe29",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that `nmr` read any value of `NMR_DEBUG`, `NMR_NO_CACHE`, `NMR_NO_LOCK`, or `NMR_RUN_IF_PRESENT` other than `1`, such as `true`, as off without reporting it, by making `nmr` and `nmr-fmt` exit 2 with a message that names the variable and the values that it accepts. (#1297)",
+            "migration": "Set each of these variables to `1` to turn it on, and to `0` or an empty value, or leave it unset, to turn it off. Any other value now stops the run with exit 2 before a command runs.",
+            "hash": "3a396f8788b37d60546eebf5b4c33859064314c6",
+            "entry": 1
+          },
+          {
+            "description": "Fixes the issue that `nmr upgrade --write` rewrote the `nodejs` pin in `.tool-versions` to a release that asdf could not install yet, by limiting the check to releases that node-build defines and reporting a newer release without a definition as held back. (#1300)",
+            "hash": "d97eab803118bb0055b9acd781f928c4ec548a55",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Replaces the copies of the inherited-stdio spawn and exit-code mapping in `nmr-actionlint`, `nmr-shellcheck`, and `nmr-vitest` with the shared `spawnInherited` and `resolveInheritedExitCode` in `spawn-inherited.ts`, so that the copies can no longer change independently. (#1281)",
+            "hash": "9999694c843db32f1fc2851617402b61794abd3d",
+            "entry": 2
+          },
+          {
+            "description": "Replaces the separate `bin` parsing in `resolveVitestCli` and `resolvePrettierCli` with one `resolveDeclaredCli` in `package-manifest.ts`, which takes `bin` either as a bare path or as a map keyed by the package name, so `nmr-vitest` now also accepts a Vitest manifest whose `bin` is a bare path. (#1283)",
+            "hash": "31ebafea1ceb209f1f8993520f90f10cb87bf88d",
+            "entry": 1
+          },
+          {
+            "description": "Groups nmr's check-cache modules under `packages/nmr/src/check-cache/` and its delegation modules under `packages/nmr/src/delegation/`, each directory containing its own tests in `__tests__/`. (#1293)",
+            "hash": "91f900f679d4e84687e1ba74ece7d42bf089abc3",
+            "entry": 1
+          },
+          {
+            "description": "Makes `runCli` accept `runSteps` and `readFilterSelection` as optional dependencies that default to the real functions, and passes them on the `Invocation` to fan-out and the check-cache gate, which no longer import the real functions. (#1295)",
+            "hash": "40098138b5136fdb4c6824d03e1873ab15583693",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🧪 Tests",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Adds `createRunCliHarness` and a shared `it` in `test-utils/run-cli-fixtures.ts` that gives each test a workspace `tree` and fresh fakes, and moves the five `runCli` unit suites onto them, so that the suites no longer depend on the file layout of the modules that they used to mock. (#1295)",
+            "hash": "40098138b5136fdb4c6824d03e1873ab15583693",
+            "entry": 2
+          },
+          {
+            "description": "Covers each decision branch of the check-cache gate with unit suites for lookup, recording, scope, and the command's own stated outcome, which inject a fake tree reader through a new `readTree` option on `runCli`, and removes the tool cases that they supersede, including `check-cache-gate.build-output.tool.test.ts`. (#1298)",
+            "hash": "2b3163471bc0adf4b70b8fe5b386e341241aaaae",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "2.0.1",
     "date": "2026-11-11",

package/.readyup/kits/default.js

@@ -8019,7 +8019,6 @@ import { isRecord as isRecord5 } from "readyup/check-utils";
 
 // src/config.ts
 import { existsSync as existsSync3 } from "node:fs";
-import { pathToFileURL } from "node:url";
 
 // src/helpers/findClosestName.ts
 function findClosestName(name, candidates) {
@@ -8673,7 +8672,7 @@ function buildRootRegistry(config, monorepoRoot) {
   };
 }
 
-// src/config-check-cache.ts
+// src/check-cache/config-check-cache.ts
 function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
   const { checkCache } = config;
   if (checkCache === void 0 || !isMonorepoRoot(baseDir)) {
@@ -8968,6 +8967,44 @@ function escapeControlCharacters(text) {
   return escapedText;
 }
 
+// src/helpers/importConfigDefault.ts
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+async function importConfigDefault(configPath) {
+  let importedModule;
+  try {
+    importedModule = await import(pathToFileURL(configPath).href);
+  } catch (error) {
+    const location = readSyntaxErrorLocation(error);
+    const isInConfig = location !== void 0 && isConfigFile(location.file, configPath);
+    const configLocation = isInConfig ? `${configPath}:${location.line}` : configPath;
+    const foreignLocation = location === void 0 || isInConfig ? "" : `${location.file}:${location.line}: `;
+    throw new UserError(
+      `Cannot load nmr config at ${configLocation}: ${foreignLocation}${describeError(error)}. Fix the file and rerun.`,
+      { cause: error }
+    );
+  }
+  return isRecord2(importedModule) ? importedModule["default"] : void 0;
+}
+function isConfigFile(file, configPath) {
+  return file === configPath || file === resolveRealPath(configPath);
+}
+function readSyntaxErrorLocation(error) {
+  if (!isError(error) || error.stack === void 0) {
+    return void 0;
+  }
+  const match = /^(?<file>.+):(?<line>\d+)$/u.exec(error.stack.split("\n", 1)[0] ?? "");
+  const { file, line } = match?.groups ?? {};
+  return file === void 0 || line === void 0 ? void 0 : { file, line };
+}
+function resolveRealPath(filePath) {
+  try {
+    return realpathSync(filePath);
+  } catch {
+    return void 0;
+  }
+}
+
 // src/config.ts
 var SCRIPT_FIELDS = [
   { field: "rootScripts", scope: "root" },
@@ -8978,8 +9015,7 @@ async function loadConfig(baseDir) {
   if (!existsSync3(configPath)) {
     return {};
   }
-  const importedModule = await import(pathToFileURL(configPath).href);
-  const loadedConfig = isRecord2(importedModule) ? importedModule["default"] : void 0;
+  const loadedConfig = await importConfigDefault(configPath);
   return validateConfig(loadedConfig, configPath, baseDir);
 }
 async function loadRootConfig(monorepoRoot) {
@@ -9595,7 +9631,7 @@ function hasSupportedStrictLintVersion() {
   });
 }
 function getMinVersion() {
-  const pickedFields = { "version": "2.0.1" };
+  const pickedFields = { "version": "2.0.2" };
   if (typeof pickedFields["version"] !== "string") {
     throw new TypeError("nmr/package.json: 'version' must be a string");
   }

package/.readyup/manifest.json

@@ -32,7 +32,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 2.0.1",
+            "@williamthorsen/nmr >= 2.0.2",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -236,7 +236,7 @@
           "path": "lib/workspace-build.ts"
         },
         {
-          "hash": "c0b5a504",
+          "hash": "cf90a835",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -244,22 +244,22 @@
           ]
         },
         {
-          "hash": "eb0306ed",
+          "hash": "a34d9027",
           "kind": "module",
-          "path": "../src/commands/ensure-prepublish-hooks.ts"
+          "path": "../src/check-cache/config-check-cache.ts"
         },
         {
-          "hash": "578af9fd",
+          "hash": "eb0306ed",
           "kind": "module",
-          "path": "../src/config-check-cache.ts"
+          "path": "../src/commands/ensure-prepublish-hooks.ts"
         },
         {
-          "hash": "d25aef4f",
+          "hash": "0555552a",
           "kind": "module",
           "path": "../src/config-validation.ts"
         },
         {
-          "hash": "d345a285",
+          "hash": "f5e9e2fd",
           "kind": "module",
           "path": "../src/config.ts"
         },
@@ -293,6 +293,11 @@
           "kind": "module",
           "path": "../src/helpers/hook-name.ts"
         },
+        {
+          "hash": "d6455b2e",
+          "kind": "module",
+          "path": "../src/helpers/importConfigDefault.ts"
+        },
         {
           "hash": "62caa37e",
           "kind": "module",
@@ -359,7 +364,7 @@
       "readyupVersion": "0.45.1",
       "source": "kits/default.ts",
       "sourceHash": "9fd61bf4",
-      "targetHash": "8eca943d"
+      "targetHash": "9895b0df"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## 2.0.2 — 2026-11-12
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `nmr-fmt` and `nmr-taze` exited with 1 when a signal ended Prettier or taze, and makes each exit with 128 plus the signal number, as the other commands that nmr runs already did. (#1281)
+- Fixes the issue that `nmr-fmt` formatted with nmr's own copy of Prettier when the repository's copy had a malformed or unreadable manifest, and makes `nmr-fmt` fail with an error that names that manifest instead. (#1282)
+- Fixes the issue that `nmr-vitest` reported a Vitest whose manifest is malformed or unreadable as not installed, and makes `nmr-vitest` name that manifest and the repair instead. (#1282)
+- Fixes the issue that `nmr-fmt` and `nmr-vitest` crashed on a Prettier or Vitest manifest that starts with a byte-order mark, which Node accepts. (#1282)
+- Fixes the issue that a `.config/nmr.config.ts` or `~/.config/nmr/config.ts` that failed to parse or threw while loading crashed `nmr` with an internal error that did not name the file, and makes `nmr` report an error that names the config and, for a syntax error, the file and line that Node reports, including those of a module that the config imports. (#1296)
+- Fixes the issue that `nmr` read any value of `NMR_DEBUG`, `NMR_NO_CACHE`, `NMR_NO_LOCK`, or `NMR_RUN_IF_PRESENT` other than `1`, such as `true`, as off without reporting it, by making `nmr` and `nmr-fmt` exit 2 with a message that names the variable and the values that it accepts. (#1297)
+- Fixes the issue that `nmr upgrade --write` rewrote the `nodejs` pin in `.tool-versions` to a release that asdf could not install yet, by limiting the check to releases that node-build defines and reporting a newer release without a definition as held back. (#1300)
+
+### ♻️ Refactoring
+
+- Replaces the copies of the inherited-stdio spawn and exit-code mapping in `nmr-actionlint`, `nmr-shellcheck`, and `nmr-vitest` with the shared `spawnInherited` and `resolveInheritedExitCode` in `spawn-inherited.ts`, so that the copies can no longer change independently. (#1281)
+- Replaces the separate `bin` parsing in `resolveVitestCli` and `resolvePrettierCli` with one `resolveDeclaredCli` in `package-manifest.ts`, which takes `bin` either as a bare path or as a map keyed by the package name, so `nmr-vitest` now also accepts a Vitest manifest whose `bin` is a bare path. (#1283)
+- Groups nmr's check-cache modules under `packages/nmr/src/check-cache/` and its delegation modules under `packages/nmr/src/delegation/`, each directory containing its own tests in `__tests__/`. (#1293)
+- Makes `runCli` accept `runSteps` and `readFilterSelection` as optional dependencies that default to the real functions, and passes them on the `Invocation` to fan-out and the check-cache gate, which no longer import the real functions. (#1295)
+
+### 🧪 Tests
+
+- Adds `createRunCliHarness` and a shared `it` in `test-utils/run-cli-fixtures.ts` that gives each test a workspace `tree` and fresh fakes, and moves the five `runCli` unit suites onto them, so that the suites no longer depend on the file layout of the modules that they used to mock. (#1295)
+- Covers each decision branch of the check-cache gate with unit suites for lookup, recording, scope, and the command's own stated outcome, which inject a fake tree reader through a new `readTree` option on `runCli`, and removes the tool cases that they supersede, including `check-cache-gate.build-output.tool.test.ts`. (#1298)
+
 ## 2.0.1 — 2026-11-11
 
 ### 🐛 Bug fixes

package/README.md

@@ -5,11 +5,17 @@
 Context-aware script runner for pnpm monorepos. Includes an `nmr` (node-monorepo run) binary that provides centralized, consistent script execution across workspace packages and the monorepo root.
 
 <!-- section:release-notes -->
-## Release notes — v2.0.1 (2026-11-11)
+## Release notes — v2.0.2 (2026-11-12)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that `nmr-clean`, `nmr-compile`, `nmr-report-catalog`, and `nmr-report-overrides` ignored their arguments, so `--help` or a mistyped option ran the command, and `nmr-clean --help` removed build output instead of printing usage. (#1273)
+- Fixes the issue that `nmr-fmt` and `nmr-taze` exited with 1 when a signal ended Prettier or taze, and makes each exit with 128 plus the signal number, as the other commands that nmr runs already did. (#1281)
+- Fixes the issue that `nmr-fmt` formatted with nmr's own copy of Prettier when the repository's copy had a malformed or unreadable manifest, and makes `nmr-fmt` fail with an error that names that manifest instead. (#1282)
+- Fixes the issue that `nmr-vitest` reported a Vitest whose manifest is malformed or unreadable as not installed, and makes `nmr-vitest` name that manifest and the repair instead. (#1282)
+- Fixes the issue that `nmr-fmt` and `nmr-vitest` crashed on a Prettier or Vitest manifest that starts with a byte-order mark, which Node accepts. (#1282)
+- Fixes the issue that a `.config/nmr.config.ts` or `~/.config/nmr/config.ts` that failed to parse or threw while loading crashed `nmr` with an internal error that did not name the file, and makes `nmr` report an error that names the config and, for a syntax error, the file and line that Node reports, including those of a module that the config imports. (#1296)
+- Fixes the issue that `nmr` read any value of `NMR_DEBUG`, `NMR_NO_CACHE`, `NMR_NO_LOCK`, or `NMR_RUN_IF_PRESENT` other than `1`, such as `true`, as off without reporting it, by making `nmr` and `nmr-fmt` exit 2 with a message that names the variable and the values that it accepts. (#1297)
+- Fixes the issue that `nmr upgrade --write` rewrote the `nodejs` pin in `.tool-versions` to a release that asdf could not install yet, by limiting the check to releases that node-build defines and reporting a newer release without a definition as held back. (#1300)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -189,7 +195,7 @@ $ nmr check
 nmr: waiting for test in /Users/me/repos/other-repo (pid 41872) to finish
 ```
 
-The lock lives in `/tmp/nmr-<uid>/`, or in `NMR_LOCK_DIR`; a sandboxed session needs write access to it. `nmr --no-lock <command>` or `NMR_NO_LOCK=1` runs without waiting. [Machine lock](docs/machine-lock.md) covers which commands take it, nesting and fan-outs, reclaiming a lock that its holder left behind, and CI.
+The lock lives in `/tmp/nmr-<uid>/`, or in `NMR_LOCK_DIR`; a sandboxed session needs write access to it. `nmr --no-lock <command>` or `NMR_NO_LOCK=1` runs without waiting; [environment switches](docs/scripts.md#environment-switches) lists the values that the variable accepts. [Machine lock](docs/machine-lock.md) covers which commands take it, nesting and fan-outs, reclaiming a lock that its holder left behind, and CI.
 
 ## Delegating to another machine
 

package/dist/esm/{check-cache-build-output.d.ts → check-cache/check-cache-build-output.d.ts}

@@ -1,4 +1,4 @@
-import type { NmrConfig } from './types.js';
+import type { NmrConfig } from '../types.js';
 /** What nmr's own build has left on disk across the workspace. */
 export interface BuildOutputState {
     /** Covered packages whose output is absent. */

package/dist/esm/{check-cache-build-output.js → check-cache/check-cache-build-output.js}

@@ -1,10 +1,10 @@
 import path from 'node:path';
-import { hasBuildOutput, readBuildDigest } from "./commands/build-output.js";
-import { loadWorkspaceConfig } from "./config.js";
-import { getDefaultWorkspaceScripts } from "./resolve-scripts.js";
-import { buildWorkspaceRegistry, resolveScript } from "./resolver.js";
-import { renderChain } from "./steps.js";
-import { getWorkspacePackageDirs } from "./workspace.js";
+import { hasBuildOutput, readBuildDigest } from "../commands/build-output.js";
+import { loadWorkspaceConfig } from "../config.js";
+import { getDefaultWorkspaceScripts } from "../resolve-scripts.js";
+import { buildWorkspaceRegistry, resolveScript } from "../resolver.js";
+import { renderChain } from "../steps.js";
+import { getWorkspacePackageDirs } from "../workspace.js";
 const BUILT_IN_COMPILE = 'nmr-compile';
 export function findStaleBuildOutput(earlierDigests, laterDigests) {
     const names = [...new Set([...Object.keys(earlierDigests), ...Object.keys(laterDigests)])].toSorted();

package/dist/esm/{check-cache-delegation.d.ts → check-cache/check-cache-delegation.d.ts}

@@ -1,8 +1,8 @@
+import type { HostRunResult } from '../delegation/delegate-host.js';
+import { type RunPlan } from '../invocation.js';
+import type { OutputChannels } from '../output-channel.js';
 import { type TreeSnapshot } from './check-cache.js';
 import type { BuildOutputState } from './check-cache-build-output.js';
-import type { HostRunResult } from './delegate-host.js';
-import { type RunPlan } from './invocation.js';
-import type { OutputChannels } from './output-channel.js';
 /** What the check-result cache gates a run on: the key, the tree, and the build output that the run saw. */
 export interface Gate {
     buildOutputBefore: BuildOutputState;

package/dist/esm/{check-cache-delegation.js → check-cache/check-cache-delegation.js}

@@ -1,8 +1,8 @@
 import path from 'node:path';
+import { VERSION } from "../invocation.js";
 import { resolveTreeSnapshot, writeDebugNote } from "./check-cache.js";
 import { computeCacheKey, computeRetentionKey } from "./check-cache-key.js";
 import { recordHostPass } from "./check-cache-record.js";
-import { VERSION } from "./invocation.js";
 import { formatManifestScope, validatePassManifest } from "./pass-manifest.js";
 export async function recordDelegatedPass(plan, gate, hostRun) {
     const { anchorDir, command, context, env, stderr } = plan.invocation;
@@ -11,7 +11,7 @@ export async function recordDelegatedPass(plan, gate, hostRun) {
         writeDebugNote(`not recording ${command}: the pushed tree is not the tree that the gate keyed on`, env, stderr);
         return;
     }
-    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {}, readTree: plan.invocation.readTree });
     if (!currentRead.ok) {
         writeDebugNote(`not recording ${command}: ${currentRead.reason}`, env, stderr);
         return;

package/dist/esm/{check-cache-entries.js → check-cache/check-cache-entries.js}

@@ -1,8 +1,8 @@
 import path from 'node:path';
 import { isRecord, readCacheEntry, readJsonCacheEntry, removeCacheDir, removeCacheEntry, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isStringRecord } from "../helpers/type-guards.js";
 import { writeDebugNote } from "./check-cache.js";
-import { isStringRecord } from "./helpers/type-guards.js";
 const CACHE_TOOL = 'nmr-check';
 const UNSAFE_SLUG_CHARACTERS = /[^\w.-]+/g;
 export async function certifyRetention(options) {

package/dist/esm/{check-cache-gate.d.ts → check-cache/check-cache-gate.d.ts}

@@ -1,9 +1,9 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-import { type TreeSnapshot } from './check-cache.js';
-import { type RunPlan } from './invocation.js';
-import type { NmrConfig } from './types.js';
-import type { VerdictOutcome } from './verdict.js';
+import { type RunPlan } from '../invocation.js';
+import type { NmrConfig } from '../types.js';
+import type { VerdictOutcome } from '../verdict.js';
+import { type TreeReader, type TreeSnapshot } from './check-cache.js';
 /**
  * Decides whether the check-result cache covers this invocation, and takes the tree snapshot on which it would
  * gate.
@@ -20,6 +20,7 @@ export declare function openGate(options: {
     env: NodeJS.ProcessEnv;
     monorepoRoot: string;
     passthrough: string[];
+    readTree: TreeReader;
     stderr: Writable;
     style: OutputStyle;
 }): TreeSnapshot | undefined;

package/dist/esm/{check-cache-gate.js → check-cache/check-cache-gate.js}

@@ -1,20 +1,19 @@
 import { startTimer } from '@williamthorsen/nmr-core';
+import { addLockEnv, takeMachineLock } from "../child-env.js";
+import { runPlanOnHost } from "../delegation/delegate-host.js";
+import { VERSION } from "../invocation.js";
+import { formatFlagSpelling } from "../nmr-flags.js";
+import { resolveChannel } from "../output-channel.js";
+import { splitSegments } from "../shell-syntax.js";
 import { formatMisplacedNoCacheWarning, isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
 import { recordDelegatedPass } from "./check-cache-delegation.js";
 import { certifyRetention, readCheckCacheEntry } from "./check-cache-entries.js";
 import { computeCacheKey, computeRetentionKey } from "./check-cache-key.js";
 import { recordPass } from "./check-cache-record.js";
-import { addLockEnv, takeMachineLock } from "./child-env.js";
-import { runPlanOnHost } from "./delegate-host.js";
-import { VERSION } from "./invocation.js";
-import { formatFlagSpelling } from "./nmr-flags.js";
-import { resolveChannel } from "./output-channel.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
-import { runSteps } from "./runner.js";
-import { splitSegments } from "./shell-syntax.js";
 export function openGate(options) {
-    const { command, config, env, monorepoRoot, passthrough, stderr, style } = options;
+    const { command, config, env, monorepoRoot, passthrough, readTree, stderr, style } = options;
     if (!isCacheableCommand(config.checkCache, command)) {
         return undefined;
     }
@@ -25,7 +24,7 @@ export function openGate(options) {
         writeDebugNote(`gate disabled: ${command} was passed arguments`, env, stderr);
         return undefined;
     }
-    const snapshot = resolveTreeSnapshot({ monorepoRoot, env });
+    const snapshot = resolveTreeSnapshot({ monorepoRoot, env, readTree });
     if (!snapshot.ok) {
         writeDebugNote(`gate disabled: ${snapshot.reason}`, env, stderr);
         return undefined;
@@ -83,7 +82,7 @@ export async function runGated(plan) {
         }
         const runOptions = { ...plan.runOptions, env: addLockEnv(plan.runOptions.env ?? env, lock) };
         const readElapsedMs = startTimer();
-        const { exitCode, retainedOutput, statedOutcomes } = await runSteps(plan.steps, anchorDir, runOptions);
+        const { exitCode, retainedOutput, statedOutcomes } = await plan.invocation.runSteps(plan.steps, anchorDir, runOptions);
         const durationMs = readElapsedMs();
         if (exitCode === 0 && gate !== undefined) {
             await recordPass({
@@ -97,6 +96,7 @@ export async function runGated(plan) {
                 key: gate.key,
                 monorepoRoot,
                 ownSteps: plan.ownSteps,
+                readTree: plan.invocation.readTree,
                 retainedOutput,
                 retentionKey: gate.retentionKey,
                 runId: plan.runId,

package/dist/esm/{check-cache-key.d.ts → check-cache/check-cache-key.d.ts}

@@ -1,5 +1,5 @@
+import type { OutputChannels } from '../output-channel.js';
 import type { TreeSnapshot } from './check-cache.js';
-import type { OutputChannels } from './output-channel.js';
 /** The parts of the running interpreter that can change what a check concludes. */
 export interface RuntimeIdentity {
     arch: string;

package/dist/esm/{check-cache-record.d.ts → check-cache/check-cache-record.d.ts}

@@ -1,11 +1,11 @@
 import type { Writable } from 'node:stream';
-import { type TreeSnapshot } from './check-cache.js';
+import { type RunCliResult, type RunPlan } from '../invocation.js';
+import type { RetainedOutput } from '../runner.js';
+import type { Step } from '../steps.js';
+import type { NmrConfig } from '../types.js';
+import { type TreeReader, type TreeSnapshot } from './check-cache.js';
 import { type BuildOutputState } from './check-cache-build-output.js';
 import { type EntryRef, type Retention } from './check-cache-entries.js';
-import { type RunCliResult, type RunPlan } from './invocation.js';
-import type { RetainedOutput } from './runner.js';
-import type { Step } from './steps.js';
-import type { NmrConfig } from './types.js';
 /**
  * Records a pass that `host` earned, unless a pass earned here under the same key would still be recalled, because
  * that pass satisfies every invocation that the host pass would. One whose build output is missing or came from
@@ -53,6 +53,7 @@ export declare function recordPass(options: {
     monorepoRoot: string;
     retainedOutput: RetainedOutput | undefined;
     ownSteps: readonly Step[];
+    readTree: TreeReader;
     retentionKey: string;
     runId: string;
     snapshot: TreeSnapshot;

package/dist/esm/{check-cache-record.js → check-cache/check-cache-record.js}

@@ -1,12 +1,13 @@
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { isCacheableCommand, resolveTreeSnapshot, writeDebugNote } from "./check-cache.js";
+import { isEnvSwitchOn } from "../env-switch.js";
+import { deriveExcerpt } from "../helpers/deriveExcerpt.js";
+import { composeTranscript } from "../helpers/transcript.js";
+import { RUN_IF_PRESENT_ENV_VAR, VERSION } from "../invocation.js";
+import { isCacheableCommand, resolveTreeSnapshot, writeDebugNote, } from "./check-cache.js";
 import { findStaleBuildOutput, readBuildOutputState } from "./check-cache-build-output.js";
 import { readCheckCacheEntry, recordTranscript, writeCheckCacheEntry, } from "./check-cache-entries.js";
 import { CURRENT_RUNTIME } from "./check-cache-key.js";
-import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
-import { composeTranscript } from "./helpers/transcript.js";
-import { RUN_IF_PRESENT_ENV_VAR, VERSION } from "./invocation.js";
 import { writePassManifestEntry } from "./pass-manifest.js";
 import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
 import { assembleReplay } from "./replay-assembly.js";
@@ -43,7 +44,7 @@ export async function recordHostPass(options) {
 }
 export async function recordPass(options) {
     const { anchorDir, command, env, monorepoRoot, snapshot, stderr } = options;
-    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {}, readTree: options.readTree });
     if (!currentRead.ok) {
         writeDebugNote(`not recording ${command}: ${currentRead.reason}`, env, stderr);
         return;
@@ -124,7 +125,7 @@ export async function reportRecording(plan) {
     });
     if (!lookup.ok) {
         stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
-        return { exitCode: env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
+        return { exitCode: isEnvSwitchOn(env, RUN_IF_PRESENT_ENV_VAR) ? 0 : 1 };
     }
     stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
     return { exitCode: 0 };

package/dist/esm/{check-cache.d.ts → check-cache/check-cache.d.ts}

@@ -1,11 +1,18 @@
 import type { Writable } from 'node:stream';
-import { type OutputStyle } from '@williamthorsen/nmr-core';
-import type { CheckCacheConfig } from './types.js';
+import { hashWorkingTree, type OutputStyle, readHeadSha } from '@williamthorsen/nmr-core';
+import type { CheckCacheConfig } from '../types.js';
 /** One working tree, observed once per top-level invocation and shared with every process below it. */
 export interface TreeSnapshot {
     treeId: string;
     headSha: string;
 }
+/** The git reads behind a tree snapshot, which a test replaces with a fake. */
+export interface TreeReader {
+    hashWorkingTree: typeof hashWorkingTree;
+    readHeadSha: typeof readHeadSha;
+}
+/** The tree reader that asks git. */
+export declare const GIT_TREE_READER: TreeReader;
 /** Set to `1` to hear why the gate did not skip, or why it is disabled. */
 export declare const DEBUG_ENV_VAR = "NMR_DEBUG";
 /**
@@ -72,6 +79,7 @@ export declare function resolveRunId(env: NodeJS.ProcessEnv): string;
 export declare function resolveTreeSnapshot(options: {
     monorepoRoot: string;
     env: NodeJS.ProcessEnv;
+    readTree: TreeReader;
 }): {
     ok: true;
     snapshot: TreeSnapshot;

package/dist/esm/{check-cache.js → check-cache/check-cache.js}

@@ -1,7 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import { realpathSync } from 'node:fs';
 import { hashWorkingTree, readHeadSha, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
-import { isHookName } from "./helpers/hook-name.js";
+import { isEnvSwitchOn } from "../env-switch.js";
+import { isHookName } from "../helpers/hook-name.js";
+export const GIT_TREE_READER = { hashWorkingTree, readHeadSha };
 export const DEBUG_ENV_VAR = 'NMR_DEBUG';
 export const DEFAULT_CACHEABLE_COMMANDS = [
     'check',
@@ -54,10 +56,11 @@ export function resolveRunId(env) {
 }
 export function resolveTreeSnapshot(options) {
     const inheritedSnapshot = decodeTreeSnapshot(options.env[TREE_SNAPSHOT_ENV_VAR]);
-    if (inheritedSnapshot !== undefined && readHeadSha(options.monorepoRoot) === inheritedSnapshot.headSha) {
+    if (inheritedSnapshot !== undefined &&
+        options.readTree.readHeadSha(options.monorepoRoot) === inheritedSnapshot.headSha) {
         return { ok: true, snapshot: inheritedSnapshot };
     }
-    const hashedTree = hashWorkingTree(options.monorepoRoot);
+    const hashedTree = options.readTree.hashWorkingTree(options.monorepoRoot);
     if (!hashedTree.ok) {
         return hashedTree;
     }
@@ -74,7 +77,7 @@ export function resolveTreeSnapshot(options) {
     return { ok: true, snapshot: { treeId: hashedTree.treeId, headSha: hashedTree.headSha } };
 }
 export function writeDebugNote(message, env, stderr) {
-    if (env[DEBUG_ENV_VAR] === '1') {
+    if (isEnvSwitchOn(env, DEBUG_ENV_VAR)) {
         stderr.write(`nmr check-cache: ${message}\n`);
     }
 }

package/dist/esm/{config-check-cache.d.ts → check-cache/config-check-cache.d.ts}

@@ -1,4 +1,4 @@
-import type { NmrConfig } from './types.js';
+import type { NmrConfig } from '../types.js';
 /**
  * Rejects a `checkCache` name that does not resolve to any command. Both fields are read by name alone, so a
  * misspelt entry is inert: The command that it meant to name goes on running, indistinguishable from one that

package/dist/esm/{config-check-cache.js → check-cache/config-check-cache.js}

@@ -1,8 +1,8 @@
 import { UserError } from '@williamthorsen/nmr-core';
-import { findClosestName } from "./helpers/findClosestName.js";
-import { isHookName } from "./helpers/hook-name.js";
-import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
-import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
+import { findClosestName } from "../helpers/findClosestName.js";
+import { isHookName } from "../helpers/hook-name.js";
+import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "../resolver.js";
+import { getWorkspacePackageDirs, isMonorepoRoot } from "../workspace.js";
 export function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     const { checkCache } = config;
     if (checkCache === undefined || !isMonorepoRoot(baseDir)) {

package/dist/esm/{pass-manifest.d.ts → check-cache/pass-manifest.d.ts}

@@ -1,6 +1,6 @@
 import type { Writable } from 'node:stream';
+import type { CheckCacheConfig } from '../types.js';
 import { type ReplayLine } from './check-cache-entries.js';
-import type { CheckCacheConfig } from './types.js';
 /**
  * One pass that an nmr process on a host recorded or recalled during a delegated run, as the host session returns it
  * to the delegating machine.

package/dist/esm/{pass-manifest.js → check-cache/pass-manifest.js}

@@ -4,9 +4,9 @@ import path from 'node:path';
 import process from 'node:process';
 import { isRecord } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { MAX_EXCERPT_BYTES } from "../helpers/deriveExcerpt.js";
 import { isCacheableCommand, PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
 import { isReplayLine } from "./check-cache-entries.js";
-import { MAX_EXCERPT_BYTES } from "./helpers/deriveExcerpt.js";
 export function formatManifestScope(monorepoRoot, anchorDir) {
     const scope = path.relative(monorepoRoot, anchorDir);
     return scope === '' ? '.' : scope.split(path.sep).join('/');