utilful 3.0.2 → 3.2.0

package/README.md

@@ -7,6 +7,7 @@ A collection of TypeScript utilities that I use across my projects.
 - [Installation](#installation)
 - [API](#api)
   - [Array](#array)
+  - [CLI](#cli)
   - [CSV](#csv)
   - [Defu](#defu)
   - [Emitter](#emitter)
@@ -21,15 +22,24 @@ A collection of TypeScript utilities that I use across my projects.
 
 ```bash
 # npm
-npm install -D utilful
+npm install utilful
 
 # pnpm
-pnpm add -D utilful
+pnpm add utilful
 
 # yarn
-yarn add -D utilful
+yarn add utilful
 ```
 
+Every module is also available on its own subpath, so you can import just the part you need:
+
+```ts
+import { defu } from 'utilful' // Everything
+import { joinURL } from 'utilful/path' // Just the path helpers
+```
+
+The `cli` module is the exception: it is Node-only (22.13 or later) and lives on its subpaths `utilful/cli` and `utilful/cli/testing` alone.
+
 ## API
 
 ### Array
@@ -44,6 +54,67 @@ type MaybeArray<T> = T | T[]
 declare function toArray<T>(array?: MaybeArray<T> | null | undefined): T[]
 ```
 
+### CLI
+
+A command runner on top of Node's `util.parseArgs`: strict option parsing, one level of sub-commands, `--help` and `--version`, and an error boundary that prints a recognized error as a message and anything else with its stack. `-h` and `-v` belong to the runner, so no option may take either letter as its alias.
+
+#### `defineCommand`
+
+Types a command definition, so `run` receives its `args` typed by their definitions.
+
+```ts
+import { CliError, commonArgs, defineCommand } from 'utilful/cli'
+
+const build = defineCommand({
+  meta: { name: 'build', description: 'Compile the entry file' },
+  args: {
+    ...commonArgs, // Adds --verbose
+    'file': { type: 'positional', description: 'Entry file', required: true }, // string
+    'out-dir': { type: 'string', alias: 'd', description: 'Output directory', valueHint: 'path' }, // string | undefined
+    'watch': { type: 'boolean', alias: 'w', description: 'Rebuild on change' }, // boolean, --no-watch turns it off
+  },
+  run({ args }) {
+    if (args.watch && args['out-dir'] === undefined)
+      throw new CliError('--watch needs an --out-dir') // Printed as a message, no stack
+  },
+})
+```
+
+#### `runMain`
+
+Runs a command tree from `process.argv`, or from `argv` when given, and sets `process.exitCode` instead of exiting. A tree with a `run` of its own runs it when no sub-command is named.
+
+```ts
+import { defineCommand, runMain } from 'utilful/cli'
+
+const main = defineCommand({
+  meta: { name: 'tool', version: '1.0.0', description: 'Does things' },
+  subCommands: { build },
+})
+
+void runMain(main, { expectedErrors: [MyLibraryError] }) // Reported like a `CliError`
+```
+
+Also exported: `runCommand` (runs the tree and throws instead of reporting), `parseArgs`, `reportFailure` (for a failure that outlives `run`, such as a watch rebuild), and `log` with `error`, `warn`, `info`, `success` and `blankLine`, all writing to stderr.
+
+#### `createCliHarness`
+
+From `utilful/cli/testing`, which needs `vitest`. `runCli` runs the tree in-process and captures both streams and the exit code, `runCliProcess` runs the entry file as a child process. `useTemporaryDirectories` and `mockStdin` ship alongside.
+
+```ts
+import { createCliHarness, useTemporaryDirectories } from 'utilful/cli/testing'
+
+const { runCli, runCliProcess } = createCliHarness(main, { entry: 'src/entry.ts' }) // `entry` only matters to `runCliProcess`
+const createDirectory = useTemporaryDirectories()
+
+it('rejects an unknown option', async () => {
+  const { stderr, exitCode } = await runCli(['build', 'x.js', '--typo'])
+
+  expect(stderr).toContain('Unknown option \'--typo\'')
+  expect(exitCode).toBe(1)
+})
+```
+
 ### CSV
 
 #### `createCSV`
@@ -130,7 +201,12 @@ declare function parseCSV<Header extends string>(
 ): CSVRow<Header>[]
 ```
 
-The parser accepts a few lenient deviations from RFC 4180: LF, CR, and CRLF line endings are all recognized, whitespace between a closing quote and the next delimiter or line break is ignored, and quotes inside unquoted fields are kept as literal characters (a field only counts as quoted if it starts with a quote).
+The parser accepts a few lenient deviations from RFC 4180:
+
+- LF, CR, and CRLF line endings are all recognized
+- whitespace between a closing quote and the next delimiter or line break is ignored
+- quotes inside unquoted fields are kept as literal characters, since a field only counts as quoted if it starts with a quote
+- text following a closing quote is appended to the field rather than rejected, so `"ab" cd` parses as `abcd`
 
 **Example:**
 
@@ -148,6 +224,9 @@ const data = parseCSV<'name' | 'age'>(csv) // [{ name: 'John', age: '30' }, { na
 
 Creates a CSV stream from an iterable or async iterable of objects. Yields complete lines (header and/or data rows) including line endings – useful for large datasets that should not be buffered in memory.
 
+> [!NOTE]
+> Unlike `createCSV`, `columns` is required here. Inferring them would mean reading every row before writing the first one, which is exactly what streaming avoids.
+
 ```ts
 declare function createCSVStream<T extends Record<string, unknown>>(
   data: AsyncIterable<T> | Iterable<T>,
@@ -228,7 +307,7 @@ escapeCSVValue('contains "quotes"') // '"contains ""quotes"""'
 
 ### Defu
 
-Recursively assign default properties. Simplified version based on [unjs/defu](https://github.com/unjs/defu).
+Fills in missing properties from a chain of defaults. A trimmed-down take on [unjs/defu](https://github.com/unjs/defu).
 
 #### `defu`
 
@@ -286,7 +365,7 @@ const result = defu(
 
 #### `createDefu`
 
-Creates a custom defu function with a custom merger.
+Creates a `defu` variant that hands every property to your own merger first. Return `true` to signal you handled it; return nothing to fall back to the default behavior.
 
 ```ts
 type DefuMerger<T extends PlainObject = PlainObject> = (
@@ -325,8 +404,7 @@ Tiny functional event emitter / pubsub, based on [mitt](https://github.com/devel
 ```ts
 import { createEmitter } from 'utilful'
 
-// eslint-disable-next-line ts/consistent-type-definitions
-type Events = {
+interface Events {
   foo: { a: string }
 }
 
@@ -388,12 +466,9 @@ async function loadModule() {
 
 #### `memoize`
 
-A simple general purpose memoizer utility.
+Defers a computation until the value is first read, then caches it.
 
-- Lazily computes a value when accessed
-- Auto-caches the result by overwriting the getter
-
-Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invocation, since the getter itself is overwritten with the memoized value.
+Useful for expensive setup you may never need. Unlike a plain getter, there is no runtime cost after the first read, because the getter replaces itself with the computed value.
 
 ```ts
 declare function memoize<T>(getter: () => T): { value: T }
@@ -426,15 +501,20 @@ declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof
 
 #### `deepApply`
 
-Deeply applies a callback to every key-value pair in the given object, as well as nested objects and arrays (including arrays nested inside arrays).
+Applies a callback to every key-value pair of the given object, and to every pair inside nested objects and arrays (including arrays nested inside arrays).
+
+The callback also fires for nested objects, so `item` is whichever object the pair belongs to rather than the one you passed in.
 
 ```ts
-declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void
+declare function deepApply<T extends Record<any, any>>(
+  data: T,
+  callback: (item: Record<string, any>, key: string, value: any) => void
+): void
 ```
 
 #### `isObject`
 
-Checks if a value is an object with the plain `[object Object]` tag. Returns `true` for object literals, class instances, and `null`-prototype objects.
+Checks whether a value is an object. Object literals, class instances, and `null`-prototype objects all count; arrays, `Date`, `RegExp`, and `null` do not.
 
 ```ts
 declare function isObject(value: unknown): value is Record<any, any>
@@ -442,7 +522,7 @@ declare function isObject(value: unknown): value is Record<any, any>
 
 ### Path
 
-Utilities to build and normalize URL paths. All of them are also available from the `utilful/path` subpath export.
+Utilities to build and normalize URL paths. They slice strings instead of parsing a full `URL`, which keeps them cheap enough for hot paths. Only `withQuery` and `getQuery` reach for `URLSearchParams`, where correct percent-encoding is worth the allocation.
 
 #### `withoutLeadingSlash` / `withLeadingSlash`
 
@@ -478,7 +558,7 @@ joinURL('/api/', '/users', '42') // '/api/users/42'
 
 #### `withBase` / `withoutBase`
 
-Adds or removes a base path – each is a no-op if the base is already present (or absent).
+Adds or removes a base path – each is a no-op if the base is already present (or absent). An absolute URL is returned as it is, since no base path can prefix it.
 
 ```ts
 declare function withBase(input?: string, base?: string): string
@@ -489,20 +569,36 @@ declare function withoutBase(input?: string, base?: string): string
 
 ```ts
 withBase('/users', '/api') // '/api/users'
+withBase('https://example.com/users', '/api') // 'https://example.com/users'
 withoutBase('/api/users', '/api') // '/users'
 ```
 
 #### `getPathname`
 
-Returns the pathname of the given path – everything before the query string or hash. Absolute URLs (with a scheme, e.g. `https://example.com/foo`) return the URL's pathname; all other inputs are returned unchanged with the query string and hash removed.
+Returns the pathname of the given path – everything before the query string or hash. Absolute URLs return the part after the host, whether they carry a scheme (`https://example.com/foo`) or are protocol-relative (`//example.com/foo`).
+
+The pathname is sliced out as written and never normalized, so percent-encoding and `..` segments survive:
 
 ```ts
 declare function getPathname(path?: string): string
 ```
 
+```ts
+getPathname('/foo?bar#baz') // '/foo'
+getPathname('https://example.com/foo') // '/foo'
+getPathname('//example.com/foo') // '/foo'
+getPathname('https://example.com') // '/'
+getPathname('https://example.com/a/../b') // '/a/../b' – use `new URL` if you need this resolved
+```
+
 #### `withQuery`
 
-Returns the URL with the given query parameters merged in. `undefined` values remove the parameter, array values append one entry per item, and object values are JSON-stringified.
+Returns the URL with the given query parameters merged in. A fragment stays where it belongs, at the very end.
+
+- `undefined` removes the parameter
+- `null` keeps the parameter with an empty value
+- arrays append one entry per item, and empty arrays are skipped
+- objects are JSON-stringified
 
 ```ts
 type QueryValue = string | number | boolean | QueryValue[] | Record<string, any> | null | undefined
@@ -515,6 +611,25 @@ declare function withQuery(input: string, query?: QueryObject): string
 
 ```ts
 withQuery('/api/users', { page: 2, tags: ['a', 'b'] }) // '/api/users?page=2&tags=a&tags=b'
+withQuery('/api/users#list', { page: 2 }) // '/api/users?page=2#list'
+withQuery('/api/users?page=2', { page: undefined }) // '/api/users'
+```
+
+#### `getQuery`
+
+Reads the query parameters back out of a URL, ignoring the fragment. A parameter that appears more than once becomes an array of its values.
+
+```ts
+type ParsedQuery = Record<string, string | string[]>
+
+declare function getQuery(input: string): ParsedQuery
+```
+
+**Example:**
+
+```ts
+getQuery('/api/users?page=2&tags=a&tags=b') // { page: '2', tags: ['a', 'b'] }
+getQuery('/api/users') // {}
 ```
 
 ### Result
@@ -525,7 +640,7 @@ The `Result` type represents either success (`Ok`) or failure (`Err`). It provid
 type Result<T, E> = Ok<T, E> | Err<T, E>
 ```
 
-Both `Ok` and `Err` carry phantom types for proper type inference in unions.
+Both variants carry the success *and* the error type, so the two stay in sync as you chain `map` and `mapError` calls.
 
 **Basic example:**
 
@@ -616,7 +731,7 @@ Chains a function that returns a `Result`. Useful for composing fallible operati
 
 ```ts
 ok(2).andThen(x => x > 0 ? ok(x) : err('negative')) // Ok(2)
-err('fail').andThen(x => ok(x * 2)) // Err('fail') - short-circuits
+err('fail').andThen(x => ok(x * 2)) // Err('fail') – short-circuits
 ```
 
 #### `Result.unwrap`
@@ -629,6 +744,16 @@ err('fail').unwrap() // throws Error
 err('fail').unwrap('custom message') // throws Error('custom message')
 ```
 
+#### `Result.unwrapErr`
+
+Extracts the error, or throws if the result is `Ok`. The mirror image of `unwrap`.
+
+```ts
+err('fail').unwrapErr() // 'fail'
+ok(42).unwrapErr() // throws Error
+ok(42).unwrapErr('custom message') // throws Error('custom message')
+```
+
 #### `Result.unwrapOr`
 
 Extracts the value or returns a fallback.
@@ -690,6 +815,9 @@ declare function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undef
 declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
 ```
 
+> [!NOTE]
+> Like `toResult`, the function overload must be synchronous, and passing a function that returns a promise throws a `TypeError` rather than returning it as an error. Pass the promise itself.
+
 **Example:**
 
 ```ts
@@ -704,7 +832,9 @@ const { value, error } = await tryCatch(fetch('https://api.example.com').then(r
 
 #### `template`
 
-Simple template engine to replace variables in a string.
+Replaces `{name}` placeholders in a string with the matching variable.
+
+A placeholder with no matching variable is left as its own key, unless you pass a `fallback` – either a fixed string or a function receiving the key. A variable that is present but `null` or `undefined` is treated the same as a missing one. Only own properties are read, so `{constructor}` cannot reach prototype members.
 
 ```ts
 declare function template(
@@ -727,7 +857,10 @@ console.log(template(str, variables)) // Hello, world!
 
 #### `generateRandomId`
 
-Generates a random string. The function is ported from [`nanoid`](https://github.com/ai/nanoid). You can specify the size of the string and the dictionary of characters to use.
+Generates a random string. Ported from [`nanoid`](https://github.com/ai/nanoid). You can specify the length and the dictionary of characters to draw from.
+
+> [!WARNING]
+> Backed by `Math.random()` and therefore not cryptographically secure. Use `crypto.randomUUID()` or `crypto.getRandomValues()` for session tokens, password resets, and anything else an attacker would like to guess.
 
 ```ts
 declare function generateRandomId(size?: number, dict?: string): string

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/cli/args.d.mts

@@ -0,0 +1,44 @@
+//#region src/cli/args.d.ts
+interface StringArgDef {
+  type: "string";
+  /** One letter, as in `-d`. */
+  alias?: string;
+  description?: string;
+  default?: string;
+  required?: boolean;
+  /** Placeholder in the help, as in `--out-dir=<path>`. */
+  valueHint?: string;
+}
+interface BooleanArgDef {
+  type: "boolean";
+  alias?: string;
+  description?: string;
+  default?: boolean;
+}
+interface PositionalArgDef {
+  type: "positional";
+  description?: string;
+  required?: boolean;
+}
+type ArgDef = StringArgDef | BooleanArgDef | PositionalArgDef;
+type ArgsDef = Record<string, ArgDef>;
+type ParsedArgs<T extends ArgsDef = ArgsDef> = {
+  /** Every positional, bound by a definition or not. */
+  _: string[];
+} & { [K in keyof T]: ArgDef extends T[K] ? string | boolean | undefined : T[K] extends {
+  type: "boolean";
+} ? boolean : T[K] extends {
+  default: string;
+} | {
+  required: true;
+} ? string : string | undefined; };
+interface CommonArgs extends ArgsDef {
+  verbose: BooleanArgDef;
+}
+declare const commonArgs: CommonArgs;
+/** Parses `argv` against a definition. An absent boolean reads as `false`, and `--no-<name>` turns one off. */
+declare function parseArgs$1<T extends ArgsDef>(argv: readonly string[], argsDef: T, { allowExtraPositionals }?: {
+  allowExtraPositionals?: boolean;
+}): ParsedArgs<T>;
+//#endregion
+export { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs$1 as parseArgs };

package/dist/cli/args.mjs

@@ -0,0 +1,109 @@
+import { ArgumentError } from "./errors.mjs";
+import { parseArgs } from "node:util";
+//#region src/cli/args.ts
+const commonArgs = { verbose: {
+	type: "boolean",
+	description: "Print the cause chain and stack trace on failure"
+} };
+/** Parses `argv` against a definition. An absent boolean reads as `false`, and `--no-<name>` turns one off. */
+function parseArgs$1(argv, argsDef, { allowExtraPositionals = false } = {}) {
+	let parseResult;
+	try {
+		parseResult = parseArgs({
+			args: joinNegativeValues(splitShortOptionValues(argv), argsDef),
+			options: toNodeOptions(argsDef),
+			strict: true,
+			allowPositionals: true,
+			allowNegative: true
+		});
+	} catch (error) {
+		if (isNodeArgumentError(error)) throw new ArgumentError(error.message.split(". ")[0]);
+		throw error;
+	}
+	const args = { _: parseResult.positionals };
+	const positionalNames = [];
+	for (const [name, definition] of Object.entries(argsDef)) {
+		if (definition.type === "positional") {
+			positionalNames.push(name);
+			continue;
+		}
+		const value = parseResult.values[name];
+		if (definition.type === "boolean") args[name] = value ?? false;
+		else if (value === void 0 && definition.required === true) throw new ArgumentError(`Missing required argument: --${name}`);
+		else args[name] = value;
+	}
+	positionalNames.forEach((name, index) => {
+		const definition = argsDef[name];
+		const value = parseResult.positionals[index];
+		if (value === void 0 && definition.required === true) throw new ArgumentError(`Missing required positional argument: ${name.toUpperCase()}`);
+		args[name] = value;
+	});
+	if (!allowExtraPositionals && parseResult.positionals.length > positionalNames.length) throw new ArgumentError(`Unexpected argument: ${JSON.stringify(parseResult.positionals[positionalNames.length])}`);
+	return args;
+}
+function toNodeOptions(argsDef) {
+	const options = {};
+	for (const [name, definition] of Object.entries(argsDef)) {
+		if (definition.type === "positional") continue;
+		const option = { type: definition.type };
+		if (definition.alias !== void 0) option.short = definition.alias;
+		if (definition.default !== void 0) option.default = definition.default;
+		options[name] = option;
+	}
+	return options;
+}
+/**
+* Splits an inline value off a short option. Node's `parseArgs` splits
+* `--name=value` but leaves `-n=value` whole, so `-o=report.json` would write to
+* a file named `=report.json`. Past `--` every token is an operand and stays as
+* it was written.
+*/
+function splitShortOptionValues(argv) {
+	const splitArguments = [];
+	let isTerminated = false;
+	for (const argument of argv) {
+		const match = /^(-[^-])=(.*)$/.exec(argument);
+		if (isTerminated || match === null) {
+			splitArguments.push(argument);
+			isTerminated ||= argument === "--";
+			continue;
+		}
+		splitArguments.push(match[1], match[2]);
+	}
+	return splitArguments;
+}
+/**
+* Joins a negative number onto the value-taking option before it, as
+* `--start=-3`. Node refuses `--start -3` as ambiguous, but a token that starts
+* with a digit after its dash is a number wherever a value is due.
+*/
+function joinNegativeValues(argv, argsDef) {
+	const optionNamesBySpelling = /* @__PURE__ */ new Map();
+	for (const [name, definition] of Object.entries(argsDef)) {
+		if (definition.type !== "string") continue;
+		optionNamesBySpelling.set(`--${name}`, name);
+		if (definition.alias !== void 0) optionNamesBySpelling.set(`-${definition.alias}`, name);
+	}
+	const joinedArguments = [];
+	for (let index = 0; index < argv.length; index++) {
+		const argument = argv[index];
+		const next = argv[index + 1];
+		const name = optionNamesBySpelling.get(argument);
+		if (argument === "--") {
+			joinedArguments.push(...argv.slice(index));
+			break;
+		}
+		if (name !== void 0 && next !== void 0 && /^-\d/.test(next)) {
+			joinedArguments.push(`--${name}=${next}`);
+			index++;
+			continue;
+		}
+		joinedArguments.push(argument);
+	}
+	return joinedArguments;
+}
+function isNodeArgumentError(error) {
+	return error instanceof Error && String(error.code).startsWith("ERR_PARSE_ARGS");
+}
+//#endregion
+export { commonArgs, parseArgs$1 as parseArgs, toNodeOptions };

package/dist/cli/command.d.mts

@@ -0,0 +1,33 @@
+import { ArgsDef, ParsedArgs } from "./args.mjs";
+import { ReportOptions } from "./errors.mjs";
+//#region src/cli/command.d.ts
+interface CommandMeta {
+  name?: string;
+  version?: string;
+  description?: string;
+}
+interface CommandContext<T extends ArgsDef = ArgsDef> {
+  args: ParsedArgs<T>;
+}
+interface CommandDef<T extends ArgsDef = ArgsDef> {
+  meta?: CommandMeta;
+  args?: T;
+  subCommands?: Record<string, CommandDef<any>>;
+  allowExtraPositionals?: boolean;
+  run?: (context: CommandContext<T>) => unknown;
+}
+interface RunMainOptions extends Omit<ReportOptions, "verbose"> {
+  /** @default process.argv.slice(2) */
+  argv?: readonly string[];
+}
+declare function defineCommand<T extends ArgsDef>(command: CommandDef<T>): CommandDef<T>;
+/**
+ * Runs the command tree and reports whatever it throws. Help someone asked for
+ * is the result of the run and goes to stdout; usage that follows a wrong
+ * argument is diagnostics and joins its message on stderr.
+ */
+declare function runMain<T extends ArgsDef>(command: CommandDef<T>, options?: RunMainOptions): Promise<void>;
+/** Runs like `runMain`, but without the error boundary. */
+declare function runCommand<T extends ArgsDef>(command: CommandDef<T>, argv: readonly string[]): Promise<void>;
+//#endregion
+export { CommandContext, CommandDef, CommandMeta, RunMainOptions, defineCommand, runCommand, runMain };

package/dist/cli/command.mjs

@@ -0,0 +1,76 @@
+import { ArgumentError, reportFailure } from "./errors.mjs";
+import { parseArgs as parseArgs$1, toNodeOptions } from "./args.mjs";
+import { renderUsage } from "./usage.mjs";
+import { parseArgs } from "node:util";
+import process from "node:process";
+//#region src/cli/command.ts
+const HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+const VERSION_FLAGS = /* @__PURE__ */ new Set(["--version", "-v"]);
+function defineCommand(command) {
+	return command;
+}
+/**
+* Runs the command tree and reports whatever it throws. Help someone asked for
+* is the result of the run and goes to stdout; usage that follows a wrong
+* argument is diagnostics and joins its message on stderr.
+*/
+async function runMain(command, options = {}) {
+	const argv = options.argv ?? process.argv.slice(2);
+	const beforeTerminator = argv.slice(0, argv.includes("--") ? argv.indexOf("--") : void 0);
+	const hasFlag = (flags) => beforeTerminator.some((argument) => flags.has(argument));
+	try {
+		if (hasFlag(HELP_FLAGS)) process.stdout.write(`${usageFor(command, argv, process.stdout)}\n`);
+		else if (hasFlag(VERSION_FLAGS)) process.stdout.write(`${command.meta?.version ?? ""}\n`);
+		else await runCommand(command, argv);
+	} catch (error) {
+		if (error instanceof ArgumentError) process.stderr.write(`${usageFor(command, argv, process.stderr)}\n\n`);
+		const verbose = !(error instanceof ArgumentError) && beforeTerminator.includes("--verbose");
+		reportFailure(error, {
+			...options,
+			verbose
+		});
+	}
+}
+/** Runs like `runMain`, but without the error boundary. */
+async function runCommand(command, argv) {
+	const { name, firstOperand, rest } = findSubCommand(command, argv);
+	if (name !== void 0) return runCommand(command.subCommands[name], rest);
+	if (command.subCommands !== void 0 && command.run === void 0) throw new ArgumentError(firstOperand === void 0 ? "Missing command" : `Unknown command: ${firstOperand}`);
+	const args = parseArgs$1(rest, command.args ?? {}, { allowExtraPositionals: command.allowExtraPositionals });
+	await command.run?.({ args });
+}
+function usageFor(command, argv, stream) {
+	const { name } = findSubCommand(command, argv);
+	return name === void 0 ? renderUsage(command, { stream }) : renderUsage(command.subCommands[name], {
+		parent: command,
+		stream
+	});
+}
+/**
+* Finds the sub-command the first operand names, wherever it stands among the
+* options. Telling an operand from the value of an option needs every
+* value-taking option of every sub-command, since the command is still unknown.
+*/
+function findSubCommand(command, argv) {
+	if (command.subCommands === void 0) return { rest: [...argv] };
+	const options = Object.assign(toNodeOptions(command.args ?? {}), ...Object.values(command.subCommands).map((subCommand) => toNodeOptions(subCommand.args ?? {})));
+	const { tokens } = parseArgs({
+		args: [...argv],
+		options,
+		strict: false,
+		allowPositionals: true,
+		tokens: true
+	});
+	const firstOperand = tokens.find((token) => token.kind === "positional" || token.kind === "option-terminator");
+	if (firstOperand?.kind !== "positional") return { rest: [...argv] };
+	if (Object.hasOwn(command.subCommands, firstOperand.value)) return {
+		name: firstOperand.value,
+		rest: argv.toSpliced(firstOperand.index, 1)
+	};
+	return {
+		firstOperand: firstOperand.value,
+		rest: [...argv]
+	};
+}
+//#endregion
+export { defineCommand, runCommand, runMain };

package/dist/cli/errors.d.mts

@@ -0,0 +1,20 @@
+//#region src/cli/errors.d.ts
+type ErrorClass = abstract new (...args: never[]) => Error;
+interface ReportOptions {
+  verbose?: boolean;
+  /** Treated like `CliError`: message only, no stack. */
+  expectedErrors?: readonly ErrorClass[];
+  /** Renders an error where its message alone will not do; `undefined` falls back to the message. */
+  describe?: (error: Error) => string | undefined;
+}
+/**
+ * A condition the CLI recognized and phrased for a human. Anything else
+ * reaching the boundary is a defect in the tool and prints its stack unasked.
+ */
+declare class CliError extends Error {}
+/** Gets usage printed alongside its message. */
+declare class ArgumentError extends CliError {}
+/** Reports a failure the way the boundary does, for one that outlives `run`, such as a watch rebuild. */
+declare function reportFailure(error: unknown, { verbose, expectedErrors, describe }?: ReportOptions): void;
+//#endregion
+export { ArgumentError, CliError, ErrorClass, ReportOptions, reportFailure };