utilful 3.4.0 → 3.5.0

package/README.md

@@ -39,7 +39,7 @@ import { defu } from 'utilful' // Everything
 import { joinURL } from 'utilful/path' // Just the path helpers
 ```
 
-Two modules are the exception and live on their subpaths alone. `cli` is Node-only (22.13 or later) and ships as `utilful/cli` and `utilful/cli/testing`. `image` is browser-only and ships as `utilful/image`.
+Two modules are the exception and live on their subpaths alone. `cli` is Node-only (24.16 or later) and ships as `utilful/cli` and `utilful/cli/testing`. `image` is browser-only and ships as `utilful/image`.
 
 ## API
 
@@ -57,23 +57,26 @@ 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.
+A command runner on top of Node's `util.parseArgs`: strict option parsing, sub-commands at any depth, `--help`, `--version` and `--verbose` on every command, and an error boundary that prints a recognized error as its message and causes, and anything else with its stack as well. `--verbose` adds the stack to every failure but a wrong argument. `-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.
+Types a command definition, so `run` receives its `args` typed by their definitions. Declared `as const`, the arguments also type an exported command under `isolatedDeclarations`.
 
 ```ts
-import { CliError, commonArgs, defineCommand } from 'utilful/cli'
+import type { CommandDef } from 'utilful/cli'
+import { CliError, defineCommand } from 'utilful/cli'
 
-const build = defineCommand({
+const buildArgs = {
+  'file': { type: 'positional', description: 'Entry file', required: true }, // string
+  'out-dir': { type: 'string', alias: 'd', description: 'Output directory', valueHint: 'path' }, // string | undefined
+  'format': { type: 'enum', options: ['esm', 'iife'], default: 'esm' }, // 'esm' | 'iife'
+  'watch': { type: 'boolean', alias: 'w', description: 'Rebuild on change' }, // boolean, --no-watch turns it off
+} as const
+
+export const build: CommandDef<typeof buildArgs> = 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
-  },
+  args: buildArgs,
   run({ args }) {
     if (args.watch && args['out-dir'] === undefined)
       throw new CliError('--watch needs an --out-dir') // Printed as a message, no stack
@@ -96,11 +99,11 @@ const main = defineCommand({
 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.
+Also exported: `runCommand` (runs the tree and throws instead of reporting), `parseArgs`, `reportFailure` (for a failure that outlives `run`, such as a watch rebuild), `readStdin` (everything piped in, as text), `paint` (`styleText` for a given stream, hex colors included), 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.
+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. Both take a `cwd` and an `env`, where `undefined` removes a variable. `useTemporaryDirectories` and `mockStdin` ship alongside and clean up after the test.
 
 ```ts
 import { createCliHarness, useTemporaryDirectories } from 'utilful/cli/testing'

package/dist/cli/args.d.mts

@@ -15,30 +15,40 @@ interface BooleanArgDef {
   description?: string;
   default?: boolean;
 }
+interface EnumArgDef extends Omit<StringArgDef, "type"> {
+  type: "enum";
+  options: readonly string[];
+}
 interface PositionalArgDef {
   type: "positional";
   description?: string;
   required?: boolean;
 }
-type ArgDef = StringArgDef | BooleanArgDef | PositionalArgDef;
+type ArgDef = StringArgDef | BooleanArgDef | EnumArgDef | 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 {
+} ? boolean : OptionalUnless<T[K], T[K] extends {
+  type: "enum";
+  options: readonly (infer V)[];
+} ? V : string>; };
+type OptionalUnless<D, V> = D extends {
   default: string;
 } | {
   required: true;
-} ? string : string | undefined; };
+} ? V : V | undefined;
+/** @deprecated See `commonArgs`. */
 interface CommonArgs extends ArgsDef {
   verbose: BooleanArgDef;
 }
+/** @deprecated The runner accepts `--verbose` on every command, so spreading this adds nothing. */
 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 }?: {
+declare function parseArgs$1<const 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 };
+export { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, EnumArgDef, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs$1 as parseArgs };

package/dist/cli/args.mjs

@@ -1,10 +1,12 @@
 import { ArgumentError } from "./errors.mjs";
 import { parseArgs } from "node:util";
 //#region src/cli/args.ts
-const commonArgs = { verbose: {
+const verboseArg = {
 	type: "boolean",
-	description: "Print the cause chain and stack trace on failure"
-} };
+	description: "Print the stack trace on failure"
+};
+/** @deprecated The runner accepts `--verbose` on every command, so spreading this adds nothing. */
+const commonArgs = { verbose: verboseArg };
 /** 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;
@@ -28,6 +30,7 @@ function parseArgs$1(argv, argsDef, { allowExtraPositionals = false } = {}) {
 			continue;
 		}
 		const value = parseResult.values[name];
+		if (definition.type === "enum") assertEnumValue(name, definition, value);
 		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;
@@ -45,7 +48,7 @@ function toNodeOptions(argsDef) {
 	const options = {};
 	for (const [name, definition] of Object.entries(argsDef)) {
 		if (definition.type === "positional") continue;
-		const option = { type: definition.type };
+		const option = { type: definition.type === "boolean" ? "boolean" : "string" };
 		if (definition.alias !== void 0) option.short = definition.alias;
 		if (definition.default !== void 0) option.default = definition.default;
 		options[name] = option;
@@ -80,7 +83,7 @@ function splitShortOptionValues(argv) {
 function joinNegativeValues(argv, argsDef) {
 	const optionNamesBySpelling = /* @__PURE__ */ new Map();
 	for (const [name, definition] of Object.entries(argsDef)) {
-		if (definition.type !== "string") continue;
+		if (definition.type !== "string" && definition.type !== "enum") continue;
 		optionNamesBySpelling.set(`--${name}`, name);
 		if (definition.alias !== void 0) optionNamesBySpelling.set(`-${definition.alias}`, name);
 	}
@@ -102,8 +105,13 @@ function joinNegativeValues(argv, argsDef) {
 	}
 	return joinedArguments;
 }
+function assertEnumValue(name, definition, value) {
+	const options = definition.options.join(", ");
+	if (definition.default !== void 0 && !definition.options.includes(definition.default)) throw new Error(`The default of --${name}, ${JSON.stringify(definition.default)}, is not one of: ${options}`);
+	if (value !== void 0 && !definition.options.includes(value)) throw new ArgumentError(`Invalid value for --${name}: ${JSON.stringify(value)}. Expected one of: ${options}`);
+}
 function isNodeArgumentError(error) {
 	return error instanceof Error && String(error.code).startsWith("ERR_PARSE_ARGS");
 }
 //#endregion
-export { commonArgs, parseArgs$1 as parseArgs, toNodeOptions };
+export { commonArgs, parseArgs$1 as parseArgs, toNodeOptions, verboseArg };

package/dist/cli/command.d.mts

@@ -1,4 +1,4 @@
-import { ArgsDef, ParsedArgs } from "./args.mjs";
+import { ArgDef, ArgsDef, ParsedArgs } from "./args.mjs";
 import { ReportOptions } from "./errors.mjs";
 //#region src/cli/command.d.ts
 interface CommandMeta {
@@ -20,7 +20,12 @@ 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>;
+type ArgDefKey = ArgDef extends (infer D) ? D extends unknown ? keyof D : never : never;
+/** Maps every key no argument definition knows to `never`, so a misspelled one fails where the arguments are passed. */
+type KnownKeysOnly<T> = { [K in keyof T]: { [P in keyof T[K]]: P extends ArgDefKey ? T[K][P] : never; }; };
+declare function defineCommand<const T extends ArgsDef>(command: CommandDef<T> & {
+  args?: KnownKeysOnly<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

package/dist/cli/command.mjs

@@ -1,5 +1,5 @@
 import { ArgumentError, reportFailure } from "./errors.mjs";
-import { parseArgs as parseArgs$1, toNodeOptions } from "./args.mjs";
+import { parseArgs as parseArgs$1, toNodeOptions, verboseArg } from "./args.mjs";
 import { renderUsage } from "./usage.mjs";
 import { parseArgs } from "node:util";
 import process from "node:process";
@@ -33,19 +33,51 @@ async function runMain(command, options = {}) {
 }
 /** 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 });
+	const { commands, firstOperand, rest } = resolveCommand(command, argv);
+	const leaf = withRunnerArgs(commands.at(-1));
+	if (isDispatchOnly(leaf)) throw new ArgumentError(firstOperand === void 0 ? "Missing command" : `Unknown command: ${firstOperand}`);
+	const args = parseArgs$1(rest, leaf.args ?? {}, { allowExtraPositionals: leaf.allowExtraPositionals });
+	await leaf.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,
+	const { commands, keys } = resolveCommand(command, argv);
+	return renderUsage(withRunnerArgs(commands.at(-1)), {
+		commandPath: [command.meta?.name, ...keys].filter((name) => name !== void 0).join(" "),
+		version: commands.findLast((walked) => walked.meta?.version !== void 0)?.meta?.version,
 		stream
 	});
 }
+function resolveCommand(command, argv) {
+	const commands = [command];
+	const keys = [];
+	let rest = [...argv];
+	while (true) {
+		const found = findSubCommand(commands.at(-1), rest);
+		if (found.name === void 0) return {
+			commands,
+			keys,
+			firstOperand: found.firstOperand,
+			rest
+		};
+		commands.push(commands.at(-1).subCommands[found.name]);
+		keys.push(found.name);
+		rest = found.rest;
+	}
+}
+function isDispatchOnly(command) {
+	return command.subCommands !== void 0 && command.run === void 0;
+}
+/** `runMain` reads `--verbose` from argv itself, so strict parsing has to accept it on every command that parses arguments. */
+function withRunnerArgs(command) {
+	if (isDispatchOnly(command)) return command;
+	return {
+		...command,
+		args: {
+			...command.args,
+			verbose: command.args?.verbose ?? verboseArg
+		}
+	};
+}
 /**
 * 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

package/dist/cli/errors.d.mts

@@ -2,7 +2,7 @@
 type ErrorClass = abstract new (...args: never[]) => Error;
 interface ReportOptions {
   verbose?: boolean;
-  /** Treated like `CliError`: message only, no stack. */
+  /** Treated like `CliError`: no stack unless `verbose`. */
   expectedErrors?: readonly ErrorClass[];
   /** Renders an error where its message alone will not do; `undefined` falls back to the message. */
   describe?: (error: Error) => string | undefined;

package/dist/cli/errors.mjs

@@ -10,12 +10,11 @@ var CliError = class extends Error {};
 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);
-	}
+	const message = error$1 instanceof Error ? describe?.(error$1) ?? error$1.message : String(error$1);
+	const sections = [message];
+	const causeChain = formatCauseChain(error$1, message);
+	if (causeChain) sections.push(causeChain);
+	if ((verbose || !isExpected(error$1, expectedErrors)) && error$1 instanceof Error && error$1.stack) sections.push(error$1.stack);
 	error(sections.join("\n\n"));
 	process.exitCode = 1;
 }
@@ -30,11 +29,13 @@ function isExpected(error, expectedErrors) {
 	if (expectedErrors.some((expectedError) => error instanceof expectedError)) return true;
 	return error instanceof Error && /^E[A-Z0-9]+$/.test(String(error.code));
 }
-function formatCauseChain(error) {
+function formatCauseChain(error, message) {
 	const causeLines = [];
+	const seen = /* @__PURE__ */ new Set([error]);
 	let current = error instanceof Error ? error.cause : void 0;
-	while (current instanceof Error) {
-		causeLines.push(`Caused by: ${current.name || "Error"}: ${current.message}`);
+	while (current instanceof Error && !seen.has(current)) {
+		seen.add(current);
+		if (current.message !== message) causeLines.push(`Caused by: ${current.name || "Error"}: ${current.message}`);
 		current = current.cause;
 	}
 	return causeLines.join("\n");

package/dist/cli/index.d.mts

@@ -1,5 +1,7 @@
-import { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, ParsedArgs, PositionalArgDef, StringArgDef, commonArgs, parseArgs } from "./args.mjs";
+import { ArgDef, ArgsDef, BooleanArgDef, CommonArgs, EnumArgDef, 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 };
+import { readStdin } from "./stdin.mjs";
+import { Style, paint } from "./style.mjs";
+export { type ArgDef, type ArgsDef, ArgumentError, type BooleanArgDef, CliError, type CommandContext, type CommandDef, type CommandMeta, type CommonArgs, type EnumArgDef, type ErrorClass, type ParsedArgs, type PositionalArgDef, type ReportOptions, type RunMainOptions, type StringArgDef, type Style, commonArgs, defineCommand, log_d_exports as log, paint, parseArgs, readStdin, reportFailure, runCommand, runMain };

package/dist/cli/index.mjs

@@ -1,5 +1,7 @@
+import { paint } from "./style.mjs";
 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 };
+import { readStdin } from "./stdin.mjs";
+export { ArgumentError, CliError, commonArgs, defineCommand, log_exports as log, paint, parseArgs, readStdin, reportFailure, runCommand, runMain };

package/dist/cli/stdin.d.mts

@@ -0,0 +1,4 @@
+//#region src/cli/stdin.d.ts
+declare function readStdin(): Promise<string>;
+//#endregion
+export { readStdin };

package/dist/cli/stdin.mjs

@@ -0,0 +1,8 @@
+import process from "node:process";
+import { text } from "node:stream/consumers";
+//#region src/cli/stdin.ts
+function readStdin() {
+	return text(process.stdin);
+}
+//#endregion
+export { readStdin };

package/dist/cli/style.d.mts

@@ -0,0 +1,6 @@
+import { styleText } from "node:util";
+//#region src/cli/style.d.ts
+type Style = Parameters<typeof styleText>[0];
+declare function paint(style: Style, text: string, stream: NodeJS.WriteStream): string;
+//#endregion
+export { Style, paint };

package/dist/cli/testing.d.mts

@@ -11,6 +11,7 @@ interface CliResult {
 }
 interface RunOptions {
   cwd?: string;
+  env?: Record<string, string | undefined>;
 }
 interface CliHarnessOptions extends Omit<RunMainOptions, "argv"> {
   /** Only `runCliProcess` needs it. */
@@ -24,6 +25,7 @@ interface CliHarness {
 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;
+/** Pipes `input` into stdin until the test finishes; the function it returns restores stdin earlier. */
 declare function mockStdin(input: string): () => void;
 //#endregion
 export { CliHarness, CliHarnessOptions, CliResult, FileMap, RunOptions, createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/testing.mjs

@@ -5,7 +5,7 @@ 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";
+import { afterEach, onTestFinished, vi } from "vitest";
 //#region src/cli/testing.ts
 var ProcessExitError = class extends Error {
 	constructor(exitCode) {
@@ -20,6 +20,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			const stderr = [];
 			const previousExitCode = process.exitCode;
 			const previousCwd = process.cwd();
+			const previousEnv = Object.fromEntries(Object.keys(options.env ?? {}).map((name) => [name, process.env[name]]));
 			process.exitCode = void 0;
 			const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
 				stdout.push(String(chunk));
@@ -41,6 +42,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			let exitCode;
 			try {
 				if (options.cwd !== void 0) process.chdir(options.cwd);
+				setEnv(options.env ?? {});
 				await runMain(command, {
 					...runOptions,
 					argv
@@ -51,6 +53,7 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 				exitCode = error.exitCode;
 			} finally {
 				process.chdir(previousCwd);
+				setEnv(previousEnv);
 				process.exitCode = previousExitCode;
 				exitSpy.mockRestore();
 				consoleErrorSpy.mockRestore();
@@ -69,6 +72,10 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 			return new Promise((resolve, reject) => {
 				execFile(process.execPath, [entry, ...argv], {
 					cwd: options.cwd,
+					env: {
+						...process.env,
+						...options.env
+					},
 					maxBuffer: 67108864
 				}, (spawnError, stdout, stderr) => {
 					if (spawnError && typeof spawnError.code !== "number") reject(spawnError);
@@ -82,6 +89,10 @@ function createCliHarness(command, { entry, ...runOptions } = {}) {
 		}
 	};
 }
+function setEnv(env) {
+	for (const [name, value] of Object.entries(env)) if (value === void 0) delete process.env[name];
+	else process.env[name] = value;
+}
 /** Registers an `afterEach` cleanup, so call it at the top level of a test file. */
 function useTemporaryDirectories(prefix = "cli-test-") {
 	const directories = [];
@@ -102,19 +113,22 @@ function useTemporaryDirectories(prefix = "cli-test-") {
 		return directory;
 	};
 }
+/** Pipes `input` into stdin until the test finishes; the function it returns restores stdin earlier. */
 function mockStdin(input) {
 	const stream = Readable.from([new TextEncoder().encode(input)]);
 	const originalStdin = process.stdin;
-	Object.defineProperty(process, "stdin", {
-		value: stream,
-		writable: true
-	});
-	return () => {
+	const restoreStdin = () => {
 		Object.defineProperty(process, "stdin", {
 			value: originalStdin,
 			writable: true
 		});
 	};
+	onTestFinished(restoreStdin);
+	Object.defineProperty(process, "stdin", {
+		value: stream,
+		writable: true
+	});
+	return restoreStdin;
 }
 //#endregion
 export { createCliHarness, mockStdin, useTemporaryDirectories };

package/dist/cli/usage.mjs

@@ -2,13 +2,10 @@ 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 } = {}) {
+function renderUsage(command, { commandPath: commandName = command.meta?.name ?? "", version = command.meta?.version, stream = process.stdout } = {}) {
 	const color = (style, text) => paint(style, text, stream);
 	const heading = (title) => color("bold", 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 = [];
@@ -28,7 +25,7 @@ function renderUsage(command, { parent, stream = process.stdout } = {}) {
 			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;
+		const value = definition.type === "boolean" ? void 0 : `<${definition.valueHint ?? (definition.type === "enum" ? definition.options.join("|") : name)}>`;
 		optionLines.push([color("cyan", spellings) + (value === void 0 ? "" : color("dim", `=${value}`)), hints]);
 		if (definition.type === "boolean" && definition.default === true) optionLines.push([color("cyan", `--no-${name}`), ""]);
 		if (isRequired) usageLine.push(`--${name}=${value}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "packageManager": "pnpm@11.25.0",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",