@williamthorsen/nmr 0.48.0 → 0.49.0

package/.readyup/manifest.json

@@ -24,7 +24,7 @@
           "checklist": "nmr",
           "checks": [
             "@williamthorsen/nmr in devDependencies",
-            "@williamthorsen/nmr >= 0.48.0",
+            "@williamthorsen/nmr >= 0.49.0",
             "pnpm-workspace.yaml exists",
             "catalogued dependencies use catalog:",
             "package.json has packageManager field",
@@ -75,6 +75,16 @@
           "kind": "module",
           "path": "../../nmr-core/dist/esm/cache-store.js"
         },
+        {
+          "hash": "81f1406b",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/collectChangedPaths.js"
+        },
+        {
+          "hash": "200f69f1",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/gitObjects.js"
+        },
         {
           "hash": "54384dca",
           "kind": "module",
@@ -86,7 +96,7 @@
           "path": "../../nmr-core/dist/esm/hasErrnoCode.js"
         },
         {
-          "hash": "98509862",
+          "hash": "1eb2b90c",
           "kind": "module",
           "path": "../../nmr-core/dist/esm/hashWorkingTree.js"
         },
@@ -105,6 +115,11 @@
           "kind": "module",
           "path": "../../nmr-core/dist/esm/parseArgs.js"
         },
+        {
+          "hash": "7915ba49",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/runGit.js"
+        },
         {
           "hash": "14547f78",
           "kind": "module",
@@ -126,12 +141,67 @@
           "path": "../../nmr-core/dist/esm/writeFileWithCheck.js"
         },
         {
-          "hash": "ffa13ccc",
+          "hash": "9fd61bf4",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "47f25de7",
+          "hash": "fbdddbc3",
+          "kind": "module",
+          "path": "lib/bin-targets.ts"
+        },
+        {
+          "hash": "56e92527",
+          "kind": "module",
+          "path": "lib/catalog.ts"
+        },
+        {
+          "hash": "369c92bb",
+          "kind": "module",
+          "path": "lib/github.ts"
+        },
+        {
+          "hash": "4f0d7859",
+          "kind": "module",
+          "path": "lib/manifest-fields.ts"
+        },
+        {
+          "hash": "e3de73f8",
+          "kind": "module",
+          "path": "lib/repo-files.ts"
+        },
+        {
+          "hash": "2a90a1d3",
+          "kind": "module",
+          "path": "lib/root-scripts.ts"
+        },
+        {
+          "hash": "3d661ab8",
+          "kind": "module",
+          "path": "lib/self-hosted-runner.ts"
+        },
+        {
+          "hash": "f8f79929",
+          "kind": "module",
+          "path": "lib/setup.ts"
+        },
+        {
+          "hash": "400757e6",
+          "kind": "module",
+          "path": "lib/shared-configs.ts"
+        },
+        {
+          "hash": "b3bdf8ee",
+          "kind": "module",
+          "path": "lib/vitest.ts"
+        },
+        {
+          "hash": "00130733",
+          "kind": "module",
+          "path": "lib/workspace-build.ts"
+        },
+        {
+          "hash": "08c09ade",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -139,12 +209,22 @@
           ]
         },
         {
-          "hash": "7e066d18",
+          "hash": "19b57f2e",
+          "kind": "module",
+          "path": "../src/config-check-cache.ts"
+        },
+        {
+          "hash": "2cfe8c2e",
+          "kind": "module",
+          "path": "../src/config-validation.ts"
+        },
+        {
+          "hash": "5b589c7e",
           "kind": "module",
           "path": "../src/config.ts"
         },
         {
-          "hash": "0fb883a1",
+          "hash": "d2448f72",
           "kind": "module",
           "path": "../src/default-scripts.ts"
         },
@@ -199,7 +279,12 @@
           "path": "../src/resolver.ts"
         },
         {
-          "hash": "ed585ab6",
+          "hash": "bb18a285",
+          "kind": "module",
+          "path": "../src/shell-syntax.ts"
+        },
+        {
+          "hash": "a1b70d65",
           "kind": "module",
           "path": "../src/steps.ts"
         },
@@ -214,7 +299,7 @@
           "path": "../src/UserError.ts"
         },
         {
-          "hash": "857c630c",
+          "hash": "ecf8a873",
           "kind": "module",
           "path": "../src/verbosity.ts"
         },
@@ -231,10 +316,10 @@
       ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.41.0",
+      "readyupVersion": "0.42.0",
       "source": "kits/default.ts",
-      "sourceHash": "ffa13ccc",
-      "targetHash": "6baed250"
+      "sourceHash": "9fd61bf4",
+      "targetHash": "b0939edd"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.49.0 — 2026-10-18
+
+### 🎉 Features
+
+- Makes a delegation wait while another delegation from the same worktree holds the host checkout, printing `nmr: waiting for <command> in <dir> (pid <pid>) to finish on <host>` and leaving the wait out of the verdict's duration. (#1079)
+- Extends Ctrl-C, which previously ended only the run step on the host, to end the delegation during the wait for the checkout, the check-out step, and the install step as well. (#1079)
+- Makes `nmr --delegate` fail at the check-out step with `could not check out on <host>: node is not on the PATH that the interactive login shell sets there` when the host's interactive login shell does not put Node on `PATH`, and documents that Node on the host must satisfy nmr's `engines` range (`>=24.16.0`). (#1079)
+- Makes `nmr --delegate` and `NMR_DELEGATE` look up this machine's check-result cache before contacting the host, so that a tree with a pass recorded here is reported as `passed … ago on this tree` and an unknown command is reported here, without either one reaching the host. (#1080)
+- Adds a record in this machine's check-result cache for each pass that a delegation host reports, so that a later delegation to the same host recalls it as `passed … ago on <host>` and `nmr --log` prints the host's transcript under a header that names the host. (#1080)
+- Makes `nmr --delegate` record the passes that the host reports for a delegated composite's constituents, so that `nmr --delegate <host> check` after `nmr --delegate <host> ci` on the same tree recalls the pass without contacting the host. (#1082)
+- Makes `nmr --delegate` record the excerpts that the host reports with each delegated pass, so that a recall of a delegated command, such as `ci`, replays them instead of nothing. (#1082)
+- Lets `--delegate` and `NMR_DELEGATE` take a comma-separated list of hosts in order of preference, from which nmr chooses the first host on which the delegation would not wait for a lock, otherwise the first host that answered nmr's lock check, and never the delegating machine. (#1083)
+- Extends the check-result cache to recall a pass earned on any host in the list, without checking any host's locks. (#1083)
+- 🚨 **Breaking:** Makes `--delegate` a boolean flag, under which `nmr` runs the command on a host that `NMR_DELEGATE` or the user config names, and adds `--delegate-to <hosts>` to name the hosts for one run. (#1084)
+- Adds a machine-level user config, `~/.config/nmr/config.ts`, in which `delegate.hosts` names this machine's hosts in order of preference and `delegate.when` selects the runs that `nmr` delegates to them without a flag: runs from a coding agent (`'agent'`) or every run (`'always'`), except when `CI` is set and for a `-F` or `-R` invocation. (#1084)
+- Adds the repo config key `delegate`, whose only accepted value, `false`, makes `nmr` run every check on the machine that has the working tree, overriding `NMR_DELEGATE` and the user config but not a delegation flag. (#1084)
+- Adds a stderr line, printed by `nmr` when a delegation decided by the user config cannot reach a host, that names the config file and the remedies in order: network access to the hosts, then `nmr --no-delegate <command>`. (#1084)
+- Updates the `nmr` rulebook to direct agents not to pass `--delegate` or `--delegate-to`, since the user config decides delegation, and to ask for network access to a host before running `nmr --no-delegate`. (#1084)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the snapshot sent to the host by `nmr --delegate` omitted a file edited in the same second as git's last write of the index. (#1078)
+- Fixes the issue that `NMR_NO_CACHE`, `NMR_DEBUG`, and `NMR_RUN_ID` set on this machine did not reach the delegation host, which left the host's cache in use under `NMR_NO_CACHE=1`. (#1080)
+
+### ⚡ Performance
+
+- Keys the check cache on the git tree id that `git add --all` would record for the working tree, which lets `nmr` skip a check after the checked tree is committed, and invalidates every pass recorded by earlier versions once. (#1078)
+
+### ♻️ Refactoring
+
+- Splits the `nmr` source modules that exceeded the 300-line `max-lines` limit, such as `check-cache.ts` and `commands/build.ts`, into one module per concern, and moves each module's tests with its code. (#1061)
+- Splits `config.ts`, `steps.ts`, and the default readyup kit `.readyup/kits/default.ts` to bring each under the 300-line `max-lines` limit, moving field-shape validation into `config-validation.ts`, the `checkCache` name check into `config-check-cache.ts`, shell tokenizing and quoting into `shell-syntax.ts`, and each kit section into a module under `.readyup/lib/`. (#1063)
+- Moves the argument parser, the invocation types, pnpm fan-out, the delegate host, chain assembly, hook wrapping, crossing diagnostics, the check-cache gate and its recording, the child environment, and presentation out of `runCli.ts` into modules of their own, leaving `runCli.ts` with the run orchestration and bringing it under the 300-line `max-lines` limit. (#1064)
+- Rewrites the code that the new and widened rules in `eslint-plugin-unicorn` 78 report, mostly by changing `flatMap` callbacks to return a single value rather than a one-element array. (#1072)
+- Renames nmr's default Prettier config from `prettier-default-config.ts` to `prettier-default.config.ts`, so that the upstream exemption of tool-loaded `*.config.*` files from `unicorn/no-top-level-side-effects` covers it, and updates `nmr-fmt` to resolve the new name. (#1072)
+
+### 🧪 Tests
+
+- Splits the `nmr` test files that exceeded the 500-line `max-lines` limit for tests into files by aspect, and moves the fixtures and fake-spawn helpers that the new files share into `test-utils/`. (#1061)
+- Splits `runCli.unit.test.ts` into four files named for the aspect that each covers and moves the pre/post hooks suite out of `cli.tool.test.ts` into `cli.hooks.tool.test.ts`, with the workspace-tree factory, the in-process runners, and the bin harness moved into shared files under `test-utils/`. (#1064)
+
 ## 0.48.0 — 2026-10-17
 
 ### 🎉 Features

package/README.md

@@ -5,13 +5,33 @@
 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 — v0.48.0 (2026-10-17)
+## Release notes — v0.49.0 (2026-10-18)
 
 ### 🎉 Features
 
-- Adds the `--delegate <host>` flag to `nmr`, which runs a command whose result is its exit status, such as `ci`, `check`, or a `test` command, on that host over SSH against the local working tree with its uncommitted and untracked files, and exits 255 when the delegation fails outside the command. (#1058)
-- Adds the `NMR_DELEGATE` environment variable, which names the host on which `nmr` runs every command that can be delegated, and the `--no-delegate` flag, which runs a command on the local machine whatever `NMR_DELEGATE` names. (#1058)
-- Adds the host to the verdict for a delegated command, as `passed on <host>` in the line and as a `host` field in the `--json` object. (#1058)
+- Makes a delegation wait while another delegation from the same worktree holds the host checkout, printing `nmr: waiting for <command> in <dir> (pid <pid>) to finish on <host>` and leaving the wait out of the verdict's duration. (#1079)
+- Extends Ctrl-C, which previously ended only the run step on the host, to end the delegation during the wait for the checkout, the check-out step, and the install step as well. (#1079)
+- Makes `nmr --delegate` fail at the check-out step with `could not check out on <host>: node is not on the PATH that the interactive login shell sets there` when the host's interactive login shell does not put Node on `PATH`, and documents that Node on the host must satisfy nmr's `engines` range (`>=24.16.0`). (#1079)
+- Makes `nmr --delegate` and `NMR_DELEGATE` look up this machine's check-result cache before contacting the host, so that a tree with a pass recorded here is reported as `passed … ago on this tree` and an unknown command is reported here, without either one reaching the host. (#1080)
+- Adds a record in this machine's check-result cache for each pass that a delegation host reports, so that a later delegation to the same host recalls it as `passed … ago on <host>` and `nmr --log` prints the host's transcript under a header that names the host. (#1080)
+- Makes `nmr --delegate` record the passes that the host reports for a delegated composite's constituents, so that `nmr --delegate <host> check` after `nmr --delegate <host> ci` on the same tree recalls the pass without contacting the host. (#1082)
+- Makes `nmr --delegate` record the excerpts that the host reports with each delegated pass, so that a recall of a delegated command, such as `ci`, replays them instead of nothing. (#1082)
+- Lets `--delegate` and `NMR_DELEGATE` take a comma-separated list of hosts in order of preference, from which nmr chooses the first host on which the delegation would not wait for a lock, otherwise the first host that answered nmr's lock check, and never the delegating machine. (#1083)
+- Extends the check-result cache to recall a pass earned on any host in the list, without checking any host's locks. (#1083)
+- 🚨 **Breaking:** Makes `--delegate` a boolean flag, under which `nmr` runs the command on a host that `NMR_DELEGATE` or the user config names, and adds `--delegate-to <hosts>` to name the hosts for one run. (#1084)
+- Adds a machine-level user config, `~/.config/nmr/config.ts`, in which `delegate.hosts` names this machine's hosts in order of preference and `delegate.when` selects the runs that `nmr` delegates to them without a flag: runs from a coding agent (`'agent'`) or every run (`'always'`), except when `CI` is set and for a `-F` or `-R` invocation. (#1084)
+- Adds the repo config key `delegate`, whose only accepted value, `false`, makes `nmr` run every check on the machine that has the working tree, overriding `NMR_DELEGATE` and the user config but not a delegation flag. (#1084)
+- Adds a stderr line, printed by `nmr` when a delegation decided by the user config cannot reach a host, that names the config file and the remedies in order: network access to the hosts, then `nmr --no-delegate <command>`. (#1084)
+- Updates the `nmr` rulebook to direct agents not to pass `--delegate` or `--delegate-to`, since the user config decides delegation, and to ask for network access to a host before running `nmr --no-delegate`. (#1084)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the snapshot sent to the host by `nmr --delegate` omitted a file edited in the same second as git's last write of the index. (#1078)
+- Fixes the issue that `NMR_NO_CACHE`, `NMR_DEBUG`, and `NMR_RUN_ID` set on this machine did not reach the delegation host, which left the host's cache in use under `NMR_NO_CACHE=1`. (#1080)
+
+### ⚡ Performance
+
+- Keys the check cache on the git tree id that `git add --all` would record for the working tree, which lets `nmr` skip a check after the checked tree is committed, and invalidates every pass recorded by earlier versions once. (#1078)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -195,14 +215,22 @@ The lock lives in `/tmp/nmr-<uid>/`, or in `NMR_LOCK_DIR`; a sandboxed session n
 
 ## Delegating to another machine
 
-`nmr --delegate <host> <command>` runs the command on another machine over SSH, against this working tree, and exits with its status. `NMR_DELEGATE=<host>` makes that the default:
+nmr runs a check on another machine over SSH, against this working tree, and exits with its status. A user config on each machine, `~/.config/nmr/config.ts`, names the hosts in order of preference, and with `when` delegates agents' runs, or every run, without being asked:
+
+```ts
+export default {
+  delegate: { hosts: ['imac2', 'imac3'], when: 'agent' },
+};
+```
+
+`--delegate-to` names the hosts for one run, and nmr runs on the first one that is not busy:
 
 ```console
-$ nmr --delegate imac2 ci
+$ nmr --delegate-to imac2 ci
 ✅ my-repo: ci: passed on imac2 in 1m 48s
 ```
 
-[Delegating to another machine](docs/delegate.md) covers which commands can be delegated, what the host runs, how failures are reported, and setting up the host.
+A delegation consults the [check-result cache](#check-result-cache) first, so a tree that already passed is not sent to the host; a pass that a host earned does not satisfy a run here. A repo whose checks must run on the machine that has the tree declares `delegate: false` in its config. [Delegating to another machine](docs/delegate.md) covers the user config, `--delegate`, `NMR_DELEGATE`, the rules that decide where a command runs, which commands can be delegated, how nmr chooses among several hosts, how the cache is consulted, what the host runs, how failures are reported, and setting up the host.
 
 ## Shared configs and helpers
 
@@ -308,7 +336,7 @@ rdy list --from npm:@williamthorsen/nmr  # what nmr publishes
 - [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
 - [Machine lock](docs/machine-lock.md): Which commands wait for one another, where the lock lives, and bypassing it
-- [Delegating to another machine](docs/delegate.md): `--delegate`, `NMR_DELEGATE`, what the host runs, and setting it up
+- [Delegating to another machine](docs/delegate.md): The user config, `--delegate`, `--delegate-to`, `NMR_DELEGATE`, where a command runs, choosing among several hosts, what the host runs, and setting it up
 - [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`
 - [Shared Vitest config](docs/vitest.md): Test tiers, test selections, the conventions check, and customization

package/agents/guidance/rulebooks/nmr.md

@@ -15,5 +15,5 @@ delivery: ambient
 - Every command that 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 into which it expands. Those are the words that 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 `nmr -q <command>` is the low-noise way to run rather than a silent one: It withholds the output of the commands that nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. nmr reads its own flags only before the command name and passes everything after the name to the commands that run: `nmr ci -q` hands `-q` to `nmr-fmt`, which rejects it. 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 that the test reaches -- `tool` (a process that the test starts, or a program other than the package's own code that the test makes do its work, including an embedded engine, which the package installs and the test runs in-process, such as PGlite), `localhost` (a service already running 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 --sources` reports both and warns that the check is missing.
 - A heavy command (`check`, `ci`, and the `test` commands but `test:watch`) may print `nmr: waiting for <command> in <dir> (pid <pid>) to finish` and wait: nmr runs one at a time on the machine, across every repository. The run is not stuck, and it continues once the holder ends. Do not kill it, and do not rerun it with `--no-lock` to get past the wait, which defeats the memory protection that the lock exists for. A warning that nmr is `running without the machine lock` names a directory that the sandbox cannot write.
-- A verdict reading `passed on <host>` or `failed on <host>` reports a command that ran on another machine, because `--delegate` or `NMR_DELEGATE` sent it there; the output above it is the host's. Exit 255 with `could not prepare <host>` inside a sandbox means that the sandbox refused `ssh`: Ask for network access to the host rather than treating the host as broken, or run the command here with `nmr --no-delegate <command>`.
-- 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 (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; `machine-lock.md` for which commands take the machine lock, where it lives, and its bypass; `delegate.md` for which commands `--delegate` runs on another machine, what the host runs, and its setup; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.
+- Delegation is configured per machine, in nmr's user config (`~/.config/nmr/config.ts`), so a command may run on another machine without being asked: Never pass `--delegate` or `--delegate-to`. A verdict reading `passed on <host>` or `failed on <host>` reports a command that ran on that machine; the output above it is the host's. A delegation consults this machine's check-result cache first: `passed … ago on this tree` recalls a pass earned here, and `passed … ago on <host>` one that the host earned, without contacting it. A failure that names the user config, or exit 255 with `could not prepare <host>` inside a sandbox, means that the sandbox refused `ssh`: Ask for network access to the host first, and run the command here with `nmr --no-delegate <command>` only when that is refused.
+- 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 (the repo does not define a build script of its own); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; `machine-lock.md` for which commands take the machine lock, where it lives, and its bypass; `delegate.md` for the user config, the rules that decide where a command runs, which commands can run on another machine, what the host runs, and its setup; and `check-cache.md` for the check-result cache's key, the retention key to which a replayed excerpt is additionally held, the retention ceiling within which `--log` prints, its `checkCache` config, and every condition that disables it.

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

@@ -0,0 +1,24 @@
+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. */
+    missingPackages: string[];
+    /** The digest of the inputs from which each covered package's output was built, keyed by package name. */
+    digests: Record<string, string>;
+}
+/**
+ * Names a covered package whose output differs between two observations of it, or `undefined` when every
+ * package agrees. A package that has appeared or disappeared between them counts as a disagreement, because
+ * the output that the earlier observation describes is not the output that the later one found.
+ */
+export declare function findStaleBuildOutput(earlierDigests: Record<string, string>, laterDigests: Record<string, string>): string | undefined;
+/**
+ * Reads the state of the build output that nmr's own build covers. Build output is git-ignored, so the tree id
+ * says nothing about it: a `ci` whose `build` constituent is cached would otherwise skip on a tree whose `dist`
+ * had been deleted, or whose `dist` was compiled from a different tree, and hand back a green exit over a
+ * repository that cannot run.
+ *
+ * Because a package whose `build` or `compile` is overridden emits to a location that this function does not
+ * know about, it is left out rather than made a permanent miss.
+ */
+export declare function readBuildOutputState(monorepoRoot: string, config: NmrConfig): Promise<BuildOutputState>;

package/dist/esm/check-cache-build-output.js

@@ -0,0 +1,49 @@
+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";
+const BUILT_IN_COMPILE = 'nmr-compile';
+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 async function readBuildOutputState(monorepoRoot, config) {
+    const state = { missingPackages: [], digests: {} };
+    let packageDirs;
+    try {
+        packageDirs = getWorkspacePackageDirs(monorepoRoot);
+    }
+    catch {
+        return state;
+    }
+    const registry = buildWorkspaceRegistry(config);
+    if (JSON.stringify(registry['build']) !== JSON.stringify(getDefaultWorkspaceScripts()['build'])) {
+        return state;
+    }
+    for (const packageDir of packageDirs) {
+        if (!isProbeSubject(packageDir, registry)) {
+            continue;
+        }
+        const { build } = await loadWorkspaceConfig(packageDir);
+        const options = build?.extraIgnorePatterns === undefined ? {} : { extraIgnorePatterns: build.extraIgnorePatterns };
+        const name = path.relative(monorepoRoot, packageDir);
+        if (await hasBuildOutput(packageDir, options)) {
+            state.digests[name] = (await readBuildDigest(packageDir)) ?? '';
+        }
+        else {
+            state.missingPackages.push(name);
+        }
+    }
+    return state;
+}
+function isProbeSubject(packageDir, registry) {
+    const build = resolveScript('build', registry, packageDir, false);
+    if (build === undefined || build.origin.tier === 'package') {
+        return false;
+    }
+    const compile = resolveScript('compile', registry, packageDir, false);
+    return compile !== undefined && renderChain(compile.steps) === BUILT_IN_COMPILE;
+}

package/dist/esm/check-cache-delegation.d.ts

@@ -0,0 +1,27 @@
+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;
+    /** The channels on which the invocation's output runs, which every retention key that it records folds. */
+    channels: OutputChannels;
+    key: string;
+    retentionKey: string;
+    snapshot: TreeSnapshot;
+}
+/**
+ * Records the passes that the host earned, provided that the tree pushed to it is the tree on which the gate keyed,
+ * and that the working tree did not move while the host ran: a pass over any other tree says nothing about this one.
+ *
+ * Each valid entry of the host's pass manifest is recorded as a pass that the host earned at the entry's scope. It is
+ * keyed on this machine's inputs and the host's command string, so that an entry whose string differs from what would
+ * run here is never recalled, and its excerpts are keyed on this invocation's presentation, for which the host styled
+ * them. The invocation's own entry supplies only the retention of the invocation's pass, which is recorded last, so
+ * that a reader never sees a composite's pass ahead of its constituents' passes.
+ */
+export declare function recordDelegatedPass(plan: RunPlan, gate: Gate, hostRun: Extract<HostRunResult, {
+    kind: 'ran';
+}>): Promise<void>;

package/dist/esm/check-cache-delegation.js

@@ -0,0 +1,92 @@
+import path from 'node:path';
+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;
+    const { config, monorepoRoot } = context;
+    if (hostRun.treeId !== gate.snapshot.treeId) {
+        writeDebugNote(`not recording ${command}: the pushed tree is not the tree that the gate keyed on`, env, stderr);
+        return;
+    }
+    const currentRead = resolveTreeSnapshot({ monorepoRoot, env: {} });
+    if (!currentRead.ok) {
+        writeDebugNote(`not recording ${command}: ${currentRead.reason}`, env, stderr);
+        return;
+    }
+    if (currentRead.snapshot.treeId !== gate.snapshot.treeId) {
+        writeDebugNote(`not recording ${command}: the tree changed while it ran`, env, stderr);
+        return;
+    }
+    const entries = validatePassManifest({
+        checkCache: config.checkCache,
+        entries: hostRun.passes,
+        env,
+        monorepoRoot,
+        stderr,
+        treeId: gate.snapshot.treeId,
+        workspacePackageDirs: context.workspacePackageDirs,
+    });
+    const ownScope = formatManifestScope(monorepoRoot, anchorDir);
+    let ownReplay;
+    for (const entry of entries) {
+        if (entry.scope === ownScope && entry.command === command) {
+            if (entry.commandString === plan.commandString) {
+                ownReplay = entry.replay;
+            }
+            continue;
+        }
+        await recordLearnedPass(plan, gate, hostRun.host, entry);
+    }
+    await recordHostPass({
+        commandString: plan.commandString,
+        config,
+        durationMs: hostRun.durationMs,
+        env,
+        host: hostRun.host,
+        key: gate.key,
+        monorepoRoot,
+        ref: { anchorDir, command, monorepoRoot },
+        retainedOutput: hostRun.retainedOutput,
+        retention: composeRetention(gate.retentionKey, ownReplay, plan.runId),
+        snapshot: gate.snapshot,
+        stderr,
+    });
+}
+function composeRetention(key, replay, runId) {
+    return replay === undefined ? undefined : { key, replay, runId };
+}
+async function recordLearnedPass(plan, gate, host, entry) {
+    const { context, env, stderr } = plan.invocation;
+    const { monorepoRoot } = context;
+    const anchorDir = path.resolve(monorepoRoot, entry.scope);
+    const keyed = computeCacheKey({
+        anchorDir,
+        command: entry.command,
+        commandString: entry.commandString,
+        env,
+        monorepoRoot,
+        nmrVersion: VERSION,
+        snapshot: gate.snapshot,
+    });
+    if (!keyed.ok) {
+        writeDebugNote(`not recording ${entry.command} on ${host}: ${keyed.reason}`, env, stderr);
+        return;
+    }
+    await recordHostPass({
+        commandString: entry.commandString,
+        config: context.config,
+        durationMs: entry.durationMs,
+        env,
+        host,
+        key: keyed.key,
+        monorepoRoot,
+        ref: { anchorDir, command: entry.command, monorepoRoot },
+        retainedOutput: undefined,
+        retention: composeRetention(computeRetentionKey({ channels: gate.channels, env, passKey: keyed.key }), entry.replay, plan.runId),
+        snapshot: gate.snapshot,
+        stderr,
+    });
+}

package/dist/esm/check-cache-entries.d.ts

@@ -0,0 +1,109 @@
+import type { Writable } from 'node:stream';
+/** A recorded pass: what ran, on which tree, and how long it took. */
+export interface CheckCacheEntry {
+    /** The full cache key under which the pass was recorded; a hit is this key matching the key computed now. */
+    key: string;
+    treeHash: string;
+    headSha: string;
+    commandString: string;
+    nmrVersion: string;
+    nodeVersion: string;
+    durationMs: number;
+    /** ISO-8601 instant the pass completed. */
+    recordedAt: string;
+    /**
+     * The build digest that each covered package's output had when the pass was recorded. Build output is
+     * git-ignored, so the tree id cannot describe it; comparing these separates output built from this tree from
+     * output that another tree left behind.
+     */
+    buildDigests: Record<string, string>;
+    /** The host that earned a delegated pass, absent on a pass earned on this machine. */
+    host?: string;
+    /** What a skip replays in place of the run that it recalls, absent on a pass that retained nothing. */
+    retention?: Retention;
+}
+/** What locates one command's recorded pass at one scope, and the transcript beside it. */
+export interface EntryRef {
+    anchorDir: string;
+    command: string;
+    monorepoRoot: string;
+}
+/** One command's excerpt, attributed to the scope and the command that produced it. */
+export interface ReplayLine {
+    command: string;
+    excerpt: string;
+    scope: string;
+}
+/**
+ * What a recalled pass replays, the key certifying the excerpts describe this environment's output, and the
+ * run that last vouched for them.
+ *
+ * A list rather than one excerpt: a composite's entry contains its constituents' lines, and a nested one's are
+ * spliced into its parent's, after which the attribution cannot be re-derived from the entry that contains them.
+ *
+ * The witness admits a constituent's line into the assembly that its parent records: a run writes it when it
+ * records an excerpt, and restamps it when it recalls one and replays it.
+ */
+export interface Retention {
+    key: string;
+    replay: ReplayLine[];
+    runId: string;
+}
+/**
+ * Restamps a recalled entry's retention with the run that is replaying it, so that an excerpt certified by this
+ * run can join the assembly recorded by a composite above it.
+ *
+ * A recall certifies as surely as a recording does. Because the pass key matched, the excerpt describes this
+ * tree; because the caller calls this only when the retention key matched too, the excerpt also describes this
+ * presentation environment. Everything else the entry records stands -- the instant and the duration belong to
+ * the run that earned the pass, and a recall must not make it read as later or longer than it was.
+ *
+ * A cache that cannot be written is not worth failing a green run over: `certifyRetention` reports that failure
+ * in the debug note.
+ */
+export declare function certifyRetention(options: {
+    anchorDir: string;
+    command: string;
+    entry: CheckCacheEntry;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+    runId: string;
+    stderr: Writable;
+}): Promise<void>;
+/**
+ * Reads the entry recorded for one command at one scope, or `undefined` when there is none to trust.
+ *
+ * Retention is vouched for separately from the pass that contains it: an excerpt of a shape that this function
+ * cannot read is dropped, leaving a pass that skips cleanly and reports its verdict alone.
+ */
+export declare function readCheckCacheEntry(options: {
+    anchorDir: string;
+    command: string;
+    monorepoRoot: string;
+}): Promise<CheckCacheEntry | undefined>;
+/**
+ * Reads the whole output that one recorded pass retained, or `undefined` when it retained none.
+ *
+ * Held to nothing on its own: the entry beside it says which tree the bytes describe, and a caller
+ * that has not matched the entry's key is reading a transcript of some other tree.
+ */
+export declare function readTranscript(ref: EntryRef): Promise<string | undefined>;
+/**
+ * Makes the transcript beside one entry be exactly what this pass retained, removing what an earlier pass
+ * left when this one retained nothing.
+ *
+ * A composite retains nothing of its own, so without the removal a leaf's transcript would remain beside an
+ * entry that never produced it, and `--log` would date another run's bytes by this one's instant.
+ */
+export declare function recordTranscript(ref: EntryRef, transcript: string | undefined): Promise<void>;
+/** Removes every recorded pass for a monorepo, or for a standalone package outside one. */
+export declare function removeCheckCache(scopeDir: string): Promise<void>;
+/** Narrows a recorded replay line, whose three fields a rendered line uses in full. */
+export declare function isReplayLine(value: unknown): value is ReplayLine;
+/** Records a pass, replacing whatever this command last recorded at this scope. */
+export declare function writeCheckCacheEntry(options: {
+    anchorDir: string;
+    command: string;
+    entry: CheckCacheEntry;
+    monorepoRoot: string;
+}): Promise<void>;