@williamthorsen/nmr 0.48.0 → 0.49.0

package/dist/esm/fan-out.js

@@ -0,0 +1,146 @@
+import { reportError } from '@williamthorsen/nmr-core';
+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) {
+    const { childEnv, command, parsedArgs } = options;
+    let scope;
+    let shouldRunIfPresent = parsedArgs.shouldPrintLog;
+    if (parsedArgs.filter) {
+        scope = ['--filter', parsedArgs.filter];
+    }
+    else if (parsedArgs.recursive) {
+        scope = ['--recursive'];
+        shouldRunIfPresent = true;
+    }
+    if (scope === undefined) {
+        return undefined;
+    }
+    const flags = parsedArgs.shouldPrintLog ? ['--log'] : [];
+    return {
+        env: shouldRunIfPresent ? { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' } : childEnv,
+        step: {
+            kind: 'structural',
+            argv: ['pnpm', ...scope, 'exec', 'nmr', ...flags, command, ...parsedArgs.passthrough],
+        },
+    };
+}
+export function isDefinedInAnyScope(command, context) {
+    const registries = [buildRootRegistry(context.config, context.monorepoRoot), buildWorkspaceRegistry(context.config)];
+    if (registries.some((registry) => Object.hasOwn(registry, command))) {
+        return true;
+    }
+    return [context.monorepoRoot, ...context.workspacePackageDirs].some((dir) => Object.hasOwn(readPackageJsonScripts(dir) ?? {}, command));
+}
+export async function runDelegation(options) {
+    const { context, delegation, parsedArgs, runOptions, stderr } = options;
+    const selection = parsedArgs.filter === undefined ? undefined : readFilterSelection(parsedArgs.filter, context.monorepoRoot);
+    const refusal = findEmptySelectionRefusal({ context, parsedArgs, selection });
+    if (refusal !== undefined) {
+        reportError(refusal, stderr);
+        return { exitCode: 1 };
+    }
+    const shouldWithholdInput = parsedArgs.filter === undefined || selection === 'multiple';
+    const step = shouldWithholdInput ? { ...delegation.step, shouldWithholdInput } : delegation.step;
+    return runSteps([step], context.monorepoRoot, { ...runOptions, env: delegation.env });
+}
+function describeDeclaredPatterns(patterns) {
+    const quotablePatterns = patterns.filter((pattern) => pattern.trim() !== '');
+    const emptiedCount = patterns.length - quotablePatterns.length;
+    if (emptiedCount === 0) {
+        return `declares ${renderQuotedList(patterns)}`;
+    }
+    const emptiedClause = `${emptiedCount} ${emptiedCount === 1 ? 'entry' : 'entries'} that YAML left empty`;
+    return quotablePatterns.length === 0
+        ? `declares ${emptiedClause}`
+        : `declares ${renderQuotedList(quotablePatterns)}, beside ${emptiedClause}`;
+}
+function describeEmptyWorkspace(monorepoRoot) {
+    const resolution = resolveWorkspace(monorepoRoot);
+    if (resolution.kind !== 'empty') {
+        return `pnpm-workspace.yaml at ${monorepoRoot} resolves differently now than it did when the run started.`;
+    }
+    const { cause, patterns } = resolution;
+    const declaredClause = describeDeclaredPatterns(patterns);
+    switch (cause) {
+        case 'all-excluded':
+            return (`pnpm-workspace.yaml ${declaredClause}, whose \`!\` entries exclude every directory matched by the positive ` +
+                'patterns. Drop or narrow the exclusion.');
+        case 'no-package':
+            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher did not find any directory containing a \`package.json\`. ` +
+                'nmr counts a directory as a package only when it contains `package.json`; unlike pnpm, it recognizes ' +
+                'neither `package.yaml` nor `package.json5`. Add a `package.json` to the directory that should be a ' +
+                'package, or declare a pattern reaching a directory that contains one.');
+        case 'no-packages-list':
+            return (`pnpm-workspace.yaml at ${monorepoRoot} does not declare a \`packages\` list, so the workspace contains the root ` +
+                'package alone. Declare a positive pattern such as `packages/*` to reach the packages beneath it.');
+        case 'no-pattern':
+            return (`pnpm-workspace.yaml ${declaredClause}, so the matcher does not receive any pattern. Declare a positive ` +
+                'pattern such as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string ' +
+                'when it is unquoted.');
+        case 'unreadable-packages':
+            return (`pnpm-workspace.yaml at ${monorepoRoot} declares a \`packages\` value that is not a list of strings, so ` +
+                'nothing it declares reaches the matcher. Make it a list whose every entry is a quoted pattern; a bare ' +
+                'value and an entry YAML read as a number or a map are the usual ones.');
+        case 'unreadable-manifest':
+            return (`pnpm-workspace.yaml at ${monorepoRoot} is not valid YAML, so the matcher does not receive anything that it declares. ` +
+                'Repair the syntax error and run the command again. An unterminated quoted string and a mis-indented ' +
+                'entry are the usual ones.');
+        default: {
+            const unhandledCause = cause;
+            throw new Error(`Unhandled empty-workspace cause: ${String(unhandledCause)}`);
+        }
+    }
+}
+function findEmptySelectionRefusal(options) {
+    const { context, parsedArgs, selection } = options;
+    const isPackageless = context.workspacePackageDirs.length === 0;
+    if (parsedArgs.filter !== undefined) {
+        if (selection !== 'empty') {
+            return undefined;
+        }
+        if (isPackageless) {
+            return `${formatFilterRejection(parsedArgs.filter)} ${describeEmptyWorkspace(context.monorepoRoot)}`;
+        }
+        return formatEmptyFilterError(parsedArgs.filter, readWorkspacePackageNames(context.workspacePackageDirs));
+    }
+    return isPackageless ? `${RECURSIVE_REJECTION} ${describeEmptyWorkspace(context.monorepoRoot)}` : undefined;
+}
+function formatEmptyFilterError(pattern, names) {
+    const rejection = formatFilterRejection(pattern);
+    if (pattern.startsWith('!')) {
+        return `${rejection} A pattern beginning with \`!\` excludes what it matches, and this one excludes every package.`;
+    }
+    if (pattern.includes('[')) {
+        return `${rejection} A pattern containing \`[<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 this directory does not contain any package.');
+    }
+    return (`${rejection} A pattern matches a package's manifest \`name\`, ` +
+        `not its directory name.${suggestWorkspaceNames(pattern, names)}`);
+}
+function formatFilterRejection(pattern) {
+    return `-F/--filter did not match any workspace: \`${pattern}\`.`;
+}
+function suggestWorkspaceNames(pattern, names) {
+    if (names.length === 0) {
+        return '';
+    }
+    const containingNames = names.filter((name) => name.toLowerCase().includes(pattern.toLowerCase()));
+    if (containingNames.length > 0) {
+        return ` Did you mean ${renderQuotedList(containingNames)}?`;
+    }
+    const closestName = findClosestName(pattern, names);
+    if (closestName !== undefined) {
+        return ` Did you mean \`${closestName}\`?`;
+    }
+    return ` The workspace declares ${renderQuotedList(names)}.`;
+}

package/dist/esm/glyphs.d.ts

@@ -5,5 +5,5 @@
  * `noop` is a neutral circle: Nothing ran because the repo asked for nothing to run, which is neither a
  * failure nor a block.
  */
-export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "package" | "clean" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "catalog" | "noop" | "package" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type NmrGlyphName = keyof (typeof NMR_GLYPHS)['rich'];

package/dist/esm/help.js

@@ -33,21 +33,27 @@ export function generateHelp(config, monorepoRoot, packageDir, shouldUseRoot) {
         '  -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",
-        '      --delegate <host>       Run on <host> over SSH, against this working tree',
+        '      --delegate              Run over SSH on the first free host that NMR_DELEGATE or the user config names',
+        '      --delegate-to <hosts>   Run over SSH on the first free of <hosts>, comma-separated',
         '      --json                  Report one JSON object per command, withholding command output',
         '      --log                   Print the recorded run instead of running (up to 256 KiB)',
         '      --no-cache              Run even if this tree already passed; record the result',
-        '      --no-delegate           Run here, even when NMR_DELEGATE names a host',
+        '      --no-delegate           Run here, whatever NMR_DELEGATE or the user config says',
         '      --no-lock               Run without waiting for another heavy command on this machine',
         `      ${OUTPUT_STYLE_FLAG} <style>  Output style: auto (default), plain, or rich`,
         '  -?, --help                  Show this help',
         '  -V, --version               Show version number',
         '',
         'Environment:',
-        `  ${DELEGATE_ENV_VAR}                Host on which to run each command that can be delegated`,
+        `  ${DELEGATE_ENV_VAR}                Hosts on which to run each command that can be delegated,`,
+        '                              comma-separated; nmr runs on the first free one',
         `  ${OUTPUT_STYLE_ENV_VAR}            Output style: auto (default), plain, or rich. auto prints`,
         '                              plain, without emoji, when CI is set or the stream is not a terminal.',
         '',
+        'Files:',
+        "  ~/.config/nmr/config.ts     User config: this machine's delegation hosts, and when to use them",
+        '                              ($XDG_CONFIG_HOME/nmr/config.ts when that is set)',
+        '',
         'Workspace commands:',
     ];
     const packageScripts = packageDir === undefined ? {} : readRunnableScripts(packageDir);

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

@@ -1,3 +1,12 @@
+/**
+ * The bound on the line returned by `deriveExcerpt`, and therefore on what a caller persists beside a recorded pass.
+ *
+ * The line cap bounds how many lines the reduction keeps, not how long one of them is: a tool whose closing
+ * block is a single long line -- a one-line JSON report, a wide table collapsed by the whitespace fold -- would
+ * otherwise pass the whole retained tail to whatever stores it, to show at most a verdict line's worth.
+ * Generous enough to leave every summary measured here untouched.
+ */
+export declare const MAX_EXCERPT_BYTES = 2048;
 /**
  * Reduces a transcript to the one line shown in a verdict's detail slot, or `undefined` when it contained nothing.
  *

package/dist/esm/helpers/deriveExcerpt.js

@@ -1,7 +1,7 @@
 import { clampToBytes } from "./clampToBytes.js";
 import { cleanTranscript } from "./transcript.js";
 const MAX_BLOCK_LINES = 8;
-const MAX_EXCERPT_BYTES = 2_048;
+export const MAX_EXCERPT_BYTES = 2_048;
 const NON_RULE_CHARACTER = /[^-=_~*+.|:#]/u;
 export function deriveExcerpt(transcript) {
     const lines = cleanTranscript(transcript).split('\n');

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

@@ -0,0 +1,2 @@
+/** Renders a list of items for a diagnostic, backticked and capped so that a long list does not fill the terminal. */
+export declare function renderQuotedList(items: readonly string[]): string;

package/dist/esm/helpers/renderQuotedList.js

@@ -0,0 +1,9 @@
+const LIST_CEILING = 10;
+export function renderQuotedList(items) {
+    const shownItems = items
+        .slice(0, LIST_CEILING)
+        .map((item) => `\`${item}\``)
+        .join(', ');
+    const remainder = items.length - LIST_CEILING;
+    return remainder > 0 ? `${shownItems}, and ${remainder} more` : shownItems;
+}

package/dist/esm/hooks.d.ts

@@ -0,0 +1,17 @@
+import type { ScriptRegistry } from './resolve-scripts.js';
+import { type Step } from './steps.js';
+/**
+ * Returns true when a hook resolves to a chain other than the skip values `""` and `":"`, or when its
+ * `package.json` entry chains steps onto a re-invocation of the hook.
+ */
+export declare function hasRunnableHook(hookName: string, registry: ScriptRegistry, anchorDir: string, isWorkspaceRoot: boolean): boolean;
+/**
+ * Wraps a resolved main command's steps with `nmr <command>:pre` and `nmr <command>:post`
+ * steps when the corresponding hooks resolve to non-skip values.
+ *
+ * Omits a hook that `hasRunnableHook` rejects, so a missing or skipped hook does not add a step or any output.
+ *
+ * `-w` is propagated to hook subprocesses so that each hook selects the root registry
+ * on its own, independent of where the child derives its context from.
+ */
+export declare function wrapWithHooks(command: string, mainSteps: readonly Step[], registry: ScriptRegistry, anchorDir: string, isWorkspaceRoot: boolean): readonly Step[];

package/dist/esm/hooks.js

@@ -0,0 +1,23 @@
+import { findChainedSelfReference, resolveScript } from "./resolver.js";
+import { composeNmrStep, renderChain } from "./steps.js";
+export function hasRunnableHook(hookName, registry, anchorDir, isWorkspaceRoot) {
+    if (findChainedSelfReference(anchorDir, hookName) !== undefined) {
+        return true;
+    }
+    const resolvedScript = resolveScript(hookName, registry, anchorDir, isWorkspaceRoot);
+    if (!resolvedScript)
+        return false;
+    const chain = renderChain(resolvedScript.steps);
+    return chain !== '' && chain !== ':';
+}
+export function wrapWithHooks(command, mainSteps, registry, anchorDir, isWorkspaceRoot) {
+    const steps = [];
+    if (hasRunnableHook(`${command}:pre`, registry, anchorDir, isWorkspaceRoot)) {
+        steps.push(composeNmrStep(`${command}:pre`, isWorkspaceRoot));
+    }
+    steps.push(...mainSteps);
+    if (hasRunnableHook(`${command}:post`, registry, anchorDir, isWorkspaceRoot)) {
+        steps.push(composeNmrStep(`${command}:post`, isWorkspaceRoot));
+    }
+    return steps;
+}

package/dist/esm/invocation-args.d.ts

@@ -0,0 +1,40 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+/**
+ * Renders the hint for nmr flags written after the command name, or `undefined` when the arguments do not
+ * contain any. The corrected invocation keeps every other argument where it was written.
+ */
+export declare function formatMisplacedFlagHint(args: readonly string[], passthrough: readonly string[], style: OutputStyle): string | undefined;
+/** Reports whether an argument is one of nmr's delegation flags, in any spelling. */
+export declare function isDelegationFlag(arg: string): boolean;
+/** Parses the CLI arguments into nmr's flags, the command name, and the arguments passed through to it. */
+export declare function parseArgs(args: string[]): ParseResult;
+/** @internal */
+export interface ParsedArgs {
+    /** The comma-separated hosts that `--delegate-to` names, as written. */
+    delegateHosts?: string;
+    filter?: string;
+    isWorkspaceRoot: boolean;
+    /** The flag's value as it was written, which the style resolver rather than the parser narrows. */
+    outputStyle?: string;
+    quiet: boolean;
+    recursive: boolean;
+    shouldBypassCache: boolean;
+    shouldBypassLock: boolean;
+    /** Set by `--delegate`, which leaves the hosts to `NMR_DELEGATE` or the user config. */
+    shouldDelegate: boolean;
+    shouldEmitJson: boolean;
+    shouldPrintLog: boolean;
+    shouldRunLocally: boolean;
+    shouldShowHelp: boolean;
+    shouldShowVersion: boolean;
+    command?: string;
+    passthrough: string[];
+}
+type ParseResult = {
+    ok: true;
+    parsedArgs: ParsedArgs;
+} | {
+    ok: false;
+    error: string;
+};
+export {};

package/dist/esm/invocation-args.js

@@ -0,0 +1,178 @@
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { renderQuotedList } from "./helpers/renderQuotedList.js";
+import { OUTPUT_STYLE_FLAG } from "./output-style.js";
+import { DELEGATE_FLAG, DELEGATE_TO_FLAG, NO_DELEGATE_FLAG } from "./remote-run.js";
+import { quoteToken } from "./shell-syntax.js";
+const FILTER_FLAGS = new Set(['-F', '--filter']);
+const BOOLEAN_FLAGS = new Map([
+    ['-?', 'shouldShowHelp'],
+    [DELEGATE_FLAG, 'shouldDelegate'],
+    ['--help', 'shouldShowHelp'],
+    ['--json', 'shouldEmitJson'],
+    ['--log', 'shouldPrintLog'],
+    ['--no-cache', 'shouldBypassCache'],
+    [NO_DELEGATE_FLAG, 'shouldRunLocally'],
+    ['--no-lock', 'shouldBypassLock'],
+    ['-q', 'quiet'],
+    ['--quiet', 'quiet'],
+    ['-R', 'recursive'],
+    ['--recursive', 'recursive'],
+    ['-V', 'shouldShowVersion'],
+    ['--version', 'shouldShowVersion'],
+    ['-w', 'isWorkspaceRoot'],
+    ['--workspace-root', 'isWorkspaceRoot'],
+]);
+export function formatMisplacedFlagHint(args, passthrough, style) {
+    const { flagNames, movedTokens, remainingTokens } = splitMisplacedFlags(passthrough);
+    if (flagNames.length === 0) {
+        return undefined;
+    }
+    const commandIndex = args.length - passthrough.length - 1;
+    const correctedTokens = [
+        'nmr',
+        ...args.slice(0, commandIndex),
+        ...movedTokens,
+        ...args.slice(commandIndex, commandIndex + 1),
+        ...remainingTokens,
+    ];
+    const subject = flagNames.length === 1 ? 'is an nmr flag' : 'are nmr flags';
+    return (`${STATUS_GLYPHS[style].warning.text} ${renderQuotedList(flagNames)} ${subject}; ` +
+        `nmr reads its flags only before the command: \`${correctedTokens.map(quoteToken).join(' ')}\``);
+}
+export function isDelegationFlag(arg) {
+    return (arg === DELEGATE_FLAG ||
+        arg === DELEGATE_TO_FLAG ||
+        arg === NO_DELEGATE_FLAG ||
+        arg.startsWith(`${DELEGATE_FLAG}=`) ||
+        arg.startsWith(`${DELEGATE_TO_FLAG}=`));
+}
+export function parseArgs(args) {
+    const parsedArgs = {
+        isWorkspaceRoot: false,
+        quiet: false,
+        recursive: false,
+        shouldBypassCache: false,
+        shouldBypassLock: false,
+        shouldDelegate: false,
+        shouldEmitJson: false,
+        shouldPrintLog: false,
+        shouldRunLocally: false,
+        shouldShowHelp: false,
+        shouldShowVersion: false,
+        passthrough: [],
+    };
+    let index = 0;
+    while (index < args.length) {
+        const arg = args[index];
+        if (arg === undefined)
+            break;
+        if (FILTER_FLAGS.has(arg)) {
+            index++;
+            const filterValue = args[index];
+            if (!filterValue) {
+                return { ok: false, error: '-F/--filter requires a pattern argument' };
+            }
+            parsedArgs.filter = filterValue;
+            index++;
+            continue;
+        }
+        const booleanFlag = BOOLEAN_FLAGS.get(arg);
+        if (booleanFlag !== undefined) {
+            parsedArgs[booleanFlag] = true;
+            index++;
+            continue;
+        }
+        if (arg.startsWith(`${DELEGATE_FLAG}=`)) {
+            const value = arg.slice(DELEGATE_FLAG.length + 1);
+            return {
+                ok: false,
+                error: `${DELEGATE_FLAG} does not take a value; name hosts with ${DELEGATE_TO_FLAG} ${value}`,
+            };
+        }
+        const styleArgument = readOutputStyleArgument(args, index);
+        if (styleArgument !== undefined) {
+            if (!styleArgument.ok) {
+                return styleArgument;
+            }
+            parsedArgs.outputStyle = styleArgument.value;
+            index += styleArgument.consumedCount;
+            continue;
+        }
+        const delegateArgument = readDelegateArgument(args, index);
+        if (delegateArgument !== undefined) {
+            if (!delegateArgument.ok) {
+                return delegateArgument;
+            }
+            parsedArgs.delegateHosts = delegateArgument.value;
+            index += delegateArgument.consumedCount;
+            continue;
+        }
+        parsedArgs.command = arg;
+        parsedArgs.passthrough = args.slice(index + 1);
+        break;
+    }
+    const error = findArgError(parsedArgs);
+    return error === undefined ? { ok: true, parsedArgs } : { ok: false, error };
+}
+function findArgError(parsedArgs) {
+    if (parsedArgs.shouldPrintLog &&
+        parsedArgs.command === undefined &&
+        !parsedArgs.shouldShowHelp &&
+        !parsedArgs.shouldShowVersion) {
+        return '--log requires a command name: `nmr --log <command>`';
+    }
+    return undefined;
+}
+function readDelegateArgument(args, index) {
+    return readFlagValue(args, index, DELEGATE_TO_FLAG, 'a host argument');
+}
+function readFlagValue(args, index, flag, requirement) {
+    const arg = args[index] ?? '';
+    const assignment = arg.startsWith(`${flag}=`) ? arg.slice(flag.length + 1) : undefined;
+    if (arg !== flag && assignment === undefined) {
+        return undefined;
+    }
+    const value = assignment ?? args[index + 1];
+    if (!value) {
+        return { ok: false, error: `${flag} requires ${requirement}` };
+    }
+    return { ok: true, value, consumedCount: assignment === undefined ? 2 : 1 };
+}
+function readMisplacedFlagLength(args, index) {
+    const arg = args[index] ?? '';
+    if (FILTER_FLAGS.has(arg)) {
+        return (args[index + 1] ?? '') === '' ? undefined : 2;
+    }
+    const booleanFlag = BOOLEAN_FLAGS.get(arg);
+    if (booleanFlag !== undefined) {
+        return booleanFlag === 'shouldShowHelp' || booleanFlag === 'shouldShowVersion' ? undefined : 1;
+    }
+    const valueArgument = readOutputStyleArgument(args, index) ?? readDelegateArgument(args, index);
+    return valueArgument?.ok === true ? valueArgument.consumedCount : undefined;
+}
+function readOutputStyleArgument(args, index) {
+    return readFlagValue(args, index, OUTPUT_STYLE_FLAG, 'a value argument: auto, plain, or rich');
+}
+function splitMisplacedFlags(passthrough) {
+    const flagNames = new Set();
+    const movedTokens = [];
+    const remainingTokens = [];
+    let index = 0;
+    while (index < passthrough.length) {
+        const arg = passthrough[index] ?? '';
+        if (arg === '--') {
+            remainingTokens.push(...passthrough.slice(index));
+            break;
+        }
+        const flagLength = readMisplacedFlagLength(passthrough, index);
+        if (flagLength === undefined) {
+            remainingTokens.push(arg);
+            index++;
+            continue;
+        }
+        flagNames.add(arg.split('=', 1)[0] ?? arg);
+        movedTokens.push(...passthrough.slice(index, index + flagLength));
+        index += flagLength;
+    }
+    return { flagNames: [...flagNames], movedTokens, remainingTokens };
+}

package/dist/esm/invocation.d.ts

@@ -0,0 +1,67 @@
+import type { Writable } from 'node:stream';
+import { type StreamStyles } from '@williamthorsen/nmr-core';
+import type { TreeSnapshot } from './check-cache.js';
+import type { ResolvedContext } from './context.js';
+import type { DelegationTarget } from './delegation-target.js';
+import type { ParsedArgs } from './invocation-args.js';
+import type { ReportFormat } from './report-format.js';
+import type { 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. */
+export interface Invocation {
+    anchorDir: string;
+    command: string;
+    context: ResolvedContext;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    format: ReportFormat;
+    parsedArgs: ParsedArgs;
+    scope: string;
+    shouldUseRoot: boolean;
+    stderr: Writable;
+    stdout: Writable;
+    styles: StreamStyles;
+    verbosity: CommandVerbosity;
+}
+/** Where an invocation runs, once a delegation that cannot be honored has been refused. */
+export type ExecutionTarget = Exclude<DelegationTarget, {
+    kind: 'refused';
+}>;
+/** Either the outcome with which a phase settled the invocation, or the input of the next phase. */
+export type PhaseResult<T> = {
+    settled: true;
+    result: SettledResult;
+} | {
+    settled: false;
+    value: T;
+};
+/**
+ * Marks a run made on a delegating caller's behalf, in which a command that the registry does not define, and a
+ * `--log` with nothing to show, exit 0 rather than failing.
+ */
+export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
+/** @internal */
+export interface RunCliResult {
+    exitCode: number;
+}
+/** What an invocation would run, fully determined: the chain, the key under which it records, and how it runs. */
+export interface RunPlan {
+    commandString: string;
+    /** Where a miss runs: here, or on the host to which the invocation is delegated. */
+    target: ExecutionTarget;
+    invocation: Invocation;
+    key: string | undefined;
+    overrideNotice: string | undefined;
+    ownSteps: readonly Step[];
+    runId: string;
+    runOptions: RunStepsOptions;
+    shouldBypassCache: boolean;
+    snapshot: TreeSnapshot | undefined;
+    steps: readonly Step[];
+}
+/** An invocation's exit code, and whether it failed because its command is not defined in any scope that it reaches. */
+export type SettledResult = RunCliResult & {
+    isUnknownCommand?: boolean;
+};
+export declare const VERSION: string;

package/dist/esm/invocation.js

@@ -0,0 +1,3 @@
+import { resolveSelfVersion } from '@williamthorsen/nmr-core';
+export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
+export const VERSION = resolveSelfVersion(import.meta.url);

package/dist/esm/machine-lock.d.ts

@@ -10,6 +10,8 @@ export declare const HEARTBEAT_INTERVAL_MS = 10000;
 export declare const HEAVY_COMMANDS: ReadonlySet<string>;
 /** Overrides the directory that contains the lock file. */
 export declare const LOCK_DIR_ENV_VAR = "NMR_LOCK_DIR";
+/** The lock file's name in the lock directory. */
+export declare const LOCK_FILE = "heavy.lock";
 /** Passes the holder's token to the processes below it, which run under its hold rather than waiting on it. */
 export declare const LOCK_TOKEN_ENV_VAR = "NMR_MACHINE_LOCK_TOKEN";
 /** Set to `1` to run without the lock, for the whole chain. */

package/dist/esm/machine-lock.js

@@ -6,7 +6,6 @@ import process from 'node:process';
 import { setTimeout as delay } from 'node:timers/promises';
 import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { isObject } from "./helpers/type-guards.js";
-const LOCK_FILE = 'heavy.lock';
 const RECLAIM_GUARD = 'heavy.lock.reclaim';
 const RECLAIM_GUARD_STALE_AFTER_MS = 10_000;
 export const HEARTBEAT_INTERVAL_MS = 10_000;
@@ -26,6 +25,7 @@ export const HEAVY_COMMANDS = new Set([
     'test:unit',
 ]);
 export const LOCK_DIR_ENV_VAR = 'NMR_LOCK_DIR';
+export const LOCK_FILE = 'heavy.lock';
 export const LOCK_TOKEN_ENV_VAR = 'NMR_MACHINE_LOCK_TOKEN';
 export const NO_LOCK_ENV_VAR = 'NMR_NO_LOCK';
 export const POLL_INTERVAL_MS = 1_000;

package/dist/esm/output-channel.d.ts

@@ -0,0 +1,23 @@
+import type { Writable } from 'node:stream';
+/** Where one of a child's output streams goes: a descriptor to which the child writes, or a pipe read by nmr. */
+export type OutputChannel = number | 'pipe';
+/** The channel on which each of a child's output streams runs. */
+export interface OutputChannels {
+    stderr: OutputChannel;
+    stdout: OutputChannel;
+}
+/** Narrows a stream to one backed by a terminal, whose descriptor the child can be handed. */
+export declare function isTerminal(stream: Writable): stream is Writable & {
+    fd: number;
+};
+/**
+ * Returns the channel on which a stream runs: the stream's own descriptor when it is a terminal and output is
+ * not being withheld, so that the child's terminal detection matches nmr's, and a pipe everywhere else.
+ */
+export declare function resolveChannel(stream: Writable, quiet: boolean): OutputChannel;
+/**
+ * Returns the channel for a step that runs an nmr process below this one: nmr's own descriptor whenever it has
+ * one, so that the child writes where nmr writes, without an ancestor between them relaying bytes. A stream
+ * without a descriptor falls back to a pipe.
+ */
+export declare function resolveInheritedChannel(stream: Writable): OutputChannel;

package/dist/esm/output-channel.js

@@ -0,0 +1,14 @@
+export function isTerminal(stream) {
+    return 'isTTY' in stream && stream.isTTY === true && hasDescriptor(stream);
+}
+export function resolveChannel(stream, quiet) {
+    if (quiet)
+        return 'pipe';
+    return isTerminal(stream) ? stream.fd : 'pipe';
+}
+export function resolveInheritedChannel(stream) {
+    return hasDescriptor(stream) ? stream.fd : 'pipe';
+}
+function hasDescriptor(stream) {
+    return 'fd' in stream && typeof stream.fd === 'number';
+}