cli-api 0.2.0 → 0.2.1

package/dist/{run-C903J5ca.mjs → run-DEkBUX4b.mjs}

@@ -1,4 +1,4 @@
-import { a as getExecuteHandler, c as createChalk, i as OptType, n as Command, o as hasSubCommands, r as ExecutionContext, s as isExecutable } from "./interfaces-COq24bNI.mjs";
+import { a as getExecuteHandler, c as createChalk, i as OptType, n as Command, o as hasSubCommands, r as ExecutionContext, s as isExecutable } from "./interfaces-CfKTHP7y.mjs";
 import Path from "path";
 import stringWidth from "string-width";
 import FileSys from "fs";
@@ -31,6 +31,9 @@ function print(str = "") {
 function printLn(...args) {
 	console.log(...args);
 }
+function printErrLn(...args) {
+	process.stderr.write(args.map(String).join(" ") + "\n");
+}
 /**
 * Semantic categories for user-facing CLI errors.
 */
@@ -55,15 +58,18 @@ const ERROR_PRESENTATION = {
 	}
 };
 function blockError(str, style, chalk) {
-	const lines = str.split("\n");
-	const width = Math.max(...lines.map((l) => stringWidth(l))) + 4;
+	const lines = wrapText(str, Math.max(getTerminalWidth() - 4, 1));
+	const width = Math.max(...lines.map((l) => stringWidth(l)), 0) + 4;
 	const colorize = chalk.bgHex(ERROR_PRESENTATION[style].color).hex("#FEFBEC");
-	printLn(colorize(space(width)));
+	printErrLn(colorize(space(width)));
 	for (const line of lines) {
 		const txt = `  ${line}`;
-		printLn(colorize(txt + space(width, txt)));
+		printErrLn(colorize(txt + space(width, txt)));
 	}
-	printLn(colorize(space(width)));
+	printErrLn(colorize(space(width)));
+}
+function inlineError(str) {
+	printErrLn(str);
 }
 /**
 * Creates a structured CLI error.
@@ -94,7 +100,11 @@ function getErrorExitCode(error) {
 * @returns Nothing.
 */
 function printError(error, chalk) {
-	blockError(error.message, error.type, chalk);
+	if (chalk.level > 0) {
+		blockError(error.message, error.type, chalk);
+		return;
+	}
+	inlineError(error.message);
 }
 function toArray(x) {
 	if (!x) return EMPTY_ARRAY;
@@ -116,7 +126,7 @@ function space(len, str) {
 	return len > 0 ? " ".repeat(len) : "";
 }
 function getTerminalWidth() {
-	return process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : 80;
+	return process.stderr.columns && process.stderr.columns > 0 ? process.stderr.columns : process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : 80;
 }
 function wrapText(text, width) {
 	if (width <= 0) return text.split("\n");
@@ -165,12 +175,6 @@ function sortBy(arr, cmp) {
 	return keys.map((i) => arr[i]);
 }
 
-//#endregion
-//#region src/commands/version.ts
-const versionCommand = new Command("version").describe("Displays current version").run(async (_, __, context) => {
-	printLn(context.app._version);
-});
-
 //#endregion
 //#region src/options.ts
 /**
@@ -181,8 +185,8 @@ const versionCommand = new Command("version").describe("Displays current version
 */
 var UnknownOptionError = class extends Error {
 	option;
-	constructor(option) {
-		super(`option ${option} not recognized`);
+	constructor(option, formattedOption = option) {
+		super(`option ${formattedOption} not recognized`);
 		this.option = option;
 	}
 };
@@ -212,6 +216,86 @@ function getMinRequiredCount(value) {
 	if (typeof value === "number") return value;
 	return 0;
 }
+function getFixedPositionalCount(arg) {
+	const minRequired = getMinRequiredCount(arg.required);
+	if (isRepeatable(arg.repeatable)) {
+		const maxRepeatCount = getMaxRepeatCount(arg.repeatable);
+		if (maxRepeatCount !== void 0 && maxRepeatCount === minRequired) return minRequired;
+		return;
+	}
+	return minRequired > 0 ? 1 : void 0;
+}
+function getTrailingFixedRequiredCount(positonals, startIndex) {
+	let total = 0;
+	for (let i = startIndex; i < positonals.length; ++i) {
+		const fixedCount = getFixedPositionalCount(positonals[i]);
+		if (fixedCount === void 0 || fixedCount === 0) return;
+		total += fixedCount;
+	}
+	return total;
+}
+function describeItem(itemName) {
+	return itemName ? ` for ${itemName}` : "";
+}
+function formatToken(value, chalk) {
+	return chalk.level > 0 ? chalk.bold(value) : `\`${value}\``;
+}
+function formatItem(kind, value, chalk) {
+	return `${kind} ${formatToken(value, chalk)}`;
+}
+function formatPath(value, chalk) {
+	const fullPath = Path.resolve(value);
+	if (chalk.level === 0) return `"${fullPath}"`;
+	return chalk.underline(fullPath);
+}
+function describeOptionType(type, enumValues) {
+	if (Array.isArray(type) || type === OptType.ENUM) return `one of: ${(enumValues ?? (Array.isArray(type) ? type : [])).join(", ")}`;
+	switch (type) {
+		case OptType.BOOL: return "a boolean";
+		case OptType.INT: return "an integer";
+		case OptType.FLOAT: return "a number";
+		case OptType.STRING: return "a string";
+		case OptType.INPUT_FILE: return "a readable file path";
+		case OptType.INPUT_DIRECTORY: return "a readable directory path";
+		case OptType.OUTPUT_FILE: return "a writable file path";
+		case OptType.OUTPUT_DIRECTORY: return "a writable directory path";
+		case OptType.EMPTY_DIRECTORY: return "an empty directory path";
+	}
+	return "a valid value";
+}
+function ensureFiniteNumber(value, numericValue, type, itemName) {
+	if (Number.isNaN(numericValue) || !Number.isFinite(numericValue)) throw new Error(`Invalid value "${value}"${describeItem(itemName)} (expected ${describeOptionType(type)})`);
+	return numericValue;
+}
+function createPathError(kind, path, message, itemName) {
+	return /* @__PURE__ */ new Error(`${kind} ${path} ${message}${describeItem(itemName)}`);
+}
+function ensureInputDirectory(dir, chalk, itemName) {
+	const normalizedDir = Path.normalize(dir);
+	const fullPath = formatPath(normalizedDir, chalk);
+	const stat = statSync(normalizedDir);
+	if (!stat) throw createPathError("Directory", fullPath, "does not exist", itemName);
+	if (!stat.isDirectory()) throw createPathError("Directory", fullPath, "is not a directory", itemName);
+	try {
+		FileSys.accessSync(normalizedDir, FileSys.constants.R_OK | FileSys.constants.X_OK);
+	} catch {
+		throw createPathError("Directory", fullPath, "is not readable", itemName);
+	}
+	return normalizedDir;
+}
+function ensureOutputDirectory(dir, chalk, itemName) {
+	const normalizedDir = Path.normalize(dir);
+	const fullPath = formatPath(normalizedDir, chalk);
+	const stat = statSync(normalizedDir);
+	if (!stat) throw createPathError("Directory", fullPath, "does not exist", itemName);
+	if (!stat.isDirectory()) throw createPathError("Directory", fullPath, "is not a directory", itemName);
+	try {
+		FileSys.accessSync(normalizedDir, FileSys.constants.W_OK);
+	} catch {
+		throw createPathError("Directory", fullPath, "is not writable", itemName);
+	}
+	return normalizedDir;
+}
 function assertValidCount(name, value, { allowZero = false } = {}) {
 	if (!Number.isInteger(value) || value < 0 || !allowZero && value === 0) throw new Error(`${name} must be ${allowZero ? "a non-negative" : "a positive"} integer`);
 }
@@ -228,10 +312,12 @@ function validatePositionalDefinitions(cmd) {
 			if (!repeatable) throw new Error(`"${arg.name}" argument cannot use a numeric required count unless it is repeatable`);
 		}
 		if (typeof arg.repeatable === "number") assertValidCount(`"${arg.name}" argument repeatable count`, arg.repeatable);
-		if (repeatable && i < cmd.positonals.length - 1) throw new Error("Only the last argument can be repeatable");
+		if (repeatable && i < cmd.positonals.length - 1) {
+			if (getTrailingFixedRequiredCount(cmd.positonals, i + 1) === void 0) throw new Error("Repeatable arguments can only be followed by required arguments with fixed counts");
+		}
 		if (maxRepeatCount !== void 0 && minRequired > maxRepeatCount) throw new Error(`"${arg.name}" argument requires at least ${minRequired} values but allows at most ${maxRepeatCount}`);
 		if (encounteredOptionalPositional && minRequired > 0) throw new Error("Required arguments cannot come after optional arguments");
-		if (minRequired === 0) encounteredOptionalPositional = true;
+		if (minRequired === 0 && !repeatable) encounteredOptionalPositional = true;
 	}
 }
 function pushRepeatableValue(target, value, itemName, maxCount, kind) {
@@ -307,9 +393,39 @@ function validateCommandConfig(cmd) {
 		}
 	}
 }
-function parseArgs(cmd, argv) {
+function assignPositionalArguments(positonals, rawArgs, opts, chalk) {
+	if (!positonals?.length) return [...rawArgs];
 	const args = [];
+	let rawArgIdx = 0;
+	for (let i = 0; i < positonals.length; ++i) {
+		const def = positonals[i];
+		const k = def.key ?? def.name;
+		if (isRepeatable(def.repeatable)) {
+			const trailingFixedRequiredCount = i < positonals.length - 1 ? getTrailingFixedRequiredCount(positonals, i + 1) ?? 0 : 0;
+			const valueCount = Math.max(0, rawArgs.length - rawArgIdx - trailingFixedRequiredCount);
+			const maxRepeatCount = getMaxRepeatCount(def.repeatable);
+			const arr = opts[k] ??= [];
+			if (maxRepeatCount !== void 0 && valueCount > maxRepeatCount) throw new Error(`"${def.name}" argument allows at most ${maxRepeatCount} value${maxRepeatCount === 1 ? "" : "s"}`);
+			for (let j = 0; j < valueCount; ++j) {
+				let value$1 = rawArgs[rawArgIdx++];
+				if (def.type != null) value$1 = coerceType(value$1, def.type, chalk, formatItem("argument", def.name, chalk), getEnumValues(def));
+				pushRepeatableValue(arr, value$1, def.name, maxRepeatCount, "argument");
+				args.push(value$1);
+			}
+			continue;
+		}
+		if (rawArgIdx >= rawArgs.length) continue;
+		let value = rawArgs[rawArgIdx++];
+		if (def.type != null) value = coerceType(value, def.type, chalk, formatItem("argument", def.name, chalk), getEnumValues(def));
+		opts[k] = value;
+		args.push(value);
+	}
+	if (rawArgIdx < rawArgs.length) args.push(...rawArgs.slice(rawArgIdx));
+	return args;
+}
+function parseArgs(cmd, argv, chalk, { skipRequiredOptions = false, skipRequiredPositionals = false } = {}) {
 	const opts = Object.create(null);
+	const rawArgs = [];
 	let parseFlags = true;
 	const allOptions = getOptions(cmd);
 	validateCommandConfig(cmd);
@@ -342,7 +458,6 @@ function parseArgs(cmd, argv) {
 			if (!findOpt(ch)) return ch;
 		}
 	};
-	let argIdx = 0;
 	for (let i = 0; i < argv.length; ++i) {
 		let token = argv[i];
 		if (parseFlags && token === "--") {
@@ -359,15 +474,15 @@ function parseArgs(cmd, argv) {
 				}
 				const name = token.slice(2);
 				const match = findOpt(name);
-				if (!match) throw new UnknownOptionError(`--${name}`);
+				if (!match) throw new UnknownOptionError(`--${name}`, formatToken(`--${name}`, chalk));
 				const { opt, negated } = match;
-				if (negated && inlineValue !== void 0) throw new Error(`Option \`--no-${opt.name}\` does not take a value`);
+				if (negated && inlineValue !== void 0) throw new Error(`Option ${formatToken(`--no-${opt.name}`, chalk)} does not take a value`);
 				let value = inlineValue;
 				if (negated) value = getOptionNoPrefixValue(opt);
 				else if (value === void 0) if (opt.valueNotRequired) value = getOptionImplicitValue(opt);
 				else if (i < argv.length - 1) value = argv[++i];
-				else throw new Error(`Missing required value for option \`${token}\``);
-				if (opt.type != null) value = coerceType(value, opt.type, `option \`${token}\``, getEnumValues(opt));
+				else throw new Error(`Missing required value for option ${formatToken(token, chalk)}`);
+				if (opt.type != null) value = coerceType(value, opt.type, chalk, formatItem("option", token, chalk), getEnumValues(opt));
 				const k = opt.key ?? opt.name;
 				if (isRepeatable(opt.repeatable)) pushRepeatableValue(opts[k], value, opt.name, getMaxRepeatCount(opt.repeatable), "option");
 				else opts[k] = value;
@@ -379,13 +494,13 @@ function parseArgs(cmd, argv) {
 				inlineValue = equalIndex === -1 ? void 0 : clusterText.slice(equalIndex + 1);
 				if (hasInlineAssignment) {
 					const unknownOption = getUnknownShortOption(cluster);
-					if (unknownOption !== void 0) throw new UnknownOptionError(`-${unknownOption}`);
+					if (unknownOption !== void 0) throw new UnknownOptionError(`-${unknownOption}`, formatToken(`-${unknownOption}`, chalk));
 				}
 				let j = 0;
 				while (j < cluster.length) {
 					const ch = cluster[j];
 					const match = findOpt(ch);
-					if (!match) throw new UnknownOptionError(`-${ch}`);
+					if (!match) throw new UnknownOptionError(`-${ch}`, formatToken(`-${ch}`, chalk));
 					const { opt } = match;
 					if (opt.valueNotRequired) {
 						const k$1 = opt.key ?? opt.name;
@@ -398,124 +513,118 @@ function parseArgs(cmd, argv) {
 					let value;
 					const remainder = cluster.slice(j + 1);
 					if (remainder.length && !hasInlineAssignment) value = remainder;
-					else if (remainder.length && hasInlineAssignment) throw new Error(`Missing required value for option \`-${ch}\``);
+					else if (remainder.length && hasInlineAssignment) throw new Error(`Missing required value for option ${formatToken(`-${ch}`, chalk)}`);
 					else if (inlineValue !== void 0 && remainder.length === 0) value = inlineValue;
 					else if (i < argv.length - 1) value = argv[++i];
-					else throw new Error(`Missing required value for option "-${ch}"`);
-					if (opt.type != null) value = coerceType(value, opt.type, `option \`-${ch}\``, getEnumValues(opt));
+					else throw new Error(`Missing required value for option ${formatToken(`-${ch}`, chalk)}`);
+					if (opt.type != null) value = coerceType(value, opt.type, chalk, formatItem("option", `-${ch}`, chalk), getEnumValues(opt));
 					const k = opt.key ?? opt.name;
 					if (isRepeatable(opt.repeatable)) pushRepeatableValue(opts[k], value, opt.name, getMaxRepeatCount(opt.repeatable), "option");
 					else opts[k] = value;
 					break;
 				}
 			}
-		} else {
-			let value = token;
-			const def = cmd.positonals?.[argIdx];
-			if (def) {
-				if (def.type != null) value = coerceType(value, def.type, `argument \`${def.name}\``, getEnumValues(def));
-				const k = def.key ?? def.name;
-				if (isRepeatable(def.repeatable)) {
-					const arr = opts[k] ??= [];
-					pushRepeatableValue(arr, value, def.name, getMaxRepeatCount(def.repeatable), "argument");
-					for (i = i + 1; i < argv.length; ++i) {
-						let v = argv[i];
-						if (parseFlags && v === "--") {
-							parseFlags = false;
-							continue;
-						}
-						if (parseFlags && v.startsWith("-")) {
-							i -= 1;
-							break;
-						}
-						if (def.type != null) v = coerceType(v, def.type, `argument \`${def.name}\``, getEnumValues(def));
-						pushRepeatableValue(arr, v, def.name, getMaxRepeatCount(def.repeatable), "argument");
-					}
-					argIdx = isRepeatable(def.repeatable) && cmd.positonals ? cmd.positonals.length : argIdx;
-					args.push(...arr);
-					continue;
-				} else opts[k] = value;
-			}
-			args.push(value);
-			++argIdx;
-		}
+		} else rawArgs.push(token);
 	}
+	const args = assignPositionalArguments(cmd.positonals, rawArgs, opts, chalk);
 	if (allOptions.length) for (const opt of allOptions) {
 		const k = opt.key ?? opt.name;
 		if (opts[k] === void 0) {
 			if (opt.defaultValue !== void 0) opts[k] = resolve(opt.defaultValue);
-			else if (opt.required) throw new Error(`\`${getOptName(opt)}\` option is required`);
+			else if (opt.required && !skipRequiredOptions) throw new Error(`${formatToken(getOptName(opt), chalk)} option is required`);
 		}
 	}
 	if (cmd.positonals?.length) for (let i = 0; i < cmd.positonals.length; ++i) {
 		const a = cmd.positonals[i];
 		const minRequired = getMinRequiredCount(a.required);
-		if (minRequired > 0 && argIdx <= i && !isRepeatable(a.repeatable)) throw new Error(`\`${a.name}\` argument is required`);
 		const k = a.key ?? a.name;
-		if (isRepeatable(a.repeatable) && (opts[k]?.length ?? 0) < minRequired) throw new Error(`\`${a.name}\` argument requires at least ${minRequired} value${minRequired === 1 ? "" : "s"}`);
+		if (!isRepeatable(a.repeatable) && minRequired > 0 && opts[k] === void 0 && !skipRequiredPositionals) throw new Error(`${formatToken(a.name, chalk)} argument is required`);
+		if (isRepeatable(a.repeatable) && (opts[k]?.length ?? 0) < minRequired && !skipRequiredPositionals) throw new Error(`\`${a.name}\` argument requires at least ${minRequired} value${minRequired === 1 ? "" : "s"}`);
 		if (k && opts[k] === void 0 && a.defaultValue !== void 0) opts[k] = resolve(a.defaultValue);
 	}
 	return [args, opts];
 }
-function coerceType(value, type, itemName, enumValues) {
+function coerceType(value, type, chalk, itemName, enumValues) {
 	const normalizedEnumValue = () => {
 		const normalized = String(value).trim().toLowerCase();
 		const allowedValues = enumValues ?? (Array.isArray(type) ? type : void 0);
-		if (allowedValues !== void 0 && !allowedValues.includes(normalized)) {
-			const itemText = itemName ? ` for ${itemName}` : "";
-			throw new Error(`Invalid value "${value}"${itemText} (expected one of: ${allowedValues.join(", ")})`);
-		}
+		if (allowedValues !== void 0 && !allowedValues.includes(normalized)) throw new Error(`Invalid value "${value}"${describeItem(itemName)} (expected one of: ${allowedValues.join(", ")})`);
 		return normalized;
 	};
 	if (Array.isArray(type)) return normalizedEnumValue();
 	switch (type) {
-		case OptType.BOOL: return toBool(value);
-		case OptType.INT: return Math.trunc(Number(value));
-		case OptType.FLOAT: return Number(value);
+		case OptType.BOOL: try {
+			return toBool(value);
+		} catch {
+			throw new Error(`Invalid value "${value}"${describeItem(itemName)} (expected ${describeOptionType(type)})`);
+		}
+		case OptType.INT: return Math.trunc(ensureFiniteNumber(value, Number(value), type, itemName));
+		case OptType.FLOAT: return ensureFiniteNumber(value, Number(value), type, itemName);
 		case OptType.ENUM: return normalizedEnumValue();
 		case OptType.STRING: return String(value);
 		case OptType.INPUT_FILE: {
 			if (value === "-") return "/dev/stdin";
 			const file = Path.normalize(value);
-			const fullPath = Path.resolve(file);
+			const fullPath = formatPath(file, chalk);
 			const stat = statSync(file);
-			if (!stat) throw new Error(`File ${createChalk().underline(fullPath)} does not exist`);
-			if (!stat.isFile()) throw new Error(`${createChalk().underline(fullPath)} is not a file`);
+			if (!stat) throw createPathError("File", fullPath, "does not exist", itemName);
+			if (!stat.isFile()) throw createPathError("File", fullPath, "is not a file", itemName);
 			try {
 				FileSys.accessSync(file, FileSys.constants.R_OK);
-			} catch (err) {
-				throw new Error(`${createChalk().underline(fullPath)} is not readable`);
+			} catch {
+				throw createPathError("File", fullPath, "is not readable", itemName);
 			}
 			return file;
 		}
-		case OptType.INPUT_DIRECTORY: {
-			const dir = Path.normalize(value);
-			FileSys.accessSync(dir, FileSys.constants.X_OK);
-			return dir;
-		}
+		case OptType.INPUT_DIRECTORY: return ensureInputDirectory(value, chalk, itemName);
 		case OptType.OUTPUT_FILE: {
 			if (value === "-") return "/dev/stdout";
 			const file = Path.normalize(value);
+			const fullPath = formatPath(file, chalk);
 			const stat = statSync(file);
 			if (stat) {
-				if (!stat.isFile()) throw new Error(`'${file}' is not a file`);
-				FileSys.accessSync(file, FileSys.constants.W_OK);
-			} else FileSys.accessSync(Path.dirname(file), FileSys.constants.W_OK);
+				if (!stat.isFile()) throw createPathError("File", fullPath, "is not a file", itemName);
+				try {
+					FileSys.accessSync(file, FileSys.constants.W_OK);
+				} catch {
+					throw createPathError("File", fullPath, "is not writable", itemName);
+				}
+			} else {
+				const parentDir = Path.dirname(file);
+				const fullParentDir = formatPath(parentDir, chalk);
+				const parentStat = statSync(parentDir);
+				if (!parentStat) throw createPathError("Directory", fullParentDir, "does not exist", itemName);
+				if (!parentStat.isDirectory()) throw createPathError("Directory", fullParentDir, "is not a directory", itemName);
+				try {
+					FileSys.accessSync(parentDir, FileSys.constants.W_OK);
+				} catch {
+					throw createPathError("Directory", fullParentDir, "is not writable", itemName);
+				}
+			}
 			return file;
 		}
-		case OptType.OUTPUT_DIRECTORY:
-			FileSys.accessSync(value, FileSys.constants.W_OK);
-			return Path.normalize(value);
+		case OptType.OUTPUT_DIRECTORY: return ensureOutputDirectory(value, chalk, itemName);
 		case OptType.EMPTY_DIRECTORY: {
 			const dir = Path.normalize(value);
+			const fullPath = formatPath(dir, chalk);
 			let files = [];
 			try {
 				files = FileSys.readdirSync(dir);
 			} catch (err) {
-				if (err?.code === "ENOENT") FileSys.accessSync(Path.dirname(dir), FileSys.constants.W_OK);
-				else throw err;
+				if (err?.code === "ENOENT") {
+					const parentDir = Path.dirname(dir);
+					const fullParentDir = formatPath(parentDir, chalk);
+					const parentStat = statSync(parentDir);
+					if (!parentStat) throw createPathError("Directory", fullParentDir, "does not exist", itemName);
+					if (!parentStat.isDirectory()) throw createPathError("Directory", fullParentDir, "is not a directory", itemName);
+					try {
+						FileSys.accessSync(parentDir, FileSys.constants.W_OK);
+					} catch {
+						throw createPathError("Directory", fullParentDir, "is not writable", itemName);
+					}
+				} else throw createPathError("Directory", fullPath, "is not readable", itemName);
 			}
-			if (files.length) throw new Error(`${createChalk().underline(dir)} is not empty`);
+			if (files.length) throw createPathError("Directory", fullPath, "is not empty", itemName);
 			return dir;
 		}
 	}
@@ -525,8 +634,8 @@ function getOptName(opt) {
 	return (opt.name.length > 1 ? "--" : "-") + opt.name;
 }
 function findSubCommand(name, subCommands) {
-	const cmdName = String(name).trim().replace(/^-{1,2}/, "").toLowerCase();
-	return subCommands.find((c) => c.name === cmdName || includes(cmdName, c.alias));
+	const cmdName = String(name).trim().toLowerCase();
+	return subCommands.find((c) => c.name.toLowerCase() === cmdName || toArray(c.alias).some((alias) => alias.toLowerCase() === cmdName));
 }
 function getCommand(path, subCommands) {
 	if (!path.length) throw new Error("Command path is required.");
@@ -551,41 +660,7 @@ function getCommand(path, subCommands) {
 }
 
 //#endregion
-//#region src/global-options.ts
-const HELP_OPTION = {
-	name: "help",
-	alias: "h",
-	description: "Show help text",
-	type: OptType.BOOL,
-	valueNotRequired: true,
-	valueIfSet: true
-};
-const COLOR_OPTION = {
-	name: "color",
-	description: "Control ANSI color output.",
-	type: OptType.ENUM,
-	enumValues: [
-		"always",
-		"never",
-		"auto"
-	],
-	valuePlaceholder: "WHEN",
-	valueNotRequired: true,
-	valueIfSet: "always",
-	noPrefix: true,
-	valueIfNoPrefix: "never",
-	defaultValue: "auto"
-};
-function getGlobalOptions(app) {
-	return sortOptions([
-		HELP_OPTION,
-		COLOR_OPTION,
-		...app._globalOptions ?? []
-	]);
-}
-
-//#endregion
-//#region src/app-help.ts
+//#region src/print-command-help.ts
 function shouldWrapHelpEntry$1(label, description, labelWidth) {
 	if (!description) return false;
 	const terminalWidth = getTerminalWidth();
@@ -617,71 +692,6 @@ function printOptionEntries$1(entries) {
 		if (printHelpEntry$1(label, description, width, forceWrap) && index < entries.length - 1) printLn();
 	});
 }
-function printHelp(context, commands) {
-	const app = context.app;
-	const chalk = context.chalk;
-	print(chalk.green(app.name));
-	const { _author: author, _version: version } = app;
-	if (version) print(` ver. ${chalk.yellow(version)}`);
-	if (author) print(` by ${chalk.cyan(author)}`);
-	printLn();
-	if (app.description) {
-		printLn();
-		printLn(app.description);
-	}
-	printLn();
-	printLn(chalk.yellow("Usage:"));
-	print(`  ${chalk.cyan(getProcName(app))}`);
-	if (hasSubCommands(app)) print(` ${chalk.gray("[")}--GLOBAL-OPTIONS${chalk.gray("]")} ${chalk.gray("<")}COMMAND${chalk.gray(">")}`);
-	printLn("\n");
-	if (commands.length) printAvailableCommands(commands, "Commands:", chalk);
-	const globalOptions = getGlobalOptions(app);
-	if (globalOptions.length) {
-		printLn();
-		printLn(chalk.yellow("Global Options:"));
-		printOptionEntries$1(globalOptions.map((option) => formatOption(option, chalk)));
-	}
-}
-function printAvailableCommands(commands, title, chalk) {
-	if (!commands.length) return;
-	printLn(chalk.yellow(title));
-	const width = Math.max(...commands.map((c) => stringWidth(c.name))) + 2;
-	for (const cmd of commands) printHelpEntry$1(chalk.green(cmd.name), cmd.description, width);
-}
-
-//#endregion
-//#region src/print-command-help.ts
-function shouldWrapHelpEntry(label, description, labelWidth) {
-	if (!description) return false;
-	const terminalWidth = getTerminalWidth();
-	const inlineIndent = labelWidth + 4;
-	const inlineDescriptionLines = wrapText(description, Math.max(terminalWidth - inlineIndent, 1));
-	return description.includes("\n") || inlineDescriptionLines.length > 1 || labelWidth + 4 + stringWidth(description) > terminalWidth;
-}
-function printHelpEntry(label, description, labelWidth, forceWrap = false) {
-	print(`  ${label}`);
-	if (!description) {
-		printLn();
-		return false;
-	}
-	if (!(forceWrap || shouldWrapHelpEntry(label, description, labelWidth))) {
-		printLn(`${space(labelWidth + 2, label)}${description}`);
-		return false;
-	}
-	printLn();
-	const terminalWidth = getTerminalWidth();
-	const descriptionIndent = " ".repeat(10);
-	const wrappedDescription = wrapText(description, Math.max(terminalWidth - descriptionIndent.length, 1));
-	for (const line of wrappedDescription) printLn(line.length ? `${descriptionIndent}${line}` : "");
-	return true;
-}
-function printOptionEntries(entries) {
-	const width = Math.max(...entries.map((line) => stringWidth(line[0])));
-	const forceWrap = entries.some(([label, description]) => shouldWrapHelpEntry(label, description, width));
-	entries.forEach(([label, description], index) => {
-		if (printHelpEntry(label, description, width, forceWrap) && index < entries.length - 1) printLn();
-	});
-}
 function getCommandLabel(context, path) {
 	const proc = context.chalk.cyan(getProcName(context.app));
 	if (!path.length) return proc;
@@ -737,12 +747,12 @@ function printCommandHelp(context, cmd, path = []) {
 		const allOptions = getOptions(cmd);
 		if (allOptions.length) {
 			printLn(chalk.yellow("\nOptions:"));
-			printOptionEntries(allOptions.map((option) => formatOption(option, chalk)));
+			printOptionEntries$1(allOptions.map((option) => formatOption(option, chalk)));
 		}
 		if (cmd.positonals?.length) {
 			printLn(chalk.yellow("\nArguments:"));
 			const width = Math.max(...cmd.positonals.map((arg) => stringWidth(arg.name)));
-			for (const arg of cmd.positonals) printHelpEntry(chalk.green(arg.name), arg.description, width);
+			for (const arg of cmd.positonals) printHelpEntry$1(chalk.green(arg.name), arg.description, width);
 		}
 	}
 	if (hasSubCommands(cmd)) {
@@ -753,7 +763,7 @@ function printCommandHelp(context, cmd, path = []) {
 	if (globalOptions.length) {
 		printLn();
 		printLn(chalk.yellow("Global Options:"));
-		printOptionEntries(globalOptions.map((option) => formatOption(option, chalk)));
+		printOptionEntries$1(globalOptions.map((option) => formatOption(option, chalk)));
 	}
 	if (cmd.alias) {
 		const aliases = toArray(cmd.alias);
@@ -762,23 +772,176 @@ function printCommandHelp(context, cmd, path = []) {
 }
 
 //#endregion
-//#region src/commands/command-help.ts
-const helpCommand = new Command("help").describe("Displays help for a command").arg("command", {
-	description: "The command path.",
-	repeatable: true
-}).run(async (commandPath, _, context) => {
+//#region src/builtins.ts
+const DEFAULT_HELP_CONFIG = {
+	name: "help",
+	alias: "h"
+};
+const DEFAULT_VERSION_CONFIG = { name: "version" };
+const DEFAULT_COLOR_CONFIG = { name: "color" };
+function resolveBuiltinConfig(defaults, config) {
+	return {
+		...defaults,
+		...config ?? {}
+	};
+}
+function getHelpConfig(app) {
+	return resolveBuiltinConfig(DEFAULT_HELP_CONFIG, app._helpConfig);
+}
+function getVersionConfig(app) {
+	return resolveBuiltinConfig(DEFAULT_VERSION_CONFIG, app._versionConfig);
+}
+function getColorConfig(app) {
+	return {
+		...DEFAULT_COLOR_CONFIG,
+		...app._colorConfig ?? {}
+	};
+}
+function createBuiltinOption(key, config, description) {
+	if (config.disableOption) return;
+	return {
+		name: config.name,
+		...config.alias !== void 0 ? { alias: config.alias } : {},
+		description,
+		key,
+		type: OptType.BOOL,
+		valueNotRequired: true,
+		valueIfSet: true
+	};
+}
+function createHelpCommand(app) {
+	const config = getHelpConfig(app);
+	if (config.disableCommand) return;
+	const command = new Command(config.name).describe("Displays help for a command").arg("command", {
+		description: "The command path.",
+		repeatable: true
+	}).run(async ({ command: commandPath = [] }, context) => {
+		const rootCommands = getRootCommands(context.app);
+		if (commandPath.length) {
+			const { command: command$1, path } = getCommand(commandPath, rootCommands);
+			printCommandHelp(context, command$1, path);
+		} else if (hasSubCommands(context.app)) printHelp(context, rootCommands);
+		else printCommandHelp(context, context.app, []);
+		return 0;
+	});
+	const aliases = toArray(config.alias);
+	if (aliases.length) command.aliases(...aliases);
+	return command;
+}
+function createVersionCommand(app) {
+	const config = getVersionConfig(app);
+	if (config.disableCommand) return;
+	const command = new Command(config.name).describe("Displays current version").run(async (_, context) => {
+		printLn(context.app._version);
+		return 0;
+	});
+	const aliases = toArray(config.alias);
+	if (aliases.length) command.aliases(...aliases);
+	return command;
+}
+function getHelpOption(app) {
+	return createBuiltinOption("help", getHelpConfig(app), "Show help text");
+}
+function getVersionOption(app) {
+	return createBuiltinOption("version", getVersionConfig(app), "Show current version");
+}
+function getColorOption(app) {
+	const config = getColorConfig(app);
+	if (config.disableOption) return;
+	return {
+		name: config.name,
+		...config.alias !== void 0 ? { alias: config.alias } : {},
+		description: "Control ANSI color output.",
+		key: "color",
+		type: OptType.ENUM,
+		enumValues: [
+			"always",
+			"never",
+			"auto"
+		],
+		valuePlaceholder: "WHEN",
+		valueNotRequired: true,
+		valueIfSet: "always",
+		noPrefix: true,
+		valueIfNoPrefix: "never",
+		defaultValue: "auto"
+	};
+}
+function getGlobalOptions(app) {
+	return sortOptions([...[
+		getHelpOption(app),
+		getVersionOption(app),
+		getColorOption(app)
+	].filter((value) => value !== void 0), ...app._globalOptions ?? []]);
+}
+function getRootCommands(app) {
+	return [...app.subCommands !== void 0 ? sortBy(app.subCommands, (c) => c.name) : [], ...[createVersionCommand(app), createHelpCommand(app)].filter((value) => value !== void 0)];
+}
+
+//#endregion
+//#region src/app-help.ts
+function shouldWrapHelpEntry(label, description, labelWidth) {
+	if (!description) return false;
+	const terminalWidth = getTerminalWidth();
+	const inlineIndent = labelWidth + 4;
+	const inlineDescriptionLines = wrapText(description, Math.max(terminalWidth - inlineIndent, 1));
+	return description.includes("\n") || inlineDescriptionLines.length > 1 || labelWidth + 4 + stringWidth(description) > terminalWidth;
+}
+function printHelpEntry(label, description, labelWidth, forceWrap = false) {
+	print(`  ${label}`);
+	if (!description) {
+		printLn();
+		return false;
+	}
+	if (!(forceWrap || shouldWrapHelpEntry(label, description, labelWidth))) {
+		printLn(`${space(labelWidth + 2, label)}${description}`);
+		return false;
+	}
+	printLn();
+	const terminalWidth = getTerminalWidth();
+	const descriptionIndent = " ".repeat(10);
+	const wrappedDescription = wrapText(description, Math.max(terminalWidth - descriptionIndent.length, 1));
+	for (const line of wrappedDescription) printLn(line.length ? `${descriptionIndent}${line}` : "");
+	return true;
+}
+function printOptionEntries(entries) {
+	const width = Math.max(...entries.map((line) => stringWidth(line[0])));
+	const forceWrap = entries.some(([label, description]) => shouldWrapHelpEntry(label, description, width));
+	entries.forEach(([label, description], index) => {
+		if (printHelpEntry(label, description, width, forceWrap) && index < entries.length - 1) printLn();
+	});
+}
+function printHelp(context, commands) {
 	const app = context.app;
-	const rootCommands = [
-		...app.subCommands !== void 0 ? sortBy(app.subCommands, (c) => c.name) : [],
-		versionCommand,
-		helpCommand
-	];
-	if (commandPath.length) {
-		const { command, path } = getCommand(commandPath, rootCommands);
-		printCommandHelp(context, command, path);
-	} else if (app.subCommands !== void 0) printHelp(context, rootCommands);
-	else printCommandHelp(context, app, []);
-});
+	const chalk = context.chalk;
+	print(chalk.green(app.name));
+	const { _author: author, _version: version } = app;
+	if (version) print(` ver. ${chalk.yellow(version)}`);
+	if (author) print(` by ${chalk.cyan(author)}`);
+	printLn();
+	if (app.description) {
+		printLn();
+		printLn(app.description);
+	}
+	printLn();
+	printLn(chalk.yellow("Usage:"));
+	print(`  ${chalk.cyan(getProcName(app))}`);
+	if (hasSubCommands(app)) print(` ${chalk.gray("[")}--GLOBAL-OPTIONS${chalk.gray("]")} ${chalk.gray("<")}COMMAND${chalk.gray(">")}`);
+	printLn("\n");
+	if (commands.length) printAvailableCommands(commands, "Commands:", chalk);
+	const globalOptions = getGlobalOptions(app);
+	if (globalOptions.length) {
+		printLn();
+		printLn(chalk.yellow("Global Options:"));
+		printOptionEntries(globalOptions.map((option) => formatOption(option, chalk)));
+	}
+}
+function printAvailableCommands(commands, title, chalk) {
+	if (!commands.length) return;
+	printLn(chalk.yellow(title));
+	const width = Math.max(...commands.map((c) => stringWidth(c.name))) + 2;
+	for (const cmd of commands) printHelpEntry(chalk.green(cmd.name), cmd.description, width);
+}
 
 //#endregion
 //#region src/run.ts
@@ -818,29 +981,6 @@ function mergeCommandOptions(app, cmd) {
 		options: [...getGlobalOptions(app), ...normalized.options ?? []]
 	};
 }
-function isVersionFlag(arg) {
-	return arg === "--version";
-}
-function getHelpValidationCommand(cmd) {
-	return {
-		...cmd,
-		options: cmd.options?.map((opt) => ({
-			...opt,
-			required: false
-		})),
-		positonals: cmd.positonals?.map((arg) => ({
-			...arg,
-			required: false
-		}))
-	};
-}
-function getRootCommands(app) {
-	return [
-		...app.subCommands !== void 0 ? sortBy(app.subCommands, (c) => c.name) : [],
-		versionCommand,
-		helpCommand
-	];
-}
 function createExecutionContext(app, opts, path = []) {
 	return new ExecutionContext(app, opts?.color ?? "auto", path);
 }
@@ -856,17 +996,58 @@ function createGlobalParseCommand(app) {
 		execute() {}
 	};
 }
+function getRequestedColorMode(app, argv) {
+	const colorOption = getColorOption(app);
+	if (colorOption === void 0) return "auto";
+	let mode = "auto";
+	const shortNames = /* @__PURE__ */ new Set();
+	const longNames = new Set([colorOption.name, ...Array.isArray(colorOption.alias) ? colorOption.alias : colorOption.alias !== void 0 ? [colorOption.alias] : []]);
+	if (colorOption.name.length === 1) shortNames.add(colorOption.name);
+	for (const alias of longNames) if (alias.length === 1) shortNames.add(alias);
+	for (const token of argv) {
+		if (token === `--no-${colorOption.name}`) {
+			mode = "never";
+			continue;
+		}
+		if (token.startsWith("--")) {
+			const body = token.slice(2);
+			const equalIndex = body.indexOf("=");
+			const name = equalIndex === -1 ? body : body.slice(0, equalIndex);
+			if (!longNames.has(name)) continue;
+			if (equalIndex === -1) {
+				mode = "always";
+				continue;
+			}
+			const value = body.slice(equalIndex + 1);
+			if (value === "always" || value === "never" || value === "auto") mode = value;
+			else mode = "never";
+			continue;
+		}
+		if (token.startsWith("-") && !token.startsWith("--")) {
+			const clusterText = token.slice(1);
+			if ([...clusterText.includes("=") ? clusterText.slice(0, clusterText.indexOf("=")) : clusterText].some((ch) => shortNames.has(ch))) mode = "always";
+		}
+	}
+	return mode;
+}
 function parseGlobalOptions(app, argv) {
+	const colorMode = getRequestedColorMode(app, argv);
 	try {
-		const [, opts] = parseArgs(getHelpValidationCommand(createGlobalParseCommand(app)), argv);
+		const [, opts] = parseArgs(createGlobalParseCommand(app), extractGlobalOptionArgv(argv, getGlobalOptions(app)), createChalk(colorMode), {
+			skipRequiredOptions: true,
+			skipRequiredPositionals: true
+		});
 		return { opts };
 	} catch (err) {
 		if (err instanceof UnknownOptionError) return {};
 		const error = createError(err instanceof Error ? err.message : String(err), ErrorCategory.InvalidArg);
-		return { result: {
-			code: getErrorExitCode(error),
-			error
-		} };
+		return {
+			opts: { color: colorMode },
+			result: {
+				code: getErrorExitCode(error),
+				error
+			}
+		};
 	}
 }
 function getOptionTokenConsumption(argv, index, rawOptions) {
@@ -895,6 +1076,19 @@ function getOptionTokenConsumption(argv, index, rawOptions) {
 	}
 	return 1;
 }
+function extractGlobalOptionArgv(argv, globalOptions) {
+	const extracted = [];
+	for (let index = 0; index < argv.length;) {
+		const consumed = getOptionTokenConsumption(argv, index, globalOptions);
+		if (consumed > 0) {
+			extracted.push(...argv.slice(index, index + consumed));
+			index += consumed;
+			continue;
+		}
+		index += 1;
+	}
+	return extracted;
+}
 function resolveCommandWithGlobalOptions(argv, subCommands, globalOptions) {
 	const path = [];
 	const commandIndexes = /* @__PURE__ */ new Set();
@@ -933,13 +1127,27 @@ function getFirstNonGlobalToken(argv, globalOptions) {
 		return argv[index];
 	}
 }
-function unknownCommandResult(app, commandName) {
-	const error = createError(`${getProcName(app)}: unknown command '${commandName}'`, ErrorCategory.InvalidArg);
+function unknownCommandResult(app, commandName, chalk) {
+	const error = createError(`${getProcName(app)}: unknown command ${formatToken(commandName, chalk)}`, ErrorCategory.InvalidArg);
+	return {
+		code: getErrorExitCode(error),
+		error
+	};
+}
+function isOptionLikeToken(token) {
+	return token.length >= 2 && token.startsWith("-");
+}
+function unknownOptionResult(app, optionToken, chalk) {
+	const error = createError(`${getProcName(app)}: ${new UnknownOptionError(optionToken, formatToken(optionToken, chalk)).message}`, ErrorCategory.InvalidArg);
 	return {
 		code: getErrorExitCode(error),
 		error
 	};
 }
+function unknownTokenResult(app, token, chalk) {
+	if (isOptionLikeToken(token)) return unknownOptionResult(app, token, chalk);
+	return unknownCommandResult(app, token, chalk);
+}
 async function executeLeaf(app, cmd, rawArgs, path) {
 	try {
 		validateCommandConfig(mergeCommandOptions(app, cmd));
@@ -953,11 +1161,19 @@ async function executeLeaf(app, cmd, rawArgs, path) {
 			context: createExecutionContext(app, void 0, path)
 		};
 	}
-	let args;
 	let opts;
+	const globalParse = parseGlobalOptions(app, rawArgs);
+	if (globalParse.result !== void 0) return {
+		result: globalParse.result,
+		context: createExecutionContext(app, globalParse.opts, path)
+	};
+	const parseChalk = createChalk(globalParse.opts?.color ?? "auto");
 	try {
 		const parseableCommand = mergeCommandOptions(app, cmd);
-		const [, provisionalOpts] = parseArgs(getHelpValidationCommand(parseableCommand), rawArgs);
+		const [, provisionalOpts] = parseArgs(parseableCommand, rawArgs, parseChalk, {
+			skipRequiredOptions: true,
+			skipRequiredPositionals: true
+		});
 		const provisionalContext = createExecutionContext(app, provisionalOpts, path);
 		if (provisionalOpts.help) {
 			if (cmd === app && !hasSubCommands(app)) {
@@ -973,7 +1189,14 @@ async function executeLeaf(app, cmd, rawArgs, path) {
 				context: provisionalContext
 			};
 		}
-		[args, opts] = parseArgs(parseableCommand, rawArgs);
+		if (provisionalOpts.version) {
+			printLn(app._version);
+			return {
+				result: { code: 0 },
+				context: provisionalContext
+			};
+		}
+		[, opts] = parseArgs(parseableCommand, rawArgs, parseChalk);
 	} catch (err) {
 		if (err instanceof UnknownOptionError) {
 			const error$1 = createError(`${getProcName(app)}: ${err.message}`, ErrorCategory.InvalidArg);
@@ -982,7 +1205,7 @@ async function executeLeaf(app, cmd, rawArgs, path) {
 					code: getErrorExitCode(error$1),
 					error: error$1
 				},
-				context: createExecutionContext(app, void 0, path)
+				context: createExecutionContext(app, globalParse.opts, path)
 			};
 		}
 		const error = createError(err instanceof Error ? err.message : String(err), ErrorCategory.InvalidArg);
@@ -991,7 +1214,7 @@ async function executeLeaf(app, cmd, rawArgs, path) {
 				code: getErrorExitCode(error),
 				error
 			},
-			context: createExecutionContext(app, void 0, path)
+			context: createExecutionContext(app, globalParse.opts, path)
 		};
 	}
 	const handler = getExecuteHandler(cmd);
@@ -1007,7 +1230,7 @@ async function executeLeaf(app, cmd, rawArgs, path) {
 	}
 	try {
 		const context = createExecutionContext(app, opts, path);
-		const code = await Promise.resolve(handler(opts, args, context));
+		const code = await Promise.resolve(handler(opts, context));
 		if (code === void 0) return {
 			result: { code: null },
 			context
@@ -1040,18 +1263,18 @@ async function executeAppDetailed(app, argv = process.argv.slice(2)) {
 		};
 	}
 	if (isExecutable(app) && !hasSubCommands(app)) {
-		if (isVersionFlag(argv[0])) {
+		const globalParse = parseGlobalOptions(app, argv);
+		if (globalParse.result !== void 0) return {
+			result: globalParse.result,
+			context: createExecutionContext(app, globalParse.opts)
+		};
+		if (globalParse.opts?.version) {
 			printLn(app._version);
 			return {
 				result: { code: 0 },
-				context: rootContext
+				context: createExecutionContext(app, globalParse.opts)
 			};
 		}
-		const globalParse = parseGlobalOptions(app, argv);
-		if (globalParse.result !== void 0) return {
-			result: globalParse.result,
-			context: rootContext
-		};
 		if (globalParse.opts?.help) return executeLeaf(app, normalizeAppAsLeafCommand(app), argv, []);
 		const builtin = findSubCommand(argv[0], rootCommands);
 		if (builtin && isExecutable(builtin)) return executeLeaf(app, builtin, argv.slice(1), [builtin.name]);
@@ -1062,10 +1285,17 @@ async function executeAppDetailed(app, argv = process.argv.slice(2)) {
 		const globalParse = parseGlobalOptions(app, argv);
 		if (globalParse.result !== void 0) return {
 			result: globalParse.result,
-			context: rootContext
+			context: createExecutionContext(app, globalParse.opts)
 		};
 		const globalOpts = globalParse.opts ?? {};
 		const context = createExecutionContext(app, globalOpts);
+		if (globalOpts.version) {
+			printLn(app._version);
+			return {
+				result: { code: 0 },
+				context
+			};
+		}
 		const firstNonGlobalToken = getFirstNonGlobalToken(argv, globalOptions);
 		if (firstNonGlobalToken === void 0) {
 			if (globalOpts.help || !hasSubCommands(app)) {
@@ -1083,7 +1313,7 @@ async function executeAppDetailed(app, argv = process.argv.slice(2)) {
 			};
 		}
 		return {
-			result: unknownCommandResult(app, firstNonGlobalToken),
+			result: unknownTokenResult(app, firstNonGlobalToken, context.chalk),
 			context
 		};
 	}
@@ -1091,10 +1321,17 @@ async function executeAppDetailed(app, argv = process.argv.slice(2)) {
 		const globalParse = parseGlobalOptions(app, resolved.remainingArgv);
 		if (globalParse.result !== void 0) return {
 			result: globalParse.result,
-			context: rootContext
+			context: createExecutionContext(app, globalParse.opts, resolved.path)
 		};
 		const branchOpts = globalParse.opts ?? {};
 		const context = createExecutionContext(app, branchOpts, resolved.path);
+		if (branchOpts.version) {
+			printLn(app._version);
+			return {
+				result: { code: 0 },
+				context
+			};
+		}
 		const firstNonGlobalToken = getFirstNonGlobalToken(resolved.remainingArgv, globalOptions);
 		if (!resolved.remainingArgv.length || branchOpts.help && firstNonGlobalToken === void 0) {
 			printCommandHelp(context, resolved.command, resolved.path);
@@ -1104,7 +1341,7 @@ async function executeAppDetailed(app, argv = process.argv.slice(2)) {
 			};
 		}
 		return {
-			result: unknownCommandResult(app, firstNonGlobalToken ?? resolved.remainingArgv[0]),
+			result: unknownTokenResult(app, firstNonGlobalToken ?? resolved.remainingArgv[0], context.chalk),
 			context
 		};
 	}