@williamthorsen/nmr 0.44.0 → 0.45.0

package/dist/esm/runCli.js

@@ -1,12 +1,14 @@
 import path from 'node:path';
-import { describeInvalidOutputStyle, formatGlyphLine, readPackageVersion, reportError, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
+import { describeInvalidOutputStyle, formatGlyphLine, reportError, resolveSelfVersion, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
 import { resolveContext } from "./context.js";
+import { enterChain } from "./entry-chain.js";
 import { NMR_GLYPHS } from "./glyphs.js";
 import { generateHelp } from "./help.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
+import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { readFilterSelection } from "./helpers/filter-selection.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
@@ -18,27 +20,38 @@ import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
 import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, readPackageJsonScripts, resolveScript, } from "./resolver.js";
 import { resolveChannel, runSteps } from "./runner.js";
-import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, quoteToken, renderChain } from "./steps.js";
+import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, quoteToken, readSoleNmrCommand, renderChain, } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
-const VERSION = readPackageVersion(import.meta.url);
+const VERSION = resolveSelfVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
 const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
 const LIST_CEILING = 10;
-const NAMED_ESCAPES = new Map([
-    ['\n', String.raw `\n`],
-    ['\r', String.raw `\r`],
-    ['\t', String.raw `\t`],
-]);
 export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
-    const { args, env, stdout, stderr } = options;
+    const established = await establishInvocation(options);
+    if (established.settled) {
+        return { exitCode: established.result.exitCode };
+    }
+    const invocation = established.value;
+    const planned = await planRun(invocation);
+    const { exitCode, isUnknownCommand = false } = planned.settled ? planned.result : await executePlan(planned.value);
+    if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(options.env)) {
+        const hint = formatMisplacedFlagHint(options.args, invocation.parsedArgs.passthrough, invocation.styles.stderr);
+        if (hint !== undefined) {
+            options.stderr.write(`${hint}\n`);
+        }
+    }
+    return { exitCode };
+}
+async function establishInvocation(options) {
+    const { args, cwd, env, stdout, stderr } = options;
     const parseResult = parseArgs(args);
     if (!parseResult.ok) {
         reportError(parseResult.error, stderr);
-        return { exitCode: 1 };
+        return { settled: true, result: { exitCode: 1 } };
     }
     const { parsedArgs } = parseResult;
     const presentationRead = readPresentation({
@@ -49,24 +62,12 @@ export async function runCli(options) {
     });
     if (!presentationRead.ok) {
         reportError(presentationRead.error, stderr);
-        return { exitCode: 1 };
+        return { settled: true, result: { exitCode: 1 } };
     }
     const { styles } = presentationRead;
-    const { exitCode, isUnknownCommand = false } = await runInvocation({ ...options, parsedArgs, presentationRead });
-    if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(env)) {
-        const hint = formatMisplacedFlagHint(args, parsedArgs.passthrough, styles.stderr);
-        if (hint !== undefined) {
-            stderr.write(`${hint}\n`);
-        }
-    }
-    return { exitCode };
-}
-async function runInvocation(options) {
-    const { cwd, env, parsedArgs, presentationRead, stderr, stdout } = options;
-    const { styles } = presentationRead;
     if (parsedArgs.shouldShowVersion) {
         stdout.write(`${VERSION}\n`);
-        return { exitCode: 0 };
+        return { settled: true, result: { exitCode: 0 } };
     }
     const context = await resolveContext(cwd);
     const format = resolveReportFormat({ envFormat: presentationRead.format, hasJsonFlag: parsedArgs.shouldEmitJson });
@@ -77,15 +78,33 @@ async function runInvocation(options) {
         output: context.config.output,
         hasQuietFlag: parsedArgs.quiet,
     });
-    const quiet = verbosity === 'quiet';
     const shouldUseRoot = parsedArgs.isWorkspaceRoot || context.isRoot;
     const anchorDir = shouldUseRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
     if (parsedArgs.shouldShowHelp || !parsedArgs.command) {
         stdout.write(`${generateHelp(context.config, context.monorepoRoot, anchorDir, shouldUseRoot)}\n`);
-        return { exitCode: 0 };
+        return { settled: true, result: { exitCode: 0 } };
     }
-    const { command } = parsedArgs;
-    const scope = path.basename(anchorDir);
+    return {
+        settled: false,
+        value: {
+            anchorDir,
+            command: parsedArgs.command,
+            context,
+            env,
+            format,
+            parsedArgs,
+            scope: path.basename(anchorDir),
+            shouldUseRoot,
+            stderr,
+            stdout,
+            styles,
+            verbosity,
+        },
+    };
+}
+async function planRun(invocation) {
+    const { anchorDir, command, context, env, parsedArgs, stderr, stdout, styles } = invocation;
+    const quiet = invocation.verbosity === 'quiet';
     const snapshot = openGate({
         command,
         config: context.config,
@@ -99,13 +118,13 @@ async function runInvocation(options) {
     const runId = resolveRunId(env);
     const childEnv = buildChildEnv({
         env,
-        format,
+        format: invocation.format,
         shouldBypassCache,
         passthrough: parsedArgs.passthrough,
         runId,
         snapshot,
         styles,
-        verbosity,
+        verbosity: invocation.verbosity,
     });
     const runOptions = {
         quiet,
@@ -116,9 +135,12 @@ async function runInvocation(options) {
     const delegation = composeDelegation({ childEnv, command, parsedArgs });
     if (delegation !== undefined) {
         const result = await runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
-        return { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) };
+        return {
+            settled: true,
+            result: { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) },
+        };
     }
-    const registry = shouldUseRoot
+    const registry = invocation.shouldUseRoot
         ? buildRootRegistry(context.config, context.monorepoRoot)
         : buildWorkspaceRegistry(context.config);
     assertNoSelfReference({
@@ -132,24 +154,50 @@ async function runInvocation(options) {
     const resolvedScript = resolveScript(command, registry, anchorDir, parsedArgs.isWorkspaceRoot);
     if (!resolvedScript) {
         if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
-            return { exitCode: 0 };
+            return { settled: true, result: { exitCode: 0 } };
         }
         reportError(`Unknown command: ${command}`, stderr);
-        return { exitCode: 1, isUnknownCommand: true };
+        return { settled: true, result: { exitCode: 1, isUnknownCommand: true } };
+    }
+    const entryRunOptions = parsedArgs.shouldPrintLog
+        ? runOptions
+        : {
+            ...runOptions,
+            env: enterChain({ anchorDir, command, env: childEnv, monorepoRoot: context.monorepoRoot }),
+        };
+    const chain = assembleChain({ invocation, registry, resolvedScript, snapshot });
+    if (chain.settled) {
+        return chain;
     }
+    return {
+        settled: false,
+        value: {
+            ...chain.value,
+            invocation,
+            overrideNotice: formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, styles.stdout),
+            runId,
+            runOptions: entryRunOptions,
+            shouldBypassCache,
+            snapshot,
+        },
+    };
+}
+function assembleChain(options) {
+    const { invocation, registry, resolvedScript, snapshot } = options;
+    const { anchorDir, command, context, env, parsedArgs, stderr, stdout, styles } = invocation;
     const { isEmptiedByWorkspace, steps: runnableSteps } = readRunnableSteps(resolvedScript, context.workspacePackageDirs);
     const resolvedCommand = renderChain(runnableSteps);
     const noOpReason = findNoOpReason(resolvedCommand, isEmptiedByWorkspace);
     if (noOpReason !== undefined && !parsedArgs.shouldPrintLog) {
-        reportVerdict({ command, scope, outcome: 'no-op', reason: noOpReason }, stdout, format, styles.stdout);
-        return { exitCode: 0 };
+        reportVerdict({ command, scope: invocation.scope, outcome: 'no-op', reason: noOpReason }, stdout, invocation.format, styles.stdout);
+        return { settled: true, result: { exitCode: 0 } };
     }
     const substitutedSteps = applyDevBinToSteps(runnableSteps, context.config.devBin, context.monorepoRoot);
     const substitutedCommand = renderChain(substitutedSteps);
     const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
     if (!bindResult.ok) {
         reportError(bindResult.error, stderr);
-        return { exitCode: 1 };
+        return { settled: true, result: { exitCode: 1 } };
     }
     const mainSteps = bindResult.steps;
     const isHookInvocation = isHookName(command);
@@ -164,7 +212,7 @@ async function runInvocation(options) {
         monorepoRoot: context.monorepoRoot,
         registry,
         resolvedScript,
-        shouldUseRoot,
+        shouldUseRoot: invocation.shouldUseRoot,
         stderr,
         style: styles.stderr,
     });
@@ -178,40 +226,14 @@ async function runInvocation(options) {
         stderr,
         substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
+    return { settled: false, value: { commandString: fullCommand, key, ownSteps: mainSteps, steps: fullSteps } };
+}
+async function executePlan(plan) {
+    const { command, format, parsedArgs, scope, stdout, styles } = plan.invocation;
     if (parsedArgs.shouldPrintLog) {
-        return reportRecording({
-            anchorDir,
-            command,
-            commandString: fullCommand,
-            config: context.config,
-            env,
-            key,
-            monorepoRoot: context.monorepoRoot,
-            scope,
-            snapshot,
-            stderr,
-            stdout,
-            styles,
-        });
+        return reportRecording(plan);
     }
-    const { exitCode, outcome } = await runGated({
-        anchorDir,
-        command,
-        commandString: fullCommand,
-        config: context.config,
-        steps: fullSteps,
-        env,
-        key,
-        monorepoRoot: context.monorepoRoot,
-        overrideNotice: formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, styles.stdout),
-        ownSteps: mainSteps,
-        runId,
-        runOptions,
-        shouldBypassCache,
-        snapshot,
-        stderr,
-        stdout,
-    });
+    const { exitCode, outcome } = await runGated(plan);
     reportVerdict({ command, scope, ...outcome }, stdout, format, styles.stdout);
     return { exitCode };
 }
@@ -325,7 +347,8 @@ function describeCrossingRemedy(options) {
             };
         case 'package':
             return {
-                remedy: formatPackageRemedy({ configSite, crossingStep, isWorkspaceRoot, key: origin.key, registry }),
+                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: {
@@ -350,12 +373,29 @@ function describeOrigin(origin, config, shouldUseRoot) {
         ? { tier: 'config', field, key: origin.key }
         : { tier: 'default', key: origin.key };
 }
-function escapeControlCharacters(text) {
-    let escapedText = text;
-    for (const [char, escape] of NAMED_ESCAPES) {
-        escapedText = escapedText.split(char).join(escape);
+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;
     }
-    return escapedText;
+    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);
@@ -635,26 +675,27 @@ function parseArgs(args) {
     const error = findArgError(parsedArgs);
     return error === undefined ? { ok: true, parsedArgs } : { ok: false, error };
 }
-async function reportRecording(options) {
-    const { command, config, scope, styles } = options;
+async function reportRecording(plan) {
+    const { anchorDir, command, context, env, scope, stderr, stdout, styles } = plan.invocation;
+    const { config, monorepoRoot } = context;
     const lookup = await resolveRecording({
-        anchorDir: options.anchorDir,
+        anchorDir,
         command,
         currentIdentity: {
-            commandString: options.commandString,
+            commandString: plan.commandString,
             nmrVersion: VERSION,
             nodeVersion: CURRENT_RUNTIME.nodeVersion,
-            treeHash: options.snapshot?.hash,
+            treeHash: plan.snapshot?.hash,
         },
         isCacheable: isCacheableCommand(config.checkCache, command),
-        key: options.key,
-        monorepoRoot: options.monorepoRoot,
+        key: plan.key,
+        monorepoRoot,
     });
     if (!lookup.ok) {
-        options.stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
-        return { exitCode: options.env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
+        stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
+        return { exitCode: env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
     }
-    options.stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
+    stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
     return { exitCode: 0 };
 }
 function readPresentation(options) {
@@ -814,12 +855,14 @@ async function runDelegation(options) {
     const step = shouldWithholdInput ? { ...delegation.step, shouldWithholdInput } : delegation.step;
     return runSteps([step], context.monorepoRoot, { ...runOptions, env: delegation.env });
 }
-async function runGated(options) {
-    const { anchorDir, command, commandString, env, key, monorepoRoot, snapshot, stderr, stdout } = options;
-    const quiet = options.runOptions.quiet === true;
+async function runGated(plan) {
+    const { commandString, key, snapshot } = plan;
+    const { anchorDir, command, context, env, stderr, stdout } = plan.invocation;
+    const { config, monorepoRoot } = context;
+    const quiet = plan.runOptions.quiet === true;
     const gate = key !== undefined && snapshot !== undefined
         ? {
-            buildOutputBefore: await readBuildOutputState(monorepoRoot, options.config),
+            buildOutputBefore: await readBuildOutputState(monorepoRoot, config),
             key,
             retentionKey: computeRetentionKey({
                 channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
@@ -829,7 +872,7 @@ async function runGated(options) {
             snapshot,
         }
         : undefined;
-    if (gate !== undefined && !options.shouldBypassCache) {
+    if (gate !== undefined && !plan.shouldBypassCache) {
         const recalledPass = await lookUpRecordedPass({
             anchorDir,
             buildOutput: gate.buildOutputBefore,
@@ -843,16 +886,16 @@ async function runGated(options) {
         if (recalledPass !== undefined) {
             const { entry, ...recall } = recalledPass;
             if (recall.replay !== undefined) {
-                await certifyRetention({ anchorDir, command, entry, env, monorepoRoot, runId: options.runId, stderr });
+                await certifyRetention({ anchorDir, command, entry, env, monorepoRoot, runId: plan.runId, stderr });
             }
             return { exitCode: 0, outcome: { outcome: 'recalled', ...recall } };
         }
     }
-    if (options.overrideNotice !== undefined) {
-        stdout.write(options.overrideNotice);
+    if (plan.overrideNotice !== undefined) {
+        stdout.write(plan.overrideNotice);
     }
     const startedAtMs = Date.now();
-    const { exitCode, retainedOutput } = await runSteps(options.steps, anchorDir, options.runOptions);
+    const { exitCode, retainedOutput } = await runSteps(plan.steps, anchorDir, plan.runOptions);
     const durationMs = Date.now() - startedAtMs;
     if (exitCode === 0 && gate !== undefined) {
         await recordPass({
@@ -860,15 +903,15 @@ async function runGated(options) {
             buildOutputBefore: gate.buildOutputBefore,
             command,
             commandString,
-            config: options.config,
+            config,
             durationMs,
             env,
             key: gate.key,
             monorepoRoot,
-            ownSteps: options.ownSteps,
+            ownSteps: plan.ownSteps,
             retainedOutput,
             retentionKey: gate.retentionKey,
-            runId: options.runId,
+            runId: plan.runId,
             snapshot: gate.snapshot,
             stderr,
         });

package/dist/esm/steps.d.ts

@@ -41,10 +41,18 @@ export interface NmrStepTarget {
     isWorkspaceRoot: boolean;
 }
 /**
- * How a `package.json` entry names the command under which it is declared: as its whole value, or alongside
- * other steps. `sole` covers an entry with trailing arguments, which do not declare a step of their own.
+ * How an entry names the command under which it is declared: as its whole value, or alongside other steps.
+ * `sole` covers an entry with trailing arguments, which do not declare a step of their own.
  */
 export type SelfReference = 'chained' | 'sole';
+/**
+ * Where an entry resolves, which decides the scopes that `-w`, `-R`, and `-F` send its command to:
+ * - `root`: the root's `package.json` or the config's `rootScripts`, resolved at the monorepo root.
+ * - `package`: a non-root package's own `package.json`, resolved in that package alone.
+ * - `workspaceRegistry`: the config's `workspaceScripts`, resolved in every package that does not override the
+ *   command.
+ */
+export type SelfReferenceScope = 'package' | 'root' | 'workspaceRegistry';
 /**
  * Composes the structural step that re-invokes nmr for one composite element.
  *
@@ -94,24 +102,41 @@ export declare function quoteToken(token: string): string;
  */
 export declare function readNmrStep(step: Step): NmrStepTarget | undefined;
 /**
- * Reports whether a `package.json` entry re-invokes the command under which it is declared, and whether it
- * declares anything besides. Reports nothing for an entry that names another command, or none.
- *
- * Honouring such an entry would spawn a shell running the same command in the same directory, which reads the
- * same entry again without bound, so resolution discards it however it reads. `chained` separates an entry that
- * thereby loses steps from one that declares nothing to lose.
+ * Reports whether a string entry re-invokes the command under which it is declared, and whether it declares
+ * anything besides. Reports nothing for an entry that names another command, or none.
  *
- * A segment that delegates sends the command to other scopes rather than back to this one. `-w` re-enters
- * only from the root, a package's `-w` entry resolving against the root's registry and `package.json` instead of its own.
+ * Honouring such an entry would spawn a shell running the same command in a scope that reads the same entry
+ * again, without bound. `chained` separates an entry that thereby loses steps from one that declares nothing to
+ * lose.
  *
- * Partial in the same ways `findNmrCrossing` is, and for the same reason: What goes unrecognized re-enters
- * without bound, which hangs rather than passing quietly.
+ * Partial in the same ways `findNmrCrossing` is, and for the same reason: What goes unrecognized re-enters once,
+ * and the run fails when `enterChain` finds the command repeated in the same directory.
  */
 export declare function readSelfReference(options: {
-    anchoredAtRoot: boolean;
     commandName: string;
+    scope: SelfReferenceScope;
     script: string;
 }): SelfReference | undefined;
+/**
+ * Returns the command that a string script names when its whole value is `nmr <command>`, or `undefined` for any
+ * other value.
+ *
+ * Exact by design: A flag, an argument, an environment assignment, or a launcher each change what the invocation
+ * runs, or where, so a value that contains one is not interchangeable with the script that it names.
+ */
+export declare function readSoleNmrCommand(script: string): string | undefined;
+/**
+ * Reports whether a step list names the command under which it is declared, and whether it declares anything
+ * besides. Takes each element's instruction: the bare string, or a spec's `run`.
+ *
+ * Reads an element as the instruction that nmr composes into `nmr <element>`, and applies the declaring scope
+ * directly rather than through the `-w` that composition adds at the root.
+ */
+export declare function readStepListSelfReference(options: {
+    commandName: string;
+    elements: readonly string[];
+    scope: SelfReferenceScope;
+}): SelfReference | undefined;
 /**
  * Renders a step list as the `&&` chain that a shell runs.
  *

package/dist/esm/steps.js

@@ -49,18 +49,50 @@ export function readNmrStep(step) {
     return file === 'nmr' ? readNmrTarget(rest) : undefined;
 }
 export function readSelfReference(options) {
-    const { anchoredAtRoot, commandName, script } = options;
+    const { commandName, scope, script } = options;
     const segments = splitSegments(script).filter((segment) => segment.trim() !== '');
     const doesReenter = segments.some((segment) => {
-        const tail = readNmrTail(segment);
-        const target = tail === undefined ? undefined : readNmrTarget(tail);
-        return target?.command === commandName && !target.isDelegate && (anchoredAtRoot || !target.isWorkspaceRoot);
+        const invocation = readNmrTail(segment);
+        const target = invocation === undefined ? undefined : readNmrTarget(invocation.tail);
+        if (invocation === undefined || target === undefined) {
+            return false;
+        }
+        const launcherScope = readLauncherScope(invocation.launcher, invocation.launcherArgs);
+        const effectiveTarget = {
+            command: target.command,
+            isDelegate: target.isDelegate || launcherScope.isDelegate,
+            isRecursive: target.isRecursive || launcherScope.isRecursive,
+            isWorkspaceRoot: target.isWorkspaceRoot || launcherScope.isWorkspaceRoot,
+        };
+        return isReentry(effectiveTarget, commandName, scope);
     });
     if (!doesReenter) {
         return undefined;
     }
     return segments.length === 1 ? 'sole' : 'chained';
 }
+export function readSoleNmrCommand(script) {
+    const segments = splitSegments(script).filter((segment) => segment.trim() !== '');
+    if (segments.length !== 1) {
+        return undefined;
+    }
+    const [program, command, ...rest] = tokenizeSegment(segments[0] ?? '');
+    if (program !== 'nmr' || command === undefined || rest.length > 0) {
+        return undefined;
+    }
+    return SHELL_SAFE_TOKEN.test(command) && !command.startsWith('-') ? command : undefined;
+}
+export function readStepListSelfReference(options) {
+    const { commandName, elements, scope } = options;
+    const doesReenter = elements.some((element) => {
+        const target = readNmrTarget(tokenize(element));
+        return target !== undefined && isReentry(target, commandName, scope);
+    });
+    if (!doesReenter) {
+        return undefined;
+    }
+    return elements.length === 1 ? 'sole' : 'chained';
+}
 export function renderChain(steps) {
     return steps.map(renderStep).join(' && ');
 }
@@ -74,24 +106,59 @@ function isRedirectionOperator(char, precedingText, nextChar) {
     }
     return (char === '&' && nextChar === '>') || /[<>]\s*$/.test(precedingText);
 }
+function isReentry(target, commandName, scope) {
+    if (target.command !== commandName) {
+        return false;
+    }
+    switch (scope) {
+        case 'root':
+            return !target.isDelegate;
+        case 'package':
+            return target.isRecursive || (!target.isDelegate && !target.isWorkspaceRoot);
+        case 'workspaceRegistry':
+            return target.isDelegate || !target.isWorkspaceRoot;
+    }
+}
+function readLauncherScope(launcher, launcherArgs) {
+    const scope = { isDelegate: false, isRecursive: false, isWorkspaceRoot: false };
+    if (launcher !== 'pnpm') {
+        return scope;
+    }
+    for (const token of launcherArgs) {
+        if (token === '-r' || token === '--recursive') {
+            scope.isDelegate = true;
+            scope.isRecursive = true;
+        }
+        else if (token === '-F' || token === '--filter' || token.startsWith('--filter=')) {
+            scope.isDelegate = true;
+        }
+        else if (token === '-w' || token === '--workspace-root') {
+            scope.isWorkspaceRoot = true;
+        }
+    }
+    return scope;
+}
 function readNmrTail(segment) {
     const [head, ...rest] = dropLeadingAssignments(tokenizeSegment(segment));
     if (head === undefined) {
         return undefined;
     }
     if (head === 'nmr') {
-        return rest;
+        return { launcher: undefined, launcherArgs: [], tail: rest };
     }
     const subcommands = LAUNCHERS.get(head);
     if (subcommands === undefined) {
         return undefined;
     }
-    if (subcommands.size === 0) {
-        const nameIndex = rest.findIndex((token) => !token.startsWith('-'));
-        return nameIndex !== -1 && rest[nameIndex] === 'nmr' ? rest.slice(nameIndex + 1) : undefined;
+    const nmrIndex = subcommands.size === 0
+        ? rest.findIndex((token) => !token.startsWith('-'))
+        : rest.findIndex((token) => subcommands.has(token)) + 1;
+    if (nmrIndex <= 0 && subcommands.size > 0) {
+        return undefined;
     }
-    const subcommandIndex = rest.findIndex((token) => subcommands.has(token));
-    return subcommandIndex !== -1 && rest[subcommandIndex + 1] === 'nmr' ? rest.slice(subcommandIndex + 2) : undefined;
+    return rest[nmrIndex] === 'nmr'
+        ? { launcher: head, launcherArgs: rest.slice(0, nmrIndex), tail: rest.slice(nmrIndex + 1) }
+        : undefined;
 }
 function readNmrTarget(tokens) {
     let isDelegate = false;

package/dist/esm/tiers.d.ts

@@ -56,10 +56,11 @@ export interface TestFileScanOptions {
     excludedBasenames?: readonly string[];
 }
 /**
- * The isolation ladder, ordered by the furthest thing that a test reaches. A tier names what a test reaches, never
- * how it invokes it: A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning `tsc`
- * would be. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is collected by the `tool`
- * project.
+ * The isolation ladder, ordered by the furthest thing that a test reaches, which decides what the environment must
+ * supply for the test to run. A tier names what a test reaches, never how it invokes it: A test driving a compiler
+ * through its JavaScript API is `tool`, exactly as one spawning `tsc` would be, and a spawned process is itself
+ * something reached. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is collected by the
+ * `tool` project.
  */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
 /** One of the four isolation tiers. */

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

@@ -3,8 +3,10 @@ process.env['GIT_CONFIG_GLOBAL'] = os.devNull;
 process.env['GIT_CONFIG_SYSTEM'] = os.devNull;
 process.env['GIT_CONFIG_NOSYSTEM'] = '1';
 process.env['GIT_ATTR_NOSYSTEM'] = '1';
-process.env['GIT_CONFIG_COUNT'] = '2';
+process.env['GIT_CONFIG_COUNT'] = '3';
 process.env['GIT_CONFIG_KEY_0'] = 'core.excludesFile';
 process.env['GIT_CONFIG_VALUE_0'] = os.devNull;
 process.env['GIT_CONFIG_KEY_1'] = 'core.attributesFile';
 process.env['GIT_CONFIG_VALUE_1'] = os.devNull;
+process.env['GIT_CONFIG_KEY_2'] = 'maintenance.auto';
+process.env['GIT_CONFIG_VALUE_2'] = 'false';

package/docs/reporting.md

@@ -65,6 +65,8 @@ Because the format is nmr's own reporting, and nmr does not tell the commands th
 
 `NMR_REPORT_FORMAT` is nmr's own as well, and sets how nmr renders its own verdicts. Its values are `text` and `json`; nmr reports any other non-empty value and exits 1, and an empty value reads as unset. `--json` sets it for the run and outranks an inherited value, and both values are spelled out so that either direction is expressible: Export `NMR_REPORT_FORMAT=json` for a shell whose consumer parses, and set `text` on one invocation to opt back out. The format has two sources, then, whereas a verbosity has four: It does not have a repo-level default or harness detection, because detection would hand every agent JSON in place of the prose that the [bundled guidance](../README.md#agent-guidance) teaches. See [reporting for a machine](#reporting-for-a-machine) for what the objects contain.
 
+`NMR_ENTRY_CHAIN` is nmr's own as well. It lists the commands that the current run has entered and the directories in which it entered them, and nmr passes it to every process that it starts, so that a process re-entering a command already running in its directory fails instead of repeating without end; see [self-referential entries](scripts.md#three-tier-override-system). Do not set it: nmr reports a value that it cannot read and exits 1.
+
 ### Output style
 
 `--output-style <auto|plain|rich>` sets the style for one invocation, and `NMR_OUTPUT_STYLE` sets it for a shell: `rich` marks each verdict with an emoji, such as ✅ or ❌, and `plain` prints a word in its place, such as `PASS` or `FAIL`, which a reader of a log can search for. `auto`, the default, defers to detection. Any other value is a usage error, and nmr exits with code 1, whichever source named it. The flag outranks the variable, and both accept `auto` as well as a style, so a shell exporting one style is overridable on one invocation in either direction.