@williamthorsen/nmr 0.48.0 → 0.49.0

package/dist/esm/crossing-diagnostics.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { resolveConfigPath } from "./helpers/config-path.js";
+import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
+import { isHookName } from "./helpers/hook-name.js";
+import { resolvePackageJsonPath } from "./helpers/package-json.js";
+import { hasRunnableHook } from "./hooks.js";
+import { expandScript, findChainedSelfReference, readPackageJsonScripts, } from "./resolver.js";
+import { findNmrCrossing, readSoleNmrCommand, renderChain } from "./steps.js";
+import { UserError } from "./UserError.js";
+const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
+export function assertNoSelfReference(options) {
+    const { anchorDir, command, isReading, isWorkspaceRoot, monorepoRoot, registry } = options;
+    if (isReading) {
+        return;
+    }
+    const script = findChainedSelfReference(anchorDir, command);
+    if (script === undefined) {
+        return;
+    }
+    const remedy = formatSelfReferenceRemedy({ command, isWorkspaceRoot, monorepoRoot, registry, script });
+    const site = path.relative(monorepoRoot, resolvePackageJsonPath(anchorDir));
+    throw new UserError(`${site}: \`scripts.${command}\` re-invokes \`nmr ${command}\` (\`${escapeControlCharacters(script)}\`), ` +
+        `so nmr cannot run the steps that it chains. ${remedy}`);
+}
+export function reportNmrCrossing(options) {
+    const crossingStep = findNmrCrossing(options.resolvedScript.steps);
+    if (options.isReading || crossingStep === undefined) {
+        return;
+    }
+    const warning = formatNmrCrossingWarning({
+        crossingStep,
+        isWorkspaceRoot: options.isWorkspaceRoot,
+        monorepoRoot: options.monorepoRoot,
+        origin: describeOrigin(options.resolvedScript.origin, options.config, options.shouldUseRoot),
+        registry: options.registry,
+        style: options.style,
+    });
+    options.stderr.write(`${warning}\n`);
+}
+function describeCrossingRemedy(options) {
+    const { crossingStep, isWorkspaceRoot, monorepoRoot, origin, registry } = options;
+    const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
+    switch (origin.tier) {
+        case 'default':
+            return {
+                remedy: 'A built-in default reaching nmr through a shell is an nmr defect: please report it.',
+                subject: `nmr built-in \`${origin.key}\``,
+            };
+        case 'config':
+            return {
+                remedy: `Write the nmr steps as a step list, and move any others to ${describeStepDestination(origin.key)}.`,
+                subject: `${configSite}: \`${origin.field}.${origin.key}\``,
+            };
+        case 'package':
+            return {
+                remedy: formatInlineRemedy({ crossingStep, file: origin.file, isWorkspaceRoot, key: origin.key, registry }) ??
+                    formatPackageRemedy({ configSite, crossingStep, isWorkspaceRoot, key: origin.key, registry }),
+                subject: `${path.relative(monorepoRoot, origin.file)}: \`scripts.${origin.key}\``,
+            };
+        default: {
+            const unhandledOrigin = origin;
+            throw new Error(`Unhandled script origin: ${JSON.stringify(unhandledOrigin)}`);
+        }
+    }
+}
+function describeOrigin(origin, config, shouldUseRoot) {
+    if (origin.tier === 'package') {
+        return origin;
+    }
+    const field = shouldUseRoot ? 'rootScripts' : 'workspaceScripts';
+    const configScripts = config[field];
+    return configScripts !== undefined && Object.hasOwn(configScripts, origin.key)
+        ? { tier: 'config', field, key: origin.key }
+        : { tier: 'default', key: origin.key };
+}
+function describeStepDestination(key) {
+    if (isHookName(key)) {
+        return 'a script of their own that the step list names, because a hook does not have a `:pre` or `:post` of its own';
+    }
+    return `a \`${key}:pre\` or \`${key}:post\` script`;
+}
+function formatInlineRemedy(options) {
+    const { crossingStep, file, isWorkspaceRoot, key, registry } = options;
+    const name = readSoleNmrCommand(crossingStep);
+    if (name === undefined || name === key) {
+        return undefined;
+    }
+    const scripts = readPackageJsonScripts(path.dirname(file));
+    const value = scripts !== undefined && Object.hasOwn(scripts, name) ? scripts[name]?.trim() : undefined;
+    if (value === undefined || ['', ':'].includes(value)) {
+        return undefined;
+    }
+    if (findNmrCrossing([{ kind: 'opaque', command: value }]) !== undefined) {
+        return undefined;
+    }
+    const anchorDir = path.dirname(file);
+    if (!isHookName(name) &&
+        [`${name}:pre`, `${name}:post`].some((hook) => hasRunnableHook(hook, registry, anchorDir, isWorkspaceRoot))) {
+        return undefined;
+    }
+    const inlinedValue = escapeControlCharacters(value);
+    return Object.hasOwn(registry, name)
+        ? `Replace the value with \`${inlinedValue}\`, and keep \`${name}\`, which overrides nmr's own.`
+        : `Replace the value with \`${inlinedValue}\` and delete \`${name}\`, the script that it names.`;
+}
+function formatNmrCrossingWarning(options) {
+    const { remedy, subject } = describeCrossingRemedy(options);
+    return (`${STATUS_GLYPHS[options.style].warning.text} ${subject} reaches nmr through a shell ` +
+        `(\`${escapeControlCharacters(options.crossingStep)}\`), ${CROSSING_CONSEQUENCE} ${remedy}`);
+}
+function formatPackageRemedy(options) {
+    const { configSite, crossingStep, isWorkspaceRoot, key, registry } = options;
+    const registryEntry = Object.hasOwn(registry, key) ? registry[key] : undefined;
+    if (registryEntry === undefined) {
+        return (`A \`package.json\` script cannot contain a step list: define \`${key}\` in \`${configSite}\` and move the ` +
+            `package-specific steps to ${describeStepDestination(key)}.`);
+    }
+    const registryChain = renderChain(expandScript(registryEntry, isWorkspaceRoot));
+    if (registryChain === crossingStep) {
+        return `Delete the entry: nmr's own \`${key}\` already runs \`${escapeControlCharacters(registryChain)}\`.`;
+    }
+    return `Delete the entry and move the steps that it adds to ${describeStepDestination(key)}.`;
+}
+function formatSelfReferenceRemedy(options) {
+    const { command, isWorkspaceRoot, monorepoRoot, registry, script } = options;
+    if (isHookName(command)) {
+        return `Delete the re-invocation: \`${command}\` runs the steps beside it.`;
+    }
+    const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
+    return formatPackageRemedy({ configSite, crossingStep: script, isWorkspaceRoot, key: command, registry });
+}

package/dist/esm/default-scripts.js

@@ -1,4 +1,4 @@
-import { quoteToken } from "./steps.js";
+import { quoteToken } from "./shell-syntax.js";
 const GATE_PROJECTS = '--project unit --project tool';
 const TYPECHECK_STEP = { run: 'typecheck', shouldDeclineArguments: true };
 const ROOT_TYPECHECK_STEP = { run: 'root:typecheck', shouldDeclineArguments: true };

package/dist/esm/delegate-host.d.ts

@@ -0,0 +1,43 @@
+import type { ExecutionTarget, Invocation, PhaseResult, RunCliResult, 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';
+} | {
+    kind: 'refused';
+    exitCode: number;
+} | {
+    kind: 'ran';
+    durationMs: number;
+    exitCode: number;
+    host: string;
+    outcome: VerdictOutcome;
+    /** The host's pass-manifest entries, unvalidated, empty when the run did not complete or its host sent none. */
+    passes: unknown[];
+    retainedOutput: RetainedOutput;
+    /** The tree that was pushed, absent when the working tree could not be snapshotted. */
+    treeId: string | undefined;
+};
+/**
+ * Decides where the invocation runs, warning about a delegation flag that the command will receive as an argument.
+ * Settles an invocation whose delegation is refused.
+ */
+export declare function resolveExecutionTarget(invocation: Invocation): Promise<PhaseResult<ExecutionTarget>>;
+/**
+ * Runs the whole invocation on the host and reports one verdict for it, its connection, transfer, and install
+ * included. Returns `undefined` when the invocation runs here after all.
+ *
+ * Serves a `-F` or `-R` invocation, which does not have a gate of its own to consult first: the host fans it out.
+ */
+export declare function runInvocationOnHost(invocation: Invocation, target: RemoteTarget): Promise<RunCliResult | undefined>;
+/**
+ * Runs a plan's command on the host, once the gate has found no pass to recall. Returns what the run produced, its
+ * output included so that a pass can be recorded with its transcript, and leaves the verdict to the caller.
+ */
+export declare function runPlanOnHost(plan: RunPlan, target: RemoteTarget): Promise<HostRunResult>;
+/** A target that names its candidate hosts. */
+type RemoteTarget = Extract<ExecutionTarget, {
+    kind: 'remote';
+}>;
+export {};

package/dist/esm/delegate-host.js

@@ -0,0 +1,178 @@
+import os from 'node:os';
+import { Writable } from 'node:stream';
+import { reportError } from '@williamthorsen/nmr-core';
+import { NO_CACHE_ENV_VAR, resolveRunId, writeDebugNote } from "./check-cache.js";
+import { buildChildEnv, buildRemoteEnv } from "./child-env.js";
+import { resolveDelegationTarget } from "./delegation-target.js";
+import { createBoundedBuffer } from "./helpers/createBoundedBuffer.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, NO_DELEGATE_FLAG, runRemotely, } from "./remote-run.js";
+import { createSnapshot } from "./remote-snapshot.js";
+import { formatDisplayPath, loadUserConfig } from "./user-config.js";
+export async function resolveExecutionTarget(invocation) {
+    const { command, context, env, parsedArgs, stderr, styles } = invocation;
+    if (parsedArgs.passthrough.some(isDelegationFlag)) {
+        stderr.write(`${formatMisplacedDelegationWarning(command, styles.stderr)}\n`);
+    }
+    const target = await resolveDelegationTarget({
+        command,
+        env,
+        extraAgentEnvVars: context.config.output?.extraAgentEnvVars,
+        flagValue: parsedArgs.delegateHosts,
+        isFanOut: parsedArgs.filter !== undefined || parsedArgs.recursive,
+        isOptedOut: parsedArgs.shouldRunLocally,
+        isReading: parsedArgs.shouldPrintLog,
+        isRepoOptedOut: context.config.delegate === false,
+        readUserConfig: () => loadUserConfig(env),
+        shouldDelegate: parsedArgs.shouldDelegate,
+    });
+    if (target.kind === 'refused') {
+        reportError(target.error, stderr);
+        return { settled: true, result: { exitCode: 1 } };
+    }
+    if (target.kind === 'remote') {
+        writeDebugNote(`delegating ${command} per ${describeDelegationSource(target, parsedArgs, env)}`, env, stderr);
+    }
+    return { settled: false, value: target };
+}
+export async function runInvocationOnHost(invocation, target) {
+    const { env, format, parsedArgs, styles } = invocation;
+    const childEnv = buildChildEnv({
+        env,
+        format,
+        passthrough: parsedArgs.passthrough,
+        runId: resolveRunId(env),
+        shouldBypassCache: parsedArgs.shouldBypassCache || env[NO_CACHE_ENV_VAR] === '1',
+        shouldBypassLock: parsedArgs.shouldBypassLock,
+        snapshot: undefined,
+        styles,
+        verbosity: invocation.verbosity,
+    });
+    const result = await delegate({ invocation, remoteEnv: buildRemoteEnv(childEnv), target });
+    if (result.kind === 'here') {
+        return undefined;
+    }
+    if (result.kind === 'ran') {
+        reportVerdict({ command: invocation.command, host: result.host, scope: invocation.scope, ...result.outcome }, invocation.stdout, format, styles.stdout);
+    }
+    return { exitCode: result.exitCode };
+}
+export async function runPlanOnHost(plan, target) {
+    return delegate({
+        invocation: plan.invocation,
+        remoteEnv: buildRemoteEnv(plan.runOptions.env ?? plan.invocation.env),
+        target,
+    });
+}
+const PROBE_RESULT_PHRASES = {
+    busy: 'is busy',
+    free: 'is free',
+    'no-answer': 'did not answer the lock probe',
+};
+function composeForwardedArgs(command, parsedArgs) {
+    return [
+        ...(parsedArgs.filter === undefined ? [] : ['--filter', parsedArgs.filter]),
+        ...(parsedArgs.recursive ? ['--recursive'] : []),
+        ...(parsedArgs.isWorkspaceRoot ? ['--workspace-root'] : []),
+        ...(parsedArgs.quiet ? ['--quiet'] : []),
+        ...(parsedArgs.shouldEmitJson ? ['--json'] : []),
+        ...(parsedArgs.shouldBypassCache ? ['--no-cache'] : []),
+        ...(parsedArgs.shouldBypassLock ? ['--no-lock'] : []),
+        command,
+        ...parsedArgs.passthrough,
+    ];
+}
+function createTee(stream, buffer) {
+    return new Writable({
+        write(chunk, _encoding, callback) {
+            buffer.append(chunk);
+            stream.write(chunk);
+            callback();
+        },
+    });
+}
+function describeDelegationSource(target, parsedArgs, env) {
+    switch (target.source) {
+        case 'config':
+            return `${formatDisplayPath(target.configPath, env)} (when: ${target.when})`;
+        case 'env':
+            return DELEGATE_ENV_VAR;
+        case 'flag':
+            return parsedArgs.delegateHosts === undefined ? DELEGATE_FLAG : DELEGATE_TO_FLAG;
+    }
+}
+async function delegate(options) {
+    const { invocation, remoteEnv, target } = options;
+    const { command, context, cwd, env, parsedArgs, stderr, stdout } = invocation;
+    const listedHosts = target.hosts.join(', ');
+    const startedAtMs = Date.now();
+    const snapshot = createSnapshot(cwd, env);
+    if (!snapshot.ok && snapshot.isUnsupported) {
+        if (target.source === 'flag') {
+            reportError(`Cannot delegate to ${listedHosts}: ${snapshot.reason}`, stderr);
+            return { kind: 'refused', exitCode: 1 };
+        }
+        stderr.write(`nmr: running ${command} here rather than on ${listedHosts}: ${snapshot.reason}\n`);
+        return { kind: 'here' };
+    }
+    const host = snapshot.ok ? await resolveHost(target.hosts, snapshot.toplevel, env, stderr) : target.hosts[0];
+    const retained = { stderr: createBoundedBuffer(), stdout: createBoundedBuffer() };
+    const result = snapshot.ok
+        ? await runRemotely({
+            command,
+            cwd,
+            env,
+            host,
+            monorepoRoot: context.monorepoRoot,
+            nmrArgs: composeForwardedArgs(command, parsedArgs),
+            remoteEnv,
+            snapshot,
+            stderr: createTee(stderr, retained.stderr),
+            stdout: createTee(stdout, retained.stdout),
+        })
+        : { ok: false, message: 'could not snapshot the working tree', output: snapshot.reason, waitedMs: 0 };
+    const durationMs = Date.now() - startedAtMs - result.waitedMs;
+    const ran = {
+        kind: 'ran',
+        durationMs,
+        host,
+        retainedOutput: { stderr: retained.stderr.readBuffer(), stdout: retained.stdout.readBuffer() },
+        treeId: snapshot.ok ? snapshot.treeId : undefined,
+    };
+    if (!result.ok) {
+        if (result.output.trim() !== '') {
+            stderr.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+        }
+        if (target.source === 'config' && 'phase' in result && result.phase === 'prepare') {
+            const configPath = formatDisplayPath(target.configPath, env);
+            stderr.write(`nmr: ${configPath} sent ${command} to ${listedHosts}; ask for network access to ${listedHosts}, ` +
+                `or run it here with nmr ${NO_DELEGATE_FLAG} ${command}\n`);
+        }
+        return {
+            ...ran,
+            exitCode: DELEGATION_FAILURE_EXIT_CODE,
+            passes: [],
+            outcome: { outcome: 'failed', detail: result.message, durationMs, exitCode: DELEGATION_FAILURE_EXIT_CODE },
+        };
+    }
+    const outcome = result.exitCode === 0
+        ? { outcome: 'passed', durationMs }
+        : { outcome: 'failed', durationMs, exitCode: result.exitCode };
+    return { ...ran, exitCode: result.exitCode, outcome, passes: result.passes };
+}
+async function resolveHost(hosts, toplevel, env, stderr) {
+    const [first, ...rest] = hosts;
+    if (rest.length === 0) {
+        return first;
+    }
+    const checkoutPath = deriveCheckoutPath(os.hostname(), toplevel);
+    return chooseHost({
+        hosts,
+        onSettled(host, result) {
+            writeDebugNote(`${host} ${PROBE_RESULT_PHRASES[result]}`, env, stderr);
+        },
+        probe: (host, signal) => probeHost({ checkoutPath, env, host, signal }),
+    });
+}

package/dist/esm/delegation-target.d.ts

@@ -0,0 +1,52 @@
+import { type HostList } from './remote-run.js';
+import { type DelegateWhen, type LoadedUserConfig } from './user-config.js';
+/**
+ * Where a delegation runs, or why the invocation cannot run where it asked to. A delegation that the user config
+ * decided names the file and the `when` that matched.
+ */
+export type DelegationTarget = {
+    kind: 'local';
+} | {
+    kind: 'remote';
+    hosts: HostList;
+    source: 'env' | 'flag';
+} | {
+    kind: 'remote';
+    hosts: HostList;
+    source: 'config';
+    configPath: string;
+    when: DelegateWhen;
+} | {
+    kind: 'refused';
+    error: string;
+};
+/**
+ * Decides where an invocation runs, by the first rule that applies:
+ *
+ * 1. `--no-delegate` runs it here.
+ * 2. `--delegate-to` runs it on the hosts that it names, and `--delegate` on `NMR_DELEGATE`'s, or else the user
+ *    config's.
+ * 3. A repo config declaring `delegate: false` runs it here.
+ * 4. `NMR_DELEGATE` naming hosts runs it on them.
+ * 5. `NMR_DELEGATE` set without a host runs it here, which is how a step keeps to where its parent runs.
+ * 6. The user config's `when` matching runs it on the config's hosts, unless `CI` is set or the invocation fans out.
+ * 7. Otherwise, it runs here.
+ *
+ * A command that rewrites the tree, or that runs until it is stopped, cannot be delegated, and neither can `--log`,
+ * which reads this machine's recordings. Asked for by a flag, such an invocation is refused; asked for by the
+ * variable or the user config, which set a default for every invocation, it runs here.
+ *
+ * The user config is read only when a rule reaches it, so an invalid one fails only a run that consults it.
+ */
+export declare function resolveDelegationTarget(options: {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    extraAgentEnvVars: readonly string[] | undefined;
+    flagValue: string | undefined;
+    isFanOut: boolean;
+    isOptedOut: boolean;
+    isReading: boolean;
+    isRepoOptedOut: boolean;
+    readUserConfig: () => Promise<LoadedUserConfig | undefined>;
+    shouldDelegate: boolean;
+}): Promise<DelegationTarget>;

package/dist/esm/delegation-target.js

@@ -0,0 +1,71 @@
+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;
+    if (isOptedOut) {
+        return { kind: 'local' };
+    }
+    const isDelegable = !isReading && !NON_DELEGABLE_COMMANDS.has(command);
+    const envValue = env[DELEGATE_ENV_VAR];
+    const envHosts = parseHostList(envValue ?? '');
+    if (flagValue !== undefined || shouldDelegate) {
+        return resolveRequestedTarget({ command, env, envHosts, flagValue, isDelegable, isReading, readUserConfig });
+    }
+    if (isRepoOptedOut) {
+        return { kind: 'local' };
+    }
+    if (envHosts !== undefined) {
+        return isDelegable ? { kind: 'remote', hosts: envHosts, source: 'env' } : { kind: 'local' };
+    }
+    if (envValue !== undefined || !isDelegable || isFanOut || hasValue(env['CI'])) {
+        return { kind: 'local' };
+    }
+    const loaded = await readUserConfig();
+    const delegate = loaded?.config.delegate;
+    if (loaded === undefined || delegate?.when === undefined) {
+        return { kind: 'local' };
+    }
+    if (delegate.when === 'agent' && !hasAgentMarker(env, extraAgentEnvVars)) {
+        return { kind: 'local' };
+    }
+    return { kind: 'remote', hosts: delegate.hosts, source: 'config', configPath: loaded.path, when: delegate.when };
+}
+const DEFAULT_USER_CONFIG_PATH = '~/.config/nmr/config.ts';
+const NON_DELEGABLE_BASE_COMMANDS = ['build', 'clean', 'compile', 'fix', 'fmt', 'lint', 'test:watch', 'upgrade'];
+const NON_DELEGABLE_COMMANDS = new Set([
+    ...NON_DELEGABLE_BASE_COMMANDS,
+    ...NON_DELEGABLE_BASE_COMMANDS.map((command) => `root:${command}`),
+]);
+function hasValue(value) {
+    return value !== undefined && value !== '';
+}
+function parseHostList(value) {
+    const names = value.split(',').map((host) => host.trim());
+    const [first, ...rest] = new Set(names.filter((host) => host !== ''));
+    return first === undefined ? undefined : [first, ...rest];
+}
+async function resolveRequestedTarget(options) {
+    const { command, env, envHosts, flagValue, isDelegable, isReading, readUserConfig } = options;
+    const flag = flagValue === undefined ? DELEGATE_FLAG : DELEGATE_TO_FLAG;
+    const flagHosts = flagValue === undefined ? undefined : parseHostList(flagValue);
+    if (flagValue !== undefined && flagHosts === undefined) {
+        return { kind: 'refused', error: `${DELEGATE_TO_FLAG} requires a host: "${flagValue}" does not name a host.` };
+    }
+    if (!isDelegable) {
+        const subject = isReading ? '--log' : `\`${command}\``;
+        const reason = isReading ? "reads this machine's recordings" : 'rewrites the working tree or runs until stopped';
+        return { kind: 'refused', error: `${subject} cannot be delegated: it ${reason}. Run it without ${flag}.` };
+    }
+    const hosts = flagHosts ?? envHosts ?? (await readUserConfig())?.config.delegate?.hosts;
+    if (hosts === undefined) {
+        const configPath = formatDisplayPath(resolveUserConfigPath(env) ?? DEFAULT_USER_CONFIG_PATH, env);
+        return {
+            kind: 'refused',
+            error: `${DELEGATE_FLAG} needs hosts: set \`delegate.hosts\` in ${configPath}, or name them with ` +
+                `${DELEGATE_TO_FLAG} <host,...>.`,
+        };
+    }
+    return { kind: 'remote', hosts, source: 'flag' };
+}

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

@@ -0,0 +1,57 @@
+import type { Writable } from 'node:stream';
+import type { ResolvedContext } from './context.js';
+import { type RunCliResult } from './invocation.js';
+import type { ParsedArgs } from './invocation-args.js';
+import { type 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.
+ *
+ * One structural step, to keep the pattern given to `-F` and the arguments passed on as argv tokens rather than
+ * text spliced into a shell string, and to make the nmr processes underneath write where this one writes although
+ * the binary spawned is `pnpm`. A flag of nmr's own precedes the command name, where the nmr underneath reads
+ * it as its own rather than passing it on to the command.
+ *
+ * A `--log` fan-out surveys the scopes selected, so a scope with nothing to show is a gap in the survey rather
+ * than a failure of it, however that scope was selected.
+ */
+export declare function composeDelegation(options: {
+    childEnv: NodeJS.ProcessEnv;
+    command: string;
+    parsedArgs: ParsedArgs;
+}): {
+    env: NodeJS.ProcessEnv;
+    step: Extract<Step, {
+        kind: 'structural';
+    }>;
+} | undefined;
+/**
+ * Reports whether any scope that a delegation can select defines the command. A package config does not define
+ * scripts, so the root config's registries and each `package.json` cover every scope.
+ */
+export declare function isDefinedInAnyScope(command: string, context: ResolvedContext): boolean;
+/**
+ * Runs a `-F` or `-R` delegation, or refuses it when it would not select any scope.
+ *
+ * The refusal precedes the delegate rather than reading its outcome, since a delegation that selected nothing
+ * has already run to completion, reporting nothing and exiting 0, by the time nmr sees it.
+ *
+ * A `-R` delegation withholds stdin from its packages, as does a filter that pnpm lists as several packages. pnpm 12
+ * starts each package of a concurrent `exec` in a background process group, which the system stops when it reads
+ * from the terminal or changes its mode, so a command such as `next build` would hang the run. pnpm keeps a serial
+ * run in the foreground, which nmr cannot observe; `-R` itself and a filter's package count stand in for it, and a
+ * `-R` or a dependency-chain filter that pnpm runs serially loses its input as well. A filter whose selection pnpm
+ * did not report keeps nmr's stdin.
+ */
+export declare function runDelegation(options: {
+    context: ResolvedContext;
+    delegation: {
+        env: NodeJS.ProcessEnv;
+        step: Extract<Step, {
+            kind: 'structural';
+        }>;
+    };
+    parsedArgs: ParsedArgs;
+    runOptions: RunStepsOptions;
+    stderr: Writable;
+}): Promise<RunCliResult>;