@williamthorsen/nmr 0.42.0 → 0.44.0

package/.readyup/manifest.json

@@ -3,21 +3,99 @@
   "kits": [
     {
       "bundledDependencies": {
-        "@williamthorsen/toolbelt.errors": "0.8.2",
+        "@williamthorsen/toolbelt.errors": "0.8.3",
+        "@williamthorsen/toolbelt.filesystem": "0.9.3",
+        "@williamthorsen/toolbelt.terminal": "0.2.1",
+        "ansi-regex": "6.4.0",
+        "ansi-styles": "6.2.3",
+        "cli-truncate": "6.1.1",
+        "diff": "9.0.0",
+        "get-east-asian-width": "1.7.0",
+        "is-fullwidth-code-point": "5.1.0",
+        "slice-ansi": "9.0.1",
+        "string-width": "8.3.0",
+        "strip-ansi": "7.2.0",
+        "wrap-ansi": "10.0.2",
         "yaml": "2.9.1"
       },
       "checklists": [
-        "nmr"
+        "nmr",
+        "self-hosted runner"
       ],
       "esbuildVersion": "0.28.2",
       "inputs": [
         {
-          "hash": "50b5aac3",
+          "hash": "aed52073",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/cache-store.js"
+        },
+        {
+          "hash": "a5f44396",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/findPackageRoot.js"
+        },
+        {
+          "hash": "54384dca",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/gitOutputLimit.js"
+        },
+        {
+          "hash": "6b7d0243",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/hasErrnoCode.js"
+        },
+        {
+          "hash": "211453c6",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/hashWorkingTree.js"
+        },
+        {
+          "hash": "41232d10",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/helpers/workspace-patterns.js"
+        },
+        {
+          "hash": "1467293d",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/index.js"
+        },
+        {
+          "hash": "2507870d",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/parseArgs.js"
+        },
+        {
+          "hash": "a7efc38f",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/readPackageVersion.js"
+        },
+        {
+          "hash": "14547f78",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/terminal.js"
+        },
+        {
+          "hash": "3c395f31",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/updateManagedFile.js"
+        },
+        {
+          "hash": "2224ec3a",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/workspace.js"
+        },
+        {
+          "hash": "24bde686",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/writeFileWithCheck.js"
+        },
+        {
+          "hash": "aaeb1a84",
           "kind": "module",
           "path": "kits/default.ts"
         },
         {
-          "hash": "fa3a837f",
+          "hash": "747d941f",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -25,7 +103,12 @@
           ]
         },
         {
-          "hash": "9336f4c0",
+          "hash": "b23f5a52",
+          "kind": "module",
+          "path": "../src/config.ts"
+        },
+        {
+          "hash": "0fb883a1",
           "kind": "module",
           "path": "../src/default-scripts.ts"
         },
@@ -35,22 +118,82 @@
           "path": "../src/git-ignored-paths.ts"
         },
         {
-          "hash": "23646439",
+          "hash": "ae257d50",
+          "kind": "module",
+          "path": "../src/helpers/config-path.ts"
+        },
+        {
+          "hash": "47249ca4",
+          "kind": "module",
+          "path": "../src/helpers/findClosestName.ts"
+        },
+        {
+          "hash": "3efe4131",
+          "kind": "module",
+          "path": "../src/helpers/hook-name.ts"
+        },
+        {
+          "hash": "8850834f",
+          "kind": "module",
+          "path": "../src/helpers/package-json.ts"
+        },
+        {
+          "hash": "61629be6",
+          "kind": "module",
+          "path": "../src/helpers/readStringValues.ts"
+        },
+        {
+          "hash": "56d2bb48",
+          "kind": "module",
+          "path": "../src/helpers/type-guards.ts"
+        },
+        {
+          "hash": "78ca6bd4",
           "kind": "module",
           "path": "../src/resolve-scripts.ts"
         },
+        {
+          "hash": "6ae507a5",
+          "kind": "module",
+          "path": "../src/resolver.ts"
+        },
+        {
+          "hash": "c4b31275",
+          "kind": "module",
+          "path": "../src/steps.ts"
+        },
         {
           "hash": "19dec003",
           "kind": "module",
           "path": "../src/tiers.ts"
+        },
+        {
+          "hash": "faad986a",
+          "kind": "module",
+          "path": "../src/UserError.ts"
+        },
+        {
+          "hash": "857c630c",
+          "kind": "module",
+          "path": "../src/verbosity.ts"
+        },
+        {
+          "hash": "f08b6ff3",
+          "kind": "module",
+          "path": "../src/workspace-globs.ts"
+        },
+        {
+          "hash": "922e7155",
+          "kind": "module",
+          "path": "../src/workspace.ts"
         }
       ],
       "name": "default",
       "path": "kits/default.js",
       "readyupVersion": "0.40.0",
       "source": "kits/default.ts",
-      "sourceHash": "50b5aac3",
-      "targetHash": "3bc734de"
+      "sourceHash": "aaeb1a84",
+      "targetHash": "25b7edfb"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.44.0 — 2026-10-11
+
+### 🎉 Features
+
+- Enables Prettier's content-keyed cache in `nmr-fmt` (run by `nmr fmt` and `nmr fmt:check`), which skips each file whose content, Prettier version, resolved options, and lockfile are unchanged since a run that passed it, and adds `--no-cache` and `NMR_NO_CACHE=1` to bypass it. (#993)
+- Adds the `shouldRunInBackground` field to a composite element in `.config/nmr.config.ts`, which starts the step, runs the steps after it without waiting, prints the step's output whole after the step ends, and fails the composite if the step fails. (#1003)
+- Adds a `self-hosted runner` checklist to nmr's readyup kit, which reads the repo's GitHub settings through `gh`, recommends setting `CI_RUNS_ON` when a private repo with an online self-hosted runner and compatible workflows has not set it, and warns about each failing condition once the variable is set. (#1006)
+- Adds the root-only config key `selfHostedRunner.exempt`, a non-empty reason that stops the kit from recommending `CI_RUNS_ON` for a repo that qualifies for the self-hosted runners but stays off them. (#1006)
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Removes the zero-argument form of `getDefaultRootScripts` from the `@williamthorsen/nmr/scripts` export, which now requires the monorepo root so that it can read the declared workspaces. (#992)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `root:lint`, `root:lint:check`, and `root:lint:strict` linted every workspace outside `packages/` under the root ESLint config, by excluding each workspace package that `pnpm-workspace.yaml` declares, with its `!` exclusions honored, in place of the fixed `packages/**`. (#992)
+- Fixes the issue that `defineConfig({ mode: undefined })` emptied the `nmr upgrade` report, by translating a cleared `mode` into the `'default'` mode of taze (the upgrade tool that `nmr upgrade` runs), which follows the range that each dependency declares. (#1008)
+
+### ⚡ Performance
+
+- Sets `maxWorkers: 3` on every project built by `defineVitestConfig` and `defineRootVitestConfig` when the machine has 2 or fewer cores, such as GitHub's standard runner for a private repo, on which Vitest's default ran every test file serially on one worker. (#994)
+- Changes the default `check` and `check:strict` to start lint first and run it in the background, so that a local check, `nmr ci`, and `nmr prepush` no longer wait for type-aware lint to finish before typecheck, the format check, and the tests run. (#1003)
+
+### 📚 Documentation
+
+- Documents in `docs/vitest.md` that Vitest's `--maxWorkers` flag has no effect on a machine with 2 or fewer cores, and that `VITEST_MAX_WORKERS`, `--no-file-parallelism`, or `maxWorkers` in the `project` seam overrides the default there. (#994)
+
+## 0.43.0 — 2026-10-09
+
+### 🎉 Features
+
+- Extends `nmr-compile` to compile `.tsx` sources and to rewrite relative `.tsx` specifiers to `.js`, and leaves the JSX transform to the package's own tsconfig `jsx` option. (#988)
+
 ## 0.42.0 — 2026-10-08
 
 ### 🎉 Features

package/README.md

@@ -5,23 +5,28 @@
 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.42.0 (2026-10-08)
+## Release notes — v0.44.0 (2026-10-11)
 
 ### 🎉 Features
 
-- Adds the kit check `catalogued dependencies use catalog:`, which warns about every manifest, the root's included, that declares a literal version or range for a package listed by the default `catalog` or a named `catalogs` entry in `pnpm-workspace.yaml`, and exempts `peerDependencies` and specifiers that name a protocol, such as `workspace:` or `npm:`. (#958)
-- Adds the kit check `no package.json declares a workspaces field`, which warns about every `package.json` in the tree that declares `workspaces`, a field that pnpm ignores because it reads workspace globs only from `pnpm-workspace.yaml`. (#958)
-- Adds a `Package scripts:` section to the `nmr` listing, which shows each script declared by the current scope's `package.json` under a name that the active registry does not contain, hooks such as `build:pre` included and npm and pnpm lifecycle scripts excluded. (#960)
-- Makes Prettier a dependency of `@williamthorsen/nmr`, so that `pnpm dlx --package @williamthorsen/nmr nmr-fmt --check` (or `--write`) formats a git repository that has nothing installed, while a repository that installs its own Prettier keeps formatting with that copy. (#961)
-- Makes `nmr-fmt` apply the house config from `@williamthorsen/nmr/prettier`, shell plugin included, when Prettier does not find a config searching from the working directory, which also gives the house config to a repository whose only Prettier configs are in subdirectories below that directory. (#961)
-- Makes `typescript` an optional peer of `@williamthorsen/nmr`, so that installing nmr no longer requires it, and makes `nmr-compile` report a missing `typescript` together with the version range that it supports. (#961)
+- Enables Prettier's content-keyed cache in `nmr-fmt` (run by `nmr fmt` and `nmr fmt:check`), which skips each file whose content, Prettier version, resolved options, and lockfile are unchanged since a run that passed it, and adds `--no-cache` and `NMR_NO_CACHE=1` to bypass it. (#993)
+- Adds the `shouldRunInBackground` field to a composite element in `.config/nmr.config.ts`, which starts the step, runs the steps after it without waiting, prints the step's output whole after the step ends, and fails the composite if the step fails. (#1003)
+- Adds a `self-hosted runner` checklist to nmr's readyup kit, which reads the repo's GitHub settings through `gh`, recommends setting `CI_RUNS_ON` when a private repo with an online self-hosted runner and compatible workflows has not set it, and warns about each failing condition once the variable is set. (#1006)
+- Adds the root-only config key `selfHostedRunner.exempt`, a non-empty reason that stops the kit from recommending `CI_RUNS_ON` for a repo that qualifies for the self-hosted runners but stays off them. (#1006)
+
+### 🪦 Removed
+
+- 🚨 **Breaking:** Removes the zero-argument form of `getDefaultRootScripts` from the `@williamthorsen/nmr/scripts` export, which now requires the monorepo root so that it can read the declared workspaces. (#992)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that `nmr fmt` and `nmr fmt:check` aborted with a load failure when a file listed by git could not be stat'ed because of `EACCES` or `EPERM`, such as a tracked `.envrc` under a sandbox that denies reads of `.env*` files; `nmr-fmt` now skips each such file and names it on stderr. (#959)
-- Fixes the issue that `nmr-fmt` reported any other stat failure on a listed file, such as `ELOOP` from a symlink loop, as a load failure; the run now fails with an error that names the path. (#959)
-- Fixes the issue that `nmr-compile` failed with a `TypeError` under TypeScript 7, which it now rejects with an error naming the supported range, `>=5.7 <7`. (#961)
-- Fixes the issue that `nmr fmt` and `nmr fmt:check` failed in a repository that commits a symlink, because `nmr-fmt` passed the symlink to Prettier, which rejects an explicitly named symlink even when `.prettierignore` lists it. (#968)
+- Fixes the issue that `root:lint`, `root:lint:check`, and `root:lint:strict` linted every workspace outside `packages/` under the root ESLint config, by excluding each workspace package that `pnpm-workspace.yaml` declares, with its `!` exclusions honored, in place of the fixed `packages/**`. (#992)
+- Fixes the issue that `defineConfig({ mode: undefined })` emptied the `nmr upgrade` report, by translating a cleared `mode` into the `'default'` mode of taze (the upgrade tool that `nmr upgrade` runs), which follows the range that each dependency declares. (#1008)
+
+### ⚡ Performance
+
+- Sets `maxWorkers: 3` on every project built by `defineVitestConfig` and `defineRootVitestConfig` when the machine has 2 or fewer cores, such as GitHub's standard runner for a private repo, on which Vitest's default ran every test file serially on one worker. (#994)
+- Changes the default `check` and `check:strict` to start lint first and run it in the background, so that a local check, `nmr ci`, and `nmr prepush` no longer wait for type-aware lint to finish before typecheck, the format check, and the tests run. (#1003)
 <!-- /section:release-notes -->
 
 ## Installation
@@ -125,6 +130,8 @@ Scripts resolve through three tiers. Higher tiers override lower ones:
 
 Every `nmr X` invocation auto-wraps as the equivalent of `nmr X:pre && nmr X && nmr X:post`. Hooks are first-class scripts that resolve through the same three tiers as any other script (built-in defaults, then `.config/nmr.config.ts`, then per-package `package.json`). Wrapping is uniform: Nested invocations from composite expansion get their own hook treatment. A failing hook ends the sequence, and its exit code propagates.
 
+A composite runs its steps in series, except a step declared with `shouldRunInBackground`, which runs alongside the steps after it. The default `check` and `check:strict` run lint that way; [Running a step in the background](docs/scripts.md#running-a-step-in-the-background) covers how its output prints and how it fails.
+
 Extend `nmr build` with a pre-build step for every workspace package:
 
 ```ts
@@ -267,6 +274,8 @@ Wiring the sync to `postinstall` keeps it current without a hand-run command:
 
 nmr publishes a `readyup` kit that checks a consuming repo against the current release: the shared Vitest and Prettier configs, the workspace layout, the root script registry, the test-file conventions ([tier names](docs/vitest.md#test-tiers) and `__tests__` placement), that the repo's own suite gates them, that every `bin` target is a committed wrapper rather than build output that pnpm cannot link at install time, that `files` covers the output that each wrapper loads, that the root install scripts do not run `lefthook install` without `lefthook check-install`, and that the `package.json` files in the tree declare neither a `pnpm` field, from which pnpm 11 does not read any key, nor a `workspaces` field, which pnpm ignores. Those settings belong in `pnpm-workspace.yaml`, and `pnpx codemod run pnpm-v10-to-v11` moves the `pnpm` field's. It also checks that every manifest declares a package listed by a `pnpm-workspace.yaml` catalog as `catalog:` rather than as a literal version. A peer range is exempt, and a version that must differ belongs in a named catalog, referenced as `catalog:<name>`. The kit is included in the package, so it checks against the nmr version installed rather than whatever a repository ref happens to point at, and a tier added or renamed in nmr takes effect in the repo when it upgrades nmr. A repo that declares the [conventions check](docs/vitest.md#gating-the-test-file-conventions) gates both conventions in its own test run, and the kit then leaves the test files to that check.
 
+A second checklist, `self-hosted runner`, reads the repo's GitHub settings through `gh` and recommends setting `CI_RUNS_ON` to `"self-hosted"` when the repo is private, has an online `self-hosted` runner, does not pin a code-quality workflow older than v8 or override its `runs-on`, and runs Node.js and pnpm only after a step installs them and does not run `gh`, which the image lacks. Once the variable is set, the checklist warns about each of those conditions that fails. It skips when `gh` is not installed or not authenticated. A repo that qualifies but keeps its CI off the runners records why in the root config's [`selfHostedRunner.exempt`](docs/scripts.md#defineconfig-fields).
+
 Add `readyup` as a devDependency, then name nmr in its config:
 
 ```ts

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

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { findPackageRoot, readCacheEntry, resolveCacheEntryPath } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import { readPackageJson } from "../helpers/package-json.js";
-export const DEFAULT_ENTRY_GLOBS = ['src/**/*.ts'];
+export const DEFAULT_ENTRY_GLOBS = ['src/**/*.{ts,tsx}'];
 export const DEFAULT_IGNORE_PATTERNS = ['**/__fixtures__/**', '**/__mocks__/**', '**/__tests__/**', '**/test-utils/**'];
 export const DEFAULT_OUTDIR = 'dist/esm/';
 const BUILD_CACHE_TOOL = 'nmr-compile';

package/dist/esm/commands/build.js

@@ -13,7 +13,7 @@ const MINIMUM_TYPESCRIPT_MINOR = 7;
 const UNSUPPORTED_TYPESCRIPT_MAJOR = 7;
 const SUPPORTED_TYPESCRIPT_RANGE = `>=${MINIMUM_TYPESCRIPT_MAJOR}.${MINIMUM_TYPESCRIPT_MINOR} <${UNSUPPORTED_TYPESCRIPT_MAJOR}`;
 const INSTALL_TYPESCRIPT_GUIDANCE = "Install a version in that range as the 'typescript' peer dependency.";
-const TS_EXTENSION = '.ts';
+const TS_EXTENSIONS = ['.ts', '.tsx'];
 const JS_EXTENSION = '.js';
 let ts;
 export async function buildPackage(packageDir, options) {
@@ -401,5 +401,6 @@ function resolveScriptKind(file) {
     return file.endsWith('.d.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS;
 }
 function swapTypeScriptExtension(specifier) {
-    return specifier.endsWith(TS_EXTENSION) ? `${specifier.slice(0, -TS_EXTENSION.length)}${JS_EXTENSION}` : specifier;
+    const extension = TS_EXTENSIONS.find((candidate) => specifier.endsWith(candidate));
+    return extension === undefined ? specifier : `${specifier.slice(0, -extension.length)}${JS_EXTENSION}`;
 }

package/dist/esm/commands/fmt-cache.d.ts

@@ -0,0 +1,26 @@
+/** The directory, relative to the repository root, holding one Prettier cache file per scope. */
+export declare const FMT_CACHE_DIRECTORY: string;
+export interface PrepareFmtCacheOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    repositoryRoot: string;
+    shouldBypassCache: boolean;
+}
+export type PrepareFmtCacheResult = {
+    kind: 'cached';
+    location: string;
+} | {
+    kind: 'uncached';
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/**
+ * Resolves the Prettier cache file for this scope, after pruning cache files keyed to an outdated lockfile and
+ * discarding a corrupt one, or reports why the run goes uncached.
+ *
+ * The file name combines a hash of the scope with a fingerprint of the repository's lockfiles. Prettier keys
+ * entries by path relative to its working directory, so each scope needs a file of its own; Prettier's own key
+ * covers its version and the resolved options but not plugin code, which the lockfile fingerprint covers.
+ */
+export declare function prepareFmtCache(options: PrepareFmtCacheOptions): PrepareFmtCacheResult;

package/dist/esm/commands/fmt-cache.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { NO_CACHE_ENV_VAR } from "../check-cache.js";
+export const FMT_CACHE_DIRECTORY = path.join('node_modules', '.cache', 'prettier', 'nmr-fmt');
+const LOCKFILE_NAMES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+const NO_LOCKFILE_MARKER = 'nolock';
+const HASH_LENGTH = 16;
+const CACHE_FILE_PATTERN = /^([0-9a-f]{16})\.([0-9a-f]{16}|nolock)\.json$/;
+export function prepareFmtCache(options) {
+    const { cwd, env, repositoryRoot, shouldBypassCache } = options;
+    if (shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1')
+        return { kind: 'uncached' };
+    try {
+        if (statSync(path.join(repositoryRoot, 'node_modules'), { throwIfNoEntry: false })?.isDirectory() !== true) {
+            return { kind: 'uncached' };
+        }
+        const cacheDirectory = path.join(repositoryRoot, FMT_CACHE_DIRECTORY);
+        mkdirSync(cacheDirectory, { recursive: true });
+        const lockfileHash = hashLockfiles(repositoryRoot);
+        pruneOutdatedCacheFiles(cacheDirectory, lockfileHash);
+        const scope = path.relative(repositoryRoot, realpathSync(cwd)).split(path.sep).join('/');
+        const location = path.join(cacheDirectory, `${hash(scope)}.${lockfileHash}.json`);
+        if (isCorruptCacheFile(location))
+            rmSync(location, { force: true });
+        return { kind: 'cached', location };
+    }
+    catch (error) {
+        return { kind: 'failed', reason: describeError(error) };
+    }
+}
+function hash(input) {
+    return createHash('sha256').update(input).digest('hex').slice(0, HASH_LENGTH);
+}
+function hashLockfiles(repositoryRoot) {
+    const digest = createHash('sha256');
+    let hasLockfile = false;
+    for (const name of LOCKFILE_NAMES) {
+        const lockfilePath = path.join(repositoryRoot, name);
+        if (statSync(lockfilePath, { throwIfNoEntry: false })?.isFile() !== true)
+            continue;
+        digest.update(`${name}\0`).update(readFileSync(lockfilePath)).update('\0');
+        hasLockfile = true;
+    }
+    return hasLockfile ? digest.digest('hex').slice(0, HASH_LENGTH) : NO_LOCKFILE_MARKER;
+}
+function isCorruptCacheFile(location) {
+    let content;
+    try {
+        content = readFileSync(location, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    try {
+        JSON.parse(content);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function pruneOutdatedCacheFiles(cacheDirectory, lockfileHash) {
+    for (const name of readdirSync(cacheDirectory)) {
+        const match = CACHE_FILE_PATTERN.exec(name);
+        if (match !== null && match[2] !== lockfileHash) {
+            rmSync(path.join(cacheDirectory, name), { force: true });
+        }
+    }
+}

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

@@ -4,6 +4,8 @@ export interface FormatTargets {
     files: string[];
     /** Absolute paths to every `.prettierignore` governing the repository, root-most first. */
     ignorePaths: string[];
+    /** The repository's top-level directory, as git reports it. */
+    repositoryRoot: string;
     /** Listed paths that this process is denied access to, each with the errno code that its stat raised. */
     unreadableFiles: UnreadableFile[];
 }
@@ -20,7 +22,8 @@ export type ResolveTargetsResult = {
 };
 /**
  * Formats or checks the files that git reports for `cwd`, and returns the exit code to report. A repository
- * without a Prettier config of its own is formatted with the house config.
+ * without a Prettier config of its own is formatted with the house config. The run uses Prettier's content-keyed
+ * cache unless `--no-cache` or `NMR_NO_CACHE=1` bypasses it.
  *
  * Trailing arguments are git pathspecs, not Prettier flags; an unrecognized option is rejected rather
  * than passed along, since git would read it as a pathspec matching nothing and the run would report
@@ -46,6 +49,8 @@ export declare function resolveFormatTargets(cwd: string, pathspecs?: string[]):
 /** @internal */
 export interface RunPrettierOptions {
     cliPath: string;
+    /** Absolute path of the cache file to pass to Prettier; the run is uncached when it is absent. */
+    cacheLocation?: string | undefined;
     /** Passed as `--config`, which replaces Prettier's own config discovery. */
     configPath?: string | undefined;
     mode: FormatMode;

package/dist/esm/commands/fmt.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { hasErrnoCode, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { isObject } from "../helpers/type-guards.js";
+import { prepareFmtCache } from "./fmt-cache.js";
 const IGNORE_FILENAME = '.prettierignore';
 const LIST_FILES_ARGS = ['ls-files', '-z', '--cached', '--others', '--exclude-standard'];
 const IGNORE_FILE_PATHSPEC = `*${IGNORE_FILENAME}`;
@@ -15,7 +16,7 @@ const UNREADABLE_CODES = ['EACCES', 'EPERM'];
 const PRETTIER_PACKAGE = 'prettier';
 const DEFAULT_CONFIG_PATH = fileURLToPath(new URL(`../prettier-default-config${path.extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 const ARGUMENT_BUDGET_BYTES = 100_000;
-const USAGE = 'Usage: nmr-fmt (--check | --write) [pathspec...]';
+const USAGE = 'Usage: nmr-fmt (--check | --write) [--no-cache] [pathspec...]';
 const MODE_ARGS = {
     check: ['--check'],
     write: ['--list-different', '--write'],
@@ -32,7 +33,7 @@ export async function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${resolvedTargets.error}`);
         return 1;
     }
-    const { files, ignorePaths, unreadableFiles } = resolvedTargets.targets;
+    const { files, ignorePaths, repositoryRoot, unreadableFiles } = resolvedTargets.targets;
     for (const { file, code } of unreadableFiles) {
         process.stderr.write(`nmr-fmt: skipped ${file}, which cannot be read (${code})\n`);
     }
@@ -53,7 +54,17 @@ export async function runFmt(argv, cwd = process.cwd()) {
         reportError(`nmr-fmt: ${repositoryConfig.error}`);
         return 1;
     }
+    const cache = prepareFmtCache({
+        cwd,
+        env: process.env,
+        repositoryRoot,
+        shouldBypassCache: parsedArgs.shouldBypassCache,
+    });
+    if (cache.kind === 'failed') {
+        process.stderr.write(`nmr-fmt: running without the Prettier cache: ${cache.reason}\n`);
+    }
     return runPrettier({
+        cacheLocation: cache.kind === 'cached' ? cache.location : undefined,
         cliPath: cli.cliPath,
         configPath: repositoryConfig.found ? undefined : DEFAULT_CONFIG_PATH,
         mode: parsedArgs.mode,
@@ -99,6 +110,7 @@ export function resolveFormatTargets(cwd, pathspecs = []) {
         targets: {
             files: files.toSorted(),
             ignorePaths: dedupe([path.join(repositoryRoot, IGNORE_FILENAME), ...discoveredIgnorePaths]),
+            repositoryRoot,
             unreadableFiles,
         },
     };
@@ -117,8 +129,13 @@ function classifyListedFile(cwd, file) {
 }
 function parseFmtArgs(argv) {
     let mode;
+    let shouldBypassCache = false;
     const pathspecs = [];
     for (const arg of argv) {
+        if (arg === '--no-cache') {
+            shouldBypassCache = true;
+            continue;
+        }
         if (arg === '--check' || arg === '--write') {
             const requestedMode = arg === '--check' ? 'check' : 'write';
             if (mode !== undefined && mode !== requestedMode) {
@@ -135,7 +152,7 @@ function parseFmtArgs(argv) {
     if (mode === undefined) {
         return { ok: false, error: 'Pass --check or --write.' };
     }
-    return { ok: true, mode, pathspecs };
+    return { ok: true, mode, pathspecs, shouldBypassCache };
 }
 function resolvePrettierCli(cwd) {
     const missingResult = {
@@ -172,12 +189,15 @@ async function findRepositoryConfig(manifestPath, cwd) {
     }
 }
 export function runPrettier(options) {
-    const { cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES } = options;
+    const { cacheLocation, cliPath, configPath, mode, files, ignorePaths, cwd, budgetBytes = ARGUMENT_BUDGET_BYTES, } = options;
     const prettierArgs = [
         cliPath,
         ...(configPath === undefined ? [] : ['--config', configPath]),
         '--ignore-unknown',
         ...ignorePaths.flatMap((ignorePath) => ['--ignore-path', ignorePath]),
+        ...(cacheLocation === undefined
+            ? []
+            : ['--cache', '--cache-strategy', 'content', '--cache-location', cacheLocation]),
         ...MODE_ARGS[mode],
     ];
     let firstFailureStatus = 0;

package/dist/esm/config.js

@@ -20,7 +20,7 @@ import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
 const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'devBin', 'output', 'rootScripts', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'devBin', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -33,7 +33,8 @@ const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.works
 const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
-const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments'];
+const RECOGNIZED_SELF_HOSTED_RUNNER_KEYS = ['exempt'];
+const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments', 'shouldRunInBackground'];
 const RETIRED_STEP_KEYS = new Map([['declinesArgs', 'shouldDeclineArguments']]);
 function isScriptRecord(value) {
     if (!isObject(value))
@@ -51,8 +52,7 @@ function isScriptElement(value) {
         return true;
     if (!isObject(value) || typeof value['run'] !== 'string')
         return false;
-    const shouldDeclineArguments = value['shouldDeclineArguments'];
-    return shouldDeclineArguments === undefined || typeof shouldDeclineArguments === 'boolean';
+    return isOptionalBoolean(value['shouldDeclineArguments']) && isOptionalBoolean(value['shouldRunInBackground']);
 }
 function validateScriptField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
@@ -61,7 +61,8 @@ function validateScriptField(value, fieldName, configPath) {
     const scripts = value[fieldName];
     if (!isScriptRecord(scripts)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | element[]>, ` +
-            'where an element is a command string or `{ run: string, shouldDeclineArguments?: boolean }`');
+            'where an element is a command string or ' +
+            '`{ run: string, shouldDeclineArguments?: boolean, shouldRunInBackground?: boolean }`');
     }
     assertValidElements(scripts, fieldName, configPath);
     return scripts;
@@ -85,6 +86,9 @@ function assertValidElements(scripts, fieldName, configPath) {
         }
     }
 }
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
@@ -132,6 +136,21 @@ function validateCheckCacheField(value, configPath) {
     }
     return config;
 }
+function validateSelfHostedRunnerField(value, configPath) {
+    const selfHostedRunner = value['selfHostedRunner'];
+    if (selfHostedRunner === undefined) {
+        return undefined;
+    }
+    if (!isObject(selfHostedRunner)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`selfHostedRunner\` must be an object`);
+    }
+    assertRecognizedKeys(selfHostedRunner, RECOGNIZED_SELF_HOSTED_RUNNER_KEYS, configPath, 'selfHostedRunner.');
+    const exempt = selfHostedRunner['exempt'];
+    if (typeof exempt !== 'string' || exempt.trim() === '') {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`selfHostedRunner.exempt\` must be a non-empty string giving the reason`);
+    }
+    return { exempt };
+}
 function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     const { checkCache } = config;
     if (checkCache === undefined || !isMonorepoRoot(baseDir)) {
@@ -145,7 +164,7 @@ function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
             'which is never gated on its own: It runs as part of the chain of the command that it wraps.');
     }
     const registeredNames = new Set([
-        ...Object.keys(buildRootRegistry(config)),
+        ...Object.keys(buildRootRegistry(config, baseDir)),
         ...Object.keys(buildWorkspaceRegistry(config)),
     ]);
     const missingEntries = entries.filter(({ command }) => !registeredNames.has(command));
@@ -250,6 +269,9 @@ function validateConfig(value, configPath, baseDir) {
     const rootScripts = validateScriptField(value, 'rootScripts', configPath);
     if (rootScripts)
         config.rootScripts = rootScripts;
+    const selfHostedRunner = validateSelfHostedRunnerField(value, configPath);
+    if (selfHostedRunner)
+        config.selfHostedRunner = selfHostedRunner;
     assertResolvableCheckCacheCommands(config, configPath, baseDir);
     return config;
 }