@williamthorsen/nmr 2.0.0 → 2.0.2

package/dist/esm/config.js

@@ -1,18 +1,10 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 import { existsSync } from 'node:fs';
-import { pathToFileURL } from 'node:url';
-import { isRecord, UserError } from '@williamthorsen/nmr-core';
+import { UserError } from '@williamthorsen/nmr-core';
 import { CONFIG_TIERS, validateConfig } from "./config-validation.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { isHookName } from "./helpers/hook-name.js";
+import { importConfigDefault } from "./helpers/importConfigDefault.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { describeScript } from "./resolver.js";
 import { readSelfReference, readStepListSelfReference } from "./steps.js";
@@ -25,8 +17,7 @@ export async function loadConfig(baseDir) {
     if (!existsSync(configPath)) {
         return {};
     }
-    const importedModule = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
-    const loadedConfig = isRecord(importedModule) ? importedModule['default'] : undefined;
+    const loadedConfig = await importConfigDefault(configPath);
     return validateConfig(loadedConfig, configPath, baseDir);
 }
 export async function loadRootConfig(monorepoRoot) {

package/dist/esm/{delegate-host.d.ts → delegation/delegate-host.d.ts}

@@ -1,6 +1,6 @@
-import { type ExecutionTarget, type Invocation, type PhaseResult, type RunCliResult, type RunPlan } from './invocation.js';
-import type { RetainedOutput } from './runner.js';
-import type { VerdictOutcome } from './verdict.js';
+import { type ExecutionTarget, type Invocation, type PhaseResult, type RunCliResult, type RunPlan } from '../invocation.js';
+import type { RetainedOutput } from '../runner.js';
+import type { VerdictOutcome } from '../verdict.js';
 /** How a run on the host ended, or that the invocation runs here after all. */
 export type HostRunResult = {
     kind: 'here';

package/dist/esm/{delegate-host.js → delegation/delegate-host.js}

@@ -1,14 +1,15 @@
 import os from 'node:os';
 import { Writable } from 'node:stream';
 import { reportError, startTimer } from '@williamthorsen/nmr-core';
-import { NMR_BIN } from "./bins.js";
-import { NO_CACHE_ENV_VAR, resolveRunId, writeDebugNote } from "./check-cache.js";
-import { buildChildEnv, buildRemoteEnv } from "./child-env.js";
+import { NMR_BIN } from "../bins.js";
+import { NO_CACHE_ENV_VAR, resolveRunId, writeDebugNote } from "../check-cache/check-cache.js";
+import { buildChildEnv, buildRemoteEnv } from "../child-env.js";
+import { isEnvSwitchOn } from "../env-switch.js";
+import { createBoundedBuffer } from "../helpers/createBoundedBuffer.js";
+import { USAGE_EXIT_CODE, } from "../invocation.js";
+import { isDelegationFlag } from "../invocation-args.js";
+import { reportVerdict } from "../presentation.js";
 import { resolveDelegationTarget } from "./delegation-target.js";
-import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
-import { USAGE_EXIT_CODE, } from "./invocation.js";
-import { isDelegationFlag } from "./invocation-args.js";
-import { reportVerdict } from "./presentation.js";
 import { chooseHost, probeHost } from "./remote-probe.js";
 import { DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATE_TO_FLAG, DELEGATION_FAILURE_EXIT_CODE, deriveCheckoutPath, formatMisplacedDelegationWarning, readLastLine, runRemotely, } from "./remote-run.js";
 import { createSnapshot } from "./remote-snapshot.js";
@@ -46,7 +47,7 @@ export async function runInvocationOnHost(invocation, target) {
         format,
         passthrough: parsedArgs.passthrough,
         runId: resolveRunId(env),
-        shouldBypassCache: parsedArgs.shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1',
+        shouldBypassCache: parsedArgs.shouldBypassCache || isEnvSwitchOn(env, NO_CACHE_ENV_VAR),
         shouldBypassLock: parsedArgs.shouldBypassLock,
         snapshot: undefined,
         styles,

package/dist/esm/{delegation-target.js → delegation/delegation-target.js}

@@ -1,6 +1,6 @@
+import { hasAgentMarker } from "../verbosity.js";
 import { DELEGATE_ENV_VAR, DELEGATE_FLAG, DELEGATE_TO_FLAG } from "./remote-run.js";
 import { formatDisplayPath, resolveUserConfigPath } from "./user-config.js";
-import { hasAgentMarker } from "./verbosity.js";
 export async function resolveDelegationTarget(options) {
     const { command, env, extraAgentEnvVars, flagValue, isFanOut, isOptedOut, isReading } = options;
     const { isRepoOptedOut, readUserConfig, shouldDelegate } = options;

package/dist/esm/{remote-probe.js → delegation/remote-probe.js}

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { isRecord } from '@williamthorsen/nmr-core';
-import { quoteForShell } from "./helpers/quoteForShell.js";
-import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "./machine-lock.js";
+import { quoteForShell } from "../helpers/quoteForShell.js";
+import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "../machine-lock.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
 import { probeHostLocks } from "./remote-probe-host.js";
 import { DELEGATION_FAILURE_EXIT_CODE, readLastLine, runSsh } from "./remote-run.js";

package/dist/esm/{remote-run.js → delegation/remote-run.js}

@@ -4,11 +4,11 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { GIT_OUTPUT_LIMIT_BYTES, startTimer, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
-import { PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
-import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
-import { quoteForShell } from "./helpers/quoteForShell.js";
-import { STALE_AFTER_MS } from "./machine-lock.js";
-import { formatFlagSpelling } from "./nmr-flags.js";
+import { PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "../check-cache/check-cache.js";
+import { createBoundedBuffer } from "../helpers/createBoundedBuffer.js";
+import { quoteForShell } from "../helpers/quoteForShell.js";
+import { STALE_AFTER_MS } from "../machine-lock.js";
+import { formatFlagSpelling } from "../nmr-flags.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
 import { composeSessionScript, createSessionDemultiplexer, formatDelegationWaitingLine } from "./remote-session.js";
 export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';

package/dist/esm/{remote-session.js → delegation/remote-session.js}

@@ -1,6 +1,6 @@
 import { Writable } from 'node:stream';
 import { isRecord } from '@williamthorsen/nmr-core';
-import { quoteForShell } from "./helpers/quoteForShell.js";
+import { quoteForShell } from "../helpers/quoteForShell.js";
 import { runHostSession, } from "./remote-host-session.js";
 export function composeSessionScript(options) {
     const { checkoutDir, params } = options;

package/dist/esm/{user-config.js → delegation/user-config.js}

@@ -1,17 +1,9 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
-import { assertRecognizedKeys } from "./config-validation.js";
-import { resolveXdgBaseDir } from "./helpers/resolveXdgBaseDir.js";
+import { assertRecognizedKeys } from "../config-validation.js";
+import { importConfigDefault } from "../helpers/importConfigDefault.js";
+import { resolveXdgBaseDir } from "../helpers/resolveXdgBaseDir.js";
 export const DELEGATE_WHEN_VALUES = ['agent', 'always'];
 export function formatDisplayPath(filePath, env) {
     const home = env['HOME'];
@@ -29,8 +21,7 @@ export async function loadUserConfig(env) {
     if (configPath === undefined || !existsSync(configPath)) {
         return undefined;
     }
-    const importedModule = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
-    const loadedConfig = isRecord(importedModule) ? importedModule['default'] : undefined;
+    const loadedConfig = await importConfigDefault(configPath);
     return { config: validateUserConfig(loadedConfig, configPath), path: configPath };
 }
 export function resolveUserConfigPath(env) {

package/dist/esm/env-switch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The values that an on/off environment switch accepts. An unset or empty variable is off as well, so that a shell
+ * that clears a switch keeps working.
+ */
+export declare const ENV_SWITCH_VALUES: readonly ["0", "1"];
+/**
+ * Reports whether a switch is on. A value that the switch does not accept reads as off: nmr and `nmr-fmt` reject
+ * one at entry, through `readEnvSwitch`, before any command runs.
+ */
+export declare function isEnvSwitchOn(env: NodeJS.ProcessEnv, name: string): boolean;
+/**
+ * Reads an on/off switch from the environment. An unrecognized value is returned as an error, since a fallback to
+ * off would hide a misspelling, such as `true`, for the life of the shell.
+ */
+export declare function readEnvSwitch(env: NodeJS.ProcessEnv, name: string): EnvSwitchRead;
+/** Reads each named switch, and returns the message naming the first one whose value it does not accept. */
+export declare function readEnvSwitches(env: NodeJS.ProcessEnv, names: readonly string[]): string | undefined;
+/** Whether a switch is on, or the message naming why its value could not be read. */
+export type EnvSwitchRead = {
+    ok: true;
+    isOn: boolean;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/esm/env-switch.js

@@ -0,0 +1,26 @@
+export const ENV_SWITCH_VALUES = ['0', '1'];
+export function isEnvSwitchOn(env, name) {
+    return env[name] === '1';
+}
+export function readEnvSwitch(env, name) {
+    const rawValue = env[name];
+    if (rawValue === undefined || rawValue === '' || rawValue === '0') {
+        return { ok: true, isOn: false };
+    }
+    if (rawValue === '1') {
+        return { ok: true, isOn: true };
+    }
+    return {
+        ok: false,
+        error: `${name} is \`${rawValue}\`, which is not one of: ${ENV_SWITCH_VALUES.join(', ')} (unset or empty is off)`,
+    };
+}
+export function readEnvSwitches(env, names) {
+    for (const name of names) {
+        const read = readEnvSwitch(env, name);
+        if (!read.ok) {
+            return read.error;
+        }
+    }
+    return undefined;
+}

package/dist/esm/fan-out.d.ts

@@ -1,8 +1,9 @@
 import type { Writable } from 'node:stream';
 import type { ResolvedContext } from './context.js';
+import type { ReadFilterSelection } from './helpers/filter-selection.js';
 import { type RunCliResult } from './invocation.js';
 import type { ParsedArgs } from './nmr-flags.js';
-import { type RunStepsOptions } from './runner.js';
+import type { RunSteps, RunStepsOptions } from './runner.js';
 import type { Step } from './steps.js';
 /**
  * Composes the delegation that an `-F` or `-R` calls for, or `undefined` when the invocation runs here.
@@ -52,6 +53,8 @@ export declare function runDelegation(options: {
         }>;
     };
     parsedArgs: ParsedArgs;
+    readFilterSelection: ReadFilterSelection;
     runOptions: RunStepsOptions;
+    runSteps: RunSteps;
     stderr: Writable;
 }): Promise<RunCliResult>;

package/dist/esm/fan-out.js

@@ -1,11 +1,9 @@
 import { reportError } from '@williamthorsen/nmr-core';
 import { NMR_BIN } from "./bins.js";
-import { readFilterSelection } from "./helpers/filter-selection.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { renderQuotedList } from "./helpers/renderQuotedList.js";
 import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
 import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
-import { runSteps } from "./runner.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
 const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
 export function composeDelegation(options) {
@@ -46,7 +44,7 @@ export function listDefinedCommands(context) {
     return names;
 }
 export async function runDelegation(options) {
-    const { context, delegation, parsedArgs, runOptions, stderr } = options;
+    const { context, delegation, parsedArgs, readFilterSelection, runOptions, runSteps, stderr } = options;
     const selection = parsedArgs.filter === undefined ? undefined : readFilterSelection(parsedArgs.filter, context.monorepoRoot);
     const refusal = findEmptySelectionRefusal({ context, parsedArgs, selection });
     if (refusal !== undefined) {

package/dist/esm/help.js

@@ -1,6 +1,6 @@
+import { DELEGATE_ENV_VAR } from "./delegation/remote-run.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { OUTPUT_STYLE_ENV_VAR } from "./output-style.js";
-import { DELEGATE_ENV_VAR } from "./remote-run.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
 const LIFECYCLE_SCRIPT_NAMES = new Set([
     'dependencies',

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

@@ -32,6 +32,8 @@ export declare function interpretSelectionProbe(probe: SelectionProbe, monorepoR
 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';
+/** Reads what a `-F` pattern selects, as `readFilterSelection` does: the form in which a caller receives it. */
+export type ReadFilterSelection = typeof readFilterSelection;
 /** 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 from which a selection is read. */

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

@@ -0,0 +1,7 @@
+/**
+ * Imports the nmr config file at `configPath` and returns its default export, or `undefined` when the module does not
+ * have one. Throws a `UserError` that names the file when it fails to parse or throws while loading, keeping the
+ * original error as its `cause`. A parse error's location, when Node reports one, follows the config's path, or
+ * precedes the cause's message when it lies in a module that the config imports.
+ */
+export declare function importConfigDefault(configPath: string): Promise<unknown>;

package/dist/esm/helpers/importConfigDefault.js

@@ -0,0 +1,45 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { isRecord, UserError } from '@williamthorsen/nmr-core';
+import { describeError, isError } from '@williamthorsen/toolbelt.errors';
+export async function importConfigDefault(configPath) {
+    let importedModule;
+    try {
+        importedModule = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
+    }
+    catch (error) {
+        const location = readSyntaxErrorLocation(error);
+        const isInConfig = location !== undefined && isConfigFile(location.file, configPath);
+        const configLocation = isInConfig ? `${configPath}:${location.line}` : configPath;
+        const foreignLocation = location === undefined || isInConfig ? '' : `${location.file}:${location.line}: `;
+        throw new UserError(`Cannot load nmr config at ${configLocation}: ${foreignLocation}${describeError(error)}. Fix the file and rerun.`, { cause: error });
+    }
+    return isRecord(importedModule) ? importedModule['default'] : undefined;
+}
+function isConfigFile(file, configPath) {
+    return file === configPath || file === resolveRealPath(configPath);
+}
+function readSyntaxErrorLocation(error) {
+    if (!isError(error) || error.stack === undefined) {
+        return undefined;
+    }
+    const match = /^(?<file>.+):(?<line>\d+)$/u.exec(error.stack.split('\n', 1)[0] ?? '');
+    const { file, line } = match?.groups ?? {};
+    return file === undefined || line === undefined ? undefined : { file, line };
+}
+function resolveRealPath(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/invocation.d.ts

@@ -1,11 +1,12 @@
 import type { Writable } from 'node:stream';
 import { type StreamStyles } from '@williamthorsen/nmr-core';
-import type { TreeSnapshot } from './check-cache.js';
+import type { TreeReader, TreeSnapshot } from './check-cache/check-cache.js';
 import type { ResolvedContext } from './context.js';
-import type { DelegationTarget } from './delegation-target.js';
+import type { DelegationTarget } from './delegation/delegation-target.js';
+import type { ReadFilterSelection } from './helpers/filter-selection.js';
 import type { ParsedArgs } from './nmr-flags.js';
 import type { ReportFormat } from './report-format.js';
-import type { RunStepsOptions } from './runner.js';
+import type { RunSteps, RunStepsOptions } from './runner.js';
 import type { Step } from './steps.js';
 import type { CommandVerbosity } from './verbosity.js';
 /** An invocation that reached a command: what it asks for, how it presents itself, and where it runs. */
@@ -17,6 +18,9 @@ export interface Invocation {
     env: NodeJS.ProcessEnv;
     format: ReportFormat;
     parsedArgs: ParsedArgs;
+    readFilterSelection: ReadFilterSelection;
+    readTree: TreeReader;
+    runSteps: RunSteps;
     scope: string;
     shouldUseRoot: boolean;
     stderr: Writable;

package/dist/esm/machine-lock.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { setTimeout as delay } from 'node:timers/promises';
 import { isRecord, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { isEnvSwitchOn } from "./env-switch.js";
 const RECLAIM_GUARD = 'heavy.lock.reclaim';
 const RECLAIM_GUARD_STALE_AFTER_MS = 10_000;
 export const HEARTBEAT_INTERVAL_MS = 10_000;
@@ -31,7 +32,7 @@ export const POLL_INTERVAL_MS = 1000;
 export const STALE_AFTER_MS = 60_000;
 export async function acquireMachineLock(options) {
     const { command, dir, env, stderr } = options;
-    if (env[NO_LOCK_ENV_VAR] === '1') {
+    if (isEnvSwitchOn(env, NO_LOCK_ENV_VAR)) {
         return createHoldFreeLock({ isChainUnlocked: true, waited: false });
     }
     const lockDir = options.lockDir ?? resolveLockDir({ env, platform: process.platform, uid: process.getuid?.() });

package/dist/esm/route.d.ts

@@ -1,8 +1,11 @@
 import type { Writable } from 'node:stream';
 import { type CommandNode } from '@williamthorsen/nmr-core/cli';
+import { type TreeReader } from './check-cache/check-cache.js';
 import type { ResolvedContext } from './context.js';
+import type { ReadFilterSelection } from './helpers/filter-selection.js';
 import { type Invocation } from './invocation.js';
 import { type ParsedArgs } from './nmr-flags.js';
+import type { RunSteps } from './runner.js';
 /** What the command tree of one invocation is built from. */
 export interface RouteInput {
     context: ResolvedContext;
@@ -10,8 +13,11 @@ export interface RouteInput {
     env: NodeJS.ProcessEnv;
     /** The invocation's flags as the first pass read them, or `undefined` when they do not parse. */
     firstPass: ParsedArgs | undefined;
+    readFilterSelection: ReadFilterSelection;
+    readTree: TreeReader;
     /** Runs an invocation that reached a command and resolves to its exit code. */
     runInvocation: (invocation: Invocation) => Promise<number>;
+    runSteps: RunSteps;
     stderr: Writable;
     stdout: Writable;
 }

package/dist/esm/route.js

@@ -1,12 +1,16 @@
 import path from 'node:path';
 import { createCli, UsageError } from '@williamthorsen/nmr-core/cli';
+import { DEBUG_ENV_VAR, NO_CACHE_ENV_VAR } from "./check-cache/check-cache.js";
+import { readEnvSwitch, readEnvSwitches } from "./env-switch.js";
 import { listDefinedCommands } from "./fan-out.js";
 import { describeHelp } from "./help.js";
 import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
+import { NO_LOCK_ENV_VAR } from "./machine-lock.js";
 import { NMR_FLAGS, toParsedArgs } from "./nmr-flags.js";
 import { isTerminalStream } from "./output-style.js";
 import { readPresentation, resolveReportingVerbosity } from "./presentation.js";
 import { resolveReportFormat } from "./report-format.js";
+const ENV_SWITCH_NAMES = [DEBUG_ENV_VAR, NO_CACHE_ENV_VAR, NO_LOCK_ENV_VAR, RUN_IF_PRESENT_ENV_VAR];
 const { defineGroup } = createCli();
 const { defineCommand } = createCli();
 export function buildRoot(input) {
@@ -20,7 +24,9 @@ export function buildRoot(input) {
     }
     const command = firstPass?.command;
     if (command !== undefined && !firstPass?.shouldShowHelp && !Object.hasOwn(commands, command)) {
-        const isAnsweredByNmr = env[RUN_IF_PRESENT_ENV_VAR] === '1' ||
+        const runIfPresent = readEnvSwitch(env, RUN_IF_PRESENT_ENV_VAR);
+        const isAnsweredByNmr = !runIfPresent.ok ||
+            runIfPresent.isOn ||
             (firstPass?.shouldDelegate === true && firstPass.delegateHosts === undefined) ||
             listDefinedCommands(context).has(command);
         if (isAnsweredByNmr) {
@@ -50,7 +56,7 @@ function defineScriptCommand(name, summary, input) {
     });
 }
 function deriveInvocation(flags, input) {
-    const { context, cwd, env, firstPass, stderr, stdout } = input;
+    const { context, cwd, env, firstPass, readFilterSelection, readTree, runSteps, stderr, stdout } = input;
     const parsedArgs = toParsedArgs(flags, []);
     const presentationRead = readPresentation({
         env,
@@ -61,6 +67,10 @@ function deriveInvocation(flags, input) {
     if (!presentationRead.ok) {
         throw new UsageError(presentationRead.error);
     }
+    const switchError = readEnvSwitches(env, ENV_SWITCH_NAMES);
+    if (switchError !== undefined) {
+        throw new UsageError(switchError);
+    }
     if (parsedArgs.shouldPrintLog && firstPass?.command === undefined) {
         throw new UsageError('--log requires a command name: `nmr --log <command>`');
     }
@@ -81,6 +91,9 @@ function deriveInvocation(flags, input) {
         env,
         format,
         parsedArgs,
+        readFilterSelection,
+        readTree,
+        runSteps,
         scope: path.basename(anchorDir),
         shouldUseRoot,
         stderr,

package/dist/esm/run-chain.d.ts

@@ -1,5 +1,5 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
-import type { TreeSnapshot } from './check-cache.js';
+import type { TreeSnapshot } from './check-cache/check-cache.js';
 import { type Invocation, type PhaseResult, type RunPlan } from './invocation.js';
 import type { ScriptRegistry } from './resolve-scripts.js';
 import type { ResolvedScript } from './resolver.js';

package/dist/esm/run-chain.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { formatGlyphLine, reportError } from '@williamthorsen/nmr-core';
 import { NMR_BIN } from "./bins.js";
-import { resolveCacheKey } from "./check-cache-gate.js";
+import { resolveCacheKey } from "./check-cache/check-cache-gate.js";
 import { reportNmrCrossing } from "./crossing-diagnostics.js";
 import { NMR_GLYPHS } from "./glyphs.js";
 import { isHookName } from "./helpers/hook-name.js";

package/dist/esm/runCli.d.ts

@@ -1,5 +1,8 @@
 import type { Writable } from 'node:stream';
+import { type TreeReader } from './check-cache/check-cache.js';
+import { type ReadFilterSelection } from './helpers/filter-selection.js';
 import { type RunCliResult } from './invocation.js';
+import { type RunSteps } from './runner.js';
 /** @internal */
 export interface RunCliOptions {
     /** Post-slice CLI arguments (equivalent to `process.argv.slice(2)`). */
@@ -8,6 +11,12 @@ export interface RunCliOptions {
     cwd: string;
     /** Environment from which `runCli` reads its settings, and the base of the one that its children inherit. */
     env: NodeJS.ProcessEnv;
+    /** Reads what a `-F` pattern selects; defaults to `readFilterSelection`, which asks pnpm. */
+    readFilterSelection?: ReadFilterSelection;
+    /** Reads the working tree that the check-result cache gates on; defaults to `GIT_TREE_READER`, which asks git. */
+    readTree?: TreeReader;
+    /** Runs a step list; defaults to `runSteps`. */
+    runSteps?: RunSteps;
     /** Stream for normal output: help, version, verdicts, recordings, and override notices. */
     stdout: Writable;
     /** Stream for errors, warnings, and debug notes. */

package/dist/esm/runCli.js

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

package/dist/esm/runner.d.ts

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

package/dist/esm/runner.js

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

package/dist/esm/verdict.d.ts

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