@williamthorsen/nmr 0.55.0 → 1.0.0

package/dist/esm/commands/shellcheck.js

@@ -1,18 +1,18 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { UserError } from '@williamthorsen/nmr-core';
+import { runGit, UserError } from '@williamthorsen/nmr-core';
 import { describeSignalExitCode } from "../child-process.js";
-import { ensureTool } from "./workflow-tools.js";
+import { ensureTool, resolveToolCacheRoots } from "./workflow-tools.js";
 export async function runShellcheck(monorepoRoot, args, options = {}) {
     const shellcheckArgs = args.length > 0 ? [...args] : listPresentScripts(monorepoRoot, options.listFiles);
     if (shellcheckArgs.length === 0) {
         console.info('No shell scripts to lint: the working tree does not contain any tracked *.sh file.');
         return 0;
     }
-    const cacheRoot = options.cacheRoot ?? path.join(monorepoRoot, 'node_modules', '.cache', 'nmr-tools');
-    const ensure = options.ensure ?? ((tool, root) => ensureTool(tool, { cacheRoot: root }));
-    const shellcheckPath = await ensure('shellcheck', cacheRoot);
+    const cacheRoots = options.cacheRoots ?? resolveToolCacheRoots(monorepoRoot);
+    const ensure = options.ensure ?? ((tool, roots) => ensureTool(tool, { cacheRoots: roots }));
+    const shellcheckPath = await ensure('shellcheck', cacheRoots);
     const outcome = (options.spawn ?? spawnInherited)(shellcheckPath, shellcheckArgs, monorepoRoot);
     if (outcome.error !== undefined) {
         throw new UserError(`Cannot run shellcheck: ${outcome.error.message}`, { cause: outcome.error });
@@ -23,12 +23,9 @@ export async function runShellcheck(monorepoRoot, args, options = {}) {
     return outcome.status ?? 1;
 }
 export function listTrackedScripts(monorepoRoot) {
-    const result = spawnSync('git', ['ls-files', '-z', '--', '*.sh'], { cwd: monorepoRoot, encoding: 'utf8' });
-    if (result.error !== undefined) {
-        throw new UserError(`Cannot list tracked shell scripts: ${result.error.message}`, { cause: result.error });
-    }
-    if (result.status !== 0) {
-        throw new UserError(`Cannot list tracked shell scripts: ${result.stderr.trim()}`);
+    const result = runGit(['ls-files', '-z', '--', '*.sh'], monorepoRoot);
+    if (!result.ok) {
+        throw new UserError(`Cannot list tracked shell scripts: ${result.error}`);
     }
     return result.stdout.split('\0').filter((file) => file !== '');
 }

package/dist/esm/commands/taze.js

@@ -4,6 +4,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { NMR_TAZE_BIN } from "../bins.js";
 import { loadPackageMaturityPeriod } from "./load-package-maturity-period.js";
 import { checkNodePin as checkNodePinDefault } from "./node-pin.js";
 import { isSilent, readFlag } from "./taze-args.js";
@@ -24,7 +25,7 @@ export async function runTaze(args, options = {}) {
     }
     catch (error) {
         const detail = describeError(error);
-        reportError(`Could not resolve '${TAZE_CLI_SPECIFIER}' from nmr's dependencies. Reinstall the workspace to restore it. (${detail})`, stderr);
+        reportError(NMR_TAZE_BIN, `Could not resolve '${TAZE_CLI_SPECIFIER}' from nmr's dependencies. Reinstall the workspace to restore it. (${detail})`, stderr);
         return 1;
     }
     let passes;
@@ -32,7 +33,7 @@ export async function runTaze(args, options = {}) {
         passes = planTazePasses(args, await loadConfig(resolveConfigDir(args)));
     }
     catch (error) {
-        reportError(`Could not read the taze config: ${describeError(error)}`, stderr);
+        reportError(NMR_TAZE_BIN, `Could not read the taze config: ${describeError(error)}`, stderr);
         return 1;
     }
     if (readFlag(args, NODE_PIN_SKIP_FLAGS) === undefined) {
@@ -45,7 +46,7 @@ export async function runTaze(args, options = {}) {
             });
         }
         catch (error) {
-            reportError(`Could not check the nodejs pin: ${describeError(error)}`, stderr);
+            reportError(NMR_TAZE_BIN, `Could not check the nodejs pin: ${describeError(error)}`, stderr);
         }
     }
     const showHeadings = !isSilent(args);
@@ -55,7 +56,7 @@ export async function runTaze(args, options = {}) {
             stderr.write(`${pass.heading}\n`);
         const outcome = spawn(process.execPath, [cliPath, ...composeRequestTimeoutArgs(pass.args), ...pass.args]);
         if (outcome.error) {
-            reportError(`Failed to run taze: ${outcome.error.message}`, stderr);
+            reportError(NMR_TAZE_BIN, `Failed to run taze: ${outcome.error.message}`, stderr);
             return 1;
         }
         const status = outcome.status ?? 1;

package/dist/esm/commands/tsconfig-chain.js

@@ -15,7 +15,7 @@ export function resolveTsconfigChain(packageDir, configFileName = 'tsconfig.json
         resolvedChain.push(normalizedPath);
         const configFile = ts.readConfigFile(normalizedPath, (fileName) => ts.sys.readFile(fileName));
         if (configFile.error) {
-            throw new UserError(`nmr-compile: failed to read ${normalizedPath}.\n${formatDiagnostics([configFile.error])}`);
+            throw new UserError(`failed to read ${normalizedPath}.\n${formatDiagnostics([configFile.error])}`);
         }
         for (const entry of normalizeExtendsField(configFile.config)) {
             walk(resolveExtendsTarget(entry, normalizedPath));
@@ -48,12 +48,12 @@ function resolveExtendsTarget(extendsEntry, fromConfigPath) {
         if (ts.sys.fileExists(withJsonExtension)) {
             return withJsonExtension;
         }
-        throw new UserError(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not exist.`);
+        throw new UserError(`${fromConfigPath} extends '${extendsEntry}', which does not exist.`);
     }
     const resolvedPath = resolvePackageSpecifier(extendsEntry, fromConfigPath) ??
         resolvePackageSpecifier(`${extendsEntry}/tsconfig.json`, fromConfigPath);
     if (resolvedPath === undefined) {
-        throw new UserError(`nmr-compile: ${fromConfigPath} extends '${extendsEntry}', which does not resolve to a file.`);
+        throw new UserError(`${fromConfigPath} extends '${extendsEntry}', which does not resolve to a file.`);
     }
     return resolvedPath;
 }

package/dist/esm/commands/workflow-tools.d.ts

@@ -15,8 +15,11 @@ export type ToolPins = Record<WorkflowTool, ToolPin>;
 /** The subset of `fetch` that the download uses. */
 export type FetchFunction = (url: string, init?: RequestInit) => Promise<Response>;
 export interface EnsureToolOptions {
-    /** Directory under which each tool version is cached in a directory of its own. */
-    cacheRoot: string;
+    /**
+     * Directories under which each tool version is cached in a directory of its own, in lookup order. A miss installs
+     * into the first one that can be written.
+     */
+    cacheRoots: readonly [string, ...string[]];
     arch?: string;
     fetch?: FetchFunction;
     pins?: ToolPins;
@@ -29,11 +32,17 @@ export interface EnsureToolOptions {
  */
 export declare const TOOL_PINS: ToolPins;
 /**
- * Returns the path of the tool's pinned binary, downloading, verifying, and caching it first on a cache miss.
+ * Returns the path of the tool's pinned binary, taking the first one cached under any of the roots, and otherwise
+ * downloading, verifying, and caching it under the first root that can be written.
  *
  * A failure at any step leaves the cache without the tool, and a concurrent run never sees a partial binary: The
  * binary is assembled in a scratch directory beside its target and renamed into place only once verified.
  */
 export declare function ensureTool(tool: WorkflowTool, options: EnsureToolOptions): Promise<string>;
+/**
+ * Returns the roots under which the pinned tools are cached, in lookup order: the machine cache under the XDG cache
+ * home, when `env` resolves one, then `node_modules/.cache/nmr-tools` at the monorepo root.
+ */
+export declare function resolveToolCacheRoots(monorepoRoot: string, env?: NodeJS.ProcessEnv): [string, ...string[]];
 /** Maps Node's platform and architecture onto a supported pair, rejecting every other pair. */
 export declare function resolveToolPlatform(platform: NodeJS.Platform, arch: string): ToolPlatform;

package/dist/esm/commands/workflow-tools.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { UserError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { resolveXdgBaseDir } from "../helpers/resolveXdgBaseDir.js";
 const SUPPORTED_PLATFORMS = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64'];
 const DOWNLOAD_TIMEOUT_MS = 60_000;
 const ACTIONLINT_RELEASE = 'https://github.com/rhysd/actionlint/releases/download/v1.7.12';
@@ -58,15 +59,15 @@ export const TOOL_PINS = {
 export async function ensureTool(tool, options) {
     const pin = (options.pins ?? TOOL_PINS)[tool];
     const asset = pin.assets[resolveToolPlatform(options.platform ?? process.platform, options.arch ?? process.arch)];
-    const targetDir = path.join(options.cacheRoot, `${tool}-${pin.version}`);
-    const binaryPath = path.join(targetDir, tool);
-    if (fs.existsSync(binaryPath)) {
-        return binaryPath;
+    const versionDir = `${tool}-${pin.version}`;
+    for (const cacheRoot of options.cacheRoots) {
+        const cachedPath = path.join(cacheRoot, versionDir, tool);
+        if (fs.existsSync(cachedPath)) {
+            return cachedPath;
+        }
     }
-    createCacheRoot(options.cacheRoot);
-    const scratchDir = `${targetDir}.tmp-${process.pid}`;
-    fs.rmSync(scratchDir, { force: true, recursive: true });
-    fs.mkdirSync(scratchDir);
+    const { scratchDir, targetDir } = createScratchDir(options.cacheRoots, versionDir);
+    const binaryPath = path.join(targetDir, tool);
     try {
         const archive = await download(asset.url, options.fetch ?? globalThis.fetch);
         const actualSha256 = createHash('sha256').update(archive).digest('hex');
@@ -90,6 +91,11 @@ export async function ensureTool(tool, options) {
     }
     return binaryPath;
 }
+export function resolveToolCacheRoots(monorepoRoot, env = process.env) {
+    const worktreeRoot = path.join(monorepoRoot, 'node_modules', '.cache', 'nmr-tools');
+    const cacheHome = resolveXdgBaseDir(env, 'XDG_CACHE_HOME', '.cache');
+    return cacheHome === undefined ? [worktreeRoot] : [path.join(cacheHome, 'nmr', 'tools'), worktreeRoot];
+}
 export function resolveToolPlatform(platform, arch) {
     const key = `${platform}-${arch}`;
     const supported = SUPPORTED_PLATFORMS.find((candidate) => candidate === key);
@@ -98,13 +104,22 @@ export function resolveToolPlatform(platform, arch) {
     }
     return supported;
 }
-function createCacheRoot(cacheRoot) {
-    try {
-        fs.mkdirSync(cacheRoot, { recursive: true });
-    }
-    catch (error) {
-        throw new UserError(`Cannot create the tool cache at ${cacheRoot}: ${describeError(error)}`, { cause: error });
+function createScratchDir(cacheRoots, versionDir) {
+    let lastError;
+    for (const cacheRoot of cacheRoots) {
+        const targetDir = path.join(cacheRoot, versionDir);
+        try {
+            fs.mkdirSync(cacheRoot, { recursive: true });
+            return { scratchDir: fs.mkdtempSync(`${targetDir}.tmp-`), targetDir };
+        }
+        catch (error) {
+            lastError = error;
+        }
     }
+    const lastRoot = cacheRoots.at(-1) ?? cacheRoots[0];
+    throw new UserError(`Cannot create the tool cache at ${lastRoot}: ${describeError(lastError)}`, {
+        cause: lastError,
+    });
 }
 async function download(url, fetchImpl) {
     let response;

package/dist/esm/config-validation.js

@@ -1,6 +1,6 @@
-import { UserError } from '@williamthorsen/nmr-core';
+import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { assertResolvableCheckCacheCommands } from "./config-check-cache.js";
-import { isObject, isStringRecord } from "./helpers/type-guards.js";
+import { isStringRecord } from "./helpers/type-guards.js";
 import { findUnexpressibleToken } from "./steps.js";
 import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 export const CONFIG_TIERS = {
@@ -31,7 +31,7 @@ export function assertRecognizedKeys(value, recognizedKeys, configPath, prefix =
         `${formatKeyList(unrecognizedKeys, prefix)}. Recognized: ${formatKeyList(recognizedKeys, prefix)}.`);
 }
 export function validateConfig(value, configPath, baseDir) {
-    if (!isObject(value)) {
+    if (!isRecord(value)) {
         throw new UserError(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
     }
     assertRecognizedKeys(value, RECOGNIZED_KEYS, configPath);
@@ -99,7 +99,7 @@ function isOptionalBoolean(value) {
     return value === undefined || typeof value === 'boolean';
 }
 function isScriptRecord(value) {
-    if (!isObject(value))
+    if (!isRecord(value))
         return false;
     for (const v of Object.values(value)) {
         if (typeof v === 'string')
@@ -112,7 +112,7 @@ function isScriptRecord(value) {
 function isScriptElement(value) {
     if (typeof value === 'string')
         return true;
-    if (!isObject(value) || typeof value['run'] !== 'string')
+    if (!isRecord(value) || typeof value['run'] !== 'string')
         return false;
     return isOptionalBoolean(value['shouldDeclineArguments']) && isOptionalBoolean(value['shouldRunInBackground']);
 }
@@ -124,7 +124,7 @@ function validateBuildField(value, configPath) {
     if (build === undefined) {
         return undefined;
     }
-    if (!isObject(build)) {
+    if (!isRecord(build)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`build\` must be an object`);
     }
     assertRecognizedKeys(build, RECOGNIZED_BUILD_KEYS, configPath, 'build.');
@@ -139,7 +139,7 @@ function validateCheckCacheField(value, configPath) {
     if (checkCache === undefined) {
         return undefined;
     }
-    if (!isObject(checkCache)) {
+    if (!isRecord(checkCache)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache\` must be an object`);
     }
     assertRecognizedKeys(checkCache, RECOGNIZED_CHECK_CACHE_KEYS, configPath, 'checkCache.');
@@ -175,7 +175,7 @@ function validateOutputField(value, configPath) {
     if (output === undefined) {
         return undefined;
     }
-    if (!isObject(output)) {
+    if (!isRecord(output)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`output\` must be an object`);
     }
     assertRecognizedKeys(output, RECOGNIZED_OUTPUT_KEYS, configPath, 'output.');
@@ -202,7 +202,7 @@ function validateSelfHostedRunnerField(value, configPath) {
     if (selfHostedRunner === undefined) {
         return undefined;
     }
-    if (!isObject(selfHostedRunner)) {
+    if (!isRecord(selfHostedRunner)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`selfHostedRunner\` must be an object`);
     }
     assertRecognizedKeys(selfHostedRunner, RECOGNIZED_SELF_HOSTED_RUNNER_KEYS, configPath, 'selfHostedRunner.');

package/dist/esm/config.js

@@ -8,12 +8,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { UserError } from '@williamthorsen/nmr-core';
+import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { CONFIG_TIERS, validateConfig } from "./config-validation.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { isHookName } from "./helpers/hook-name.js";
-import { isObject } from "./helpers/type-guards.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { describeScript } from "./resolver.js";
 import { readSelfReference, readStepListSelfReference } from "./steps.js";
@@ -27,7 +26,7 @@ export async function loadConfig(baseDir) {
         return {};
     }
     const importedModule = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
-    const loadedConfig = isObject(importedModule) ? importedModule['default'] : undefined;
+    const loadedConfig = isRecord(importedModule) ? importedModule['default'] : undefined;
     return validateConfig(loadedConfig, configPath, baseDir);
 }
 export async function loadRootConfig(monorepoRoot) {

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

@@ -1,4 +1,4 @@
-import type { ExecutionTarget, Invocation, PhaseResult, RunCliResult, RunPlan } from './invocation.js';
+import { type ExecutionTarget, type Invocation, type PhaseResult, type RunCliResult, type RunPlan } from './invocation.js';
 import type { RetainedOutput } from './runner.js';
 import type { VerdictOutcome } from './verdict.js';
 /** How a run on the host ended, or that the invocation runs here after all. */

package/dist/esm/delegate-host.js

@@ -1,10 +1,12 @@
 import os from 'node:os';
 import { Writable } from 'node:stream';
 import { reportError, startTimer } from '@williamthorsen/nmr-core';
+import { NMR_BIN } from "./bins.js";
 import { NO_CACHE_ENV_VAR, resolveRunId, writeDebugNote } from "./check-cache.js";
 import { buildChildEnv, buildRemoteEnv } from "./child-env.js";
 import { resolveDelegationTarget } from "./delegation-target.js";
 import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+import { USAGE_EXIT_CODE, } from "./invocation.js";
 import { isDelegationFlag } from "./invocation-args.js";
 import { reportVerdict } from "./presentation.js";
 import { chooseHost, probeHost } from "./remote-probe.js";
@@ -29,8 +31,8 @@ export async function resolveExecutionTarget(invocation) {
         shouldDelegate: parsedArgs.shouldDelegate,
     });
     if (target.kind === 'refused') {
-        reportError(target.error, stderr);
-        return { settled: true, result: { exitCode: 1 } };
+        reportError(NMR_BIN, target.error, stderr);
+        return { settled: true, result: { exitCode: USAGE_EXIT_CODE } };
     }
     if (target.kind === 'remote') {
         writeDebugNote(`delegating ${command} per ${describeDelegationSource(target, parsedArgs, env)}`, env, stderr);
@@ -115,7 +117,7 @@ async function delegate(options) {
     const snapshot = createSnapshot(cwd, env);
     if (!snapshot.ok && snapshot.isUnsupported) {
         if (target.source === 'flag') {
-            reportError(`Cannot delegate to ${listedHosts}: ${snapshot.reason}`, stderr);
+            reportError(NMR_BIN, `Cannot delegate to ${listedHosts}: ${snapshot.reason}`, stderr);
             return { kind: 'refused', exitCode: 1 };
         }
         stderr.write(formatRunHereLine(command, listedHosts, snapshot.reason));

package/dist/esm/entry-chain.js

@@ -1,7 +1,6 @@
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
-import { UserError } from '@williamthorsen/nmr-core';
-import { isObject } from "./helpers/type-guards.js";
+import { isRecord, UserError } from '@williamthorsen/nmr-core';
 export const ENTRY_CHAIN_ENV_VAR = 'NMR_ENTRY_CHAIN';
 export function enterChain(options) {
     const { anchorDir, command, env, monorepoRoot } = options;
@@ -40,7 +39,7 @@ function formatReentryError(chain, monorepoRoot) {
     ].join('\n');
 }
 function isChainEntry(value) {
-    return isObject(value) && typeof value['command'] === 'string' && typeof value['dir'] === 'string';
+    return isRecord(value) && typeof value['command'] === 'string' && typeof value['dir'] === 'string';
 }
 function readEntryChain(value) {
     if (value === undefined || value === '') {

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

@@ -1,7 +1,7 @@
 import type { Writable } from 'node:stream';
 import type { ResolvedContext } from './context.js';
 import { type RunCliResult } from './invocation.js';
-import type { ParsedArgs } from './invocation-args.js';
+import type { ParsedArgs } from './nmr-flags.js';
 import { type RunStepsOptions } from './runner.js';
 import type { Step } from './steps.js';
 /**
@@ -26,10 +26,10 @@ export declare function composeDelegation(options: {
     }>;
 } | undefined;
 /**
- * Reports whether any scope that a delegation can select defines the command. A package config does not define
+ * Lists every command that a scope which a delegation can select defines. A package config does not define
  * scripts, so the root config's registries and each `package.json` cover every scope.
  */
-export declare function isDefinedInAnyScope(command: string, context: ResolvedContext): boolean;
+export declare function listDefinedCommands(context: ResolvedContext): Set<string>;
 /**
  * Runs a `-F` or `-R` delegation, or refuses it when it would not select any scope.
  *

package/dist/esm/fan-out.js

@@ -1,4 +1,5 @@
 import { reportError } from '@williamthorsen/nmr-core';
+import { NMR_BIN } from "./bins.js";
 import { readFilterSelection } from "./helpers/filter-selection.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { renderQuotedList } from "./helpers/renderQuotedList.js";
@@ -30,19 +31,26 @@ export function composeDelegation(options) {
         },
     };
 }
-export function isDefinedInAnyScope(command, context) {
-    const registries = [buildRootRegistry(context.config, context.monorepoRoot), buildWorkspaceRegistry(context.config)];
-    if (registries.some((registry) => Object.hasOwn(registry, command))) {
-        return true;
+export function listDefinedCommands(context) {
+    const names = new Set([
+        ...Object.keys(buildRootRegistry(context.config, context.monorepoRoot)),
+        ...Object.keys(buildWorkspaceRegistry(context.config)),
+    ]);
+    const scopeDirs = [context.monorepoRoot, ...context.workspacePackageDirs];
+    for (const dir of scopeDirs) {
+        const scripts = readPackageJsonScripts(dir) ?? {};
+        for (const name of Object.keys(scripts)) {
+            names.add(name);
+        }
     }
-    return [context.monorepoRoot, ...context.workspacePackageDirs].some((dir) => Object.hasOwn(readPackageJsonScripts(dir) ?? {}, command));
+    return names;
 }
 export async function runDelegation(options) {
     const { context, delegation, parsedArgs, runOptions, stderr } = options;
     const selection = parsedArgs.filter === undefined ? undefined : readFilterSelection(parsedArgs.filter, context.monorepoRoot);
     const refusal = findEmptySelectionRefusal({ context, parsedArgs, selection });
     if (refusal !== undefined) {
-        reportError(refusal, stderr);
+        reportError(NMR_BIN, refusal, stderr);
         return { exitCode: 1 };
     }
     const shouldWithholdInput = parsedArgs.filter === undefined || selection === 'multiple';

package/dist/esm/git-ignored-paths.js

@@ -1,7 +1,7 @@
-import { spawnSync } from 'node:child_process';
+import { runGit } from '@williamthorsen/nmr-core';
 export function listGitIgnoredPaths(dir) {
-    const result = spawnSync('git', ['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory', '--no-empty-directory'], { cwd: dir, encoding: 'utf8' });
-    if (result.error !== undefined || result.status !== 0)
+    const result = runGit(['ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--directory', '--no-empty-directory'], dir);
+    if (!result.ok)
         return [];
     return result.stdout
         .split('\0')

package/dist/esm/help.d.ts

@@ -1,19 +1,18 @@
 import type { NmrConfig } from './types.js';
+/** What nmr's help lists for one scope: each command that it runs, and the text that follows the options. */
+export interface HelpListing {
+    /** Each command's name, paired with the summary that the `Commands:` block shows for it. */
+    commands: Array<[name: string, summary: string]>;
+    epilog: string;
+}
 /**
- * Generates the help text for the `nmr` CLI. Renders the names from the
- * workspace and root registries, excluding hooks (`*:pre`, `*:post`), and
- * the scripts that the package at `packageDir` adds to them.
+ * Describes nmr's help for the scope anchored at `packageDir`: the active registry's commands, less hooks
+ * (`*:pre`, `*:post`), then the scripts that the package's `package.json` adds to them, each summarized by the
+ * shell command to which it resolves.
  *
- * When `packageDir` is provided, tier-3 entries from that package's
- * `package.json:scripts` that match a registry name in the active section
- * are inlined as overrides: The registry value is replaced with the
- * override value and the row's command name is suffixed with `*`. The
- * active section is the root section when `shouldUseRoot` is true (root cwd
- * or `-w`), otherwise the workspace section. A footnote is appended once
- * if any override marker was rendered.
- *
- * Every other entry, a hook included, is listed under `Package scripts:`
- * unless it is an npm or pnpm lifecycle script or the active registry
- * contains its name.
+ * The active registry is the root's when `shouldUseRoot` is true (root cwd or `-w`), and the workspace's otherwise.
+ * A `package.json` entry that matches an active registry name replaces that row's value and marks it with `*`, which
+ * a footnote explains. Every other entry, a hook included, is listed unless it is an npm or pnpm lifecycle script.
+ * The epilog lists the inactive registry, the environment variables, and the files that nmr reads.
  */
-export declare function generateHelp(config: NmrConfig, monorepoRoot: string, packageDir: string | undefined, shouldUseRoot: boolean): string;
+export declare function describeHelp(config: NmrConfig, monorepoRoot: string, packageDir: string | undefined, shouldUseRoot: boolean): HelpListing;

package/dist/esm/help.js

@@ -1,5 +1,5 @@
 import { isHookName } from "./helpers/hook-name.js";
-import { OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG } from "./output-style.js";
+import { OUTPUT_STYLE_ENV_VAR } from "./output-style.js";
 import { DELEGATE_ENV_VAR } from "./remote-run.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
 const LIFECYCLE_SCRIPT_NAMES = new Set([
@@ -24,64 +24,39 @@ const LIFECYCLE_SCRIPT_NAMES = new Set([
     'uninstall',
     'version',
 ]);
-export function generateHelp(config, monorepoRoot, packageDir, shouldUseRoot) {
-    const lines = [
-        'Usage: nmr [flags] <command> [args...]',
-        '',
-        'Flags:',
-        '  -F, --filter <pattern>      Run command in packages whose manifest name matches',
-        '  -R, --recursive             Run command in all packages',
-        '  -w, --workspace-root        Use root scripts, running at the monorepo root',
-        "  -q, --quiet                 Suppress command output, keeping nmr's verdicts",
-        '      --delegate              Run over SSH on the first free host that NMR_DELEGATE or the user config names',
-        '      --delegate-to <hosts>   Run over SSH on the first free of <hosts>, comma-separated',
-        '      --json                  Report one JSON object per command, withholding command output',
-        '      --log                   Print the recorded run instead of running (up to 256 KiB)',
-        '      --no-cache              Run even if this tree already passed; record the result',
-        '      --no-delegate           Run here, whatever NMR_DELEGATE or the user config says',
-        '      --no-lock               Run without waiting for another heavy command on this machine',
-        `      ${OUTPUT_STYLE_FLAG} <style>  Output style: auto (default), plain, or rich`,
-        '  -?, --help                  Show this help',
-        '  -V, --version               Show version number',
-        '',
-        'Environment:',
-        `  ${DELEGATE_ENV_VAR}                Hosts on which to run each command that can be delegated,`,
-        '                              comma-separated; nmr runs on the first free one',
-        `  ${OUTPUT_STYLE_ENV_VAR}            Output style: auto (default), plain, or rich. auto prints`,
-        '                              plain, without emoji, when CI is set or the stream is not a terminal.',
-        '',
-        'Files:',
-        "  ~/.config/nmr/config.ts     User config: this machine's delegation hosts, and when to use them",
-        '                              ($XDG_CONFIG_HOME/nmr/config.ts when that is set)',
-        '                              A command that it sends runs here when no host answers',
-        '',
-        'Workspace commands:',
-    ];
+export function describeHelp(config, monorepoRoot, packageDir, shouldUseRoot) {
     const packageScripts = packageDir === undefined ? {} : readRunnableScripts(packageDir);
-    const overrides = collectOverrides(packageScripts);
-    let hadOverride = false;
-    const workspaceRegistry = filterHooks(buildWorkspaceRegistry(config));
-    const workspaceMarkedNames = !shouldUseRoot ? applyOverrides(workspaceRegistry, overrides) : new Set();
-    if (workspaceMarkedNames.size > 0)
-        hadOverride = true;
-    formatRegistry(workspaceRegistry, workspaceMarkedNames, lines);
-    lines.push('', 'Root commands:');
-    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, monorepoRoot) : buildWorkspaceRegistry(config);
-    const unregisteredScripts = collectUnregisteredScripts(packageScripts, activeRegistry);
-    if (Object.keys(unregisteredScripts).length > 0) {
-        lines.push('', 'Package scripts:');
-        formatRegistry(unregisteredScripts, new Set(), lines);
+    const fullActiveRegistry = shouldUseRoot ? buildRootRegistry(config, monorepoRoot) : buildWorkspaceRegistry(config);
+    const activeRegistry = filterHooks(fullActiveRegistry);
+    const markedNames = applyOverrides(activeRegistry, collectOverrides(packageScripts));
+    const commands = Object.entries(activeRegistry).map(([name, value]) => [
+        name,
+        `${describeScript(value)}${markedNames.has(name) ? ' *' : ''}`,
+    ]);
+    const unregisteredScripts = collectUnregisteredScripts(packageScripts, fullActiveRegistry);
+    for (const [name, value] of Object.entries(unregisteredScripts)) {
+        commands.push([name, describeScript(value)]);
     }
-    if (hadOverride) {
+    const inactiveRegistry = filterHooks(shouldUseRoot ? buildWorkspaceRegistry(config) : buildRootRegistry(config, monorepoRoot));
+    const lines = [...ENVIRONMENT_AND_FILES_LINES, '', shouldUseRoot ? 'Workspace commands:' : 'Root commands:'];
+    formatRegistry(inactiveRegistry, new Set(), lines);
+    if (markedNames.size > 0) {
         lines.push('', '* Overridden by package.json');
     }
-    return lines.join('\n');
+    return { commands, epilog: lines.join('\n') };
 }
+const ENVIRONMENT_AND_FILES_LINES = [
+    'Environment:',
+    `  ${DELEGATE_ENV_VAR}                Hosts on which to run each command that can be delegated,`,
+    '                              comma-separated; nmr runs on the first free one',
+    `  ${OUTPUT_STYLE_ENV_VAR}            Output style: auto (default), plain, or rich. auto prints`,
+    '                              plain, without emoji, when CI is set or the stream is not a terminal.',
+    '',
+    'Files:',
+    "  ~/.config/nmr/config.ts     User config: this machine's delegation hosts, and when to use them",
+    '                              ($XDG_CONFIG_HOME/nmr/config.ts when that is set)',
+    '                              A command that it sends runs here when no host answers',
+];
 function collectOverrides(packageScripts) {
     const candidateOverrides = {};
     for (const [name, value] of Object.entries(packageScripts)) {

package/dist/esm/helpers/filter-selection.js

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { isObject } from "./type-guards.js";
+import { isRecord } from '@williamthorsen/nmr-core';
 const SELECTION_MARKER = 'nmr-selected-scope';
 export function readFilterSelection(pattern, monorepoRoot) {
     const listingRun = spawnSync('pnpm', ['ls', '--filter', pattern, '--depth', '-1', '--json'], {
@@ -42,7 +42,7 @@ export function interpretDelegateProbe(probe) {
     return probe.stdout.includes(SELECTION_MARKER) ? 'single' : 'empty';
 }
 function isRootEntry(entry, monorepoRoot) {
-    if (!isObject(entry) || typeof entry['path'] !== 'string') {
+    if (!isRecord(entry) || typeof entry['path'] !== 'string') {
         return false;
     }
     return resolveRealPath(entry['path']) === resolveRealPath(monorepoRoot);