cli-api 0.1.2 → 0.2.1

package/dist/run-DEkBUX4b.mjs

@@ -0,0 +1,1374 @@
+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";
+
+//#region src/constants.ts
+const EMPTY_ARRAY = Object.freeze([]);
+const EMPTY_OBJECT = Object.freeze(Object.create({ __proto__: null }));
+const TRUE_VALUES = new Set([
+	"y",
+	"yes",
+	"t",
+	"true",
+	"1",
+	"on"
+]);
+const FALSE_VALUES = new Set([
+	"n",
+	"no",
+	"f",
+	"false",
+	"0",
+	"off"
+]);
+
+//#endregion
+//#region src/utils.ts
+function print(str = "") {
+	return process.stdout.write(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.
+*/
+let ErrorCategory = /* @__PURE__ */ function(ErrorCategory$1) {
+	ErrorCategory$1["InvalidArg"] = "invalid-arg";
+	ErrorCategory$1["Misconfig"] = "misconfig";
+	ErrorCategory$1["Internal"] = "internal";
+	return ErrorCategory$1;
+}({});
+const ERROR_PRESENTATION = {
+	[ErrorCategory.InvalidArg]: {
+		code: 2,
+		color: "#D73737"
+	},
+	[ErrorCategory.Misconfig]: {
+		code: 254,
+		color: "#B854D4"
+	},
+	[ErrorCategory.Internal]: {
+		code: 253,
+		color: "#6684E1"
+	}
+};
+function blockError(str, style, chalk) {
+	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");
+	printErrLn(colorize(space(width)));
+	for (const line of lines) {
+		const txt = `  ${line}`;
+		printErrLn(colorize(txt + space(width, txt)));
+	}
+	printErrLn(colorize(space(width)));
+}
+function inlineError(str) {
+	printErrLn(str);
+}
+/**
+* Creates a structured CLI error.
+*
+* @param message The error text that should be rendered.
+* @param type The semantic error category used to determine presentation and exit code.
+* @returns A structured CLI error object.
+*/
+function createError(message, type) {
+	return {
+		message,
+		type
+	};
+}
+/**
+* Gets the process exit code associated with a given CLI error.
+*
+* @param error The structured CLI error to map to a process exit code.
+* @returns The default exit code used for that error type.
+*/
+function getErrorExitCode(error) {
+	return ERROR_PRESENTATION[error.type].code;
+}
+/**
+* Prints a user-facing CLI error block.
+*
+* @param error The structured CLI error to render.
+* @returns Nothing.
+*/
+function printError(error, chalk) {
+	if (chalk.level > 0) {
+		blockError(error.message, error.type, chalk);
+		return;
+	}
+	inlineError(error.message);
+}
+function toArray(x) {
+	if (!x) return EMPTY_ARRAY;
+	if (Array.isArray(x)) return x;
+	return [x];
+}
+function resolve(x) {
+	return typeof x === "function" ? x() : x;
+}
+function toBool(str) {
+	if (typeof str === "boolean") return str;
+	str = String(str).trim().toLowerCase();
+	if (TRUE_VALUES.has(str)) return true;
+	if (FALSE_VALUES.has(str)) return false;
+	throw new Error(`Could not cast "${str}" to boolean`);
+}
+function space(len, str) {
+	if (str) len -= stringWidth(str);
+	return len > 0 ? " ".repeat(len) : "";
+}
+function getTerminalWidth() {
+	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");
+	const wrappedLines = [];
+	for (const rawLine of text.split("\n")) {
+		if (rawLine.trim().length === 0) {
+			wrappedLines.push("");
+			continue;
+		}
+		const words = rawLine.trim().split(/\s+/);
+		let currentLine = "";
+		for (const word of words) {
+			const candidate = currentLine.length === 0 ? word : `${currentLine} ${word}`;
+			if (currentLine.length > 0 && stringWidth(candidate) > width) {
+				wrappedLines.push(currentLine);
+				currentLine = word;
+			} else currentLine = candidate;
+		}
+		if (currentLine.length > 0) wrappedLines.push(currentLine);
+	}
+	return wrappedLines;
+}
+function getProcName(app) {
+	const bin = app._bin;
+	if (bin != null) return bin;
+	const relPath = Path.relative(process.cwd(), process.argv[1]);
+	return `${Path.basename(process.argv[0])} ${relPath.length < process.argv[1].length ? relPath : process.argv[1]}`;
+}
+function includes(needle, haystack) {
+	if (!haystack) return false;
+	if (Array.isArray(haystack)) return haystack.includes(needle);
+	return needle === haystack;
+}
+function statSync(path) {
+	try {
+		return FileSys.lstatSync(path);
+	} catch {
+		return null;
+	}
+}
+function sortBy(arr, cmp) {
+	const collator = new Intl.Collator();
+	const values = arr.map(cmp);
+	const keys = Array.from(arr.keys());
+	keys.sort((a, b) => collator.compare(values[a], values[b]));
+	return keys.map((i) => arr[i]);
+}
+
+//#endregion
+//#region src/options.ts
+/**
+* Error thrown when argument parsing encounters an unknown option name.
+*
+* @param option The unrecognized option token, including its leading dashes.
+* @returns A parser error whose message matches the CLI's unknown-option wording.
+*/
+var UnknownOptionError = class extends Error {
+	option;
+	constructor(option, formattedOption = option) {
+		super(`option ${formattedOption} not recognized`);
+		this.option = option;
+	}
+};
+function getEnumValues(item) {
+	if (Array.isArray(item.type)) return item.type;
+	if (item.type === OptType.ENUM) return item.enumValues;
+}
+function getOptionImplicitValue(opt) {
+	if (opt.valueIfSet !== void 0) return resolve(opt.valueIfSet);
+	if (opt.type === OptType.BOOL) return true;
+	return !resolve(opt.defaultValue);
+}
+function getOptionNoPrefixValue(opt) {
+	if (opt.valueIfNoPrefix !== void 0) return resolve(opt.valueIfNoPrefix);
+	if (opt.type === OptType.BOOL) return false;
+	throw new Error(`\`${getOptName(opt)}\` option must define valueIfNoPrefix when noPrefix is enabled`);
+}
+function isRepeatable(value) {
+	return value === true || typeof value === "number";
+}
+function getMaxRepeatCount(value) {
+	if (value === true || value === false || value === void 0) return;
+	return value;
+}
+function getMinRequiredCount(value) {
+	if (value === true) return 1;
+	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`);
+}
+function validatePositionalDefinitions(cmd) {
+	if (!cmd.positonals?.length) return;
+	let encounteredOptionalPositional = false;
+	for (let i = 0; i < cmd.positonals.length; ++i) {
+		const arg = cmd.positonals[i];
+		const repeatable = isRepeatable(arg.repeatable);
+		const minRequired = getMinRequiredCount(arg.required);
+		const maxRepeatCount = getMaxRepeatCount(arg.repeatable);
+		if (typeof arg.required === "number") {
+			assertValidCount(`"${arg.name}" argument required count`, arg.required, { allowZero: true });
+			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) {
+			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 && !repeatable) encounteredOptionalPositional = true;
+	}
+}
+function pushRepeatableValue(target, value, itemName, maxCount, kind) {
+	if (maxCount !== void 0 && target.length >= maxCount) throw new Error(`"${itemName}" ${kind} allows at most ${maxCount} value${maxCount === 1 ? "" : "s"}`);
+	target.push(value);
+}
+/**
+* Formats an option definition for display in help output.
+*
+* @param opt The option metadata to render.
+* @returns A tuple containing the formatted flag label and its description text.
+*/
+function formatOption(opt, chalk) {
+	const aliases = [];
+	if (opt.alias) if (Array.isArray(opt.alias)) aliases.push(...opt.alias);
+	else aliases.push(opt.alias);
+	let flags = [...aliases.map((a) => chalk.green(a.length === 1 ? `-${a}` : `--${a}`)), chalk.green(`--${opt.name}`)].join(", ");
+	if (!opt.alias && opt.name.length > 1) flags = `    ${flags}`;
+	if (opt.type !== OptType.BOOL) {
+		const valuePlaceholder = chalk.magenta(getValuePlaceholder(opt));
+		flags += opt.valueNotRequired ? `${chalk.grey("[")}=${valuePlaceholder}${chalk.grey("]")}` : `=${valuePlaceholder}`;
+	}
+	if (opt.noPrefix) flags += `, ${chalk.green(`--no-${opt.name}`)}`;
+	let desc = opt.description ?? "";
+	let defaultValueText = opt.defaultValueText;
+	if (defaultValueText === void 0 && opt.defaultValue !== void 0) defaultValueText = JSON.stringify(resolve(opt.defaultValue));
+	if (defaultValueText !== void 0) desc += chalk.yellow(` [default: ${defaultValueText}]`);
+	const enumValues = getEnumValues(opt);
+	if (enumValues?.length) desc += ` [possible values: ${enumValues.join(", ")}]`;
+	return [flags, desc];
+}
+function getValuePlaceholder(opt) {
+	if (opt.valuePlaceholder !== void 0) return opt.valuePlaceholder;
+	const enumValues = getEnumValues(opt);
+	if (enumValues !== void 0) return enumValues.join("|").toUpperCase();
+	else if (opt.type == OptType.BOOL) return JSON.stringify(!resolve(opt.defaultValue));
+	else if (opt.type === OptType.INT || opt.type === OptType.FLOAT) return "#";
+	else if (opt.type === OptType.INPUT_FILE || opt.type === OptType.OUTPUT_FILE) return "FILE";
+	else if (opt.type === OptType.INPUT_DIRECTORY || opt.type === OptType.OUTPUT_DIRECTORY || opt.type === OptType.EMPTY_DIRECTORY) return "DIR";
+	else return opt.name.toUpperCase();
+}
+function sortOptions(options) {
+	return sortBy(options, (option) => option.name);
+}
+function getOptions(cmd) {
+	return sortOptions(toArray(cmd.options));
+}
+/**
+* Validates a command's static option and positional configuration before parsing argv.
+*
+* @param cmd The command definition to validate.
+* @returns Nothing. Throws when the command configuration is internally inconsistent.
+*/
+function validateCommandConfig(cmd) {
+	validatePositionalDefinitions(cmd);
+	const seenOptionTokens = /* @__PURE__ */ new Map();
+	for (const opt of getOptions(cmd)) {
+		if (typeof opt.repeatable === "number") assertValidCount(`\`${opt.name}\` option repeatable count`, opt.repeatable);
+		if (opt.noPrefix && !opt.valueNotRequired) throw new Error(`\`${getOptName(opt)}\` option cannot enable noPrefix unless valueNotRequired is enabled`);
+		if (opt.type === OptType.ENUM && !getEnumValues(opt)?.length) throw new Error(`\`${getOptName(opt)}\` option must define enumValues when using OptType.ENUM`);
+		if (opt.noPrefix && opt.type !== OptType.BOOL && opt.valueIfNoPrefix === void 0) throw new Error(`\`${getOptName(opt)}\` option must define valueIfNoPrefix when noPrefix is enabled`);
+		const tokens = new Set([opt.name]);
+		for (const alias of toArray(opt.alias)) tokens.add(alias);
+		if (opt.noPrefix) tokens.add(`no-${opt.name}`);
+		for (const token of tokens) {
+			const existing = seenOptionTokens.get(token);
+			if (existing !== void 0) {
+				const currentName = token.startsWith("no-") ? `--${token}` : getOptName(opt);
+				throw new Error(`Option token \`${currentName}\` collides with \`${existing}\``);
+			}
+			const displayName = token.startsWith("no-") ? `--${token}` : token.length === 1 ? `-${token}` : `--${token}`;
+			seenOptionTokens.set(token, displayName);
+		}
+	}
+}
+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);
+	for (const opt of allOptions) if (isRepeatable(opt.repeatable)) {
+		const k = opt.key ?? opt.name;
+		if (opts[k] === void 0) opts[k] = [];
+	}
+	if (cmd.positonals?.length) for (let i = 0; i < cmd.positonals.length; ++i) {
+		const a = cmd.positonals[i];
+		if (isRepeatable(a.repeatable)) {
+			const k = a.key ?? a.name;
+			if (k && opts[k] === void 0) opts[k] = [];
+		}
+	}
+	const findOpt = (name) => {
+		const option = allOptions.find((o) => o.name === name || includes(name, o.alias));
+		if (option !== void 0) return {
+			opt: option,
+			negated: false
+		};
+		const negatedOption = allOptions.find((o) => o.noPrefix && `no-${o.name}` === name);
+		if (negatedOption !== void 0) return {
+			opt: negatedOption,
+			negated: true
+		};
+	};
+	const getUnknownShortOption = (cluster) => {
+		for (let j = 0; j < cluster.length; ++j) {
+			const ch = cluster[j];
+			if (!findOpt(ch)) return ch;
+		}
+	};
+	for (let i = 0; i < argv.length; ++i) {
+		let token = argv[i];
+		if (parseFlags && token === "--") {
+			parseFlags = false;
+			continue;
+		}
+		if (parseFlags && token.length >= 2 && token.startsWith("-")) {
+			let inlineValue;
+			if (token.startsWith("--")) {
+				if (token.includes("=")) {
+					const [left, right] = token.split("=", 2);
+					token = left;
+					inlineValue = right;
+				}
+				const name = token.slice(2);
+				const match = findOpt(name);
+				if (!match) throw new UnknownOptionError(`--${name}`, formatToken(`--${name}`, chalk));
+				const { opt, negated } = match;
+				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 ${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;
+			} else {
+				const clusterText = token.slice(1);
+				const equalIndex = clusterText.indexOf("=");
+				const cluster = equalIndex === -1 ? clusterText : clusterText.slice(0, equalIndex);
+				const hasInlineAssignment = equalIndex !== -1;
+				inlineValue = equalIndex === -1 ? void 0 : clusterText.slice(equalIndex + 1);
+				if (hasInlineAssignment) {
+					const unknownOption = getUnknownShortOption(cluster);
+					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}`, formatToken(`-${ch}`, chalk));
+					const { opt } = match;
+					if (opt.valueNotRequired) {
+						const k$1 = opt.key ?? opt.name;
+						const v = getOptionImplicitValue(opt);
+						if (isRepeatable(opt.repeatable)) pushRepeatableValue(opts[k$1], v, opt.name, getMaxRepeatCount(opt.repeatable), "option");
+						else opts[k$1] = v;
+						j += 1;
+						continue;
+					}
+					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 ${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 ${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 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 && !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);
+		const k = a.key ?? a.name;
+		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, 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)) 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: 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 = formatPath(file, chalk);
+			const stat = statSync(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 {
+				throw createPathError("File", fullPath, "is not readable", itemName);
+			}
+			return file;
+		}
+		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 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: 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") {
+					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 createPathError("Directory", fullPath, "is not empty", itemName);
+			return dir;
+		}
+	}
+	return value;
+}
+function getOptName(opt) {
+	return (opt.name.length > 1 ? "--" : "-") + opt.name;
+}
+function findSubCommand(name, subCommands) {
+	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.");
+	let current = subCommands;
+	let command;
+	const resolvedPath = [];
+	for (let i = 0; i < path.length; ++i) {
+		const segment = path[i];
+		const next = findSubCommand(segment, current);
+		if (next === void 0) throw new Error(`Command "${segment}" does not exist.`);
+		command = next;
+		resolvedPath.push(next.name);
+		if (i < path.length - 1) {
+			if (!hasSubCommands(next)) throw new Error(`Command "${resolvedPath.join(" ")}" does not have subCommands.`);
+			current = next.subCommands;
+		}
+	}
+	return {
+		command,
+		path: resolvedPath
+	};
+}
+
+//#endregion
+//#region src/print-command-help.ts
+function shouldWrapHelpEntry$1(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$1(label, description, labelWidth, forceWrap = false) {
+	print(`  ${label}`);
+	if (!description) {
+		printLn();
+		return false;
+	}
+	if (!(forceWrap || shouldWrapHelpEntry$1(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$1(entries) {
+	const width = Math.max(...entries.map((line) => stringWidth(line[0])));
+	const forceWrap = entries.some(([label, description]) => shouldWrapHelpEntry$1(label, description, width));
+	entries.forEach(([label, description], index) => {
+		if (printHelpEntry$1(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;
+	return `${proc} ${path.join(" ")}`;
+}
+function formatUsageOption(opt, chalk) {
+	const optionName = chalk.green(getOptName(opt));
+	if (opt.type === OptType.BOOL) return optionName;
+	const valuePlaceholder = chalk.magenta(getValuePlaceholder(opt));
+	if (opt.valueNotRequired) return `${optionName}${chalk.grey("[")}=${valuePlaceholder}${chalk.grey("]")}`;
+	return `${optionName}=${valuePlaceholder}`;
+}
+function formatUsageArgument(arg, chalk) {
+	const argumentName = chalk.magenta(arg.repeatable ? `${arg.name}...` : arg.name);
+	return `${chalk.grey(arg.required ? "<" : "[")}${argumentName}${chalk.grey(arg.required ? ">" : "]")}`;
+}
+function printCommandHelp(context, cmd, path = []) {
+	const app = context.app;
+	const chalk = context.chalk;
+	if (cmd.description) {
+		printLn(cmd.description);
+		printLn();
+	}
+	if (cmd.longDescription) {
+		printLn(cmd.longDescription);
+		printLn();
+	}
+	if (cmd === app) {
+		const author = app._author;
+		if (author) {
+			printLn(`Author: ${author}`);
+			printLn();
+		}
+	}
+	printLn(chalk.yellow("Usage:"));
+	print(`  ${getCommandLabel(context, path)}`);
+	if (hasSubCommands(cmd)) print(` ${chalk.gray("<")}command${chalk.gray(">")}`);
+	if (isExecutable(cmd)) {
+		const allOptions = getOptions(cmd);
+		if (allOptions.length) {
+			let otherOptions = 0;
+			for (const opt of allOptions) if (opt.required) print(` ${formatUsageOption(opt, chalk)}`);
+			else ++otherOptions;
+			if (otherOptions) print(` ${chalk.gray("[")}${chalk.magenta("--options")}${chalk.gray("]")}`);
+		}
+		if (cmd.positonals?.length) {
+			print(` ${chalk.grey("[")}--${chalk.grey("]")}`);
+			for (const arg of cmd.positonals) print(` ${formatUsageArgument(arg, chalk)}`);
+		}
+	} else if (!hasSubCommands(cmd)) print(` ${chalk.gray("[options] [arguments]")}`);
+	printLn();
+	if (isExecutable(cmd)) {
+		const allOptions = getOptions(cmd);
+		if (allOptions.length) {
+			printLn(chalk.yellow("\nOptions:"));
+			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$1(chalk.green(arg.name), arg.description, width);
+		}
+	}
+	if (hasSubCommands(cmd)) {
+		printLn();
+		printAvailableCommands(cmd.subCommands, "Sub-commands:", chalk);
+	}
+	const globalOptions = getGlobalOptions(app);
+	if (globalOptions.length) {
+		printLn();
+		printLn(chalk.yellow("Global Options:"));
+		printOptionEntries$1(globalOptions.map((option) => formatOption(option, chalk)));
+	}
+	if (cmd.alias) {
+		const aliases = toArray(cmd.alias);
+		printLn(chalk.yellow(`\nAlias${aliases.length !== 1 ? "es" : ""}: `) + aliases.join(chalk.gray(", ")));
+	}
+}
+
+//#endregion
+//#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 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
+function normalizeAppAsLeafCommand(app) {
+	const handler = app.handler;
+	if (handler === void 0) throw new Error("Command is not executable.");
+	return {
+		name: app.name,
+		...app.alias !== void 0 ? { alias: app.alias } : {},
+		...app.description !== void 0 ? { description: app.description } : {},
+		...app.longDescription !== void 0 ? { longDescription: app.longDescription } : {},
+		...app.options !== void 0 ? { options: [...app.options] } : {},
+		...app.positonals !== void 0 ? { positonals: [...app.positonals] } : {},
+		execute: handler
+	};
+}
+function normalizeLeafCommand(cmd) {
+	const handler = getExecuteHandler(cmd);
+	if (handler === void 0) throw new Error("Command is not executable.");
+	return {
+		name: cmd.name,
+		...cmd.alias !== void 0 ? { alias: cmd.alias } : {},
+		...cmd.description !== void 0 ? { description: cmd.description } : {},
+		...cmd.longDescription !== void 0 ? { longDescription: cmd.longDescription } : {},
+		...cmd.options !== void 0 ? { options: [...cmd.options] } : {},
+		...cmd.positonals !== void 0 ? { positonals: [...cmd.positonals] } : {},
+		execute: handler
+	};
+}
+function formatConfigError(error) {
+	return `Config Error: ${error instanceof Error ? error.message : String(error)}`;
+}
+function mergeCommandOptions(app, cmd) {
+	const normalized = normalizeLeafCommand(cmd);
+	return {
+		...normalized,
+		options: [...getGlobalOptions(app), ...normalized.options ?? []]
+	};
+}
+function createExecutionContext(app, opts, path = []) {
+	return new ExecutionContext(app, opts?.color ?? "auto", path);
+}
+function createGlobalParseCommand(app) {
+	return {
+		name: app.name,
+		options: getGlobalOptions(app),
+		positonals: [{
+			name: "argv",
+			key: "argv",
+			repeatable: true
+		}],
+		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(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 {
+			opts: { color: colorMode },
+			result: {
+				code: getErrorExitCode(error),
+				error
+			}
+		};
+	}
+}
+function getOptionTokenConsumption(argv, index, rawOptions) {
+	const token = argv[index];
+	if (token === "--") return argv.length - index;
+	if (!token.startsWith("-") || token === "-") return 0;
+	const options = rawOptions;
+	const matchLong = (name) => options.find((opt) => opt.name === name || opt.noPrefix && `no-${opt.name}` === name || opt.alias !== void 0 && (Array.isArray(opt.alias) ? opt.alias.includes(name) : opt.alias === name));
+	if (token.startsWith("--")) {
+		const [left] = token.split("=", 1);
+		const option = matchLong(left.slice(2));
+		if (option === void 0) return 0;
+		if (left !== token || option.valueNotRequired) return 1;
+		return index < argv.length - 1 ? 2 : 1;
+	}
+	const clusterText = token.slice(1);
+	const equalIndex = clusterText.indexOf("=");
+	const cluster = equalIndex === -1 ? clusterText : clusterText.slice(0, equalIndex);
+	for (let i = 0; i < cluster.length; ++i) {
+		const option = options.find((opt) => opt.name === cluster[i] || (Array.isArray(opt.alias) ? opt.alias.includes(cluster[i]) : opt.alias === cluster[i]));
+		if (option === void 0) return 0;
+		if (!option.valueNotRequired) {
+			if (i < cluster.length - 1 || equalIndex !== -1) return 1;
+			return index < argv.length - 1 ? 2 : 1;
+		}
+	}
+	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();
+	let command;
+	let current = subCommands;
+	let index = 0;
+	while (index < argv.length) {
+		const token = argv[index];
+		const consumed = getOptionTokenConsumption(argv, index, globalOptions);
+		if (consumed > 0) {
+			index += consumed;
+			continue;
+		}
+		const candidate = findSubCommand(token, current);
+		if (candidate === void 0) break;
+		command = candidate;
+		commandIndexes.add(index);
+		path.push(candidate.name);
+		index += 1;
+		if (!hasSubCommands(candidate)) break;
+		current = candidate.subCommands;
+	}
+	return {
+		command,
+		path,
+		remainingArgv: argv.filter((_, argvIndex) => !commandIndexes.has(argvIndex))
+	};
+}
+function getFirstNonGlobalToken(argv, globalOptions) {
+	for (let index = 0; index < argv.length;) {
+		const consumed = getOptionTokenConsumption(argv, index, globalOptions);
+		if (consumed > 0) {
+			index += consumed;
+			continue;
+		}
+		return argv[index];
+	}
+}
+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));
+	} catch (err) {
+		const error = createError(formatConfigError(err), ErrorCategory.Misconfig);
+		return {
+			result: {
+				code: getErrorExitCode(error),
+				error
+			},
+			context: createExecutionContext(app, void 0, path)
+		};
+	}
+	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(parseableCommand, rawArgs, parseChalk, {
+			skipRequiredOptions: true,
+			skipRequiredPositionals: true
+		});
+		const provisionalContext = createExecutionContext(app, provisionalOpts, path);
+		if (provisionalOpts.help) {
+			if (cmd === app && !hasSubCommands(app)) {
+				printHelp(provisionalContext, getRootCommands(app));
+				return {
+					result: { code: 0 },
+					context: provisionalContext
+				};
+			}
+			printCommandHelp(provisionalContext, cmd, path);
+			return {
+				result: { code: 0 },
+				context: provisionalContext
+			};
+		}
+		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);
+			return {
+				result: {
+					code: getErrorExitCode(error$1),
+					error: error$1
+				},
+				context: createExecutionContext(app, globalParse.opts, path)
+			};
+		}
+		const error = createError(err instanceof Error ? err.message : String(err), ErrorCategory.InvalidArg);
+		return {
+			result: {
+				code: getErrorExitCode(error),
+				error
+			},
+			context: createExecutionContext(app, globalParse.opts, path)
+		};
+	}
+	const handler = getExecuteHandler(cmd);
+	if (handler === void 0) {
+		const error = createError("Command is not executable.", ErrorCategory.Internal);
+		return {
+			result: {
+				code: getErrorExitCode(error),
+				error
+			},
+			context: createExecutionContext(app, opts, path)
+		};
+	}
+	try {
+		const context = createExecutionContext(app, opts, path);
+		const code = await Promise.resolve(handler(opts, context));
+		if (code === void 0) return {
+			result: { code: null },
+			context
+		};
+		return {
+			result: { code },
+			context
+		};
+	} catch (err) {
+		const error = createError(String(err?.stack ?? err), ErrorCategory.Internal);
+		return {
+			result: {
+				code: getErrorExitCode(error),
+				error
+			},
+			context: createExecutionContext(app, opts, path)
+		};
+	}
+}
+async function executeAppDetailed(app, argv = process.argv.slice(2)) {
+	const rootCommands = getRootCommands(app);
+	const globalOptions = getGlobalOptions(app);
+	const rootContext = createExecutionContext(app);
+	if (argv.length === 0) {
+		if (isExecutable(app)) return executeLeaf(app, normalizeAppAsLeafCommand(app), [], []);
+		printHelp(rootContext, rootCommands);
+		return {
+			result: { code: 0 },
+			context: rootContext
+		};
+	}
+	if (isExecutable(app) && !hasSubCommands(app)) {
+		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: createExecutionContext(app, globalParse.opts)
+			};
+		}
+		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]);
+		return executeLeaf(app, normalizeAppAsLeafCommand(app), argv, []);
+	}
+	const resolved = resolveCommandWithGlobalOptions(argv, rootCommands, globalOptions);
+	if (!resolved.command) {
+		const globalParse = parseGlobalOptions(app, argv);
+		if (globalParse.result !== void 0) return {
+			result: globalParse.result,
+			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)) {
+				if (isExecutable(app)) return executeLeaf(app, normalizeAppAsLeafCommand(app), argv, []);
+				printHelp(context, rootCommands);
+				return {
+					result: { code: 0 },
+					context
+				};
+			}
+			printHelp(context, rootCommands);
+			return {
+				result: { code: 0 },
+				context
+			};
+		}
+		return {
+			result: unknownTokenResult(app, firstNonGlobalToken, context.chalk),
+			context
+		};
+	}
+	if (hasSubCommands(resolved.command)) {
+		const globalParse = parseGlobalOptions(app, resolved.remainingArgv);
+		if (globalParse.result !== void 0) return {
+			result: globalParse.result,
+			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);
+			return {
+				result: { code: 0 },
+				context
+			};
+		}
+		return {
+			result: unknownTokenResult(app, firstNonGlobalToken ?? resolved.remainingArgv[0], context.chalk),
+			context
+		};
+	}
+	if (!isExecutable(resolved.command)) {
+		const error = createError("Command is not executable.", ErrorCategory.Internal);
+		return {
+			result: {
+				code: getErrorExitCode(error),
+				error
+			},
+			context: createExecutionContext(app, void 0, resolved.path)
+		};
+	}
+	return executeLeaf(app, resolved.command, resolved.remainingArgv, resolved.path);
+}
+/**
+* Parses CLI arguments, prints any resulting error, and executes the matching command.
+*
+* @param app The app to execute.
+* @param argv The raw CLI arguments to parse. Defaults to `process.argv.slice(2)`.
+* @returns The process exit code for the CLI invocation.
+*/
+async function executeApp(app, argv = process.argv.slice(2)) {
+	const { result, context } = await executeAppDetailed(app, argv);
+	if (result.error !== void 0) printError(result.error, context.chalk);
+	return result.code ?? 0;
+}
+
+//#endregion
+export { executeApp };