@williamthorsen/nmr 0.35.0 → 0.37.0

package/agents/README.md

@@ -11,7 +11,7 @@ A line earns a place in it only if both hold:
 1. **It is absent from nmr's own output.** Bare `nmr` already prints the flags, every command, and the shell command each resolves to; failing checks already name their own fix. Repeating any of that costs launch tokens to say something the agent will be told anyway, at the moment it matters.
 2. **The obvious action goes wrong without it.** Guidance that prevents a silent mistake earns its place; guidance that prevents a mistake the next error message would diagnose does not.
 
-Everything else belongs in `packages/nmr/README.md`, reachable on demand at `node_modules/@williamthorsen/nmr/README.md`, with a pointer from the cheatsheet naming the topic so an agent knows to look. When adding a feature, document it there and extend that pointer rather than the cheatsheet.
+Everything else belongs in the topic document under `packages/nmr/docs/` that covers it, reachable on demand at `node_modules/@williamthorsen/nmr/docs/`, with a pointer from the cheatsheet naming the topic and its document so an agent knows where to look. When adding a feature, document it there and extend that pointer rather than the cheatsheet.
 
 ## Constraints on rulebook bodies
 

package/agents/guidance/rulebooks/nmr.md

@@ -13,5 +13,5 @@ delivery: ambient
 - A check that already passed on the current working tree skips, printing `⏭️ <scope>: <command>: passed …` and, where the recalled run left one, `— replayed: <excerpt>` of what that run concluded. Any edit, addition, or deletion re-runs it, so read the replayed excerpt rather than paying for the answer again: never pass `--no-cache` to get a "real" run, which costs the command's full runtime to reach the same answer. Its one use is a file rather than an exit status -- a skipped command writes none, so a fresh `coverage/` needs `nmr --no-cache test:coverage`. A composite replays its constituents' excerpts, each attributed as `<scope>: <command>: <excerpt>` and cut at the line's ceiling where there are too many to fit. A skip carrying no excerpt is one whose run wrote to a terminal, or one whose constituents recorded none.
 - `nmr --log <command>` prints the whole run behind that excerpt -- up to 256 KiB, led by when it was recorded, how long it ran, and the command string that produced it -- so output you need in full is a recording to read rather than a run to pay for again. It runs nothing, and it is held to the tree rather than to the terminal: a recording a piped run made prints for a reader at one. A composite prints its constituents' excerpts, so the transcript of one of them is `nmr -F <pkg> --log <command>` or that constituent's own name. Nothing to show is said on one line and exits non-zero, naming which it is.
 - Every command nmr runs reports one line -- `✅ <scope>: <command>: passed in 12.4s`, `❌ … failed in 1.2s (exit 1)`, `⏭️ … passed 4m ago on this tree`, or `⛔ … skipped, the override is empty` -- and a composite reports alongside every command it expands into. The lines print in every verbosity, so `-q` is the low-noise way to run rather than a silent one: it withholds the output of the commands nmr runs and keeps nmr's own verdicts, which is how a pass, a cached skip, and a `""`/`":"` override stay distinguishable. 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 the test reaches -- `tool` (a program the environment supplies), `localhost` (a service 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 --packages` reports the misspelt tier alone.
-- The rest is in `node_modules/@williamthorsen/nmr/README.md`: pre/post hooks (every `nmr X` auto-wraps as `nmr X:pre && nmr X && nmr X:post`), script overrides and their `""`/`":"` skip values, `nmr upgrade` ceilings (report-only until `nmr upgrade --write`), the `nmr-compile` build (there is no repo-local build script), the test tiers' timeout budgets and the `tiers` seam that raises one, which script reaches which tier, and the check-result cache's key, the retention key a replayed excerpt is additionally held to, the retention ceiling `--log` prints within, its `checkCache` config, and every condition that disables it.
+- 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 the test reaches -- `tool` (a program the environment supplies), `localhost` (a service 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 --packages` reports both and warns that the check is missing.
+- 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 (there is no repo-local build script); `vitest.md` for the test tiers' timeout budgets, the `tiers` seam that raises one, and which script reaches which tier; and `check-cache.md` for the check-result cache's key, the retention key a replayed excerpt is additionally held to, the retention ceiling `--log` prints within, its `checkCache` config, and every condition that disables it.

package/dist/esm/commands/build.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { readCacheEntry, writeCacheEntry } from '@williamthorsen/nmr-core';
 import { glob } from 'glob';
 import * as ts from 'typescript';
-import { resolveConfigPath } from "../config.js";
+import { resolveConfigPath } from "../helpers/config-path.js";
 import { DEFAULT_ENTRY_GLOBS, DEFAULT_IGNORE_PATTERNS, DEFAULT_OUTDIR, hasExpectedBuildOutput, resolveBuildCachePath, resolveScratchDirs, resolveToolchainFingerprint, } from "./build-output.js";
 const PACKAGE_ICON = '📦';
 const SKIPPED_ICON = '⏭️';

package/dist/esm/config.d.ts

@@ -1,12 +1,4 @@
 import type { NmrConfig } from './types.js';
-/** The config's path relative to the directory holding it, for a message composed without one in hand. */
-export declare const CONFIG_RELATIVE_PATH: string;
-/**
- * Resolves the config-file path for a directory, whether that is the monorepo root or a package.
- * Callers that only need to know whether a config exists -- the build, which folds it into its cache digest -- go
- * through this rather than spelling the path again, so that the two cannot drift into hashing a file nothing reads.
- */
-export declare function resolveConfigPath(baseDir: string): string;
 /**
  * Loads the nmr configuration from `.config/nmr.config.ts` under `baseDir`, which is the monorepo root for
  * the repo-wide config and a package directory for the workspace tier. Returns an empty config if the file

package/dist/esm/config.js

@@ -7,15 +7,16 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { existsSync } from 'node:fs';
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { resolveConfigPath } from "./helpers/config-path.js";
+import { findClosestName } from "./helpers/findClosestName.js";
+import { isHookName } from "./helpers/hook-name.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
+import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
-const CONFIG_FILENAME = 'nmr.config.ts';
-const CONFIG_DIR = '.config';
-export const CONFIG_RELATIVE_PATH = path.join(CONFIG_DIR, CONFIG_FILENAME);
+import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
 const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
@@ -33,9 +34,6 @@ const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
 const RECOGNIZED_STEP_KEYS = ['declinesArgs', 'run'];
-export function resolveConfigPath(baseDir) {
-    return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
-}
 function isScriptRecord(value) {
     if (!isObject(value))
         return false;
@@ -132,6 +130,64 @@ function validateCheckCacheField(value, configPath) {
     }
     return config;
 }
+function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
+    const { checkCache } = config;
+    if (checkCache === undefined || !isMonorepoRoot(baseDir)) {
+        return;
+    }
+    const fields = ['excludeCommands', 'extraCommands'];
+    const entries = fields.flatMap((field) => (checkCache[field] ?? []).map((command) => ({ command, field })));
+    const hook = entries.find(({ command }) => isHookName(command));
+    if (hook !== undefined) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${hook.field}\` names the hook \`${hook.command}\`, ` +
+            'which is never gated on its own: it runs as part of the chain of the command it wraps.');
+    }
+    const registered = new Set([
+        ...Object.keys(buildRootRegistry(config)),
+        ...Object.keys(buildWorkspaceRegistry(config)),
+    ]);
+    const missing = entries.filter(({ command }) => !registered.has(command));
+    if (missing.length === 0) {
+        return;
+    }
+    const declared = readDeclaredScriptNames(baseDir);
+    const unresolvable = missing.find(({ command }) => !declared.has(command));
+    if (unresolvable === undefined) {
+        return;
+    }
+    const closest = findClosestName(unresolvable.command, [...registered, ...declared]);
+    throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${unresolvable.field}\` names no command: ` +
+        `\`${unresolvable.command}\`.${closest === undefined ? '' : ` Did you mean \`${closest}\`?`}`);
+}
+function readDeclaredScriptNames(monorepoRoot) {
+    let packageDirs;
+    try {
+        packageDirs = getWorkspacePackageDirs(monorepoRoot);
+    }
+    catch {
+        packageDirs = [];
+    }
+    const names = new Set();
+    const dirs = [monorepoRoot, ...packageDirs];
+    for (const dir of dirs) {
+        const scripts = readPackageScripts(dir);
+        for (const name of Object.keys(scripts)) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+function readPackageScripts(packageDir) {
+    try {
+        return readPackageJsonScripts(packageDir) ?? {};
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            return {};
+        }
+        throw error;
+    }
+}
 function validateOutputField(value, configPath) {
     const output = value['output'];
     if (output === undefined) {
@@ -168,7 +224,7 @@ function validateStringRecordField(value, fieldName, configPath) {
     }
     return value[fieldName];
 }
-function validateConfig(value, configPath) {
+function validateConfig(value, configPath, baseDir) {
     if (!isObject(value)) {
         throw new UserError(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
     }
@@ -192,6 +248,7 @@ function validateConfig(value, configPath) {
     const rootScripts = validateScriptField(value, 'rootScripts', configPath);
     if (rootScripts)
         config.rootScripts = rootScripts;
+    assertResolvableCheckCacheCommands(config, configPath, baseDir);
     return config;
 }
 export async function loadConfig(baseDir) {
@@ -201,7 +258,7 @@ export async function loadConfig(baseDir) {
     }
     const imported = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
     const loaded = isObject(imported) ? imported['default'] : undefined;
-    return validateConfig(loaded, configPath);
+    return validateConfig(loaded, configPath, baseDir);
 }
 export async function loadRootConfig(monorepoRoot) {
     const config = await loadConfig(monorepoRoot);

package/dist/esm/context.d.ts

@@ -3,6 +3,8 @@ export interface ResolvedContext {
     monorepoRoot: string;
     isRoot: boolean;
     packageDir?: string;
+    /** The workspace's package directories, resolved once here rather than swept for again by each reader. */
+    workspacePackageDirs: string[];
     config: NmrConfig;
 }
 /**

package/dist/esm/context.js

@@ -24,6 +24,7 @@ export async function resolveContext(cwd) {
         monorepoRoot,
         isRoot: packageDir === undefined,
         ...(packageDir !== undefined && { packageDir }),
+        workspacePackageDirs: workspaceDirs,
         config,
     };
 }

package/dist/esm/help.js

@@ -5,7 +5,7 @@ export function generateHelp(config, packageDir, useRoot) {
         'Usage: nmr [flags] <command> [args...]',
         '',
         'Flags:',
-        '  -F, --filter <pattern>   Run command in matching packages',
+        '  -F, --filter <pattern>   Run command in packages whose manifest name matches',
         '  -R, --recursive          Run command in all packages',
         '  -w, --workspace-root     Use root scripts, running at the monorepo root',
         "  -q, --quiet              Suppress command output, keeping nmr's verdicts",

package/dist/esm/helpers/config-path.d.ts

@@ -0,0 +1,8 @@
+/** The config's path relative to the directory holding it, for a message composed without one in hand. */
+export declare const CONFIG_RELATIVE_PATH: string;
+/**
+ * Resolves the config-file path for a directory, whether that is the monorepo root or a package.
+ * Callers that only need to know whether a config exists -- the build, which folds it into its cache digest -- go
+ * through this rather than spelling the path again, so that the two cannot drift into hashing a file nothing reads.
+ */
+export declare function resolveConfigPath(baseDir: string): string;

package/dist/esm/helpers/config-path.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+const CONFIG_DIR = '.config';
+const CONFIG_FILENAME = 'nmr.config.ts';
+export const CONFIG_RELATIVE_PATH = path.join(CONFIG_DIR, CONFIG_FILENAME);
+export function resolveConfigPath(baseDir) {
+    return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
+}

package/dist/esm/helpers/filter-selection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Asks pnpm what a `-F` pattern selects, so an invocation that would select nothing is caught before it
+ * delegates, and one selecting several packages is told from one selecting a single package.
+ *
+ * pnpm's own selector answers rather than a matcher of nmr's: `-F` means the whole selector language, names
+ * and globs alongside `./path`, `{dir}`, `pkg...`, `!negation`, and `[since]`, and a matcher here would leave
+ * every form but the simplest silently unchecked.
+ *
+ * Runs from the monorepo root, where the delegate runs, so a path pattern resolves against the same directory
+ * in the probe as in the run it stands in for.
+ *
+ * The listing counts the root project wherever the filter leaves it standing, while the `exec` a delegation
+ * composes runs there only where the pattern selects the root positively: `-F '!./packages/*'` lists the root
+ * and executes nowhere. A listing of the root alone is therefore the one reading the listing cannot settle,
+ * and it is put to `exec` itself. Every other listing settles on its own, and counts the packages beside the
+ * root: two of them run in two scopes, while one beside the root may run in that package alone.
+ */
+export declare function readFilterSelection(pattern: string, monorepoRoot: string): FilterSelection;
+/**
+ * Reduces a listing to what it proves about the selection.
+ *
+ * Every outcome the probe cannot read resolves to `unresolved`, which claims nothing about the selection, and the
+ * invocation delegates as it would have. A pattern pnpm rejects rather than resolves, such as a bad git ref in
+ * a changed-since selector, is pnpm's to report, and reporting it here as a match failure would name a
+ * different fault than the one the user has.
+ */
+export declare function interpretSelectionProbe(probe: SelectionProbe, monorepoRoot: string): ProbeReading;
+/**
+ * Reduces a marked delegate run to what it proves: a scope that wrote the marker is a scope the run reached. The
+ * run is made only for a listing of the root alone, so that scope is the only one.
+ */
+export declare function interpretDelegateProbe(probe: SelectionProbe): FilterSelection;
+/** What a `-F` pattern selected, as far as pnpm could be asked. `multiple` is two or more packages beside the root. */
+export type FilterSelection = 'empty' | 'multiple' | 'single' | 'unresolved';
+/** What a listing proves, `root-only` being the reading that only the delegate can settle. */
+export type ProbeReading = FilterSelection | 'root-only';
+/** The part of a probe's completion a selection is read from. */
+export interface SelectionProbe {
+    error: Error | undefined;
+    status: number | null;
+    stdout: string;
+}

package/dist/esm/helpers/filter-selection.js

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { isObject } from "./type-guards.js";
+const SELECTION_MARKER = 'nmr-selected-scope';
+export function readFilterSelection(pattern, monorepoRoot) {
+    const listing = spawnSync('pnpm', ['ls', '--filter', pattern, '--depth', '-1', '--json'], {
+        cwd: monorepoRoot,
+        encoding: 'utf8',
+    });
+    const reading = interpretSelectionProbe({ error: listing.error, status: listing.status, stdout: listing.stdout }, monorepoRoot);
+    return reading === 'root-only' ? readDelegateSelection(pattern, monorepoRoot) : reading;
+}
+export function interpretSelectionProbe(probe, monorepoRoot) {
+    if (probe.error !== undefined || probe.status !== 0) {
+        return 'unresolved';
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(probe.stdout);
+    }
+    catch {
+        return 'unresolved';
+    }
+    if (!Array.isArray(parsed)) {
+        return 'unresolved';
+    }
+    if (parsed.length === 0) {
+        return 'empty';
+    }
+    const packageCount = parsed.filter((entry) => !isRootEntry(entry, monorepoRoot)).length;
+    if (packageCount === 0) {
+        return 'root-only';
+    }
+    return packageCount === 1 ? 'single' : 'multiple';
+}
+export function interpretDelegateProbe(probe) {
+    if (probe.error !== undefined || probe.status !== 0) {
+        return 'unresolved';
+    }
+    return probe.stdout.includes(SELECTION_MARKER) ? 'single' : 'empty';
+}
+function isRootEntry(entry, monorepoRoot) {
+    if (!isObject(entry) || typeof entry['path'] !== 'string') {
+        return false;
+    }
+    return readRealPath(entry['path']) === readRealPath(monorepoRoot);
+}
+function readRealPath(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function readDelegateSelection(pattern, monorepoRoot) {
+    const probe = spawnSync('pnpm', ['--filter', pattern, 'exec', process.execPath, '--eval', `process.stdout.write('${SELECTION_MARKER}')`], { cwd: monorepoRoot, encoding: 'utf8' });
+    return interpretDelegateProbe({ error: probe.error, status: probe.status, stdout: probe.stdout });
+}

package/dist/esm/helpers/findClosestName.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Finds the candidate closest to a name, or `undefined` where none is near enough to be worth naming.
+ *
+ * The ceiling scales with the name's length, so a short name admits one slip and a long one a few. A fixed
+ * ceiling would either miss a typo in `root:test:coverage` or offer `fix` for `ci`.
+ */
+export declare function findClosestName(name: string, candidates: Iterable<string>): string | undefined;

package/dist/esm/helpers/findClosestName.js

@@ -0,0 +1,38 @@
+export function findClosestName(name, candidates) {
+    const ceiling = Math.max(1, Math.floor(name.length / 4));
+    let closest;
+    let shortest = Infinity;
+    for (const candidate of candidates) {
+        const distance = measureDistance(name, candidate);
+        if (distance < shortest) {
+            shortest = distance;
+            closest = candidate;
+        }
+    }
+    return shortest <= ceiling ? closest : undefined;
+}
+function measureDistance(first, second) {
+    if (first.length === 0 || second.length === 0) {
+        return Math.max(first.length, second.length);
+    }
+    let previous = Array.from({ length: second.length + 1 }, (_unused, column) => column);
+    let current = Array.from({ length: second.length + 1 }, () => 0);
+    for (let row = 1; row <= first.length; row += 1) {
+        current[0] = row;
+        for (let column = 1; column <= second.length; column += 1) {
+            const substitution = readCell(previous, column - 1) + (first[row - 1] === second[column - 1] ? 0 : 1);
+            current[column] = Math.min(readCell(current, column - 1) + 1, readCell(previous, column) + 1, substitution);
+        }
+        const completed = current;
+        current = previous;
+        previous = completed;
+    }
+    return readCell(previous, second.length);
+}
+function readCell(row, index) {
+    const value = row[index];
+    if (value === undefined) {
+        throw new RangeError(`No cell at index ${index} in a row of ${row.length}`);
+    }
+    return value;
+}

package/dist/esm/helpers/package-json.js

@@ -1,9 +1,9 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { CONFIG_RELATIVE_PATH } from "../config.js";
 import { UserError } from "../UserError.js";
 import { isMonorepoRoot } from "../workspace.js";
+import { CONFIG_RELATIVE_PATH } from "./config-path.js";
 import { readStringValues } from "./readStringValues.js";
 import { isObject } from "./type-guards.js";
 export const DEPENDENCY_FIELDS = [

package/dist/esm/runCli.js

@@ -2,10 +2,12 @@ import path from 'node:path';
 import { readPackageVersion, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
-import { resolveConfigPath } from "./config.js";
 import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
+import { resolveConfigPath } from "./helpers/config-path.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
+import { readFilterSelection } from "./helpers/filter-selection.js";
+import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { resolvePackageJsonPath } from "./helpers/package-json.js";
 import { composeTranscript } from "./helpers/transcript.js";
@@ -18,8 +20,10 @@ import { composeNmrStep, findNmrCrossing, renderChain } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
+import { readWorkspacePackageNames } from "./workspace.js";
 const VERSION = readPackageVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
+const NAME_CEILING = 10;
 const NAMED_ESCAPES = new Map([
     ['\n', String.raw `\n`],
     ['\r', String.raw `\r`],
@@ -88,7 +92,7 @@ export async function runCli(options) {
     };
     const delegation = composeDelegation({ childEnv, command, parsed });
     if (delegation !== undefined) {
-        return runSteps([delegation.step], context.monorepoRoot, { ...runOptions, env: delegation.env });
+        return runDelegation({ context, delegation, parsed, runOptions, stderr });
     }
     const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
     assertNoSelfReference({
@@ -346,6 +350,58 @@ function findArgError(parsed) {
     }
     return undefined;
 }
+function findEmptySelectionRefusal(options) {
+    const { context, parsed, selection } = options;
+    if (parsed.filter !== undefined) {
+        if (selection !== 'empty') {
+            return undefined;
+        }
+        return formatEmptyFilterError(parsed.filter, readWorkspacePackageNames(context.workspacePackageDirs));
+    }
+    return context.workspacePackageDirs.length === 0 ? formatEmptyWorkspaceError() : undefined;
+}
+function formatEmptyFilterError(pattern, names) {
+    const rejection = `-F/--filter matched no workspace: \`${pattern}\`.`;
+    if (pattern.startsWith('!')) {
+        return `${rejection} A pattern beginning with \`!\` excludes what it matches, and this one leaves no package standing.`;
+    }
+    if (pattern.includes('[')) {
+        return `${rejection} A pattern carrying \`[<ref>]\` selects the packages changed since a git ref, and none has changed.`;
+    }
+    if (pattern.startsWith('.') || pattern.startsWith('/') || pattern.startsWith('{')) {
+        return (`${rejection} ` +
+            'A pattern written `./dir`, `/dir`, or `{dir}` selects the packages under a directory, ' +
+            'and no package sits under this one.');
+    }
+    return (`${rejection} A pattern matches a package's manifest \`name\`, ` +
+        `not its directory name.${suggestWorkspaceNames(pattern, names)}`);
+}
+function formatEmptyWorkspaceError() {
+    return ('-R/--recursive matched no workspace: pnpm-workspace.yaml declares no package directory, ' +
+        'so there is no scope to fan out to.');
+}
+function suggestWorkspaceNames(pattern, names) {
+    if (names.length === 0) {
+        return '';
+    }
+    const containing = names.filter((name) => name.toLowerCase().includes(pattern.toLowerCase()));
+    if (containing.length > 0) {
+        return ` Did you mean ${renderNames(containing)}?`;
+    }
+    const closest = findClosestName(pattern, names);
+    if (closest !== undefined) {
+        return ` Did you mean \`${closest}\`?`;
+    }
+    return ` The workspace declares ${renderNames(names)}.`;
+}
+function renderNames(names) {
+    const shown = names
+        .slice(0, NAME_CEILING)
+        .map((name) => `\`${name}\``)
+        .join(', ');
+    const remainder = names.length - NAME_CEILING;
+    return remainder > 0 ? `${shown}, and ${remainder} more` : shown;
+}
 function findNoOpReason(resolvedCommand) {
     if (resolvedCommand === '') {
         return 'empty-override';
@@ -446,7 +502,7 @@ function parseArgs(args) {
         if (arg === '-F' || arg === '--filter') {
             i++;
             const filterValue = args[i];
-            if (filterValue === undefined) {
+            if (!filterValue) {
                 return { ok: false, error: '-F/--filter requires a pattern argument' };
             }
             parsed.filter = filterValue;
@@ -642,6 +698,18 @@ function resolveCacheKey(options) {
     }
     return result.key;
 }
+async function runDelegation(options) {
+    const { context, delegation, parsed, runOptions, stderr } = options;
+    const selection = parsed.filter === undefined ? undefined : readFilterSelection(parsed.filter, context.monorepoRoot);
+    const refusal = findEmptySelectionRefusal({ context, parsed, selection });
+    if (refusal !== undefined) {
+        reportError(refusal, stderr);
+        return { exitCode: 1 };
+    }
+    const shouldWithholdInput = parsed.filter === undefined || selection === 'multiple';
+    const step = shouldWithholdInput ? { ...delegation.step, shouldWithholdInput } : delegation.step;
+    return runSteps([step], context.monorepoRoot, { ...runOptions, env: delegation.env });
+}
 async function runGated(options) {
     const { anchorDir, command, commandString, env, key, monorepoRoot, snapshot, stderr, stdout } = options;
     const quiet = options.runOptions.quiet === true;

package/dist/esm/runner.js

@@ -39,16 +39,16 @@ export async function runSteps(steps, cwd, options) {
     return { exitCode: 0, ...composeRetainedOutput(parts, isCaptureWhole) };
 }
 export async function runCommand(command, cwd, options) {
-    return runSpawned({ args: [], file: command, useShell: true }, cwd, options);
+    return runSpawned({ args: [], file: command, input: 'inherit', useShell: true }, cwd, options);
 }
-async function runSpawned({ args, file, useShell }, cwd, options) {
+async function runSpawned({ args, file, input, useShell }, cwd, options) {
     const quiet = options.quiet === true;
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
     const env = options.env ?? process.env;
     const child = spawn(file, args, {
         shell: useShell,
-        stdio: ['inherit', options.channels.stdout, options.channels.stderr],
+        stdio: [input, options.channels.stdout, options.channels.stderr],
         cwd,
         env,
     });
@@ -78,13 +78,14 @@ async function runSpawned({ args, file, useShell }, cwd, options) {
 function runStep(step, cwd, options) {
     const { quiet, stderr, stdout } = options;
     if (step.kind === 'opaque') {
-        return runSpawned({ args: [], file: step.command, useShell: true }, cwd, {
+        return runSpawned({ args: [], file: step.command, input: 'inherit', useShell: true }, cwd, {
             ...options,
             channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
         });
     }
     const [file, ...args] = step.argv;
-    return runSpawned({ args, file, useShell: false }, cwd, {
+    const input = step.shouldWithholdInput === true ? 'ignore' : 'inherit';
+    return runSpawned({ args, file, input, useShell: false }, cwd, {
         ...options,
         quiet: false,
         channels: { stderr: resolveInheritedChannel(stderr), stdout: resolveInheritedChannel(stdout) },

package/dist/esm/steps.d.ts

@@ -7,6 +7,9 @@
  * `declinesArgs` travels from the composite element that composed the step to the one reader that acts on it,
  * the binding of the invocation's trailing arguments. Every stage between the two -- the devBin substitution,
  * the chain rendering, the replay assembly, the runner -- passes it through and asks nothing of it.
+ *
+ * `shouldWithholdInput` is read by the runner alone, which gives the step's child the null device as stdin rather
+ * than nmr's own. Like `declinesArgs`, it is set only where it holds and leaves the rendered chain unchanged.
  */
 export type Step = {
     kind: 'opaque';
@@ -15,6 +18,7 @@ export type Step = {
     kind: 'structural';
     argv: readonly [string, ...(readonly string[])];
     declinesArgs?: boolean;
+    shouldWithholdInput?: boolean;
 };
 /** What a structural step asks of the nmr process it spawns. */
 export interface NmrStepTarget {

package/dist/esm/types.d.ts

@@ -17,13 +17,14 @@ export interface CheckCacheConfig {
     enabled?: boolean;
     /**
      * Command names removed from the cacheable set, applied after `extraCommands`. This is how a repo retires a
-     * name whose chain turned out to do more than report an exit status.
+     * name whose chain turned out to do more than report an exit status. Every name has to resolve to a command.
      */
     excludeCommands?: string[];
     /**
      * Command names added to the cacheable set. Extends rather than replaces, so that declaring one command
      * cannot silently drop the defaults. A name listed here promises exit-status-only semantics through its whole
-     * chain, hooks included.
+     * chain, hooks included, and has to resolve to a command: both lists are read by name alone, so a misspelt
+     * entry would otherwise be inert.
      */
     extraCommands?: string[];
 }

package/dist/esm/verdict.d.ts

@@ -62,7 +62,7 @@ export declare function renderVerdict(verdict: Verdict): string;
  * Held to the ceiling the prose line is held to, so one write still reaches a pipe whole where concurrent
  * scopes share a descriptor. Cuts land inside the record's text rather than across its structure, which is
  * what leaves the line parseable, and a record is fitted by rungs, each shedding what a reader can better
- * spare than the rung below it. What the ceiling costs is [documented](../README.md#reporting-for-a-machine)
+ * spare than the rung below it. What the ceiling costs is [documented](../docs/reporting.md#reporting-for-a-machine)
  * in the same order.
  */
 export declare function serializeVerdict(verdict: Verdict): string;

package/dist/esm/vitest-git-isolation.js

@@ -2,3 +2,9 @@ import os from 'node:os';
 process.env['GIT_CONFIG_GLOBAL'] = os.devNull;
 process.env['GIT_CONFIG_SYSTEM'] = os.devNull;
 process.env['GIT_CONFIG_NOSYSTEM'] = '1';
+process.env['GIT_ATTR_NOSYSTEM'] = '1';
+process.env['GIT_CONFIG_COUNT'] = '2';
+process.env['GIT_CONFIG_KEY_0'] = 'core.excludesFile';
+process.env['GIT_CONFIG_VALUE_0'] = os.devNull;
+process.env['GIT_CONFIG_KEY_1'] = 'core.attributesFile';
+process.env['GIT_CONFIG_VALUE_1'] = os.devNull;

package/dist/esm/vitest-source-resolution.d.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from 'vite';
+/**
+ * Builds the plugin that resolves a package's `source` export condition, for a package whose files sit outside
+ * every `node_modules`.
+ *
+ * The condition cannot be emitted as a `resolve.conditions` entry instead: Vitest turns the server environment's
+ * conditions into `--conditions` flags on the worker process, where Node applies them to every package it
+ * resolves natively. Node refuses to strip types from a file under `node_modules`, so a dependency declaring a
+ * TypeScript `source` entry fails to load as soon as the condition reaches that far.
+ *
+ * Resolving here instead keeps the condition inside Vite, which transforms what it resolves. A package under
+ * `node_modules` resolves through its remaining conditions, whatever its `exports` map declares.
+ */
+export declare function createSourceResolutionPlugin(): Plugin;
+/** What a resolution needs beyond the specifier and its importer: the resolving environment, and the caches. */
+export interface SourceResolutionContext {
+    /** The Vite environment resolving the specifier, which decides the environment-specific condition. */
+    environmentName: string;
+    /** Parsed manifests, keyed by package directory. Absent from a caller that resolves once. */
+    manifests?: Map<string, unknown>;
+    /** Package directories, keyed by specifier and importer directory. Absent from a caller that resolves once. */
+    packageDirs?: Map<string, string | undefined>;
+}
+/**
+ * Resolves a bare specifier to the file that its package's `source` condition names, or nothing where the condition
+ * does not reach it.
+ *
+ * Answers a bare specifier naming a package whose real directory sits outside every `node_modules`. Every other
+ * specifier returns nothing -- such as a relative or absolute path, a virtual module, a builtin, or a package under
+ * `node_modules` -- so Vite resolves the specifier through its own conditions. Throws where the condition reaches no
+ * file, because falling through to the build output is the staleness that resolving from source exists to prevent,
+ * and nothing in a run reports it.
+ *
+ * A query or hash suffix is split off before the `exports` lookup and re-appended to the resolved path, as Vite
+ * does, so `pkg/icon.svg?raw` matches the `./icon.svg` entry and still reaches the plugin that reads the suffix.
+ */
+export declare function resolveSourceTarget(specifier: string, importer: string | undefined, context: SourceResolutionContext): string | undefined;