cli-api 0.1.2 → 0.2.0

package/dist/run-C903J5ca.mjs

@@ -0,0 +1,1137 @@
+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 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);
+}
+/**
+* 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 = str.split("\n");
+	const width = Math.max(...lines.map((l) => stringWidth(l))) + 4;
+	const colorize = chalk.bgHex(ERROR_PRESENTATION[style].color).hex("#FEFBEC");
+	printLn(colorize(space(width)));
+	for (const line of lines) {
+		const txt = `  ${line}`;
+		printLn(colorize(txt + space(width, txt)));
+	}
+	printLn(colorize(space(width)));
+}
+/**
+* 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) {
+	blockError(error.message, error.type, chalk);
+}
+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.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/commands/version.ts
+const versionCommand = new Command("version").describe("Displays current version").run(async (_, __, context) => {
+	printLn(context.app._version);
+});
+
+//#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) {
+		super(`option ${option} 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 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) throw new Error("Only the last argument can be repeatable");
+		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;
+	}
+}
+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 parseArgs(cmd, argv) {
+	const args = [];
+	const opts = Object.create(null);
+	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;
+		}
+	};
+	let argIdx = 0;
+	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}`);
+				const { opt, negated } = match;
+				if (negated && inlineValue !== void 0) throw new Error(`Option \`--no-${opt.name}\` 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));
+				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}`);
+				}
+				let j = 0;
+				while (j < cluster.length) {
+					const ch = cluster[j];
+					const match = findOpt(ch);
+					if (!match) throw new UnknownOptionError(`-${ch}`);
+					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 \`-${ch}\``);
+					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));
+					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;
+		}
+	}
+	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`);
+		}
+	}
+	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 (k && opts[k] === void 0 && a.defaultValue !== void 0) opts[k] = resolve(a.defaultValue);
+	}
+	return [args, opts];
+}
+function coerceType(value, type, 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(", ")})`);
+		}
+		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.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 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`);
+			try {
+				FileSys.accessSync(file, FileSys.constants.R_OK);
+			} catch (err) {
+				throw new Error(`${createChalk().underline(fullPath)} is not readable`);
+			}
+			return file;
+		}
+		case OptType.INPUT_DIRECTORY: {
+			const dir = Path.normalize(value);
+			FileSys.accessSync(dir, FileSys.constants.X_OK);
+			return dir;
+		}
+		case OptType.OUTPUT_FILE: {
+			if (value === "-") return "/dev/stdout";
+			const file = Path.normalize(value);
+			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);
+			return file;
+		}
+		case OptType.OUTPUT_DIRECTORY:
+			FileSys.accessSync(value, FileSys.constants.W_OK);
+			return Path.normalize(value);
+		case OptType.EMPTY_DIRECTORY: {
+			const dir = Path.normalize(value);
+			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 (files.length) throw new Error(`${createChalk().underline(dir)} is not empty`);
+			return dir;
+		}
+	}
+	return value;
+}
+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));
+}
+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/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
+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 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;
+	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(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);
+		}
+	}
+	if (hasSubCommands(cmd)) {
+		printLn();
+		printAvailableCommands(cmd.subCommands, "Sub-commands:", chalk);
+	}
+	const globalOptions = getGlobalOptions(app);
+	if (globalOptions.length) {
+		printLn();
+		printLn(chalk.yellow("Global Options:"));
+		printOptionEntries(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/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) => {
+	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, []);
+});
+
+//#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 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);
+}
+function createGlobalParseCommand(app) {
+	return {
+		name: app.name,
+		options: getGlobalOptions(app),
+		positonals: [{
+			name: "argv",
+			key: "argv",
+			repeatable: true
+		}],
+		execute() {}
+	};
+}
+function parseGlobalOptions(app, argv) {
+	try {
+		const [, opts] = parseArgs(getHelpValidationCommand(createGlobalParseCommand(app)), argv);
+		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
+		} };
+	}
+}
+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 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) {
+	const error = createError(`${getProcName(app)}: unknown command '${commandName}'`, ErrorCategory.InvalidArg);
+	return {
+		code: getErrorExitCode(error),
+		error
+	};
+}
+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 args;
+	let opts;
+	try {
+		const parseableCommand = mergeCommandOptions(app, cmd);
+		const [, provisionalOpts] = parseArgs(getHelpValidationCommand(parseableCommand), rawArgs);
+		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
+			};
+		}
+		[args, opts] = parseArgs(parseableCommand, rawArgs);
+	} 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, void 0, path)
+			};
+		}
+		const error = createError(err instanceof Error ? err.message : String(err), ErrorCategory.InvalidArg);
+		return {
+			result: {
+				code: getErrorExitCode(error),
+				error
+			},
+			context: createExecutionContext(app, void 0, 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, args, 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)) {
+		if (isVersionFlag(argv[0])) {
+			printLn(app._version);
+			return {
+				result: { code: 0 },
+				context: rootContext
+			};
+		}
+		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]);
+		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: rootContext
+		};
+		const globalOpts = globalParse.opts ?? {};
+		const context = createExecutionContext(app, globalOpts);
+		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: unknownCommandResult(app, firstNonGlobalToken),
+			context
+		};
+	}
+	if (hasSubCommands(resolved.command)) {
+		const globalParse = parseGlobalOptions(app, resolved.remainingArgv);
+		if (globalParse.result !== void 0) return {
+			result: globalParse.result,
+			context: rootContext
+		};
+		const branchOpts = globalParse.opts ?? {};
+		const context = createExecutionContext(app, branchOpts, resolved.path);
+		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: unknownCommandResult(app, firstNonGlobalToken ?? resolved.remainingArgv[0]),
+			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 };