@williamthorsen/nmr 0.43.0 → 0.45.0

package/dist/esm/config.js

@@ -9,18 +9,20 @@ 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";
 const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'devBin', 'output', 'rootScripts', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'devBin', 'output', 'rootScripts', 'selfHostedRunner', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -33,7 +35,12 @@ const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.works
 const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
-const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments'];
+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))
@@ -51,8 +58,7 @@ function isScriptElement(value) {
         return true;
     if (!isObject(value) || typeof value['run'] !== 'string')
         return false;
-    const shouldDeclineArguments = value['shouldDeclineArguments'];
-    return shouldDeclineArguments === undefined || typeof shouldDeclineArguments === 'boolean';
+    return isOptionalBoolean(value['shouldDeclineArguments']) && isOptionalBoolean(value['shouldRunInBackground']);
 }
 function validateScriptField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
@@ -61,7 +67,8 @@ function validateScriptField(value, fieldName, configPath) {
     const scripts = value[fieldName];
     if (!isScriptRecord(scripts)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | element[]>, ` +
-            'where an element is a command string or `{ run: string, shouldDeclineArguments?: boolean }`');
+            'where an element is a command string or ' +
+            '`{ run: string, shouldDeclineArguments?: boolean, shouldRunInBackground?: boolean }`');
     }
     assertValidElements(scripts, fieldName, configPath);
     return scripts;
@@ -85,6 +92,9 @@ function assertValidElements(scripts, fieldName, configPath) {
         }
     }
 }
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
@@ -132,6 +142,21 @@ function validateCheckCacheField(value, configPath) {
     }
     return config;
 }
+function validateSelfHostedRunnerField(value, configPath) {
+    const selfHostedRunner = value['selfHostedRunner'];
+    if (selfHostedRunner === undefined) {
+        return undefined;
+    }
+    if (!isObject(selfHostedRunner)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`selfHostedRunner\` must be an object`);
+    }
+    assertRecognizedKeys(selfHostedRunner, RECOGNIZED_SELF_HOSTED_RUNNER_KEYS, configPath, 'selfHostedRunner.');
+    const exempt = selfHostedRunner['exempt'];
+    if (typeof exempt !== 'string' || exempt.trim() === '') {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`selfHostedRunner.exempt\` must be a non-empty string giving the reason`);
+    }
+    return { exempt };
+}
 function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
     const { checkCache } = config;
     if (checkCache === undefined || !isMonorepoRoot(baseDir)) {
@@ -145,7 +170,7 @@ function assertResolvableCheckCacheCommands(config, configPath, baseDir) {
             'which is never gated on its own: It runs as part of the chain of the command that it wraps.');
     }
     const registeredNames = new Set([
-        ...Object.keys(buildRootRegistry(config)),
+        ...Object.keys(buildRootRegistry(config, baseDir)),
         ...Object.keys(buildWorkspaceRegistry(config)),
     ]);
     const missingEntries = entries.filter(({ command }) => !registeredNames.has(command));
@@ -250,6 +275,9 @@ function validateConfig(value, configPath, baseDir) {
     const rootScripts = validateScriptField(value, 'rootScripts', configPath);
     if (rootScripts)
         config.rootScripts = rootScripts;
+    const selfHostedRunner = validateSelfHostedRunnerField(value, configPath);
+    if (selfHostedRunner)
+        config.selfHostedRunner = selfHostedRunner;
     assertResolvableCheckCacheCommands(config, configPath, baseDir);
     return config;
 }
@@ -264,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) {
@@ -280,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) {
@@ -302,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/default-scripts.d.ts

@@ -10,6 +10,11 @@ export interface StepSpec {
      * narrowed steps run, or the tool that it invokes would be misled by them. A declining step runs unnarrowed.
      */
     shouldDeclineArguments?: boolean;
+    /**
+     * Set to start this step and run the steps after it without waiting for it. The composite waits for it before
+     * ending, and prints its output whole at the first step boundary after it ends.
+     */
+    shouldRunInBackground?: boolean;
 }
 export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;
@@ -19,4 +24,8 @@ export type ScriptRegistry = Record<string, ScriptValue>;
  * collects every file that does not name any other tier.
  */
 export declare const workspaceScripts: ScriptRegistry;
-export declare const rootScripts: ScriptRegistry;
+/**
+ * Builds the root scripts. Each root-only lint command excludes the workspaces, given as globs relative to the root,
+ * so that the root ESLint config never lints a package.
+ */
+export declare function buildRootScripts(workspaceGlobs: readonly string[]): ScriptRegistry;

package/dist/esm/default-scripts.js

@@ -1,10 +1,13 @@
+import { quoteToken } from "./steps.js";
 const GATE_PROJECTS = '--project unit --project tool';
 const TYPECHECK_STEP = { run: 'typecheck', shouldDeclineArguments: true };
 const ROOT_TYPECHECK_STEP = { run: 'root:typecheck', shouldDeclineArguments: true };
+const LINT_CHECK_STEP = { run: 'lint:check', shouldRunInBackground: true };
+const LINT_STRICT_STEP = { run: 'lint:strict', shouldRunInBackground: true };
 export const workspaceScripts = {
     build: ['compile'],
-    check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
-    'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test'],
+    check: [LINT_CHECK_STEP, TYPECHECK_STEP, 'fmt:check', 'test'],
+    'check:strict': [LINT_STRICT_STEP, TYPECHECK_STEP, 'fmt:check', 'test'],
     clean: 'nmr-clean',
     compile: 'nmr-compile',
     fix: ['lint', 'fmt'],
@@ -25,40 +28,43 @@ export const workspaceScripts = {
     upgrade: 'nmr-report-catalog && nmr-taze',
     'view-coverage': 'open coverage/index.html',
 };
-export const rootScripts = {
-    audit: ['audit:prod', 'audit:dev'],
-    'audit:dev': 'pnpm exec v11y --dev',
-    'audit:prod': 'pnpm exec v11y --prod',
-    build: ['-R build'],
-    check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
-    'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test'],
-    ci: [{ run: 'build', shouldDeclineArguments: true }, 'check:strict'],
-    clean: 'nmr-clean',
-    fix: ['lint', 'fmt'],
-    'fix:check': ['fmt:check', 'lint:check'],
-    fmt: 'nmr-fmt --write',
-    'fmt:check': 'nmr-fmt --check',
-    lint: 'eslint --fix .',
-    'lint:check': 'eslint .',
-    'lint:strict': 'strict-lint',
-    prepush: [{ run: 'audit', shouldDeclineArguments: true }, 'ci'],
-    'report-overrides': 'nmr-report-overrides',
-    'root:check': [ROOT_TYPECHECK_STEP, 'fmt:check', 'root:lint:check', 'root:test'],
-    'root:lint': "eslint --fix --ignore-pattern 'packages/**' .",
-    'root:lint:check': "eslint --ignore-pattern 'packages/**' .",
-    'root:lint:strict': "strict-lint --ignore-pattern 'packages/**' .",
-    'root:test': `vitest --config ./vitest.root.config.ts ${GATE_PROJECTS}`,
-    'root:test:all': 'vitest --config ./vitest.root.config.ts',
-    'root:test:tool': 'vitest --config ./vitest.root.config.ts --project tool',
-    'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
-    'root:typecheck': 'tsgo --noEmit',
-    'root:upgrade': 'nmr-report-overrides && nmr-taze',
-    test: ['root:test', '-R test'],
-    'test:all': ['root:test:all', '-R test:all'],
-    'test:coverage': ['root:test', '-R test:coverage'],
-    'test:tool': ['root:test:tool', '-R test:tool'],
-    'test:unit': ['root:test:unit', '-R test:unit'],
-    'test:watch': `vitest ${GATE_PROJECTS} --watch`,
-    typecheck: [ROOT_TYPECHECK_STEP, { run: '-R typecheck', shouldDeclineArguments: true }],
-    upgrade: 'nmr-report-overrides && nmr-taze --recursive',
-};
+export function buildRootScripts(workspaceGlobs) {
+    const ignorePatterns = workspaceGlobs.map((glob) => `--ignore-pattern ${quoteToken(glob)} `).join('');
+    return {
+        audit: ['audit:prod', 'audit:dev'],
+        'audit:dev': 'pnpm exec v11y --dev',
+        'audit:prod': 'pnpm exec v11y --prod',
+        build: ['-R build'],
+        check: [LINT_CHECK_STEP, TYPECHECK_STEP, 'fmt:check', 'test'],
+        'check:strict': [LINT_STRICT_STEP, TYPECHECK_STEP, 'fmt:check', 'test'],
+        ci: [{ run: 'build', shouldDeclineArguments: true }, 'check:strict'],
+        clean: 'nmr-clean',
+        fix: ['lint', 'fmt'],
+        'fix:check': ['fmt:check', 'lint:check'],
+        fmt: 'nmr-fmt --write',
+        'fmt:check': 'nmr-fmt --check',
+        lint: 'eslint --fix .',
+        'lint:check': 'eslint .',
+        'lint:strict': 'strict-lint',
+        prepush: [{ run: 'audit', shouldDeclineArguments: true }, 'ci'],
+        'report-overrides': 'nmr-report-overrides',
+        'root:check': [ROOT_TYPECHECK_STEP, 'fmt:check', 'root:lint:check', 'root:test'],
+        'root:lint': `eslint --fix ${ignorePatterns}.`,
+        'root:lint:check': `eslint ${ignorePatterns}.`,
+        'root:lint:strict': `strict-lint ${ignorePatterns}.`,
+        'root:test': `vitest --config ./vitest.root.config.ts ${GATE_PROJECTS}`,
+        'root:test:all': 'vitest --config ./vitest.root.config.ts',
+        'root:test:tool': 'vitest --config ./vitest.root.config.ts --project tool',
+        'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
+        'root:typecheck': 'tsgo --noEmit',
+        'root:upgrade': 'nmr-report-overrides && nmr-taze',
+        test: ['root:test', '-R test'],
+        'test:all': ['root:test:all', '-R test:all'],
+        'test:coverage': ['root:test', '-R test:coverage'],
+        'test:tool': ['root:test:tool', '-R test:tool'],
+        'test:unit': ['root:test:unit', '-R test:unit'],
+        'test:watch': `vitest ${GATE_PROJECTS} --watch`,
+        typecheck: [ROOT_TYPECHECK_STEP, { run: '-R typecheck', shouldDeclineArguments: true }],
+        upgrade: 'nmr-report-overrides && nmr-taze --recursive',
+    };
+}

package/dist/esm/defineConfig.d.ts

@@ -1,5 +1,5 @@
 import type { NmrConfig } from './types.js';
-export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, StepSpec, } from './types.js';
+export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, SelfHostedRunnerConfig, StepSpec, } from './types.js';
 /**
  * Returns `config` unchanged, typing a configuration file's default export as `NmrConfig`.
  *

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/help.d.ts

@@ -16,4 +16,4 @@ import type { NmrConfig } from './types.js';
  * unless it is an npm or pnpm lifecycle script or the active registry
  * contains its name.
  */
-export declare function generateHelp(config: NmrConfig, packageDir: string | undefined, shouldUseRoot: boolean): string;
+export declare function generateHelp(config: NmrConfig, monorepoRoot: string, packageDir: string | undefined, shouldUseRoot: boolean): string;

package/dist/esm/help.js

@@ -23,7 +23,7 @@ const LIFECYCLE_SCRIPT_NAMES = new Set([
     'uninstall',
     'version',
 ]);
-export function generateHelp(config, packageDir, shouldUseRoot) {
+export function generateHelp(config, monorepoRoot, packageDir, shouldUseRoot) {
     const lines = [
         'Usage: nmr [flags] <command> [args...]',
         '',
@@ -54,12 +54,12 @@ export function generateHelp(config, packageDir, shouldUseRoot) {
         hadOverride = true;
     formatRegistry(workspaceRegistry, workspaceMarkedNames, lines);
     lines.push('', 'Root commands:');
-    const rootRegistry = filterHooks(buildRootRegistry(config));
+    const rootRegistry = filterHooks(buildRootRegistry(config, monorepoRoot));
     const rootMarkedNames = shouldUseRoot ? applyOverrides(rootRegistry, overrides) : new Set();
     if (rootMarkedNames.size > 0)
         hadOverride = true;
     formatRegistry(rootRegistry, rootMarkedNames, lines);
-    const activeRegistry = shouldUseRoot ? buildRootRegistry(config) : buildWorkspaceRegistry(config);
+    const activeRegistry = shouldUseRoot ? buildRootRegistry(config, monorepoRoot) : buildWorkspaceRegistry(config);
     const unregisteredScripts = collectUnregisteredScripts(packageScripts, activeRegistry);
     if (Object.keys(unregisteredScripts).length > 0) {
         lines.push('', 'Package scripts:');

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

@@ -0,0 +1,17 @@
+import { Writable } from 'node:stream';
+/** Which of a child's output streams a recorded chunk arrived on. */
+type StreamName = 'stderr' | 'stdout';
+export interface OutputRecorder {
+    /** Destination for the child's stderr. It does not have a descriptor, so a child writing to it is given a pipe. */
+    stderr: Writable;
+    /** Destination for the child's stdout. It does not have a descriptor, so a child writing to it is given a pipe. */
+    stdout: Writable;
+    /** Writes every recorded chunk to the destination matching its stream, in the order in which the chunks arrived. */
+    replay: (destinations: Record<StreamName, Writable>) => void;
+}
+/**
+ * Creates a pair of in-memory destinations that hold everything written to them, unbounded, so that output
+ * produced while other output is streaming can be printed whole afterwards.
+ */
+export declare function createOutputRecorder(): OutputRecorder;
+export {};

package/dist/esm/helpers/createOutputRecorder.js

@@ -0,0 +1,22 @@
+import { Writable } from 'node:stream';
+export function createOutputRecorder() {
+    const entries = [];
+    function createSink(stream) {
+        return new Writable({
+            write(chunk, encoding, callback) {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), encoding);
+                entries.push({ chunk: buffer, stream });
+                callback();
+            },
+        });
+    }
+    return {
+        stderr: createSink('stderr'),
+        stdout: createSink('stdout'),
+        replay: (destinations) => {
+            for (const { chunk, stream } of entries) {
+                destinations[stream].write(chunk);
+            }
+        },
+    };
+}

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/resolve-scripts.d.ts

@@ -6,7 +6,9 @@ export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js
  */
 export declare function getDefaultWorkspaceScripts(): ScriptRegistry;
 /**
- * Returns a shallow copy of the default root scripts, whose entries a caller may replace without changing the
- * defaults.
+ * Returns the default root scripts for the monorepo at `monorepoRoot`, whose root-only lint commands exclude every
+ * workspace package that its `pnpm-workspace.yaml` declares. A directory without that manifest yields commands
+ * without exclusions rather than an error, so that a caller reading only the command names need not stand in a
+ * workspace.
  */
-export declare function getDefaultRootScripts(): ScriptRegistry;
+export declare function getDefaultRootScripts(monorepoRoot: string): ScriptRegistry;

package/dist/esm/resolve-scripts.js

@@ -1,7 +1,11 @@
-import { rootScripts, workspaceScripts } from "./default-scripts.js";
+import { buildRootScripts, workspaceScripts } from "./default-scripts.js";
+import { resolveWorkspace } from "./workspace.js";
+import { toWorkspacePackageGlobs } from "./workspace-globs.js";
 export function getDefaultWorkspaceScripts() {
     return { ...workspaceScripts };
 }
-export function getDefaultRootScripts() {
-    return { ...rootScripts };
+export function getDefaultRootScripts(monorepoRoot) {
+    const resolution = resolveWorkspace(monorepoRoot);
+    const packageDirs = resolution.kind === 'packages' ? resolution.packageDirs : [];
+    return buildRootScripts(toWorkspacePackageGlobs(monorepoRoot, packageDirs));
 }

package/dist/esm/resolver.d.ts

@@ -35,8 +35,9 @@ export interface ResolvedScript {
  * Expands a script value into the ordered steps that it runs as: a string is one opaque step, and an array is one
  * structural step per element.
  *
- * A bare string element and the `{ run }` spec compose the same step. The spec's only addition is the
- * declaration of what the step does with the invocation's trailing arguments, which position cannot express.
+ * A bare string element and the `{ run }` spec compose the same step. The spec adds only declarations that
+ * position cannot express: what the step does with the invocation's trailing arguments, and whether it runs in
+ * the background.
  */
 export declare function expandScript(script: ScriptValue, isWorkspaceRoot: boolean): readonly Step[];
 /**
@@ -56,10 +57,10 @@ export declare function readPackageJsonScripts(packageDir: string): Record<strin
  */
 export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistry;
 /**
- * Builds the merged root script registry:
+ * Builds the merged root script registry for the monorepo at `monorepoRoot`:
  * tier 1 (defaults) + tier 2 (config overrides)
  */
-export declare function buildRootRegistry(config: NmrConfig): ScriptRegistry;
+export declare function buildRootRegistry(config: NmrConfig, monorepoRoot: string): ScriptRegistry;
 /**
  * Returns a `package.json` entry that re-invokes the command under which it is declared alongside other steps,
  * or `undefined` when the entry does not.

package/dist/esm/resolver.js

@@ -46,7 +46,10 @@ export function expandScript(script, isWorkspaceRoot) {
     }
     return script.map((element) => typeof element === 'string'
         ? composeNmrStep(element, isWorkspaceRoot)
-        : composeNmrStep(element.run, isWorkspaceRoot, element.shouldDeclineArguments));
+        : composeNmrStep(element.run, isWorkspaceRoot, {
+            shouldDeclineArguments: element.shouldDeclineArguments,
+            shouldRunInBackground: element.shouldRunInBackground,
+        }));
 }
 export function describeScript(script) {
     return typeof script === 'string' ? script : `[${script.map(describeElement).join(', ')}]`;
@@ -55,7 +58,11 @@ function describeElement(element) {
     if (typeof element === 'string') {
         return element;
     }
-    return element.shouldDeclineArguments === true ? `${element.run} (no args)` : element.run;
+    const notes = [
+        ...(element.shouldRunInBackground === true ? ['background'] : []),
+        ...(element.shouldDeclineArguments === true ? ['no args'] : []),
+    ];
+    return notes.length === 0 ? element.run : `${element.run} (${notes.join(', ')})`;
 }
 export function readPackageJsonScripts(packageDir) {
     const file = resolvePackageJsonPath(packageDir);
@@ -83,9 +90,9 @@ export function buildWorkspaceRegistry(config) {
         ...config.workspaceScripts,
     };
 }
-export function buildRootRegistry(config) {
+export function buildRootRegistry(config, monorepoRoot) {
     return {
-        ...getDefaultRootScripts(),
+        ...getDefaultRootScripts(monorepoRoot),
         ...config.rootScripts,
     };
 }
@@ -101,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) {
@@ -130,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';
+}