@williamthorsen/nmr 0.55.0 → 1.0.0

package/dist/esm/remote-probe.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
+import { isRecord } from '@williamthorsen/nmr-core';
 import { quoteForShell } from "./helpers/quoteForShell.js";
-import { isObject } from "./helpers/type-guards.js";
 import { LOCK_DIR_ENV_VAR, LOCK_FILE, STALE_AFTER_MS } from "./machine-lock.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
 import { probeHostLocks } from "./remote-probe-host.js";
@@ -80,7 +80,7 @@ export function selectHost(hosts, results) {
 function readBusyField(line) {
     try {
         const value = JSON.parse(line);
-        return isObject(value) && typeof value['busy'] === 'boolean' ? value['busy'] : undefined;
+        return isRecord(value) && typeof value['busy'] === 'boolean' ? value['busy'] : undefined;
     }
     catch {
         return undefined;

package/dist/esm/remote-run.d.ts

@@ -3,13 +3,13 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 /** Names the hosts to which nmr delegates a command when the invocation does not say otherwise. */
 export declare const DELEGATE_ENV_VAR = "NMR_DELEGATE";
 /** The flag that runs the command on a host that `NMR_DELEGATE` or the user config names. */
-export declare const DELEGATE_FLAG = "--delegate";
+export declare const DELEGATE_FLAG: string;
 /** The flag that names the hosts on which to run the command. */
-export declare const DELEGATE_TO_FLAG = "--delegate-to";
+export declare const DELEGATE_TO_FLAG: string;
 /** The exit status of a delegation that failed outside its command, which matches `ssh`'s own. */
 export declare const DELEGATION_FAILURE_EXIT_CODE = 255;
 /** The flag that runs the command here, whatever `NMR_DELEGATE` or the user config says. */
-export declare const NO_DELEGATE_FLAG = "--no-delegate";
+export declare const NO_DELEGATE_FLAG: string;
 /** Names the ssh command that the environment supplies, which git and nmr run in place of plain `ssh`. */
 export declare const SSH_COMMAND_ENV_VAR = "GIT_SSH_COMMAND";
 /** Keeps `ssh` from prompting or waiting on a terminal, and bounds the wait for a host that does not answer. */

package/dist/esm/remote-run.js

@@ -3,18 +3,19 @@ import { createHash, randomUUID } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { startTimer, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
+import { GIT_OUTPUT_LIMIT_BYTES, startTimer, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { PASS_MANIFEST_DIR_ENV_VAR, writeDebugNote } from "./check-cache.js";
 import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
 import { quoteForShell } from "./helpers/quoteForShell.js";
 import { STALE_AFTER_MS } from "./machine-lock.js";
+import { formatFlagSpelling } from "./nmr-flags.js";
 import { CHECKOUT_LOCK_PATH } from "./remote-host-session.js";
 import { composeSessionScript, createSessionDemultiplexer, formatDelegationWaitingLine } from "./remote-session.js";
 export const DELEGATE_ENV_VAR = 'NMR_DELEGATE';
-export const DELEGATE_FLAG = '--delegate';
-export const DELEGATE_TO_FLAG = '--delegate-to';
+export const DELEGATE_FLAG = formatFlagSpelling('delegate');
+export const DELEGATE_TO_FLAG = formatFlagSpelling('delegateTo');
 export const DELEGATION_FAILURE_EXIT_CODE = 255;
-export const NO_DELEGATE_FLAG = '--no-delegate';
+export const NO_DELEGATE_FLAG = formatFlagSpelling('noDelegate');
 export const SSH_COMMAND_ENV_VAR = 'GIT_SSH_COMMAND';
 export const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10'];
 export function composeGitSshCommand(env) {
@@ -102,6 +103,7 @@ export async function runRemotely(options) {
     const script = composeSessionScript({
         checkoutDir,
         params: {
+            gitOutputLimitBytes: GIT_OUTPUT_LIMIT_BYTES,
             holder: { command, dir: cwd, pid: process.pid },
             lockPath: CHECKOUT_LOCK_PATH,
             marker,

package/dist/esm/remote-session.js

@@ -1,6 +1,6 @@
 import { Writable } from 'node:stream';
+import { isRecord } from '@williamthorsen/nmr-core';
 import { quoteForShell } from "./helpers/quoteForShell.js";
-import { isObject } from "./helpers/type-guards.js";
 import { runHostSession, } from "./remote-host-session.js";
 export function composeSessionScript(options) {
     const { checkoutDir, params } = options;
@@ -91,7 +91,7 @@ export function createSessionDemultiplexer(options) {
         catch {
             return 'other';
         }
-        if (!isObject(value) || value['kind'] !== 'passes') {
+        if (!isRecord(value) || value['kind'] !== 'passes') {
             return 'other';
         }
         const entries = value['entries'];
@@ -116,13 +116,13 @@ export function formatDelegationWaitingLine(holder, host) {
 }
 const NEWLINE = 0x0a;
 function isDelegationHolder(value) {
-    return (isObject(value) &&
+    return (isRecord(value) &&
         typeof value['command'] === 'string' &&
         typeof value['dir'] === 'string' &&
         typeof value['pid'] === 'number');
 }
 function isSessionRecord(value) {
-    if (!isObject(value))
+    if (!isRecord(value))
         return false;
     switch (value['kind']) {
         case 'failed':

package/dist/esm/remote-snapshot.js

@@ -1,10 +1,9 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { GIT_OUTPUT_LIMIT_BYTES } from '@williamthorsen/nmr-core';
+import { runGit } from '@williamthorsen/nmr-core';
 export function createSnapshot(cwd, env) {
-    const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, env);
+    const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, undefined, env);
     if (!toplevelResult.ok) {
         return { ok: false, isUnsupported: true, reason: `not a git repository: ${toplevelResult.error}` };
     }
@@ -12,7 +11,7 @@ export function createSnapshot(cwd, env) {
     if (fs.existsSync(path.join(toplevel, '.gitmodules'))) {
         return { ok: false, isUnsupported: true, reason: 'the repository declares submodules' };
     }
-    const indexPathResult = runGit(['rev-parse', '--git-path', 'index'], toplevel, env);
+    const indexPathResult = runGit(['rev-parse', '--git-path', 'index'], toplevel, undefined, env);
     if (!indexPathResult.ok) {
         return { ok: false, isUnsupported: false, reason: indexPathResult.error };
     }
@@ -24,28 +23,25 @@ export function createSnapshot(cwd, env) {
             copyIndex(indexPath, tempIndex);
         }
         const indexEnv = { ...env, GIT_INDEX_FILE: tempIndex };
-        const addResult = runGit(['add', '--all'], toplevel, indexEnv);
+        const addResult = runGit(['add', '--all'], toplevel, undefined, indexEnv);
         if (!addResult.ok) {
             return { ok: false, isUnsupported: false, reason: addResult.error };
         }
-        const stageResult = runGit(['ls-files', '--stage', '-z'], toplevel, indexEnv);
+        const stageResult = runGit(['ls-files', '--stage', '-z'], toplevel, undefined, indexEnv);
         if (!stageResult.ok) {
             return { ok: false, isUnsupported: false, reason: stageResult.error };
         }
         if (stageResult.stdout.split('\0').some((entry) => entry.startsWith('160000 '))) {
             return { ok: false, isUnsupported: true, reason: 'the working tree contains a submodule or a nested repository' };
         }
-        const treeResult = runGit(['write-tree'], toplevel, indexEnv);
+        const treeResult = runGit(['write-tree'], toplevel, undefined, indexEnv);
         if (!treeResult.ok) {
             return { ok: false, isUnsupported: false, reason: treeResult.error };
         }
-        const headResult = runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], toplevel, env);
+        const headResult = runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], toplevel, undefined, env);
         const parentArgs = headResult.ok ? ['-p', headResult.stdout.trim()] : [];
         const treeId = treeResult.stdout.trim();
-        const commitResult = runGit(['commit-tree', treeId, ...parentArgs, '-m', 'nmr delegate snapshot'], toplevel, {
-            ...env,
-            ...SNAPSHOT_IDENTITY_ENV,
-        });
+        const commitResult = runGit(['commit-tree', treeId, ...parentArgs, '-m', 'nmr delegate snapshot'], toplevel, undefined, { ...env, ...SNAPSHOT_IDENTITY_ENV });
         if (!commitResult.ok) {
             return { ok: false, isUnsupported: false, reason: commitResult.error };
         }
@@ -68,13 +64,3 @@ function copyIndex(source, destination) {
     const { atime, mtime } = fs.statSync(source);
     fs.utimesSync(destination, atime, mtime);
 }
-function runGit(args, cwd, env) {
-    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT_BYTES });
-    if (result.error !== undefined) {
-        return { ok: false, error: result.error.message };
-    }
-    if (result.status !== 0) {
-        return { ok: false, error: result.stderr.trim() || `git ${args[0] ?? ''} exited ${result.status ?? 'abnormally'}` };
-    }
-    return { ok: true, stdout: result.stdout };
-}

package/dist/esm/resolver.js

@@ -1,8 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { hasErrnoCode } from '@williamthorsen/nmr-core';
+import { hasErrnoCode, isRecord } from '@williamthorsen/nmr-core';
 import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
-import { isObject } from "./helpers/type-guards.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts, } from "./resolve-scripts.js";
 import { composeNmrStep, readSelfReference } from "./steps.js";
 import { isMonorepoRoot } from "./workspace.js";
@@ -77,10 +76,10 @@ export function readPackageJsonScripts(packageDir) {
         throw error;
     }
     const parsedManifest = parsePackageJson(rawText, file);
-    if (!isObject(parsedManifest))
+    if (!isRecord(parsedManifest))
         return undefined;
     const scripts = parsedManifest['scripts'];
-    if (!isObject(scripts))
+    if (!isRecord(scripts))
         return undefined;
     return readScriptRecord(packageDir, scripts);
 }

package/dist/esm/route.d.ts

@@ -0,0 +1,29 @@
+import type { Writable } from 'node:stream';
+import { type CommandNode } from '@williamthorsen/nmr-core/cli';
+import type { ResolvedContext } from './context.js';
+import { type Invocation } from './invocation.js';
+import { type ParsedArgs } from './nmr-flags.js';
+/** What the command tree of one invocation is built from. */
+export interface RouteInput {
+    context: ResolvedContext;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** The invocation's flags as the first pass read them, or `undefined` when they do not parse. */
+    firstPass: ParsedArgs | undefined;
+    /** Runs an invocation that reached a command and resolves to its exit code. */
+    runInvocation: (invocation: Invocation) => Promise<number>;
+    stderr: Writable;
+    stdout: Writable;
+}
+/**
+ * Builds the command tree of one invocation: nmr's flags, and a passthrough command for each script that help lists
+ * for the scope.
+ *
+ * The command that the invocation names is added when any scope defines it, or when nmr answers for it on its own
+ * (a run on a delegating caller's behalf, or a host name after a bare `--delegate`), so that nmr rather than the
+ * router decides what an invocation that a scope cannot run reports. A request for help adds nothing, so that help
+ * lists the scope alone.
+ */
+export declare function buildRoot(input: RouteInput): CommandNode<undefined>;
+/** Builds a root that does not have any commands, which answers `--version` without loading the config. */
+export declare function buildVersionRoot(): CommandNode<undefined>;

package/dist/esm/route.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { createCli, UsageError } from '@williamthorsen/nmr-core/cli';
+import { listDefinedCommands } from "./fan-out.js";
+import { describeHelp } from "./help.js";
+import { RUN_IF_PRESENT_ENV_VAR } from "./invocation.js";
+import { NMR_FLAGS, toParsedArgs } from "./nmr-flags.js";
+import { isTerminalStream } from "./output-style.js";
+import { readPresentation, resolveReportingVerbosity } from "./presentation.js";
+import { resolveReportFormat } from "./report-format.js";
+const { defineGroup } = createCli();
+const { defineCommand } = createCli();
+export function buildRoot(input) {
+    const { context, env, firstPass } = input;
+    const shouldUseRoot = (firstPass?.isWorkspaceRoot ?? false) || context.isRoot;
+    const anchorDir = resolveAnchorDir(context, shouldUseRoot);
+    const listing = describeHelp(context.config, context.monorepoRoot, anchorDir, shouldUseRoot);
+    const commands = {};
+    for (const [name, summary] of listing.commands) {
+        commands[name] = defineScriptCommand(name, summary, input);
+    }
+    const command = firstPass?.command;
+    if (command !== undefined && !firstPass?.shouldShowHelp && !Object.hasOwn(commands, command)) {
+        const isAnsweredByNmr = env[RUN_IF_PRESENT_ENV_VAR] === '1' ||
+            (firstPass?.shouldDelegate === true && firstPass.delegateHosts === undefined) ||
+            listDefinedCommands(context).has(command);
+        if (isAnsweredByNmr) {
+            commands[command] = defineScriptCommand(command, 'A script that another scope defines', input);
+        }
+    }
+    return defineGroup({
+        summary: 'Runs the scripts of a pnpm monorepo in the scope of the current directory',
+        flags: NMR_FLAGS,
+        deriveContext: (flags) => deriveInvocation(flags, input),
+        commands,
+        epilog: listing.epilog,
+    });
+}
+export function buildVersionRoot() {
+    return defineGroup({ summary: 'nmr', flags: NMR_FLAGS, commands: {} });
+}
+function defineScriptCommand(name, summary, input) {
+    return defineCommand({
+        summary,
+        passthrough: true,
+        run: ({ args, context }) => input.runInvocation({
+            ...context,
+            command: name,
+            parsedArgs: { ...context.parsedArgs, command: name, passthrough: args },
+        }),
+    });
+}
+function deriveInvocation(flags, input) {
+    const { context, cwd, env, firstPass, stderr, stdout } = input;
+    const parsedArgs = toParsedArgs(flags, []);
+    const presentationRead = readPresentation({
+        env,
+        flagValue: parsedArgs.outputStyle,
+        stderrIsTty: isTerminalStream(stderr),
+        stdoutIsTty: isTerminalStream(stdout),
+    });
+    if (!presentationRead.ok) {
+        throw new UsageError(presentationRead.error);
+    }
+    if (parsedArgs.shouldPrintLog && firstPass?.command === undefined) {
+        throw new UsageError('--log requires a command name: `nmr --log <command>`');
+    }
+    const format = resolveReportFormat({ envFormat: presentationRead.format, hasJsonFlag: parsedArgs.shouldEmitJson });
+    const verbosity = resolveReportingVerbosity({
+        env,
+        envVerbosity: presentationRead.verbosity,
+        format,
+        output: context.config.output,
+        hasQuietFlag: parsedArgs.quiet,
+    });
+    const shouldUseRoot = parsedArgs.isWorkspaceRoot || context.isRoot;
+    const anchorDir = resolveAnchorDir(context, shouldUseRoot);
+    return {
+        anchorDir,
+        context,
+        cwd,
+        env,
+        format,
+        parsedArgs,
+        scope: path.basename(anchorDir),
+        shouldUseRoot,
+        stderr,
+        stdout,
+        styles: presentationRead.styles,
+        verbosity,
+    };
+}
+function resolveAnchorDir(context, shouldUseRoot) {
+    return shouldUseRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
+}

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

@@ -1,6 +1,6 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { TreeSnapshot } from './check-cache.js';
-import type { Invocation, PhaseResult, RunPlan } from './invocation.js';
+import { type Invocation, type PhaseResult, type RunPlan } from './invocation.js';
 import type { ScriptRegistry } from './resolve-scripts.js';
 import { type ResolvedScript } from './resolver.js';
 /**

package/dist/esm/run-chain.js

@@ -1,11 +1,13 @@
 import path from 'node:path';
 import { formatGlyphLine, reportError } from '@williamthorsen/nmr-core';
+import { NMR_BIN } from "./bins.js";
 import { resolveCacheKey } from "./check-cache-gate.js";
 import { reportNmrCrossing } from "./crossing-diagnostics.js";
 import { NMR_GLYPHS } from "./glyphs.js";
 import { isHookName } from "./helpers/hook-name.js";
 import { quoteForShell } from "./helpers/quoteForShell.js";
 import { wrapWithHooks } from "./hooks.js";
+import { USAGE_EXIT_CODE } from "./invocation.js";
 import { reportVerdict } from "./presentation.js";
 import { applyDevBinToSteps } from "./resolver.js";
 import { dropRecursiveSteps, renderChain } from "./steps.js";
@@ -23,8 +25,8 @@ export function assembleChain(options) {
     const substitutedCommand = renderChain(substitutedSteps);
     const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
     if (!bindResult.ok) {
-        reportError(bindResult.error, stderr);
-        return { settled: true, result: { exitCode: 1 } };
+        reportError(NMR_BIN, bindResult.error, stderr);
+        return { settled: true, result: { exitCode: USAGE_EXIT_CODE } };
     }
     const mainSteps = bindResult.steps;
     const isHookInvocation = isHookName(command);

package/dist/esm/runCli.d.ts

@@ -17,6 +17,8 @@ export interface RunCliOptions {
  * Executes the nmr CLI flow in-process and returns the resulting exit code.
  * Does not hold global state, does not read `process.*` globals, and never calls `process.exit`.
  *
+ * nmr's flags decide which commands the tree holds, so a first pass reads them before the router parses them again.
+ *
  * @internal
  */
 export declare function runCli(options: RunCliOptions): Promise<RunCliResult>;

package/dist/esm/runCli.js

@@ -1,6 +1,7 @@
-import path from 'node:path';
 import { reportError } from '@williamthorsen/nmr-core';
+import { runCli as runRouter } from '@williamthorsen/nmr-core/cli';
 import { prependBinDirs } from "./bin-path.js";
+import { NMR_BIN } from "./bins.js";
 import { NO_CACHE_ENV_VAR, resolveRunId, RUN_ID_ENV_VAR } from "./check-cache.js";
 import { openGate, runGated } from "./check-cache-gate.js";
 import { reportRecording } from "./check-cache-record.js";
@@ -9,32 +10,48 @@ import { resolveContext } from "./context.js";
 import { assertNoSelfReference } from "./crossing-diagnostics.js";
 import { resolveExecutionTarget, runInvocationOnHost } from "./delegate-host.js";
 import { enterChain } from "./entry-chain.js";
-import { composeDelegation, isDefinedInAnyScope, runDelegation } from "./fan-out.js";
-import { generateHelp } from "./help.js";
-import { RUN_IF_PRESENT_ENV_VAR, VERSION, } from "./invocation.js";
-import { formatMisplacedFlagHint, parseArgs } from "./invocation-args.js";
-import { isTerminalStream } from "./output-style.js";
-import { readPresentation, reportVerdict, resolveReportingVerbosity } from "./presentation.js";
+import { composeDelegation, runDelegation } from "./fan-out.js";
+import { RUN_IF_PRESENT_ENV_VAR, USAGE_EXIT_CODE, VERSION, } from "./invocation.js";
+import { formatMisplacedFlagHint } from "./invocation-args.js";
+import { readInvocationFlags } from "./nmr-flags.js";
+import { reportVerdict } from "./presentation.js";
 import { DELEGATE_TO_FLAG } from "./remote-run.js";
-import { resolveReportFormat } from "./report-format.js";
 import { buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { buildRoot, buildVersionRoot } from "./route.js";
 import { assembleChain, formatOverrideNotice } from "./run-chain.js";
 export async function runCli(options) {
-    const established = await establishInvocation(options);
-    if (established.settled) {
-        return { exitCode: established.result.exitCode };
+    const { args, cwd, env, stdout, stderr } = options;
+    const reading = readInvocationFlags(args);
+    const firstPass = reading.ok ? reading.parsedArgs : undefined;
+    const routerOptions = { name: NMR_BIN, context: undefined, stdout, stderr, baseDir: cwd, version: () => VERSION };
+    if (firstPass?.shouldShowVersion === true && !firstPass.shouldShowHelp) {
+        return { exitCode: await runRouter(args, buildVersionRoot(), routerOptions) };
     }
-    const invocation = established.value;
+    const context = await resolveContext(cwd);
+    const root = buildRoot({
+        context,
+        cwd,
+        env,
+        firstPass,
+        runInvocation: (invocation) => runInvocation(invocation, options),
+        stderr,
+        stdout,
+    });
+    const isBare = firstPass !== undefined && firstPass.command === undefined && !firstPass.shouldPrintLog && !args.includes('--');
+    const routedArgs = isBare ? [...args, '--help'] : args;
+    return { exitCode: await runRouter(routedArgs, root, routerOptions) };
+}
+async function runInvocation(invocation, options) {
     const resolvedTarget = await resolveExecutionTarget(invocation);
     if (resolvedTarget.settled) {
-        return { exitCode: resolvedTarget.result.exitCode };
+        return resolvedTarget.result.exitCode;
     }
     let target = resolvedTarget.value;
     const { filter, recursive } = invocation.parsedArgs;
     if (target.kind === 'remote' && (filter !== undefined || recursive)) {
         const delegated = await runInvocationOnHost(invocation, target);
         if (delegated !== undefined) {
-            return delegated;
+            return delegated.exitCode;
         }
         target = { kind: 'local' };
     }
@@ -46,64 +63,7 @@ export async function runCli(options) {
             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 { settled: true, result: { exitCode: 1 } };
-    }
-    const { parsedArgs } = parseResult;
-    const presentationRead = readPresentation({
-        env,
-        flagValue: parsedArgs.outputStyle,
-        stderrIsTty: isTerminalStream(stderr),
-        stdoutIsTty: isTerminalStream(stdout),
-    });
-    if (!presentationRead.ok) {
-        reportError(presentationRead.error, stderr);
-        return { settled: true, result: { exitCode: 1 } };
-    }
-    const { styles } = presentationRead;
-    if (parsedArgs.shouldShowVersion) {
-        stdout.write(`${VERSION}\n`);
-        return { settled: true, result: { exitCode: 0 } };
-    }
-    const context = await resolveContext(cwd);
-    const format = resolveReportFormat({ envFormat: presentationRead.format, hasJsonFlag: parsedArgs.shouldEmitJson });
-    const verbosity = resolveReportingVerbosity({
-        env,
-        envVerbosity: presentationRead.verbosity,
-        format,
-        output: context.config.output,
-        hasQuietFlag: parsedArgs.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 { settled: true, result: { exitCode: 0 } };
-    }
-    return {
-        settled: false,
-        value: {
-            anchorDir,
-            command: parsedArgs.command,
-            context,
-            cwd,
-            env,
-            format,
-            parsedArgs,
-            scope: path.basename(anchorDir),
-            shouldUseRoot,
-            stderr,
-            stdout,
-            styles,
-            verbosity,
-        },
-    };
+    return exitCode;
 }
 async function planRun(invocation, target) {
     const { anchorDir, command, context, env, parsedArgs, stderr, stdout, styles } = invocation;
@@ -131,6 +91,7 @@ async function planRun(invocation, target) {
         verbosity: invocation.verbosity,
     });
     const runOptions = {
+        bin: NMR_BIN,
         quiet,
         stdout,
         stderr,
@@ -147,10 +108,7 @@ async function planRun(invocation, target) {
         finally {
             await lock?.release();
         }
-        return {
-            settled: true,
-            result: { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) },
-        };
+        return { settled: true, result };
     }
     const registry = invocation.shouldUseRoot
         ? buildRootRegistry(context.config, context.monorepoRoot)
@@ -171,8 +129,8 @@ async function planRun(invocation, target) {
         const delegateToHint = parsedArgs.shouldDelegate && parsedArgs.delegateHosts === undefined
             ? `. \`${command}\` is not a command; name a host with ${DELEGATE_TO_FLAG} ${command}`
             : '';
-        reportError(`Unknown command: ${command}${delegateToHint}`, stderr);
-        return { settled: true, result: { exitCode: 1, isUnknownCommand: true } };
+        reportError(NMR_BIN, `Unknown command: ${command}${delegateToHint}`, stderr);
+        return { settled: true, result: { exitCode: USAGE_EXIT_CODE, isUnknownCommand: true } };
     }
     const entryRunOptions = parsedArgs.shouldPrintLog
         ? runOptions

package/dist/esm/stated-outcome.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import process from 'node:process';
+import { isRecord } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { isObject } from "./helpers/type-guards.js";
 export const OUTCOME_FILE_ENV_VAR = 'NMR_OUTCOME_FILE';
 export function omitOutcomeFile(env) {
     return Object.fromEntries(Object.entries(env).filter(([name]) => name !== OUTCOME_FILE_ENV_VAR));
@@ -49,10 +49,10 @@ export async function writeStatedOutcome(env, outcome) {
     }
 }
 function isMissingFileError(error) {
-    return isObject(error) && error['code'] === 'ENOENT';
+    return isRecord(error) && error['code'] === 'ENOENT';
 }
 function isStatedOutcome(value) {
-    if (!isObject(value) || value['kind'] !== 'build-unchanged' || !Number.isSafeInteger(value['parentPid'])) {
+    if (!isRecord(value) || value['kind'] !== 'build-unchanged' || !Number.isSafeInteger(value['parentPid'])) {
         return false;
     }
     const savedMs = value['savedMs'];

package/dist/esm/steps.js

@@ -1,3 +1,4 @@
+import { readInvocationFlags } from "./nmr-flags.js";
 import { dropLeadingAssignments, isShellSafeToken, quoteToken, splitSegments, tokenize, tokenizeSegment, } from "./shell-syntax.js";
 const LAUNCHERS = new Map([
     ['bun', new Set(['x'])],
@@ -141,37 +142,12 @@ function readNmrTail(segment) {
         : undefined;
 }
 function readNmrTarget(tokens) {
-    let isDelegate = false;
-    let isRecursive = false;
-    let isWorkspaceRoot = false;
-    let index = 0;
-    while (index < tokens.length) {
-        const token = tokens[index] ?? '';
-        switch (token) {
-            case '-F':
-            case '--filter':
-                isDelegate = true;
-                index += 2;
-                break;
-            case '-R':
-            case '--recursive':
-                isDelegate = true;
-                isRecursive = true;
-                index += 1;
-                break;
-            case '-w':
-            case '--workspace-root':
-                isWorkspaceRoot = true;
-                index += 1;
-                break;
-            default:
-                if (!token.startsWith('-')) {
-                    return { command: token, isDelegate, isRecursive, isWorkspaceRoot };
-                }
-                index += 1;
-        }
+    const reading = readInvocationFlags(tokens);
+    if (!reading.ok || reading.parsedArgs.command === undefined) {
+        return undefined;
     }
-    return undefined;
+    const { command, filter, isWorkspaceRoot, recursive } = reading.parsedArgs;
+    return { command, isDelegate: filter !== undefined || recursive, isRecursive: recursive, isWorkspaceRoot };
 }
 function renderStep(step) {
     return step.kind === 'opaque' ? step.command : step.argv.map(quoteToken).join(' ');

package/dist/esm/user-config.js

@@ -9,9 +9,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { UserError } from '@williamthorsen/nmr-core';
+import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { assertRecognizedKeys } from "./config-validation.js";
-import { isObject } from "./helpers/type-guards.js";
+import { resolveXdgBaseDir } from "./helpers/resolveXdgBaseDir.js";
 export const DELEGATE_WHEN_VALUES = ['agent', 'always'];
 export function formatDisplayPath(filePath, env) {
     const home = env['HOME'];
@@ -30,19 +30,12 @@ export async function loadUserConfig(env) {
         return undefined;
     }
     const importedModule = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
-    const loadedConfig = isObject(importedModule) ? importedModule['default'] : undefined;
+    const loadedConfig = isRecord(importedModule) ? importedModule['default'] : undefined;
     return { config: validateUserConfig(loadedConfig, configPath), path: configPath };
 }
 export function resolveUserConfigPath(env) {
-    const configHome = env['XDG_CONFIG_HOME'];
-    if (configHome !== undefined && path.isAbsolute(configHome)) {
-        return path.join(configHome, USER_CONFIG_RELATIVE_PATH);
-    }
-    const home = env['HOME'];
-    if (home !== undefined && path.isAbsolute(home)) {
-        return path.join(home, '.config', USER_CONFIG_RELATIVE_PATH);
-    }
-    return undefined;
+    const configHome = resolveXdgBaseDir(env, 'XDG_CONFIG_HOME', '.config');
+    return configHome === undefined ? undefined : path.join(configHome, USER_CONFIG_RELATIVE_PATH);
 }
 const USER_CONFIG_RELATIVE_PATH = path.join('nmr', 'config.ts');
 const RECOGNIZED_KEYS = ['delegate'];
@@ -56,7 +49,7 @@ function validateDelegateField(value, configPath) {
     if (delegate === undefined) {
         return undefined;
     }
-    if (!isObject(delegate)) {
+    if (!isRecord(delegate)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`delegate\` must be an object`);
     }
     assertRecognizedKeys(delegate, RECOGNIZED_DELEGATE_KEYS, configPath, 'delegate.');
@@ -84,7 +77,7 @@ function validateHosts(value, configPath) {
     return [first, ...rest];
 }
 function validateUserConfig(value, configPath) {
-    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);