utilful 3.1.0 → 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)
@@ -37,6 +38,8 @@ 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
@@ -51,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`

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

package/dist/cli/errors.mjs

@@ -0,0 +1,43 @@
+import { error } from "./log.mjs";
+import process from "node:process";
+//#region src/cli/errors.ts
+/**
+* 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.
+*/
+var CliError = class extends Error {};
+/** Gets usage printed alongside its message. */
+var ArgumentError = class extends CliError {};
+/** Reports a failure the way the boundary does, for one that outlives `run`, such as a watch rebuild. */
+function reportFailure(error$1, { verbose = false, expectedErrors = [], describe } = {}) {
+	const sections = [error$1 instanceof Error ? describe?.(error$1) ?? error$1.message : String(error$1)];
+	if (verbose || !isExpected(error$1, expectedErrors)) {
+		const causeChain = formatCauseChain(error$1);
+		if (causeChain) sections.push(causeChain);
+		if (error$1 instanceof Error && error$1.stack) sections.push(error$1.stack);
+	}
+	error(sections.join("\n\n"));
+	process.exitCode = 1;
+}
+/**
+* Reports whether the CLI raised this error deliberately rather than tripping
+* over it. A system error such as `ENOENT` reaches the boundary as the honest
+* answer to what the user asked for, so it reads as deliberate too, while an
+* `ERR_*` error from a Node API is a wrong call and stays a defect.
+*/
+function isExpected(error, expectedErrors) {
+	if (error instanceof CliError) return true;
+	if (expectedErrors.some((expectedError) => error instanceof expectedError)) return true;
+	return error instanceof Error && /^E[A-Z0-9]+$/.test(String(error.code));
+}
+function formatCauseChain(error) {
+	const causeLines = [];
+	let current = error instanceof Error ? error.cause : void 0;
+	while (current instanceof Error) {
+		causeLines.push(`Caused by: ${current.name || "Error"}: ${current.message}`);
+		current = current.cause;
+	}
+	return causeLines.join("\n");
+}
+//#endregion
+export { ArgumentError, CliError, reportFailure };

package/dist/cli/index.d.mts

@@ -0,0 +1,5 @@
+import { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs } from "./args.mjs";
+import { ArgumentError, CliError, ErrorClass, ReportOptions, reportFailure } from "./errors.mjs";
+import { CommandContext, CommandDef, CommandMeta, RunMainOptions, defineCommand, runCommand, runMain } from "./command.mjs";
+import { log_d_exports } from "./log.mjs";
+export { type ArgDef, type ArgsDef, ArgumentError, type BooleanArgDef, CliError, type CommandContext, type CommandDef, type CommandMeta, type CommonArgs, type ErrorClass, type ParsedArgs, type PositionalArgDef, type ReportOptions, type RunMainOptions, type StringArgDef, commonArgs, defineCommand, log_d_exports as log, parseArgs, reportFailure, runCommand, runMain };

package/dist/cli/index.mjs

@@ -0,0 +1,5 @@
+import { log_exports } from "./log.mjs";
+import { ArgumentError, CliError, reportFailure } from "./errors.mjs";
+import { commonArgs, parseArgs } from "./args.mjs";
+import { defineCommand, runCommand, runMain } from "./command.mjs";
+export { ArgumentError, CliError, commonArgs, defineCommand, log_exports as log, parseArgs, reportFailure, runCommand, runMain };

package/dist/cli/log.d.mts

@@ -0,0 +1,10 @@
+declare namespace log_d_exports {
+  export { blankLine, error, info, success, warn };
+}
+declare function error(message: string): void;
+declare function warn(message: string): void;
+declare function info(message: string): void;
+declare function success(message: string): void;
+declare function blankLine(): void;
+//#endregion
+export { blankLine, error, info, log_d_exports, success, warn };

package/dist/cli/log.mjs

@@ -0,0 +1,28 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { paint } from "./style.mjs";
+import process from "node:process";
+//#region src/cli/log.ts
+var log_exports = /* @__PURE__ */ __exportAll({
+	blankLine: () => blankLine,
+	error: () => error,
+	info: () => info,
+	success: () => success,
+	warn: () => warn
+});
+function error(message) {
+	console.error(`${paint("red", "✖", process.stderr)} ${message}`);
+}
+function warn(message) {
+	console.error(`${paint("yellow", "⚠", process.stderr)} ${message}`);
+}
+function info(message) {
+	console.error(`${paint("cyan", "●", process.stderr)} ${message}`);
+}
+function success(message) {
+	console.error(`${paint("green", "✔", process.stderr)} ${message}`);
+}
+function blankLine() {
+	console.error("");
+}
+//#endregion
+export { blankLine, error, info, log_exports, success, warn };

package/dist/cli/style.mjs

@@ -0,0 +1,7 @@
+import { styleText } from "node:util";
+//#region src/cli/style.ts
+function paint(style, text, stream) {
+	return styleText(style, text, { stream });
+}
+//#endregion
+export { paint };

package/dist/cli/testing.d.mts

@@ -0,0 +1,29 @@
+import { ArgsDef } from "./args.mjs";
+import { CommandDef, RunMainOptions } from "./command.mjs";
+//#region src/cli/testing.d.ts
+interface FileMap {
+  [relativePath: string]: string;
+}
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+interface RunOptions {
+  cwd?: string;
+}
+interface CliHarnessOptions extends Omit<RunMainOptions, "argv"> {
+  /** Only `runCliProcess` needs it. */
+  entry?: string;
+}
+interface CliHarness {
+  runCli: (argv: readonly string[], options?: RunOptions) => Promise<CliResult>;
+  /** Runs the entry file as a child process, where the exit code is real and stdout can be cut short by exiting. */
+  runCliProcess: (argv: readonly string[], options?: RunOptions) => Promise<CliResult>;
+}
+declare function createCliHarness<T extends ArgsDef>(command: CommandDef<T>, { entry, ...runOptions }?: CliHarnessOptions): CliHarness;
+/** Registers an `afterEach` cleanup, so call it at the top level of a test file. */
+declare function useTemporaryDirectories(prefix?: string): (files?: FileMap) => string;
+declare function mockStdin(input: string): () => void;
+//#endregion
+export { CliHarness, CliHarnessOptions, CliResult, FileMap, RunOptions, createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/testing.mjs

@@ -0,0 +1,120 @@
+import { runMain } from "./command.mjs";
+import process from "node:process";
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+import { afterEach, vi } from "vitest";
+//#region src/cli/testing.ts
+var ProcessExitError = class extends Error {
+	constructor(exitCode) {
+		super(`process.exit(${exitCode})`);
+		this.exitCode = exitCode;
+	}
+};
+function createCliHarness(command, { entry, ...runOptions } = {}) {
+	return {
+		async runCli(argv, options = {}) {
+			const stdout = [];
+			const stderr = [];
+			const previousExitCode = process.exitCode;
+			const previousCwd = process.cwd();
+			process.exitCode = void 0;
+			const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+				stdout.push(String(chunk));
+				return true;
+			});
+			const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+				stderr.push(String(chunk));
+				return true;
+			});
+			const consoleLogSpy = vi.spyOn(console, "log").mockImplementation((...parts) => {
+				stdout.push(`${parts.map(String).join(" ")}\n`);
+			});
+			const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation((...parts) => {
+				stderr.push(`${parts.map(String).join(" ")}\n`);
+			});
+			const exitSpy = vi.spyOn(process, "exit").mockImplementation((code) => {
+				throw new ProcessExitError(typeof code === "number" ? code : 0);
+			});
+			let exitCode;
+			try {
+				if (options.cwd !== void 0) process.chdir(options.cwd);
+				await runMain(command, {
+					...runOptions,
+					argv
+				});
+				exitCode = process.exitCode ?? 0;
+			} catch (error) {
+				if (!(error instanceof ProcessExitError)) throw error;
+				exitCode = error.exitCode;
+			} finally {
+				process.chdir(previousCwd);
+				process.exitCode = previousExitCode;
+				exitSpy.mockRestore();
+				consoleErrorSpy.mockRestore();
+				consoleLogSpy.mockRestore();
+				stderrSpy.mockRestore();
+				stdoutSpy.mockRestore();
+			}
+			return {
+				stdout: stdout.join(""),
+				stderr: stderr.join(""),
+				exitCode
+			};
+		},
+		runCliProcess(argv, options = {}) {
+			if (entry === void 0) return Promise.reject(/* @__PURE__ */ new Error("runCliProcess needs the entry file of the CLI"));
+			return new Promise((resolve, reject) => {
+				execFile(process.execPath, [entry, ...argv], {
+					cwd: options.cwd,
+					maxBuffer: 64 * 1024 * 1024
+				}, (spawnError, stdout, stderr) => {
+					if (spawnError && typeof spawnError.code !== "number") reject(spawnError);
+					else resolve({
+						stdout,
+						stderr,
+						exitCode: spawnError ? spawnError.code : 0
+					});
+				});
+			});
+		}
+	};
+}
+/** Registers an `afterEach` cleanup, so call it at the top level of a test file. */
+function useTemporaryDirectories(prefix = "cli-test-") {
+	const directories = [];
+	afterEach(() => {
+		while (directories.length > 0) rmSync(directories.pop(), {
+			recursive: true,
+			force: true
+		});
+	});
+	return (files = {}) => {
+		const directory = mkdtempSync(path.join(os.tmpdir(), prefix));
+		directories.push(directory);
+		for (const [relativePath, contents] of Object.entries(files)) {
+			const filePath = path.join(directory, relativePath);
+			mkdirSync(path.dirname(filePath), { recursive: true });
+			writeFileSync(filePath, contents, "utf-8");
+		}
+		return directory;
+	};
+}
+function mockStdin(input) {
+	const stream = Readable.from([new TextEncoder().encode(input)]);
+	const originalStdin = process.stdin;
+	Object.defineProperty(process, "stdin", {
+		value: stream,
+		writable: true
+	});
+	return () => {
+		Object.defineProperty(process, "stdin", {
+			value: originalStdin,
+			writable: true
+		});
+	};
+}
+//#endregion
+export { createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/usage.mjs

@@ -0,0 +1,65 @@
+import { paint } from "./style.mjs";
+import { stripVTControlCharacters } from "node:util";
+import process from "node:process";
+//#region src/cli/usage.ts
+function renderUsage(command, { parent, stream = process.stdout } = {}) {
+	const color = (style, text) => paint(style, text, stream);
+	const heading = (title) => color(["bold", "underline"], title);
+	const meta = command.meta ?? {};
+	const parentMeta = parent?.meta ?? {};
+	const commandName = [parentMeta.name, meta.name].filter((name) => name !== void 0).join(" ");
+	const version = meta.version ?? parentMeta.version;
+	const positionalLines = [];
+	const optionLines = [];
+	const commandLines = [];
+	const usageLine = [];
+	for (const [name, definition] of Object.entries(command.args ?? {})) {
+		const isRequired = definition.type !== "boolean" && definition.required === true;
+		const hasDefault = definition.type !== "positional" && definition.default !== void 0 && definition.default !== false;
+		const hints = [
+			definition.description,
+			isRequired ? color("gray", "(Required)") : void 0,
+			hasDefault ? color("gray", `(Default: ${definition.default})`) : void 0
+		].filter((hint) => hint !== void 0).join(" ");
+		if (definition.type === "positional") {
+			const label = name.toUpperCase();
+			positionalLines.push([color("cyan", label), hints]);
+			usageLine.push(isRequired ? `<${label}>` : `[${label}]`);
+			continue;
+		}
+		const spellings = [definition.alias === void 0 ? void 0 : `-${definition.alias}`, `--${name}`].filter((spelling) => spelling !== void 0).join(", ");
+		const value = definition.type === "string" ? `<${definition.valueHint ?? name}>` : void 0;
+		optionLines.push([color("cyan", value === void 0 ? spellings : `${spellings}=${value}`), hints]);
+		if (definition.type === "boolean" && definition.default === true) optionLines.push([color("cyan", `--no-${name}`), ""]);
+		if (isRequired) usageLine.push(`--${name}=${value}`);
+	}
+	for (const [name, subCommand] of Object.entries(command.subCommands ?? {})) commandLines.push([color("cyan", name), subCommand.meta?.description ?? ""]);
+	const hasArguments = positionalLines.length > 0 || optionLines.length > 0;
+	if (commandLines.length > 0 && !hasArguments) usageLine.push(Object.keys(command.subCommands).join("|"));
+	const lines = [
+		color("gray", `${meta.description ?? ""} (${commandName}${version === void 0 ? "" : ` v${version}`})`),
+		"",
+		`${heading("USAGE")} ${color("cyan", [
+			commandName,
+			hasArguments ? "[OPTIONS]" : void 0,
+			...usageLine
+		].filter((part) => part !== void 0).join(" "))}`,
+		""
+	];
+	for (const [title, rows] of [
+		["ARGUMENTS", positionalLines],
+		["OPTIONS", optionLines],
+		["COMMANDS", commandLines]
+	]) if (rows.length > 0) lines.push(heading(title), "", formatColumns(rows), "");
+	if (commandLines.length > 0) lines.push(`Use ${color("cyan", `${commandName} <command> --help`)} for more information about a command.`);
+	return lines.join("\n").trimEnd();
+}
+function formatColumns(rows) {
+	const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => visibleLength(row[column]))));
+	return rows.map((row) => row.map((cell, column) => `  ${cell}${" ".repeat(widths[column] - visibleLength(cell))}`).join("").trimEnd()).join("\n");
+}
+function visibleLength(text) {
+	return stripVTControlCharacters(text).length;
+}
+//#endregion
+export { renderUsage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "packageManager": "pnpm@11.15.1",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
@@ -15,6 +15,7 @@
     "url": "https://github.com/johannschopplich/utilful/issues"
   },
   "keywords": [
+    "cli",
     "csv",
     "defu",
     "emitter",
@@ -33,6 +34,14 @@
       "types": "./dist/array.d.mts",
       "default": "./dist/array.mjs"
     },
+    "./cli": {
+      "types": "./dist/cli/index.d.mts",
+      "default": "./dist/cli/index.mjs"
+    },
+    "./cli/testing": {
+      "types": "./dist/cli/testing.d.mts",
+      "default": "./dist/cli/testing.mjs"
+    },
     "./csv": {
       "types": "./dist/csv.d.mts",
       "default": "./dist/csv.mjs"
@@ -86,6 +95,14 @@
     "test:types": "tsc --noEmit",
     "release": "bumpp"
   },
+  "peerDependencies": {
+    "vitest": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@antfu/eslint-config": "^9.1.0",
     "@types/node": "^26.1.1",