@williamthorsen/nmr 0.44.0 → 0.46.0

package/dist/esm/config.js

@@ -9,11 +9,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { resolveConfigPath } from "./helpers/config-path.js";
+import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
-import { buildRootRegistry, buildWorkspaceRegistry, readPackageJsonScripts } from "./resolver.js";
-import { findUnexpressibleToken } from "./steps.js";
+import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { buildRootRegistry, buildWorkspaceRegistry, describeScript, readPackageJsonScripts } from "./resolver.js";
+import { findUnexpressibleToken, readSelfReference, readStepListSelfReference, } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 import { getWorkspacePackageDirs, isMonorepoRoot } from "./workspace.js";
@@ -35,6 +37,10 @@ const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommand
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
 const RECOGNIZED_SELF_HOSTED_RUNNER_KEYS = ['exempt'];
 const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments', 'shouldRunInBackground'];
+const SCRIPT_FIELDS = [
+    { field: 'rootScripts', scope: 'root' },
+    { field: 'workspaceScripts', scope: 'workspaceRegistry' },
+];
 const RETIRED_STEP_KEYS = new Map([['declinesArgs', 'shouldDeclineArguments']]);
 function isScriptRecord(value) {
     if (!isObject(value))
@@ -286,7 +292,9 @@ export async function loadConfig(baseDir) {
 }
 export async function loadRootConfig(monorepoRoot) {
     const config = await loadConfig(monorepoRoot);
-    assertTierKeys(config, CONFIG_TIERS.root, resolveConfigPath(monorepoRoot));
+    const configPath = resolveConfigPath(monorepoRoot);
+    assertTierKeys(config, CONFIG_TIERS.root, configPath);
+    assertNoSelfReferences(config, configPath, monorepoRoot);
     return config;
 }
 export async function loadWorkspaceConfig(packageDir) {
@@ -302,6 +310,30 @@ function assertNoRetiredKeys(value, retiredKeys, configPath, prefix) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`${prefix}${key}\` was renamed to \`${prefix}${replacement}\`.`);
     }
 }
+function assertNoSelfReferences(config, configPath, monorepoRoot) {
+    for (const { field, scope } of SCRIPT_FIELDS) {
+        const scripts = config[field] ?? {};
+        for (const [key, script] of Object.entries(scripts)) {
+            const selfReference = typeof script === 'string'
+                ? readSelfReference({ commandName: key, scope, script })
+                : readStepListSelfReference({
+                    commandName: key,
+                    elements: script.map((element) => (typeof element === 'string' ? element : element.run)),
+                    scope,
+                });
+            if (selfReference === undefined)
+                continue;
+            const defaults = field === 'rootScripts' ? getDefaultRootScripts(monorepoRoot) : getDefaultWorkspaceScripts();
+            const remedy = formatSelfReferenceRemedy({
+                isDefault: !isHookName(key) && Object.hasOwn(defaults, key),
+                key,
+                selfReference,
+            });
+            throw new UserError(`Invalid nmr config at ${configPath}: \`${field}.${key}\` re-invokes \`${key}\` ` +
+                `(\`${escapeControlCharacters(describeScript(script))}\`), which would re-enter nmr without bound. ${remedy}`);
+        }
+    }
+}
 function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
     const unrecognizedKeys = Object.keys(value).filter((key) => !recognizedKeys.includes(key));
     if (unrecognizedKeys.length === 0) {
@@ -324,3 +356,14 @@ function formatKeyList(keys, prefix) {
         .map((key) => `\`${prefix}${key}\``)
         .join(', ');
 }
+function formatSelfReferenceRemedy(options) {
+    const { isDefault, key, selfReference } = options;
+    if (isDefault) {
+        return selfReference === 'sole'
+            ? `Delete the entry: nmr's own \`${key}\` then runs.`
+            : `Delete the entry and move the steps that it adds to a \`${key}:pre\` or \`${key}:post\` script.`;
+    }
+    return selfReference === 'sole'
+        ? 'Delete the entry.'
+        : `Delete the re-invocation: \`${key}\` runs the steps beside it.`;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Carries the entries that a run is inside, from the outermost inward, down to every process that it spawns. An
+ * entry that finds itself already on the chain would re-enter itself without bound.
+ */
+export declare const ENTRY_CHAIN_ENV_VAR = "NMR_ENTRY_CHAIN";
+/** A command that an invocation resolved, and the directory whose registry it resolved the command from. */
+export interface ChainEntry {
+    command: string;
+    dir: string;
+}
+/**
+ * Admits an invocation onto the chain that it inherited, returning the environment that its steps inherit in turn.
+ * Throws a `UserError` when an ancestor in the run is already running the same command from the same directory, or
+ * when the inherited chain cannot be read.
+ *
+ * Records the directory's real path, so that a symlinked checkout or a `/private` prefix seen by one process and not
+ * another cannot hide a repeat.
+ */
+export declare function enterChain(options: {
+    anchorDir: string;
+    command: string;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+}): NodeJS.ProcessEnv;

package/dist/esm/entry-chain.js

@@ -0,0 +1,57 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { isObject } from "./helpers/type-guards.js";
+import { UserError } from "./UserError.js";
+export const ENTRY_CHAIN_ENV_VAR = 'NMR_ENTRY_CHAIN';
+export function enterChain(options) {
+    const { anchorDir, command, env, monorepoRoot } = options;
+    const chain = readEntryChain(env[ENTRY_CHAIN_ENV_VAR]);
+    if (chain === undefined) {
+        throw new UserError(`${ENTRY_CHAIN_ENV_VAR} is not a chain that nmr wrote; unset it. nmr passes it to the processes that it starts.`);
+    }
+    const entry = { command, dir: realpathSync(anchorDir) };
+    const extendedChain = [...chain, entry];
+    if (chain.some((ancestor) => ancestor.command === entry.command && ancestor.dir === entry.dir)) {
+        throw new UserError(formatReentryError(extendedChain, realpathSync(monorepoRoot)));
+    }
+    return { ...env, [ENTRY_CHAIN_ENV_VAR]: JSON.stringify(extendedChain) };
+}
+function describeDir(dir, monorepoRoot) {
+    const relativeDir = path.relative(monorepoRoot, dir);
+    if (relativeDir === '') {
+        return 'root';
+    }
+    return relativeDir.startsWith('..') || path.isAbsolute(relativeDir) ? dir : relativeDir;
+}
+function formatReentryError(chain, monorepoRoot) {
+    const repeat = chain.at(-1);
+    if (repeat === undefined) {
+        throw new Error('A re-entry error needs the entry that repeats.');
+    }
+    const repeatDir = describeDir(repeat.dir, monorepoRoot);
+    const lines = chain.map((entry) => {
+        const isRepeat = entry.command === repeat.command && entry.dir === repeat.dir;
+        return `  ${entry.command} in ${describeDir(entry.dir, monorepoRoot)}${isRepeat ? '  (repeat)' : ''}`;
+    });
+    return [
+        `nmr re-entered \`${repeat.command}\` in ${repeatDir}, which this run is already running there, ` +
+            'so the run would never end. The entries that this run has entered, outermost first:',
+        ...lines,
+    ].join('\n');
+}
+function isChainEntry(value) {
+    return isObject(value) && typeof value['command'] === 'string' && typeof value['dir'] === 'string';
+}
+function readEntryChain(value) {
+    if (value === undefined || value === '') {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    return Array.isArray(parsed) && parsed.every(isChainEntry) ? parsed : undefined;
+}

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" | "clean" | "package" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "package" | "clean" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type NmrGlyphName = keyof (typeof NMR_GLYPHS)['rich'];

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

@@ -0,0 +1,10 @@
+/**
+ * Renders a declaration's text as the file stores it, so that a value written across lines is quoted on one line.
+ *
+ * A diagnostic names a declaration that the reader has to edit, and a JSON string contains an escape sequence where
+ * a shell would read a control character. The rendered escape keeps the diagnostic on one line, and it is the text
+ * for which the reader will search the file.
+ *
+ * Apply it only where the text is quoted: A comparison against the declaration reads the unescaped text.
+ */
+export declare function escapeControlCharacters(text: string): string;

package/dist/esm/helpers/escapeControlCharacters.js

@@ -0,0 +1,12 @@
+const NAMED_ESCAPES = new Map([
+    ['\n', String.raw `\n`],
+    ['\r', String.raw `\r`],
+    ['\t', String.raw `\t`],
+]);
+export function escapeControlCharacters(text) {
+    let escapedText = text;
+    for (const [char, escape] of NAMED_ESCAPES) {
+        escapedText = escapedText.split(char).join(escape);
+    }
+    return escapedText;
+}

package/dist/esm/resolver.js

@@ -108,12 +108,12 @@ export function findChainedSelfReference(packageDir, commandName) {
     if (script === undefined) {
         return undefined;
     }
-    return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) === 'chained'
+    return readSelfReference({ commandName, scope: readPackageScope(packageDir), script }) === 'chained'
         ? script
         : undefined;
 }
 export function isSelfReferential(script, commandName, packageDir) {
-    return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) !== undefined;
+    return readSelfReference({ commandName, scope: readPackageScope(packageDir), script }) !== undefined;
 }
 export function resolveScript(commandName, registry, packageDir, isWorkspaceRoot) {
     if (packageDir) {
@@ -137,3 +137,6 @@ export function resolveScript(commandName, registry, packageDir, isWorkspaceRoot
     }
     return { origin: { tier: 'registry', key: commandName }, steps: expandScript(registryEntry, isWorkspaceRoot) };
 }
+function readPackageScope(packageDir) {
+    return isMonorepoRoot(packageDir) ? 'root' : 'package';
+}

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,
         });