@williamthorsen/nmr 2.0.1 → 2.0.3

package/dist/esm/commands/shellcheck.js

@@ -1,8 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { runGit, UserError } from '@williamthorsen/nmr-core';
-import { describeSignalExitCode } from "../child-process.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { ensureTool, resolveToolCacheRoots } from "./workflow-tools.js";
 export async function runShellcheck(monorepoRoot, args, options = {}) {
     const shellcheckArgs = args.length > 0 ? [...args] : listPresentScripts(monorepoRoot, options.listFiles);
@@ -13,14 +12,11 @@ export async function runShellcheck(monorepoRoot, args, options = {}) {
     const cacheRoots = options.cacheRoots ?? resolveToolCacheRoots(monorepoRoot);
     const ensure = options.ensure ?? ((tool, roots) => ensureTool(tool, { cacheRoots: roots }));
     const shellcheckPath = await ensure('shellcheck', cacheRoots);
-    const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, monorepoRoot);
+    const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, { cwd: monorepoRoot });
     if (outcome.error !== undefined) {
         throw new UserError(`Cannot run shellcheck: ${outcome.error.message}`, { cause: outcome.error });
     }
-    if (outcome.signal !== null) {
-        return describeSignalExitCode(outcome.signal);
-    }
-    return outcome.status ?? 1;
+    return resolveInheritedExitCode(outcome);
 }
 export function listTrackedScripts(monorepoRoot) {
     const result = runGit(['ls-files', '-z', '--', '*.sh'], monorepoRoot);
@@ -32,7 +28,3 @@ export function listTrackedScripts(monorepoRoot) {
 function listPresentScripts(monorepoRoot, listFiles = listTrackedScripts) {
     return listFiles(monorepoRoot).filter((file) => fs.existsSync(path.join(monorepoRoot, file)));
 }
-function spawnInherited(file, args, cwd) {
-    const result = spawnSync(file, args, { cwd, stdio: 'inherit' });
-    return { error: result.error, signal: result.signal, status: result.status };
-}

package/dist/esm/commands/spawn-inherited.d.ts

@@ -0,0 +1,21 @@
+/** How a program spawned on the caller's stdio ended. */
+export interface InheritedOutcome {
+    error?: Error | undefined;
+    signal: NodeJS.Signals | null;
+    status: number | null;
+}
+export interface SpawnInheritedOptions {
+    /** Directory in which the program runs. Defaults to the current one. */
+    cwd?: string;
+    /** Environment for the program. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/** A function that runs a program on the caller's stdio, the shape of each command's injectable spawn. */
+export type SpawnInherited = typeof spawnInherited;
+/** Returns the exit code that reports how the program ended: the shell's code for a death by signal, else its status. */
+export declare function resolveInheritedExitCode({ signal, status }: Pick<InheritedOutcome, 'signal' | 'status'>): number;
+/**
+ * Runs a program on the caller's stdio, so that it sees the caller's terminal: It colors its output, renders
+ * progress, and reads input as it would when run directly.
+ */
+export declare function spawnInherited(file: string, args: readonly string[], options?: SpawnInheritedOptions): InheritedOutcome;

package/dist/esm/commands/spawn-inherited.js

@@ -0,0 +1,11 @@
+import { spawnSync } from 'node:child_process';
+import { describeSignalExitCode } from "../child-process.js";
+export function resolveInheritedExitCode({ signal, status }) {
+    if (signal !== null)
+        return describeSignalExitCode(signal);
+    return status ?? 1;
+}
+export function spawnInherited(file, args, options = {}) {
+    const result = spawnSync(file, args, { cwd: options.cwd, env: options.env, stdio: 'inherit' });
+    return { error: result.error, signal: result.signal, status: result.status };
+}

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

@@ -1,10 +1,7 @@
 import type { Writable } from 'node:stream';
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import { type CheckNodePinOptions } from './node-pin.js';
-export interface SpawnOutcome {
-    status: number | null;
-    error?: Error | undefined;
-}
+import { type SpawnInherited } from './spawn-inherited.js';
 export interface RunTazeOptions {
     /** Checks the `.tool-versions` Node pin in a directory. Injected by tests. */
     checkNodePin?: (dir: string, options: CheckNodePinOptions) => Promise<void>;
@@ -12,8 +9,11 @@ export interface RunTazeOptions {
     loadConfig?: (cwd: string) => Promise<unknown>;
     /** Resolves the absolute path of taze's CLI entry. Injected by tests. */
     resolveCliPath?: () => string;
-    /** Runs the CLI and reports how it exited. Injected by tests. */
-    spawn?: (nodePath: string, argv: string[]) => SpawnOutcome;
+    /**
+     * Runs the CLI on the caller's stdio, so that taze's progress rendering, cursor restore, and `--interactive` mode
+     * see the caller's TTY. Injected by tests.
+     */
+    spawn?: SpawnInherited;
     /** Stream that error output and pass headings are written to. Defaults to `process.stderr`. */
     stderr?: Writable;
     /** Style of `stderr`, in which the Node pin check reports. Defaults to `'plain'`. */

package/dist/esm/commands/taze.js

@@ -1,4 +1,3 @@
-import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -7,6 +6,7 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { NMR_TAZE_BIN } from "../bins.js";
 import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
 import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
+import { resolveInheritedExitCode, spawnInherited } from "./spawn-inherited.js";
 import { isSilent, readFlag } from "./taze-args.js";
 import { planTazePasses } from "./taze-passes.js";
 const TAZE_CLI_SPECIFIER = 'taze/cli';
@@ -17,7 +17,7 @@ const NODE_PIN_SKIP_FLAGS = ['--no-node-version', '--help', '-h', '--version', '
 export async function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
     const resolveCliPath = options.resolveCliPath ?? resolveTazeCliPath;
-    const spawn = options.spawn ?? spawnNode;
+    const spawn = options.spawn ?? spawnInherited;
     const loadConfig = options.loadConfig ?? loadPackageMaturityPeriod;
     let cliPath;
     try {
@@ -59,7 +59,7 @@ export async function runTaze(args, options = {}) {
             reportError(NMR_TAZE_BIN, `Failed to run taze: ${outcome.error.message}`, stderr);
             return 1;
         }
-        const status = outcome.status ?? 1;
+        const status = resolveInheritedExitCode(outcome);
         if (exitCode === 0)
             exitCode = status;
     }
@@ -74,7 +74,3 @@ function composeRequestTimeoutArgs(args) {
 function resolveConfigDir(args) {
     return path.resolve(readFlag(args, ['--cwd', '-C'])?.value ?? '.');
 }
-function spawnNode(nodePath, argv) {
-    const result = spawnSync(nodePath, argv, { stdio: 'inherit' });
-    return { status: result.status, error: result.error };
-}

package/dist/esm/config-validation.js

@@ -1,5 +1,5 @@
 import { isRecord, UserError } from '@williamthorsen/nmr-core';
-import { assertResolvableCheckCacheCommands } from "./config-check-cache.js";
+import { assertResolvableCheckCacheCommands } from "./check-cache/config-check-cache.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {

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. */