@clo4/cli 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,1705 @@
+// \0rolldown/runtime.js
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod, mod.exports), cb = null), mod.exports);
+// src/util.ts
+function isArray(o) {
+	return Array.isArray(o);
+}
+/** Convert the value, if any, to an array with 0 or more elements */
+function makeArray(thing) {
+	if (thing === void 0) return [];
+	if (isArray(thing)) return thing.slice();
+	return [thing];
+}
+/**
+* Like {@link makeArray}, but without copying when the input is already an
+* array. Only safe when the caller treats the result as read-only — use it on
+* the hot path to avoid slicing read-only spec metadata.
+*/
+function asArray(thing) {
+	if (thing === void 0) return [];
+	if (isArray(thing)) return thing;
+	return [thing];
+}
+/** Convert the value to an array with at least one element */
+function makeArray1(thing) {
+	if (isArray(thing)) return thing.slice();
+	return [thing];
+}
+/** Set many keys in a Map to the same value */
+function setEach(map, keys, value) {
+	if (isArray(keys)) for (const key of keys) map.set(key, value);
+	else map.set(keys, value);
+}
+function assert(expr, msg = "") {
+	if (!expr) throw new Error(msg);
+}
+/** Print a message to stdout, trimming trailing whitespace. */
+function print(text) {
+	console.log(text.trimEnd());
+}
+/** Print an error message to stderr with the shared `Error:` prefix. */
+function printActionError(message) {
+	console.error("Error:", message);
+}
+// src/analyze.ts
+const $optionArg = (index, start, end, literal, option, separator) => ({
+	kind: "option-arg",
+	index,
+	literal,
+	start,
+	end,
+	option,
+	separator
+});
+const $unknownOption = (index, start, end, literal, validOptions) => ({
+	kind: "unknown-option",
+	index,
+	start,
+	end,
+	literal,
+	validOptions
+});
+const $arg = (index, start, end, literal) => ({
+	kind: "arg",
+	index,
+	start,
+	end,
+	literal
+});
+const $argSeparator = (index, start, end, literal) => ({
+	kind: "arg-separator",
+	index,
+	start,
+	end,
+	literal
+});
+const $subcommand = (index, start, end, literal, subcommand) => {
+	return {
+		kind: "subcommand",
+		index,
+		start,
+		end,
+		literal,
+		subcommand
+	};
+};
+const $option = (index, start, end, literal, option) => {
+	return {
+		kind: "option",
+		index,
+		start,
+		end,
+		literal,
+		option
+	};
+};
+/**
+* Lex the input, output some tokens
+*
+* This generator uses the options and subcommands to categorize the
+* input tokens. It will not track or reject arguments - tokens that
+* don't match an option or subcommand are yielded as arguments.
+*/
+function analyze(input, spec) {
+	const tokens = [];
+	if (input.length === 0) {
+		const localOptions = /* @__PURE__ */ new Map();
+		const localRequiredOptions = /* @__PURE__ */ new Map();
+		const persistentOptions = /* @__PURE__ */ new Map();
+		const persistentRequiredOptions = /* @__PURE__ */ new Map();
+		if (spec.options) for (const option of spec.options) if (option.isPersistent) {
+			setEach(persistentOptions, option.name, option);
+			if (option.isRequired) setEach(persistentRequiredOptions, option.name, option);
+		} else {
+			setEach(localOptions, option.name, option);
+			if (option.isRequired) setEach(localRequiredOptions, option.name, option);
+		}
+		return {
+			finalState: {
+				localOptions,
+				persistentOptions,
+				localRequiredOptions,
+				persistentRequiredOptions
+			},
+			tokens
+		};
+	}
+	let localSubcommands;
+	const localOptions = /* @__PURE__ */ new Map();
+	const persistentOptions = /* @__PURE__ */ new Map();
+	const localRequiredOptions = /* @__PURE__ */ new Map();
+	const persistentRequiredOptions = /* @__PURE__ */ new Map();
+	let separators = ["="];
+	let hasFoundArg = false;
+	let posixCompliantOptions = true;
+	let subcommandsMatchUniquePrefix = false;
+	let optionsMustPrecedeArguments = false;
+	let hasUsedNonPersistentOption = false;
+	const getOption = (name) => localOptions.get(name) ?? persistentOptions.get(name) ?? null;
+	const hasOption = (name) => localOptions.has(name) || persistentOptions.has(name);
+	const getSubcommand = (name) => {
+		if (!localSubcommands) return null;
+		let prefixMatch = null;
+		let prefixCount = 0;
+		for (const command of localSubcommands) {
+			const names = typeof command.name === "string" ? [command.name] : command.name;
+			for (const cmdName of names) {
+				if (cmdName === name) return command;
+				if (subcommandsMatchUniquePrefix && cmdName.startsWith(name)) {
+					prefixMatch = command;
+					prefixCount += 1;
+					break;
+				}
+			}
+		}
+		return prefixCount === 1 ? prefixMatch : null;
+	};
+	const updateCurrentCommand = (command) => {
+		if (command.options) for (const option of command.options) if (option.isPersistent) {
+			setEach(persistentOptions, option.name, option);
+			if (option.isRequired) setEach(persistentRequiredOptions, option.name, option);
+		} else {
+			setEach(localOptions, option.name, option);
+			if (option.isRequired) setEach(localRequiredOptions, option.name, option);
+		}
+		localSubcommands = command.subcommands;
+		const directives = command.parserDirectives;
+		if (directives?.optionArgSeparators) separators = asArray(directives.optionArgSeparators);
+		if (directives?.subcommandsMatchUniquePrefix) subcommandsMatchUniquePrefix = directives.subcommandsMatchUniquePrefix;
+		if (directives?.optionsMustPrecedeArguments) optionsMustPrecedeArguments = directives.optionsMustPrecedeArguments;
+		if (typeof directives?.flagsArePosixNoncompliant === "boolean") posixCompliantOptions = !directives.flagsArePosixNoncompliant;
+	};
+	updateCurrentCommand(spec);
+	tokens: for (let index = 0; index < input.length; index++) {
+		const token = input[index];
+		if (token === "--") {
+			tokens.push($argSeparator(index, 0, token.length, token));
+			index += 1;
+			for (; index < input.length; index++) {
+				const tok = input[index];
+				tokens.push($arg(index, 0, tok.length, tok));
+			}
+			break tokens;
+		}
+		if (!hasFoundArg && !hasUsedNonPersistentOption && localSubcommands) {
+			const command = getSubcommand(token);
+			if (command) {
+				localOptions.clear();
+				updateCurrentCommand(command);
+				tokens.push($subcommand(index, 0, token.length, token, command));
+				continue tokens;
+			}
+		}
+		if (!(optionsMustPrecedeArguments && hasFoundArg)) {
+			if (posixCompliantOptions && token.length > 1 && (token.startsWith("-") || token.startsWith("+")) && !token.startsWith("--")) {
+				const leadingChar = token[0];
+				const dashOption = getOption(leadingChar);
+				if (dashOption?.args && !hasOption(token.slice(0, 2))) {
+					tokens.push($option(index, 0, 1, leadingChar, dashOption));
+					tokens.push($optionArg(index, 1, token.length, token.slice(1), leadingChar, ""));
+					continue tokens;
+				}
+				chars: for (let char = 1; char < token.length; char++) {
+					const optionName = `${leadingChar}${token[char]}`;
+					const option = getOption(optionName);
+					if (!option) {
+						tokens.push($unknownOption(index, char, char + 1, optionName, [...localOptions.keys(), ...persistentOptions.keys()]));
+						continue chars;
+					}
+					if (!hasUsedNonPersistentOption && !option.isPersistent) hasUsedNonPersistentOption = true;
+					tokens.push($option(index, char, char + 1, optionName, option));
+					if (option.args && char < token.length - 1) {
+						const remainingChars = token.slice(char + 1);
+						const sep = separators.find((sep) => remainingChars.startsWith(sep)) || "";
+						const argStartOffset = char + sep.length;
+						tokens.push($optionArg(index, argStartOffset + 1, token.length, token.slice(argStartOffset + 1), optionName, sep));
+						break;
+					}
+				}
+				continue tokens;
+			}
+			if (!posixCompliantOptions || token.length > 2 && token.startsWith("--")) {
+				let foundSep = null;
+				let foundSepIndex = -1;
+				separators: for (const sep of separators) {
+					const index = token.indexOf(sep);
+					if (index === -1) continue separators;
+					foundSep = sep;
+					foundSepIndex = index;
+				}
+				if (foundSep) {
+					const optionName = token.slice(0, foundSepIndex);
+					const option = getOption(optionName);
+					if (option) {
+						if (!hasUsedNonPersistentOption && !option.isPersistent) hasUsedNonPersistentOption = true;
+						tokens.push($option(index, 0, foundSepIndex, token.slice(0, foundSepIndex), option));
+						tokens.push($optionArg(index, foundSepIndex + foundSep.length, token.length, token.slice(foundSepIndex + foundSep.length), optionName, foundSep));
+						continue tokens;
+					} else if (posixCompliantOptions) {
+						const optionName = token.slice(0, foundSepIndex);
+						tokens.push($unknownOption(index, 0, foundSepIndex, optionName, [...localOptions.keys(), ...persistentOptions.keys()]));
+						tokens.push($optionArg(index, foundSepIndex + foundSep.length, token.length, token.slice(foundSepIndex + foundSep.length), optionName, foundSep));
+						continue tokens;
+					}
+				} else {
+					const option = getOption(token);
+					if (option) {
+						if (!hasUsedNonPersistentOption && !option.isPersistent) hasUsedNonPersistentOption = true;
+						tokens.push($option(index, 0, token.length, token, option));
+						continue tokens;
+					} else if (posixCompliantOptions) {
+						tokens.push($unknownOption(index, 0, token.length, token, [...localOptions.keys(), ...persistentOptions.keys()]));
+						continue tokens;
+					}
+				}
+			}
+		}
+		if (!hasFoundArg) hasFoundArg = true;
+		tokens.push($arg(index, 0, token.length, token));
+	}
+	return {
+		finalState: {
+			localOptions,
+			persistentOptions,
+			localRequiredOptions,
+			persistentRequiredOptions
+		},
+		tokens
+	};
+}
+// src/errors.ts
+const repr = JSON.stringify;
+var ParseError = class extends Error {
+	context;
+	constructor(context, ...args) {
+		super(...args);
+		this.context = context;
+		this.name = this.constructor.name;
+	}
+};
+var UnknownOption = class extends ParseError {
+	index;
+	start;
+	end;
+	option;
+	validOptions;
+	constructor(token, context) {
+		const msg = `${repr(token.literal)} looks like a flag, but is unknown in this context`;
+		super(context, msg);
+		this.option = token.literal;
+		this.validOptions = token.validOptions;
+		this.index = token.index;
+		this.start = token.start;
+		this.end = token.end;
+	}
+};
+var InvalidOptionArg = class extends ParseError {
+	index;
+	start;
+	end;
+	arg;
+	option;
+	constructor(token, context) {
+		const msg = `Option ${token.option} doesn't take arguments`;
+		super(context, msg);
+		this.index = token.index;
+		this.start = token.start;
+		this.end = token.end;
+		this.option = token.option;
+		this.arg = token.literal;
+	}
+};
+var TooManyArguments = class extends ParseError {
+	index;
+	value;
+	constructor(token, context) {
+		const msg = `Too many arguments, ${repr(token.literal)} was unexpected`;
+		super(context, msg);
+		this.index = token.index;
+		this.value = token.literal;
+	}
+};
+var TooFewOptionArguments = class extends ParseError {
+	constructor(min, max, context) {
+		const msg = min === max ? `Option needs ${min} argument${min === 1 ? "" : "s"}` : !Number.isFinite(max) ? `Option needs at least ${min} argument${min === 1 ? "" : "s"}` : `Option needs between ${min} and ${max} arguments`;
+		super(context, msg);
+	}
+};
+var TooFewArguments = class extends ParseError {
+	constructor(min, max, context) {
+		const msg = min === max ? `Expected ${min} argument${min === 1 ? "" : "s"}` : !Number.isFinite(max) ? `Expected at least ${min} argument${min === 1 ? "" : "s"}` : `Expected between ${min} and ${max} arguments`;
+		super(context, msg);
+	}
+};
+var MissingRequiredOption = class extends ParseError {
+	constructor(name, context) {
+		const msg = `Option ${name} is required, but wasn't found`;
+		super(context, msg);
+	}
+};
+// src/help.ts
+var import_fastest_levenshtein = (/* @__PURE__ */ __commonJSMin(((exports) => {
+	exports.__esModule = true;
+	exports.distance = exports.closest = void 0;
+	var peq = /* @__PURE__ */ new Uint32Array(65536);
+	var myers_32 = function(a, b) {
+		var n = a.length;
+		var m = b.length;
+		var lst = 1 << n - 1;
+		var pv = -1;
+		var mv = 0;
+		var sc = n;
+		var i = n;
+		while (i--) peq[a.charCodeAt(i)] |= 1 << i;
+		for (i = 0; i < m; i++) {
+			var eq = peq[b.charCodeAt(i)];
+			var xv = eq | mv;
+			eq |= (eq & pv) + pv ^ pv;
+			mv |= ~(eq | pv);
+			pv &= eq;
+			if (mv & lst) sc++;
+			if (pv & lst) sc--;
+			mv = mv << 1 | 1;
+			pv = pv << 1 | ~(xv | mv);
+			mv &= xv;
+		}
+		i = n;
+		while (i--) peq[a.charCodeAt(i)] = 0;
+		return sc;
+	};
+	var myers_x = function(b, a) {
+		var n = a.length;
+		var m = b.length;
+		var mhc = [];
+		var phc = [];
+		var hsize = Math.ceil(n / 32);
+		var vsize = Math.ceil(m / 32);
+		for (var i = 0; i < hsize; i++) {
+			phc[i] = -1;
+			mhc[i] = 0;
+		}
+		var j = 0;
+		for (; j < vsize - 1; j++) {
+			var mv_1 = 0;
+			var pv_1 = -1;
+			var start_1 = j * 32;
+			var vlen_1 = Math.min(32, m) + start_1;
+			for (var k = start_1; k < vlen_1; k++) peq[b.charCodeAt(k)] |= 1 << k;
+			for (var i = 0; i < n; i++) {
+				var eq = peq[a.charCodeAt(i)];
+				var pb = phc[i / 32 | 0] >>> i & 1;
+				var mb = mhc[i / 32 | 0] >>> i & 1;
+				var xv = eq | mv_1;
+				var xh = ((eq | mb) & pv_1) + pv_1 ^ pv_1 | eq | mb;
+				var ph = mv_1 | ~(xh | pv_1);
+				var mh = pv_1 & xh;
+				if (ph >>> 31 ^ pb) phc[i / 32 | 0] ^= 1 << i;
+				if (mh >>> 31 ^ mb) mhc[i / 32 | 0] ^= 1 << i;
+				ph = ph << 1 | pb;
+				mh = mh << 1 | mb;
+				pv_1 = mh | ~(xv | ph);
+				mv_1 = ph & xv;
+			}
+			for (var k = start_1; k < vlen_1; k++) peq[b.charCodeAt(k)] = 0;
+		}
+		var mv = 0;
+		var pv = -1;
+		var start = j * 32;
+		var vlen = Math.min(32, m - start) + start;
+		for (var k = start; k < vlen; k++) peq[b.charCodeAt(k)] |= 1 << k;
+		var score = m;
+		for (var i = 0; i < n; i++) {
+			var eq = peq[a.charCodeAt(i)];
+			var pb = phc[i / 32 | 0] >>> i & 1;
+			var mb = mhc[i / 32 | 0] >>> i & 1;
+			var xv = eq | mv;
+			var xh = ((eq | mb) & pv) + pv ^ pv | eq | mb;
+			var ph = mv | ~(xh | pv);
+			var mh = pv & xh;
+			score += ph >>> m - 1 & 1;
+			score -= mh >>> m - 1 & 1;
+			if (ph >>> 31 ^ pb) phc[i / 32 | 0] ^= 1 << i;
+			if (mh >>> 31 ^ mb) mhc[i / 32 | 0] ^= 1 << i;
+			ph = ph << 1 | pb;
+			mh = mh << 1 | mb;
+			pv = mh | ~(xv | ph);
+			mv = ph & xv;
+		}
+		for (var k = start; k < vlen; k++) peq[b.charCodeAt(k)] = 0;
+		return score;
+	};
+	var distance = function(a, b) {
+		if (a.length < b.length) {
+			var tmp = b;
+			b = a;
+			a = tmp;
+		}
+		if (b.length === 0) return a.length;
+		if (a.length <= 32) return myers_32(a, b);
+		return myers_x(a, b);
+	};
+	exports.distance = distance;
+	var closest = function(str, arr) {
+		var min_distance = Infinity;
+		var min_index = 0;
+		for (var i = 0; i < arr.length; i++) {
+			var dist = distance(str, arr[i]);
+			if (dist < min_distance) {
+				min_distance = dist;
+				min_index = i;
+			}
+		}
+		return arr[min_index];
+	};
+	exports.closest = closest;
+})))();
+function getNamed(named, name) {
+	return named.find((obj) => makeArray(obj.name).includes(name)) ?? null;
+}
+function getParserDirective(path, key) {
+	for (let index = path.length - 1; index >= 0; index -= 1) {
+		const command = path[index];
+		if (command?.parserDirectives && key in command.parserDirectives) return command.parserDirectives[key];
+	}
+}
+function dedent(str) {
+	if (str[0] !== "\n") return str;
+	const lines = str.split("\n").slice(1, -1);
+	const margin = lines[0].length - lines[0].trimStart().length;
+	return lines.map((line) => line.slice(margin)).join("\n");
+}
+/** Get the help message used by the built-in help option and command. */
+function getHelp(path, config = {}) {
+	const { description = true, usage = true, didYouMean } = config;
+	const sections = getSections(path);
+	if (didYouMean) sections.didYouMean = (0, import_fastest_levenshtein.closest)(didYouMean.input, didYouMean.choices);
+	if (!description) sections.description = void 0;
+	if (!usage) sections.usage = void 0;
+	return formatHelpSections(sections);
+}
+/**
+* Action that prints usage for commands where a subcommand must be provided.
+*/
+const usage = ({ path, args: [command], help }) => {
+	if (command === void 0) {
+		print(help());
+		return 0;
+	}
+	if (command === "") {
+		printActionError(`Expected a command, but the value was empty\n\n${help({ description: false })}`);
+		return 1;
+	}
+	const subcommands = path.at(-1)?.subcommands?.filter((cmd) => !cmd.hidden).flatMap((cmd) => cmd.name);
+	if (subcommands && subcommands.length > 0) {
+		if (getParserDirective(path, "subcommandsMatchUniquePrefix")) {
+			const possible = subcommands.filter((name) => name.startsWith(command));
+			if (possible.length > 0) {
+				printActionError(`Ambiguous command '${command}', could be: ${possible.join(", ")}\n\n${help({ description: false })}`);
+				return 1;
+			}
+		}
+		printActionError(`Unknown command '${command}'\n\n${help({
+			description: false,
+			didYouMean: {
+				input: command,
+				choices: subcommands
+			}
+		})}`);
+		return 1;
+	}
+	printActionError(`Unknown command '${command}'\n\n${help({ description: false })}`);
+	return 1;
+};
+/** A subcommand that prints help for its parent or a sibling command. */
+const helpCommand = {
+	name: "help",
+	description: "Print a help message",
+	args: {
+		name: "command",
+		isOptional: true
+	},
+	action({ path, args: [commandName], help }) {
+		const helpRoot = path.slice(0, -1);
+		if (!commandName) {
+			print(help({ path: helpRoot }));
+			return 0;
+		}
+		const parent = path[path.length - 2];
+		if (!parent.subcommands) {
+			printActionError(`No subcommands, try using 'help' with nothing after it\n\n${help({
+				description: false,
+				path: helpRoot
+			})}`);
+			return 1;
+		}
+		const command = getNamed(parent.subcommands, commandName);
+		if (!command) {
+			const subcommands = parent.subcommands.filter((cmd) => !cmd.hidden).flatMap((cmd) => cmd.name);
+			if (subcommands.length > 0) {
+				printActionError(`There is no subcommand named '${commandName}'\n\n${help({
+					path: helpRoot,
+					didYouMean: {
+						input: commandName,
+						choices: subcommands
+					}
+				})}`);
+				return 1;
+			}
+			printActionError(`There is no subcommand named '${commandName}'\n\n${help({
+				description: false,
+				path: helpRoot
+			})}`);
+			return 1;
+		}
+		print(help({ path: [...helpRoot, command] }));
+	}
+};
+/** A persistent help option that prints help for the selected command. */
+const help = {
+	name: ["-h", "--help"],
+	description: "Print a help message",
+	isPersistent: true,
+	action({ path }) {
+		print(formatHelpSections(getSections(path)));
+		return 0;
+	}
+};
+function getSubcommandPathString(commands) {
+	return commands.map((command) => getLongestString(makeArray1(command.name))).join(" ");
+}
+function nonNullable(value) {
+	return value !== null && value !== void 0;
+}
+function getSections(commands) {
+	const command = commands[commands.length - 1];
+	const description = command.description;
+	const defaultDesc = "No description";
+	const subcommands = command.subcommands ? command.subcommands.filter((subcommand) => !subcommand.hidden).map((subcommand) => [makeArray1(subcommand.name).sort((a, b) => a.length - b.length).join(", "), subcommand.description ?? defaultDesc]) : [];
+	let persistentOptionObjects = [];
+	let optionObjects = [];
+	let persistentOptions = [];
+	let options = [];
+	if (commands.length === 1 && subcommands.length === 0) {
+		optionObjects = command.options ? command.options.filter((option) => !option.hidden) : [];
+		options = optionObjects.map((option) => [optionToString(option), option.description ?? defaultDesc]);
+	} else {
+		persistentOptionObjects = commands.map((command) => command.options).filter(nonNullable).flat().filter((option) => option.isPersistent && !option.hidden);
+		persistentOptions = persistentOptionObjects.map((option) => [optionToString(option), option.description ?? defaultDesc]);
+		optionObjects = (command.options ?? []).filter((option) => !option.hidden && !option.isPersistent);
+		options = optionObjects.map((option) => [optionToString(option), option.description ?? defaultDesc]);
+	}
+	return {
+		usage: (() => {
+			const parts = [getSubcommandPathString(commands)];
+			const required = [...optionObjects.filter((option) => option.isRequired), ...persistentOptionObjects.filter((option) => option.isRequired)];
+			for (const option of required) parts.push(optionToString(option));
+			if (options.length || persistentOptions.length) parts.push("[flags]");
+			if (command.requiresSubcommand) parts.push("<command>");
+			else {
+				const args = makeArray(command.args);
+				if (args.length > 0) parts.push(summarizeArguments(args));
+			}
+			return parts.join(" ");
+		})(),
+		description,
+		persistentOptions,
+		options,
+		subcommands
+	};
+}
+function formatHelpSections(sections) {
+	const parts = [];
+	const indent = "  ";
+	if (sections.didYouMean) parts.push(`    Did you mean '${sections.didYouMean}'?`);
+	if (sections.description) parts.push(dedent(sections.description));
+	if (sections.usage) parts.push(`Usage:\n${indent}${sections.usage}`);
+	const longestOptionName = Math.max(0, ...sections.options.map(([name]) => name.length), ...sections.persistentOptions.map(([name]) => name.length));
+	const minSpacingBetweenNameAndDesc = 2;
+	const formatOptions = (options) => {
+		const lines = [];
+		const newline = indent + " ".repeat(longestOptionName + minSpacingBetweenNameAndDesc);
+		for (const [name, desc] of options) {
+			const spaces = " ".repeat(longestOptionName - name.length + minSpacingBetweenNameAndDesc);
+			const [head, ...tail] = desc.split("\n");
+			const description = [head, ...tail.map((line) => newline + line)].join("\n");
+			lines.push(`${indent}${name}${spaces}${description}`);
+		}
+		return lines;
+	};
+	if (sections.subcommands.length > 0) {
+		const lines = ["Commands:"];
+		const longestName = Math.max(...sections.subcommands.map(([name]) => name.length));
+		const newline = indent + " ".repeat(longestName + minSpacingBetweenNameAndDesc);
+		for (const [name, desc] of sections.subcommands) {
+			const spaces = " ".repeat(longestName - name.length + minSpacingBetweenNameAndDesc);
+			const [head, ...tail] = desc.split("\n\n")[0].split("\n");
+			const description = [head, ...tail.map((line) => newline + line)].join("\n");
+			lines.push(`${indent}${name}${spaces}${description}`);
+		}
+		parts.push(lines.join("\n"));
+	}
+	if (sections.options.length > 0) {
+		const lines = ["Flags:", ...formatOptions(sections.options)];
+		parts.push(lines.join("\n"));
+	}
+	if (sections.persistentOptions.length > 0) {
+		const lines = ["Global flags:", ...formatOptions(sections.persistentOptions)];
+		parts.push(lines.join("\n"));
+	}
+	return parts.join("\n\n") + "\n";
+}
+function getLongestString(strings) {
+	let longest = strings[0];
+	for (let i = 1; i < strings.length; i++) {
+		const string = strings[i];
+		if (string.length > longest.length) longest = string;
+	}
+	return longest;
+}
+function optionToString(option) {
+	const name = makeArray1(option.name).sort((a, b) => a.length - b.length).join(", ");
+	const optionArgs = makeArray(option.args);
+	if (optionArgs.length === 0) return name;
+	if (option.requiresSeparator) {
+		const separator = option.requiresSeparator === true ? "=" : option.requiresSeparator;
+		if (optionArgs[0].isOptional) return `${name}[${separator}${optionArgs[0].name || "argument"}]`;
+		return `${name}${separator}<${optionArgs[0].name || "argument"}>`;
+	}
+	return `${name} ${summarizeArguments(optionArgs)}`;
+}
+function summarizeArguments(args) {
+	return args.map((arg) => argToString(arg)).join(" ");
+}
+function argToString(arg) {
+	const name = arg.name || "argument";
+	let lhs = "<";
+	let rhs = ">";
+	let suffix = "";
+	if (arg.isOptional) {
+		lhs = "[";
+		rhs = "]";
+	}
+	if (arg.isVariadic) suffix = "...";
+	return `${lhs}${name}${rhs}${suffix}`;
+}
+// src/parse.ts
+/**
+* Returns the minimum number of arguments that satisfies the args.
+*
+* Accepts the raw spec value (a single arg, an array, or `undefined`) so the
+* hot path doesn't have to copy it into an array first.
+*/
+function getMinArgs(args) {
+	if (args === void 0) return 0;
+	if (!isArray(args)) return args.isOptional ? 0 : 1;
+	let count = 0;
+	for (let i = 0; i < args.length; i++) {
+		if (args[i].isOptional) break;
+		count++;
+	}
+	return count;
+}
+/** Returns the maximum number of arguments that satisfies the args. */
+function getMaxArgs(args) {
+	if (args === void 0) return 0;
+	if (!isArray(args)) return args.isVariadic ? Infinity : 1;
+	for (let i = 0; i < args.length; i++) if (args[args.length - 1 - i].isVariadic) return Infinity;
+	return args.length;
+}
+/** Check if a map has a key or any key from an array */
+function has(map, key) {
+	if (isArray(key)) return map.has(key[0]);
+	return map.has(key);
+}
+/** Get a value from a map by a key or any key from an array */
+function get(map, key) {
+	if (isArray(key)) return map.get(key[0]);
+	return map.get(key);
+}
+/**
+* Parse the input tokens using the given CLI spec.
+*
+* This returns a `ParseResult`, which contains the array of
+* subcommands used, the provided options, and the arguments.
+*
+* If parsing fails, this function throws.
+*
+* This function is exposed to make it easier to build a custom runner.
+*/
+function parse(input, spec) {
+	const path = [spec];
+	const actions = [];
+	const optionActions = [];
+	if (spec.action) actions.push(spec.action);
+	else if (spec.requiresSubcommand) actions.push(usage);
+	let commandArgsMin = getMinArgs(spec.args);
+	let commandArgsMax = getMaxArgs(spec.args);
+	const foundArgs = [];
+	const foundOptions = /* @__PURE__ */ new Map();
+	let state = 0;
+	let optionArgs = null;
+	let optionArgsMin = 0;
+	let optionArgsMax = 0;
+	let requiredSeparator = false;
+	let argSeparatorIndex = -1;
+	const dependsOnOptions = [];
+	const exclusiveOnOptions = [];
+	const parseOption = (token) => {
+		const option = token.option;
+		if (!option.isRepeatable && has(foundOptions, option.name)) throw new ParseError(ctx(), "Repeated option");
+		if (option.exclusiveOn) exclusiveOnOptions.push(option);
+		if (option.dependsOn) dependsOnOptions.push(option);
+		if (option.action) optionActions.push(option.action);
+		if (option.isRepeatable) {
+			const maxRepeat = option.isRepeatable === true ? Infinity : option.isRepeatable;
+			let arr = get(foundOptions, option.name);
+			if (!arr) {
+				arr = [];
+				setEach(foundOptions, option.name, arr);
+			}
+			if (arr.length >= maxRepeat) throw new ParseError(ctx(), "Too many repetitions");
+			arr.push("");
+			return;
+		}
+		optionArgsMin = getMinArgs(option.args);
+		optionArgsMax = getMaxArgs(option.args);
+		optionArgs = [];
+		setEach(foundOptions, option.name, optionArgs);
+		if (optionArgsMax === 0) {
+			optionArgs = null;
+			state = 0;
+			return;
+		}
+		if (option.requiresSeparator) {
+			state = 2;
+			requiredSeparator = option.requiresSeparator;
+		} else state = 1;
+	};
+	const parseArg = (token) => {
+		if (!path[path.length - 1].requiresSubcommand && foundArgs.length >= commandArgsMax) throw new TooManyArguments(token, ctx());
+		foundArgs.push(token.literal);
+	};
+	const parseArgSeparator = () => {
+		if (foundArgs.length >= commandArgsMax) throw new ParseError(ctx(), "Unexpected argument '--', did you mean to use an option instead?");
+		argSeparatorIndex = foundArgs.length;
+		state = 0;
+	};
+	const parseSubcommand = (token) => {
+		path.push(token.subcommand);
+		commandArgsMin = getMinArgs(token.subcommand.args);
+		commandArgsMax = getMaxArgs(token.subcommand.args);
+		if (token.subcommand.action) actions.push(token.subcommand.action);
+		else if (token.subcommand.requiresSubcommand) actions.push(usage);
+	};
+	const ctx = () => ({ path });
+	const { finalState, tokens } = analyze(input, spec);
+	for (const token of tokens) switch (state) {
+		case 0:
+			switch (token.kind) {
+				case "subcommand":
+					parseSubcommand(token);
+					break;
+				case "arg":
+					parseArg(token);
+					break;
+				case "option":
+					parseOption(token);
+					break;
+				case "unknown-option": throw new UnknownOption(token, ctx());
+				case "option-arg": throw new InvalidOptionArg(token, ctx());
+				case "arg-separator":
+					parseArgSeparator();
+					break;
+				default: throw new ParseError(ctx(), "Unreachable");
+			}
+			break;
+		case 1:
+			assert(Array.isArray(optionArgs), "Invalid state, must have an array to store option arguments");
+			switch (token.kind) {
+				case "option-arg":
+				case "arg":
+					if (optionArgs.length < optionArgsMax) optionArgs.push(token.literal);
+					else {
+						optionArgs = null;
+						state = 0;
+						parseArg(token);
+					}
+					break;
+				case "option":
+					if (optionArgs.length < optionArgsMin) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
+					parseOption(token);
+					break;
+				case "unknown-option":
+					if (optionArgs.length < optionArgsMax) optionArgs.push(token.literal);
+					else throw new UnknownOption(token, ctx());
+					break;
+				case "arg-separator":
+					if (optionArgs.length < optionArgsMin) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
+					parseArgSeparator();
+					break;
+				case "subcommand": throw new ParseError(ctx(), "Unexpected token");
+				default: throw new ParseError(ctx(), "Unreachable");
+			}
+			break;
+		case 2:
+			assert(Array.isArray(optionArgs), "Invalid state, must have an array to store option arguments");
+			assert(requiredSeparator, "Invalid state, a separator must be set");
+			switch (token.kind) {
+				case "option-arg":
+					if (typeof requiredSeparator === "string" && token.separator !== requiredSeparator) throw new ParseError(ctx(), `Incorrect separator, use '${requiredSeparator}' instead of '${token.separator}'`);
+					optionArgs.push(token.literal);
+					state = 0;
+					break;
+				case "arg":
+					if (optionArgsMin > 0) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
+					optionArgs = null;
+					state = 0;
+					parseArg(token);
+					break;
+				case "option":
+					if (optionArgsMin > 0) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
+					parseOption(token);
+					break;
+				case "unknown-option": throw new UnknownOption(token, ctx());
+				case "arg-separator": throw new ParseError(ctx(), "Unexpected token");
+				case "subcommand":
+					if (optionArgsMin > 0) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
+					parseSubcommand(token);
+					state = 0;
+					break;
+				default: throw new ParseError(ctx(), "Unreachable");
+			}
+	}
+	const hasOptionAction = optionActions.length > 0;
+	if (!hasOptionAction && foundArgs.length < commandArgsMin) throw new TooFewArguments(commandArgsMin, commandArgsMax, ctx());
+	if (optionArgs && optionArgs.length < optionArgsMin) throw new TooFewOptionArguments(optionArgsMin, optionArgsMax, ctx());
+	for (const option of dependsOnOptions) for (const name of option.dependsOn) if (!foundOptions.has(name)) throw new ParseError(ctx(), `${option.name} requires ${name}, add it to fix this error`);
+	for (const option of exclusiveOnOptions) for (const name of option.exclusiveOn) if (foundOptions.has(name)) throw new ParseError(ctx(), `${option.name} can't be used together with ${name}`);
+	if (!hasOptionAction) {
+		for (const name of finalState.localRequiredOptions.keys()) if (!foundOptions.has(name)) throw new MissingRequiredOption(name, ctx());
+		for (const name of finalState.persistentRequiredOptions.keys()) if (!foundOptions.has(name)) throw new MissingRequiredOption(name, ctx());
+	}
+	return {
+		path,
+		actions,
+		optionActions,
+		argSeparatorIndex,
+		args: foundArgs,
+		options: foundOptions
+	};
+}
+// src/completion.ts
+const SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+function isShell(value) {
+	return SHELLS.includes(value);
+}
+const firstLine = (description) => description ? description.split("\n", 1)[0].trim() : "";
+/** Turn an arbitrary name into a safe shell identifier fragment. */
+const sanitize = (value) => value.replace(/[^A-Za-z0-9]+/g, "_");
+function encodeLocation(location) {
+	const bytes = new TextEncoder().encode(JSON.stringify(location));
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+function decodeLocation(encoded) {
+	const binary = atob(encoded);
+	const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+	return JSON.parse(new TextDecoder().decode(bytes));
+}
+/** Build {@link ArgComplete} for one argument at a known spec location. */
+function argCompleteFor(arg, location) {
+	const staticValues = (arg.suggestions ?? []).map((suggestion) => typeof suggestion === "string" ? suggestion : makeArray(suggestion.name)[0]);
+	const genIndex = makeArray(arg.generators).findIndex((generator) => generator.custom);
+	const customLocation = genIndex >= 0 ? encodeLocation({
+		...location,
+		genIndex
+	}) : void 0;
+	if (!arg.template && staticValues.length === 0 && !customLocation) return;
+	return {
+		template: arg.template,
+		staticValues,
+		customLocation
+	};
+}
+/** Completion for a option's first argument, if it has any metadata. */
+function optionArgComplete(option, path) {
+	const arg = asArray(option.args)[0];
+	if (!arg) return void 0;
+	return argCompleteFor(arg, {
+		path,
+		option: makeArray(option.name)[0],
+		argIndex: 0
+	});
+}
+/** Completion for a command's first positional arg that has metadata. */
+function positionalComplete(command, path) {
+	const args = asArray(command.args);
+	for (let index = 0; index < args.length; index += 1) {
+		const ac = argCompleteFor(args[index], {
+			path,
+			argIndex: index
+		});
+		if (ac) return ac;
+	}
+}
+function toOptionInfo(option, path) {
+	return {
+		tokens: makeArray(option.name),
+		description: firstLine(option.description),
+		takesArg: asArray(option.args).length > 0,
+		argComplete: optionArgComplete(option, path)
+	};
+}
+/**
+* Flatten the spec into a list of command nodes. Hidden options and subcommands
+* are excluded; persistent options are propagated to descendants.
+*/
+function walk(spec) {
+	const nodes = [];
+	const recurse = (command, key, path, inheritedPersistent) => {
+		const ownOptions = (command.options ?? []).filter((option) => !option.hidden);
+		const children = (command.subcommands ?? []).filter((sub) => !sub.hidden);
+		const node = {
+			key,
+			path,
+			subcommands: [],
+			options: [...inheritedPersistent, ...ownOptions].map((option) => toOptionInfo(option, path)),
+			positional: positionalComplete(command, path),
+			transitions: []
+		};
+		const childPersistent = [...inheritedPersistent, ...ownOptions.filter((option) => option.isPersistent)];
+		for (const child of children) {
+			const tokens = makeArray(child.name);
+			const childKey = `${key}_${sanitize(tokens[0])}`;
+			node.subcommands.push({
+				tokens,
+				description: firstLine(child.description)
+			});
+			for (const token of tokens) node.transitions.push({
+				token,
+				childKey
+			});
+			recurse(child, childKey, [...path, tokens[0]], childPersistent);
+		}
+		nodes.push(node);
+	};
+	recurse(spec, "cmd", [], []);
+	return nodes;
+}
+/** Single-quote a string for bash/zsh. */
+function shQuote(value) {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** Single-quote a string for fish (only `\` and `'` are special). */
+function fishQuote(value) {
+	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+/** Every candidate token offered at a node (subcommand aliases + option aliases). */
+function candidateTokens(node) {
+	const tokens = [];
+	for (const sub of node.subcommands) tokens.push(...sub.tokens);
+	for (const option of node.options) tokens.push(...option.tokens);
+	return tokens;
+}
+function renderTransitionCases(nodes, indent) {
+	const lines = [];
+	for (const node of nodes) for (const { token, childKey } of node.transitions) lines.push(`${indent}${shQuote(`${node.key}::${token}`)}) cmd=${shQuote(childKey)} ;;`);
+	return lines;
+}
+/**
+* bash candidate lines for an arg. `append` keeps existing COMPREPLY (for a
+* positional, which coexists with subcommands/options); otherwise it replaces.
+* The generator callback uses the typed command and is guarded for resilience.
+*/
+function bashArgLines(ac, indent, append) {
+	const lines = [];
+	const op = append ? "COMPREPLY+=" : "COMPREPLY=";
+	const hasWords = ac.staticValues.length > 0 || ac.customLocation !== void 0;
+	if (hasWords) {
+		lines.push(`${indent}local words=${ac.staticValues.length > 0 ? shQuote(ac.staticValues.join(" ")) : "\"\""}`);
+		if (ac.customLocation) {
+			lines.push(`${indent}if command -v "\${COMP_WORDS[0]}" >/dev/null 2>&1; then`);
+			lines.push(`${indent}  words="$words $("\${COMP_WORDS[0]}" completion generate-suggestions ${shQuote(ac.customLocation)} -- "\${COMP_WORDS[@]:1}" 2>/dev/null)"`);
+			lines.push(`${indent}fi`);
+		}
+		lines.push(`${indent}${op}( $(compgen -W "$words" -- "$cur") )`);
+	}
+	if (ac.template) {
+		const option = ac.template === "folders" ? "-d" : "-f";
+		const fileOp = hasWords || append ? "COMPREPLY+=" : "COMPREPLY=";
+		lines.push(`${indent}${fileOp}( $(compgen ${option} -- "$cur") )`);
+	}
+	return lines;
+}
+function renderBash(spec, nodes) {
+	const id = sanitize(spec.name);
+	const lines = [];
+	lines.push(`_${id}() {`);
+	lines.push(`  local cur="\${COMP_WORDS[COMP_CWORD]}"`);
+	lines.push(`  local prev="\${COMP_WORDS[COMP_CWORD-1]}"`);
+	lines.push(`  local cmd="cmd" i w`);
+	lines.push(`  for (( i=1; i < COMP_CWORD; i++ )); do`);
+	lines.push(`    w="\${COMP_WORDS[i]}"`);
+	lines.push(`    case "$w" in -* ) continue ;; esac`);
+	lines.push(`    case "\${cmd}::\${w}" in`);
+	lines.push(...renderTransitionCases(nodes, "      "));
+	lines.push(`    esac`);
+	lines.push(`  done`);
+	const argCases = [];
+	for (const node of nodes) for (const option of node.options) {
+		if (!option.argComplete) continue;
+		for (const token of option.tokens) {
+			argCases.push(`    ${shQuote(`${node.key}::${token}`)})`);
+			argCases.push(...bashArgLines(option.argComplete, "      ", false));
+			argCases.push(`      return ;;`);
+		}
+	}
+	if (argCases.length > 0) {
+		lines.push(`  case "\${cmd}::\${prev}" in`);
+		lines.push(...argCases);
+		lines.push(`  esac`);
+	}
+	lines.push(`  local opts=""`);
+	lines.push(`  case "$cmd" in`);
+	for (const node of nodes) lines.push(`    ${shQuote(node.key)}) opts=${shQuote(candidateTokens(node).join(" "))} ;;`);
+	lines.push(`  esac`);
+	lines.push(`  COMPREPLY=( $(compgen -W "$opts" -- "$cur") )`);
+	const posCases = [];
+	for (const node of nodes) {
+		if (!node.positional) continue;
+		posCases.push(`    ${shQuote(node.key)})`);
+		posCases.push(...bashArgLines(node.positional, "      ", true));
+		posCases.push(`      ;;`);
+	}
+	if (posCases.length > 0) {
+		lines.push(`  case "$cmd" in`);
+		lines.push(...posCases);
+		lines.push(`  esac`);
+	}
+	lines.push(`}`);
+	lines.push(`complete -F _${id} ${shQuote(spec.name)}`);
+	return lines.join("\n");
+}
+/** zsh candidate lines for an arg (used for both option values and positionals). */
+function zshArgLines(ac, indent) {
+	const lines = [];
+	if (ac.staticValues.length > 0 || ac.customLocation !== void 0) {
+		lines.push(`${indent}local -a vals`);
+		lines.push(`${indent}vals=( ${ac.staticValues.map(shQuote).join(" ")} )`);
+		if (ac.customLocation) {
+			lines.push(`${indent}if command -v "$words[1]" >/dev/null 2>&1; then`);
+			lines.push(`${indent}  vals+=( \${(f)"$("$words[1]" completion generate-suggestions ${shQuote(ac.customLocation)} -- \${words[2,-1]} 2>/dev/null)"} )`);
+			lines.push(`${indent}fi`);
+		}
+		lines.push(`${indent}compadd -a vals`);
+	}
+	if (ac.template) lines.push(`${indent}${ac.template === "folders" ? "_files -/" : "_files"}`);
+	return lines;
+}
+function renderZsh(spec, nodes) {
+	const id = sanitize(spec.name);
+	const lines = [];
+	lines.push(`#compdef ${spec.name}`);
+	lines.push(`_${id}() {`);
+	lines.push(`  local cmd=cmd i w prev`);
+	lines.push(`  for (( i=2; i < CURRENT; i++ )); do`);
+	lines.push(`    w="\${words[i]}"`);
+	lines.push(`    case "$w" in -* ) continue ;; esac`);
+	lines.push(`    case "\${cmd}::\${w}" in`);
+	lines.push(...renderTransitionCases(nodes, "      "));
+	lines.push(`    esac`);
+	lines.push(`  done`);
+	lines.push(`  prev="\${words[CURRENT-1]}"`);
+	const argCases = [];
+	for (const node of nodes) for (const option of node.options) {
+		if (!option.argComplete) continue;
+		for (const token of option.tokens) {
+			argCases.push(`    ${shQuote(`${node.key}::${token}`)})`);
+			argCases.push(...zshArgLines(option.argComplete, "      "));
+			argCases.push(`      return ;;`);
+		}
+	}
+	if (argCases.length > 0) {
+		lines.push(`  case "\${cmd}::\${prev}" in`);
+		lines.push(...argCases);
+		lines.push(`  esac`);
+	}
+	lines.push(`  local -a opts`);
+	lines.push(`  case "$cmd" in`);
+	for (const node of nodes) {
+		const entries = [];
+		for (const sub of node.subcommands) for (const token of sub.tokens) entries.push(shQuote(`${token}:${sub.description}`));
+		for (const option of node.options) for (const token of option.tokens) entries.push(shQuote(`${token}:${option.description}`));
+		lines.push(`    ${shQuote(node.key)}) opts=( ${entries.join(" ")} ) ;;`);
+	}
+	lines.push(`  esac`);
+	lines.push(`  _describe -t values ${shQuote(spec.name)} opts`);
+	const posCases = [];
+	for (const node of nodes) {
+		if (!node.positional) continue;
+		posCases.push(`    ${shQuote(node.key)})`);
+		posCases.push(...zshArgLines(node.positional, "      "));
+		posCases.push(`      ;;`);
+	}
+	if (posCases.length > 0) {
+		lines.push(`  case "$cmd" in`);
+		lines.push(...posCases);
+		lines.push(`  esac`);
+	}
+	lines.push(`}`);
+	lines.push(`_${id} "$@"`);
+	return lines.join("\n");
+}
+/** Build the fish `complete` option selectors (`-s x`, `-l long`, `-o old`). */
+function fishOptionSelectors(tokens) {
+	const parts = [];
+	for (const token of tokens) if (token.startsWith("--")) parts.push(`-l ${fishQuote(token.slice(2))}`);
+	else if (token.startsWith("-") && token.length === 2) parts.push(`-s ${fishQuote(token.slice(1))}`);
+	else if (token.startsWith("-") && token.length > 2) parts.push(`-o ${fishQuote(token.slice(1))}`);
+	else parts.push(`-a ${fishQuote(token)}`);
+	return parts.join(" ");
+}
+/** A guarded fish command substitution that runs a generator by location. */
+function fishGuardedCallback(location) {
+	return `(set -l c (commandline -opc)[1]; if command -q -- $c; or test -x "$c"; $c completion generate-suggestions ${location} -- (commandline -opc) 2>/dev/null; end)`;
+}
+/** The `-a` candidate bits and whether the shell's file completion is wanted. */
+function fishValueBits(ac) {
+	const parts = [...ac.staticValues];
+	if (ac.template === "folders" || Array.isArray(ac.template)) parts.push("(__fish_complete_directories)");
+	if (ac.customLocation) parts.push(fishGuardedCallback(ac.customLocation));
+	return {
+		aBits: parts.length > 0 ? ` -a ${fishQuote(parts.join(" "))}` : "",
+		wantsFiles: ac.template === "filepaths" || Array.isArray(ac.template)
+	};
+}
+/**
+* The suffix after a option's selectors. Uses `-x` (exclusive: requires a value
+* and suppresses fish's file fallback) when the arg has its own candidates and
+* isn't a filepaths template; `-r` lets files through when they're wanted.
+*/
+function fishOptionArgSuffix(option) {
+	if (!option.takesArg) return "";
+	if (!option.argComplete) return " -r";
+	const { aBits, wantsFiles } = fishValueBits(option.argComplete);
+	return `${wantsFiles ? " -r" : " -x"}${aBits}`;
+}
+function renderFish(spec, nodes) {
+	const id = sanitize(spec.name);
+	const name = spec.name;
+	const lines = [];
+	lines.push(`function __fish_${id}_at`);
+	lines.push(`  set -l cmd cmd`);
+	lines.push(`  set -l toks (commandline -opc)`);
+	lines.push(`  for w in $toks[2..-1]`);
+	lines.push(`    if string match -qr '^-' -- $w`);
+	lines.push(`      continue`);
+	lines.push(`    end`);
+	lines.push(`    switch "$cmd $w"`);
+	for (const node of nodes) for (const { token, childKey } of node.transitions) {
+		lines.push(`      case ${fishQuote(`${node.key} ${token}`)}`);
+		lines.push(`        set cmd ${fishQuote(childKey)}`);
+	}
+	lines.push(`    end`);
+	lines.push(`  end`);
+	lines.push(`  test "$cmd" = "$argv[1]"`);
+	lines.push(`end`);
+	lines.push("");
+	lines.push(`complete -c ${fishQuote(name)} -f`);
+	for (const node of nodes) {
+		const guard = `-n ${fishQuote(`__fish_${id}_at ${node.key}`)}`;
+		for (const sub of node.subcommands) for (const token of sub.tokens) {
+			const desc = sub.description ? ` -d ${fishQuote(sub.description)}` : "";
+			lines.push(`complete -c ${fishQuote(name)} ${guard} -a ${fishQuote(token)}${desc}`);
+		}
+		for (const option of node.options) {
+			const desc = option.description ? ` -d ${fishQuote(option.description)}` : "";
+			const suffix = fishOptionArgSuffix(option);
+			lines.push(`complete -c ${fishQuote(name)} ${guard} ${fishOptionSelectors(option.tokens)}${suffix}${desc}`);
+		}
+		if (node.positional) {
+			const { aBits, wantsFiles } = fishValueBits(node.positional);
+			lines.push(`complete -c ${fishQuote(name)} ${guard}${aBits}${wantsFiles ? " -F" : ""}`);
+		}
+	}
+	return lines.join("\n");
+}
+function analyzeState(spec, before) {
+	const { tokens, finalState } = analyze(before, spec);
+	const path = [spec];
+	let current = spec;
+	let pending = null;
+	let pendingFilled = 0;
+	let pendingMax = 0;
+	let positionalIndex = 0;
+	let forceArgs = false;
+	let sawPositional = false;
+	let usedNonPersistentOption = false;
+	const presentNames = /* @__PURE__ */ new Set();
+	const countByOption = /* @__PURE__ */ new Map();
+	for (const token of tokens) switch (token.kind) {
+		case "subcommand":
+			current = token.subcommand;
+			path.push(current);
+			positionalIndex = 0;
+			sawPositional = false;
+			pending = null;
+			break;
+		case "option": {
+			const option = token.option;
+			for (const name of makeArray(option.name)) presentNames.add(name);
+			countByOption.set(option, (countByOption.get(option) ?? 0) + 1);
+			if (!option.isPersistent) usedNonPersistentOption = true;
+			const max = getMaxArgs(option.args);
+			if (max > 0 && !option.requiresSeparator) {
+				pending = {
+					option,
+					argIndex: 0
+				};
+				pendingFilled = 0;
+				pendingMax = max;
+			} else pending = null;
+			break;
+		}
+		case "option-arg":
+			pending = null;
+			break;
+		case "arg":
+			if (pending && pendingFilled < pendingMax) {
+				pendingFilled += 1;
+				pending = {
+					option: pending.option,
+					argIndex: pendingFilled
+				};
+				if (pendingFilled >= pendingMax) pending = null;
+			} else {
+				positionalIndex += 1;
+				sawPositional = true;
+				pending = null;
+			}
+			break;
+		case "arg-separator":
+			forceArgs = true;
+			pending = null;
+			break;
+		case "unknown-option": pending = null;
+	}
+	const availableOptions = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const map of [finalState.localOptions, finalState.persistentOptions]) for (const option of map.values()) if (!seen.has(option)) {
+		seen.add(option);
+		availableOptions.push(option);
+	}
+	return {
+		path,
+		current,
+		availableOptions,
+		pending,
+		positionalIndex,
+		presentNames,
+		countByOption,
+		forceArgs,
+		sawPositional,
+		usedNonPersistentOption
+	};
+}
+/** Does any command on the path enable a sticky parser directive? */
+function directiveOnPath(path, key) {
+	return path.some((command) => command.parserDirectives?.[key]);
+}
+/** The option-arg separators in effect (the deepest command that sets them). */
+function separatorsOnPath(path) {
+	let separators = ["="];
+	for (const command of path) {
+		const configured = command.parserDirectives?.optionArgSeparators;
+		if (configured) separators = makeArray(configured);
+	}
+	return separators;
+}
+/** Enumerate filesystem entries matching `partial` for a path template. */
+async function enumeratePaths(partial, template) {
+	const { readdirSync } = await import("node:fs");
+	const slash = partial.lastIndexOf("/");
+	const dir = slash >= 0 ? partial.slice(0, slash + 1) : "";
+	const base = slash >= 0 ? partial.slice(slash + 1) : partial;
+	const foldersOnly = template === "folders";
+	let entries;
+	try {
+		entries = readdirSync(dir || ".", { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const candidates = [];
+	for (const entry of entries) {
+		if (!entry.name.startsWith(base)) continue;
+		const isDir = entry.isDirectory();
+		if (foldersOnly && !isDir) continue;
+		candidates.push({ value: `${dir}${entry.name}${isDir ? "/" : ""}` });
+	}
+	return candidates;
+}
+/** All candidate values for a single argument (suggestions/generators/template). */
+async function argValues(arg, tokens, partial) {
+	const candidates = [];
+	for (const suggestion of arg.suggestions ?? []) candidates.push(typeof suggestion === "string" ? { value: suggestion } : {
+		value: makeArray(suggestion.name)[0],
+		description: suggestion.description
+	});
+	for (const generator of makeArray(arg.generators)) {
+		if (!generator.custom) continue;
+		const produced = await generator.custom([...tokens, partial]);
+		for (const suggestion of produced) candidates.push(typeof suggestion === "string" ? { value: suggestion } : {
+			value: makeArray(suggestion.name)[0],
+			description: suggestion.description
+		});
+	}
+	if (arg.template) candidates.push(...await enumeratePaths(partial, arg.template));
+	return candidates;
+}
+/** Pick the argument being completed at a positional index (honors variadic). */
+function positionalArg(command, index) {
+	const args = asArray(command.args);
+	if (args.length === 0) return void 0;
+	if (index < args.length) return args[index];
+	const last = args[args.length - 1];
+	return last?.isVariadic ? last : void 0;
+}
+/**
+* Resolve completion candidates for a partial command line, reusing the parser
+* (`analyze`) for context. Dispatches between completing a option's value and
+* completing a fresh token (subcommand / positional / option).
+*/
+async function completeRuntime(req) {
+	const state = analyzeState(req.spec, req.before);
+	const separators = separatorsOnPath(state.path);
+	const optionValue = await resolveOptionValue(state, req, separators);
+	if (optionValue) return optionValue;
+	return freshTokenCandidates(state, req, separators);
+}
+/**
+* Candidates when the word being completed is a option's value — either attached
+* (`--option=value`) or the separate token after a option that expects one. Returns
+* null when no option value is being completed.
+*/
+async function resolveOptionValue(state, req, separators) {
+	const tokens = [...req.before];
+	for (const separator of separators) {
+		const at = req.partial.indexOf(separator);
+		if (at <= 0) continue;
+		const optionName = req.partial.slice(0, at);
+		const option = state.availableOptions.find((candidate) => makeArray(candidate.name).includes(optionName));
+		const arg = option && asArray(option.args)[0];
+		if (option && arg) return (await argValues(arg, tokens, req.partial.slice(at + separator.length))).map((candidate) => ({
+			value: `${optionName}${separator}${candidate.value}`,
+			description: candidate.description
+		}));
+	}
+	if (state.pending) {
+		const arg = asArray(state.pending.option.args)[state.pending.argIndex];
+		return arg ? argValues(arg, tokens, req.partial) : [];
+	}
+	return null;
+}
+/** Candidates when completing a fresh token: subcommand / positional / option. */
+async function freshTokenCandidates(state, req, separators) {
+	const candidates = [];
+	const tokens = [...req.before];
+	const posixNoncompliant = directiveOnPath(state.path, "flagsArePosixNoncompliant");
+	const partialIsOption = !posixNoncompliant && (req.partial.startsWith("-") || req.partial.startsWith("+"));
+	const wantValues = !(req.gateOptions && partialIsOption);
+	const wantOptions = !req.gateOptions || partialIsOption || posixNoncompliant;
+	if (wantValues) {
+		const positional = positionalArg(state.current, state.positionalIndex);
+		if (positional) candidates.push(...await argValues(positional, tokens, req.partial));
+		if (state.forceArgs) return candidates;
+		if (!state.sawPositional && !state.usedNonPersistentOption) for (const sub of state.current.subcommands ?? []) {
+			if (sub.hidden) continue;
+			const description = firstLine(sub.description);
+			for (const token of makeArray(sub.name)) candidates.push({
+				value: token,
+				description
+			});
+		}
+	} else if (state.forceArgs) return candidates;
+	const optionsBlocked = state.sawPositional && directiveOnPath(state.path, "optionsMustPrecedeArguments");
+	if (wantOptions && !optionsBlocked) candidates.push(...optionCandidates(state, separators));
+	return candidates;
+}
+/** Eligible option candidates after relationship filtering. */
+function optionCandidates(state, separators) {
+	const required = [];
+	const optional = [];
+	for (const option of state.availableOptions) {
+		if (option.hidden) continue;
+		const count = state.countByOption.get(option) ?? 0;
+		if (count > 0) {
+			if (!option.isRepeatable) continue;
+			if (typeof option.isRepeatable === "number" && count >= option.isRepeatable) continue;
+		}
+		if (option.exclusiveOn?.some((name) => state.presentNames.has(name))) continue;
+		if (state.availableOptions.some((other) => other !== option && makeArray(other.name).some((name) => state.presentNames.has(name)) && other.exclusiveOn?.some((name) => makeArray(option.name).includes(name)))) continue;
+		let description = firstLine(option.description);
+		if (option.dependsOn) {
+			const needs = option.dependsOn.join(", ");
+			description = description ? `${description} (requires ${needs})` : `requires ${needs}`;
+		}
+		if (option.isRequired) description = description ? `${description} [required]` : "[required]";
+		const sep = option.requiresSeparator === true ? separators[0] : typeof option.requiresSeparator === "string" ? option.requiresSeparator : void 0;
+		const bucket = option.isRequired ? required : optional;
+		for (const token of makeArray(option.name)) bucket.push({
+			value: sep ? `${token}${sep}` : token,
+			description
+		});
+	}
+	return [...required, ...optional];
+}
+/**
+* Render the thin shim that forwards the line to `completion complete`. The
+* binary is invoked as typed (so `./pack` works) and guarded so a missing
+* command degrades to no completion instead of an error.
+*/
+function renderRuntimeShim(spec, shell) {
+	const id = sanitize(spec.name);
+	const name = spec.name;
+	if (shell === "bash") return [
+		`_${id}_complete() {`,
+		`  local bin="\${COMP_WORDS[0]}"`,
+		`  command -v "$bin" >/dev/null 2>&1 || return`,
+		`  local cur="\${COMP_WORDS[COMP_CWORD]}"`,
+		`  local out`,
+		`  out="$("$bin" completion complete --gate-options -- "\${COMP_WORDS[@]:1:COMP_CWORD-1}" "$cur" 2>/dev/null | cut -f1)"`,
+		`  local IFS=$'\\n'`,
+		`  COMPREPLY=( $(compgen -W "$out" -- "$cur") )`,
+		`}`,
+		`complete -F _${id}_complete ${shQuote(name)}`
+	].join("\n");
+	if (shell === "zsh") return [
+		`#compdef ${name}`,
+		`_${id}_complete() {`,
+		`  local bin="$words[1]"`,
+		`  command -v "$bin" >/dev/null 2>&1 || return`,
+		`  local -a lines`,
+		`  lines=( "\${(@f)$("$bin" completion complete -- "\${words[2,CURRENT-1]}" "\${words[CURRENT]}" 2>/dev/null)}" )`,
+		`  local -a disp`,
+		`  local line`,
+		`  for line in $lines; do disp+=( "\${line//$'\\t'/:}" ); done`,
+		`  _describe -t values ${shQuote(name)} disp`,
+		`}`,
+		`_${id}_complete "$@"`
+	].join("\n");
+	return [
+		`function __${id}_complete`,
+		`  set -l toks (commandline -opc)`,
+		`  set -l cur (commandline -ct)`,
+		`  set -l bin $toks[1]`,
+		`  command -q -- $bin; or test -x "$bin"; or return`,
+		`  $bin completion complete --gate-options -- $toks[2..-1] $cur 2>/dev/null`,
+		`end`,
+		`complete -c ${fishQuote(name)} -f -a '(__${id}_complete)'`
+	].join("\n");
+}
+/** Generate a completion script for `shell` from a CLI spec. */
+function getCompletion(spec, shell, mode = "runtime") {
+	if (mode === "runtime") return renderRuntimeShim(spec, shell);
+	const nodes = walk(spec);
+	switch (shell) {
+		case "bash": return renderBash(spec, nodes);
+		case "zsh": return renderZsh(spec, nodes);
+		case "fish": return renderFish(spec, nodes);
+	}
+}
+/** Resolve the argument a {@link Location} points at, or null if it's stale. */
+function resolveArg(spec, location) {
+	let command = spec;
+	let ancestorPersistent = [];
+	for (const segment of location.path) {
+		ancestorPersistent = [...ancestorPersistent, ...(command.options ?? []).filter((option) => option.isPersistent)];
+		const child = (command.subcommands ?? []).find((sub) => makeArray(sub.name).includes(segment));
+		if (!child) return null;
+		command = child;
+	}
+	let args;
+	if (location.option !== void 0) {
+		const option = [...ancestorPersistent, ...command.options ?? []].find((candidate) => makeArray(candidate.name).includes(location.option));
+		if (!option) return null;
+		args = asArray(option.args);
+	} else args = asArray(command.args);
+	return args[location.argIndex] ?? null;
+}
+/**
+* Run the generator a base64 location points at and return its suggestions as
+* insertable strings, or null if the location is invalid.
+*/
+async function generateSuggestions(spec, encoded, tokens) {
+	let location;
+	try {
+		location = decodeLocation(encoded);
+	} catch {
+		return null;
+	}
+	const arg = resolveArg(spec, location);
+	if (!arg) return null;
+	const generator = makeArray(arg.generators)[location.genIndex];
+	if (!generator?.custom) return null;
+	return (await generator.custom(tokens)).map((suggestion) => typeof suggestion === "string" ? suggestion : makeArray(suggestion.name)[0]);
+}
+/** A subcommand that prints a shell completion script for the whole CLI. */
+const completion = {
+	name: "completion",
+	description: "Print a shell completion script",
+	args: {
+		name: "shell",
+		isOptional: true,
+		suggestions: SHELLS
+	},
+	options: [{
+		name: "--runtime",
+		description: "Resolve candidates by invoking the CLI (default)",
+		exclusiveOn: ["--shell"]
+	}, {
+		name: "--shell",
+		description: "Emit a self-contained script with no per-Tab CLI call",
+		exclusiveOn: ["--runtime"]
+	}],
+	subcommands: [{
+		name: "complete",
+		description: "Resolve completion candidates for a partial command line",
+		hidden: true,
+		options: [{
+			name: "--gate-options",
+			description: "Only suggest options after a leading dash"
+		}],
+		args: {
+			name: "tokens",
+			isVariadic: true,
+			isOptional: true
+		},
+		async action({ path, args, options }) {
+			const spec = path[0];
+			const partial = args.length > 0 ? args[args.length - 1] : "";
+			const lines = (await completeRuntime({
+				spec,
+				before: args.slice(0, -1),
+				partial,
+				gateOptions: options.has("--gate-options")
+			})).map((candidate) => candidate.description ? `${candidate.value}\t${candidate.description}` : candidate.value);
+			if (lines.length > 0) print(lines.join("\n"));
+			return 0;
+		}
+	}, {
+		name: "generate-suggestions",
+		description: "Print dynamic suggestions for a completion generator",
+		hidden: true,
+		args: [{ name: "location" }, {
+			name: "tokens",
+			isVariadic: true,
+			isOptional: true
+		}],
+		async action({ path, args: [encoded, ...tokens] }) {
+			const spec = path[0];
+			if (encoded === void 0) {
+				printActionError("Missing generator location");
+				return 1;
+			}
+			const suggestions = await generateSuggestions(spec, encoded, tokens);
+			if (suggestions === null) {
+				printActionError(`Unknown generator location '${encoded}'`);
+				return 1;
+			}
+			if (suggestions.length > 0) print(suggestions.join("\n"));
+			return 0;
+		}
+	}],
+	action({ path: [spec], args: [shell], options, help }) {
+		if (shell === void 0) {
+			print(`Supported shells: ${SHELLS.join(", ")}`);
+			return 0;
+		}
+		if (!isShell(shell)) {
+			printActionError(`Unsupported shell '${shell}'\n\n${help({
+				description: false,
+				didYouMean: {
+					input: shell,
+					choices: SHELLS
+				}
+			})}`);
+			return 1;
+		}
+		print(getCompletion(spec, shell, options.has("--shell") ? "shell" : "runtime"));
+		return 0;
+	}
+};
+// src/run.ts
+/**
+* Parse argv and execute the selected action.
+*
+* The final command action runs unless a parsed option has an action. Option
+* actions take precedence so helpers like `--help` can run without satisfying
+* the selected command's required arguments.
+*/
+async function run(spec, args = defaultArgs()) {
+	let result;
+	try {
+		result = parse(args, spec);
+	} catch (error) {
+		if (error instanceof UnknownOption) {
+			const helpMessage = getHelp(error.context.path, {
+				description: false,
+				didYouMean: {
+					input: error.option,
+					choices: error.validOptions
+				}
+			});
+			printError(`${error.message}\n\n${helpMessage}`);
+		} else if (error instanceof ParseError) printError(`${error.message}\n\n${getHelp(error.context.path, { description: false })}`);
+		else printError(`${error}`);
+		return 1;
+	}
+	const action = result.optionActions.at(-1) ?? result.actions.at(-1);
+	if (!action) return 1;
+	const options = result.options;
+	const actionInit = {
+		help: (helpOptions) => getHelp(helpOptions?.path ?? result.path, helpOptions),
+		args: result.args,
+		path: result.path,
+		argSeparatorIndex: result.argSeparatorIndex,
+		options: {
+			options,
+			has: (name) => options.has(name),
+			get: (name) => options.get(name)?.[0],
+			all: (name) => options.get(name),
+			count: (name) => options.get(name)?.length ?? 0
+		}
+	};
+	let exitCode;
+	try {
+		const actionResult = action(actionInit);
+		exitCode = typeof actionResult === "object" ? await actionResult : actionResult;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+	return Math.min(Math.max(exitCode ?? 0, 0), 255);
+}
+function printError(...strings) {
+	console.error("Error:", ...strings);
+}
+function defaultArgs() {
+	return globalThis.process?.argv?.slice(2) ?? [];
+}
+// src/index.ts
+var src_default = {
+	completion,
+	help,
+	helpCommand,
+	printError,
+	run
+};
+export { completion, src_default as default, help, helpCommand, printError, run };
+
+//# sourceMappingURL=index.js.map