@clo4/cli 2.0.0 → 3.0.1

package/dist/index.js

@@ -56,9 +56,21 @@ const output = { write: writeFd };
 function print(text) {
 	output.write(1, `${text.trimEnd()}\n`);
 }
-/** Print an error message to stderr with the shared `Error:` prefix. */
-function printActionError(message) {
-	output.write(2, `Error: ${message}\n`);
+/** Print `Error:` and the given values to stderr, separated by spaces. */
+function printError(...strings) {
+	output.write(2, `${["Error:", ...strings].map(String).join(" ")}\n`);
+}
+/**
+* Add the defaults of the arguments from index `from` on to `values`, stopping
+* at the first argument without one. The parser and help both use this, so
+* help only shows the defaults the parser uses.
+*/
+function addDefaults(values, args, from = 0) {
+	for (let i = from; i < args.length; i++) {
+		const value = args[i].default;
+		if (value === void 0) return;
+		values.push(value);
+	}
 }
 /**
 * Returns the minimum number of arguments that satisfies the args.
@@ -83,76 +95,6 @@ function getMaxArgs(args) {
 	for (let i = 0; i < args.length; i++) if (args[args.length - 1 - i].isVariadic) return Infinity;
 	return args.length;
 }
-// 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(found, context) {
-		const msg = `${repr(found.option)} looks like a flag, but is unknown in this context`;
-		super(context, msg);
-		this.option = found.option;
-		this.validOptions = found.validOptions;
-		this.index = found.index;
-		this.start = found.start;
-		this.end = found.end;
-	}
-};
-var InvalidOptionArg = class extends ParseError {
-	index;
-	start;
-	end;
-	arg;
-	option;
-	constructor(found, context) {
-		const msg = `Option ${found.option} doesn't take arguments`;
-		super(context, msg);
-		this.index = found.index;
-		this.start = found.start;
-		this.end = found.end;
-		this.option = found.option;
-		this.arg = found.arg;
-	}
-};
-var TooManyArguments = class extends ParseError {
-	index;
-	value;
-	constructor(found, context) {
-		const msg = `Too many arguments, ${repr(found.value)} was unexpected`;
-		super(context, msg);
-		this.index = found.index;
-		this.value = found.value;
-	}
-};
-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/suggest.ts
 /**
 * "Did you mean" suggestions for unknown commands and options.
@@ -202,61 +144,350 @@ function editDistance(a, b, limit) {
 	}
 	return previous[b.length];
 }
+/** The first name of the only choice with a name that `matches`, if exactly one has one. */
+function onlyMatch(choices, matches) {
+	let match;
+	for (const choice of choices) {
+		const name = (typeof choice === "string" ? [choice] : choice).find(matches);
+		if (name === void 0) continue;
+		if (match !== void 0) return;
+		match = name;
+	}
+	return match;
+}
 /**
-* The choice the user most likely meant by `input`, or `undefined` if none is
+* The name the user most likely meant by `input`, or `undefined` if none is
 * close enough to be worth suggesting. In order:
 *
 * 1. The only choice that starts with the input (`--verb` for `--verbose`).
 * 2. The only choice that contains every character of the input in order, for
 *    inputs of 3 or more characters (`bld` for `build`).
-* 3. The choice with the fewest edits, allowing one edit per three characters
+* 3. The name with the fewest edits, allowing one edit per three characters
 *    of the input. Leading dashes don't count toward the length or the edits.
 */
 function closestChoice(input, choices) {
 	const inputDashes = dashCount(input);
 	const bare = input.slice(inputDashes);
 	if (bare.length >= 2) {
-		let match;
-		let count = 0;
-		for (const choice of choices) if (choice.startsWith(input)) {
-			match = choice;
-			count++;
-		}
-		if (count === 1) return match;
+		const match = onlyMatch(choices, (name) => name.startsWith(input));
+		if (match !== void 0) return match;
 	}
 	if (bare.length >= 3) {
-		let match;
-		let count = 0;
-		for (const choice of choices) if (isAbbreviation(bare, choice.slice(dashCount(choice)))) {
-			match = choice;
-			count++;
-		}
-		if (count === 1) return match;
+		const match = onlyMatch(choices, (name) => isAbbreviation(bare, name.slice(dashCount(name))));
+		if (match !== void 0) return match;
 	}
 	let best;
 	let limit = Math.floor(bare.length / 3);
-	for (const choice of choices) {
-		const other = choice.slice(dashCount(choice));
+	for (const name of choices.flat()) {
+		const other = name.slice(dashCount(name));
 		if (Math.abs(other.length - bare.length) > limit) continue;
 		const distance = editDistance(bare, other, limit);
 		if (distance <= limit && (best === void 0 || distance < limit)) {
-			best = choice;
+			best = name;
 			limit = distance;
 			if (distance === 0) break;
 		}
 	}
 	return best;
 }
-// src/help.ts
-function getNamed(named, name) {
-	return named.find((obj) => makeArray(obj.name).includes(name)) ?? null;
+// src/subcommands.ts
+/**
+* A token that names no subcommand. The reason is only worked out when asked
+* for, since most tokens the parser tries aren't subcommands.
+*/
+var NoSubcommand = class {
+	subcommands;
+	token;
+	prefixOf;
+	command = null;
+	/**
+	* `prefixOf` are the commands `token` is a prefix of a name of, where
+	* prefixes match. There is never exactly one of them.
+	*/
+	constructor(subcommands, token, prefixOf) {
+		this.subcommands = subcommands;
+		this.token = token;
+		this.prefixOf = prefixOf;
+	}
+	/** Why the token names none of the subcommands, as an error message and suggestions. */
+	reason() {
+		const token = this.token;
+		if (token === "") return { message: "Expected a command, but the value was empty" };
+		if (this.prefixOf.length > 0) return { message: `Ambiguous command '${token}', could be: ${this.prefixOf.flatMap((command) => asArray(command.name).filter((name) => name.startsWith(token))).join(", ")}` };
+		const choices = visibleSubcommands(this.subcommands).map((command) => asArray(command.name));
+		return {
+			message: `Unknown command '${token}'`,
+			didYouMean: {
+				input: token,
+				choices
+			}
+		};
+	}
+};
+/** The subcommands that help, completion and suggestions show. */
+function visibleSubcommands(subcommands) {
+	return subcommands?.filter((subcommand) => !subcommand.hidden) ?? [];
 }
-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];
+/** The action of a command that has none of its own: print the command's help. */
+const usage = ({ help }) => {
+	print(help());
+	return 0;
+};
+// src/directives.ts
+/** The directives in effect when no command sets any. */
+function defaultDirectives() {
+	return {
+		optionArgSeparators: ["="],
+		flagsArePosixNoncompliant: false,
+		optionsMustPrecedeArguments: false,
+		subcommandsMatchUniquePrefix: false
+	};
+}
+/**
+* Update `directives` for entering `command`. A subcommand inherits each
+* directive until it sets its own.
+*/
+function applyDirectives(directives, command) {
+	const configured = command.parserDirectives;
+	if (!configured) return;
+	if (configured.optionArgSeparators) directives.optionArgSeparators = asArray(configured.optionArgSeparators);
+	if (typeof configured.subcommandsMatchUniquePrefix === "boolean") directives.subcommandsMatchUniquePrefix = configured.subcommandsMatchUniquePrefix;
+	if (typeof configured.optionsMustPrecedeArguments === "boolean") directives.optionsMustPrecedeArguments = configured.optionsMustPrecedeArguments;
+	if (typeof configured.flagsArePosixNoncompliant === "boolean") directives.flagsArePosixNoncompliant = configured.flagsArePosixNoncompliant;
+}
+// src/scope.ts
+/**
+* What a name means at one command on a path: the options, subcommands,
+* directives and argument limits in effect there.
+*
+* Moving to a subcommand replaces the local options and adds its persistent
+* options to the inherited ones. A name refers to one option: a local option
+* wins over a persistent one, and a later option wins over an earlier one in
+* the same list. A subcommand wins over an option where the next token can
+* name a subcommand. The parser, help, completion and the spec checker all
+* ask this module what a name refers to, so they can't disagree.
+*/
+var CommandScope = class CommandScope {
+	/** Non-persistent options of the current command, in definition order. */
+	local = [];
+	/** Persistent options from every command on the path, in definition order. */
+	persistent = [];
+	/**
+	* Persistent subcommands of the commands above the current one, nearest
+	* command first, so a nearer one wins a name.
+	*/
+	inheritedSubcommands = [];
+	/** The directives in effect. A subcommand inherits each until it sets its own. */
+	directives = defaultDirectives();
+	current = null;
+	/** The fewest positional arguments the current command takes. */
+	argsMin = 0;
+	/** The most positional arguments the current command takes. */
+	argsMax = 0;
+	/** The scope at the last command on `path`. */
+	static at(path) {
+		const scope = new CommandScope();
+		for (const command of path) scope.enter(command);
+		return scope;
 	}
+	/** Move to `command`, a subcommand of the current one. */
+	enter(command) {
+		const parentSubcommands = this.current?.subcommands;
+		if (parentSubcommands) {
+			const persistent = parentSubcommands.filter((subcommand) => subcommand.isPersistent);
+			if (persistent.length > 0) this.inheritedSubcommands.unshift(...persistent);
+		}
+		this.current = command;
+		this.argsMin = getMinArgs(command.args);
+		this.argsMax = getMaxArgs(command.args);
+		this.local.length = 0;
+		if (command.options) for (const option of command.options) (option.isPersistent ? this.persistent : this.local).push(option);
+		applyDirectives(this.directives, command);
+	}
+	/** The current command. */
+	get command() {
+		if (!this.current) throw new Error("The scope hasn't entered a command");
+		return this.current;
+	}
+	/** Whether the current command has subcommands of its own or inherits any. */
+	get hasSubcommands() {
+		return this.current?.subcommands !== void 0 || this.inheritedSubcommands.length > 0;
+	}
+	/**
+	* The subcommands the next token can name: the current command's own,
+	* followed by each inherited one that an earlier one doesn't shadow a name
+	* of. Hidden ones are included.
+	*/
+	subcommands() {
+		const own = this.current?.subcommands ?? [];
+		if (this.inheritedSubcommands.length === 0) return own;
+		const all = [...own];
+		for (const candidate of this.inheritedSubcommands) if (!asArray(candidate.name).some((name) => all.some((earlier) => hasName(earlier.name, name)))) all.push(candidate);
+		return all;
+	}
+	/**
+	* Find the subcommand `token` names: one of the current command's own, or
+	* else an inherited persistent one. An exact name always wins. With
+	* `subcommandsMatchUniquePrefix`, a token that's a prefix of exactly one of
+	* the command's own names matches that command, unless `exactOnly`. A hidden
+	* or inherited command only matches its exact name, so it can't make a
+	* visible command's prefix ambiguous or take a prefix meant as an argument,
+	* and an empty token is no command's prefix.
+	*/
+	matchSubcommand(token, exactOnly = false) {
+		const own = this.current?.subcommands ?? [];
+		for (const candidate of own) if (hasName(candidate.name, token)) return { command: candidate };
+		for (const candidate of this.inheritedSubcommands) if (hasName(candidate.name, token)) return { command: candidate };
+		const matches = this.directives.subcommandsMatchUniquePrefix && !exactOnly ? prefixMatches(own, token) : [];
+		if (matches.length === 1) return { command: matches[0] };
+		return new NoSubcommand(this.subcommands(), token, matches);
+	}
+	/** The option `name` refers to, if any. */
+	resolve(name) {
+		const { local, persistent } = this;
+		for (let i = local.length - 1; i >= 0; i--) if (hasName(local[i].name, name)) return local[i];
+		for (let i = persistent.length - 1; i >= 0; i--) if (hasName(persistent[i].name, name)) return persistent[i];
+		return null;
+	}
+	/**
+	* The options that can be used here, in definition order, each with only
+	* its live names: the names that still refer to it. Options with every name
+	* shadowed are left out. Where the next token can name a subcommand, as
+	* `subcommands` says, a name that one matches is that subcommand's.
+	*/
+	live(subcommands = null) {
+		const owner = /* @__PURE__ */ new Map();
+		for (const options of [this.persistent, this.local]) for (const option of options) for (const name of asArray(option.name)) owner.set(name, option);
+		const pick = (options) => {
+			const picked = [];
+			for (const option of options) {
+				const names = asArray(option.name).filter((name) => owner.get(name) === option && !(subcommands && this.matchSubcommand(name, subcommands.exactOnly).command));
+				if (names.length > 0) picked.push({
+					option,
+					names
+				});
+			}
+			return picked;
+		};
+		return {
+			local: pick(this.local),
+			persistent: pick(this.persistent)
+		};
+	}
+	/**
+	* The options a user can see at the start of the current command: the
+	* {@link live} ones that aren't hidden, without the names a subcommand takes.
+	*/
+	visible() {
+		const { local, persistent } = this.live(this.hasSubcommands ? { exactOnly: false } : null);
+		const shown = (visible) => !visible.option.hidden;
+		return {
+			local: local.filter(shown),
+			persistent: persistent.filter(shown)
+		};
+	}
+	/** The live names of each option a user could have meant, for "did you mean" suggestions. */
+	suggestionNames() {
+		const { local, persistent } = this.live();
+		const shown = (visible) => !visible.option.hidden;
+		return [...local, ...persistent].filter(shown).map((visible) => visible.names);
+	}
+	/** The options that must be used, local first. */
+	required() {
+		return [...this.local, ...this.persistent].filter((option) => option.isRequired);
+	}
+	/**
+	* How each of `names` is written with `option`'s value here. Help shows
+	* these, completion offers them, and the spec checker reads each one back
+	* through the parser.
+	*/
+	forms(option, names = asArray(option.name)) {
+		const join = (name) => {
+			if (getMaxArgs(option.args) === 0) return null;
+			if (option.requiresSeparator) return this.requiredSeparator(option);
+			return !this.directives.flagsArePosixNoncompliant && (name === "-" || name === "+") ? "" : null;
+		};
+		return names.map((name) => ({
+			name,
+			join: join(name)
+		}));
+	}
+	/**
+	* The separator that must come between `option` and its value, or null if
+	* it can take a value as a separate token.
+	*/
+	requiredSeparator(option) {
+		const required = option.requiresSeparator;
+		if (typeof required === "string") return required;
+		return required ? this.directives.optionArgSeparators[0] ?? "=" : null;
+	}
+	/** Whether the parser splits an option from its value at `separator` here. */
+	readsSeparator(separator) {
+		return this.directives.optionArgSeparators.includes(separator);
+	}
+	/** The separator that `text` starts with, or "" if none. Used after a short option. */
+	leadingSeparator(text) {
+		for (const separator of this.directives.optionArgSeparators) if (text.startsWith(separator)) return separator;
+		return "";
+	}
+	/**
+	* The separator that appears first in `token`, so the value after it can
+	* contain the other separators. When two separators start at the same place,
+	* the longer one wins. Null if there's none, or if the one found is empty.
+	*/
+	firstSeparator(token) {
+		let found = "";
+		let index = -1;
+		for (const candidate of this.directives.optionArgSeparators) {
+			const at = token.indexOf(candidate);
+			if (at === -1) continue;
+			if (index === -1 || at < index || at === index && candidate.length > found.length) {
+				found = candidate;
+				index = at;
+			}
+		}
+		return found ? {
+			index,
+			separator: found
+		} : null;
+	}
+	/**
+	* Why `option`, used as `name`, can't take a value given after `separator`,
+	* or null if it can. A separate token has the separator "".
+	*/
+	separatorProblem(option, name, separator) {
+		const required = option.requiresSeparator;
+		if (typeof required === "string" && separator !== required) return `Incorrect separator, use '${required}' instead of '${separator}'`;
+		if (required === true && separator === "") return `Missing separator, use '${this.requiredSeparator(option)}' between ${name} and its value`;
+		return null;
+	}
+};
+const optionKeys = /* @__PURE__ */ new WeakMap();
+/**
+* A key for the set of `option`'s names. Options with the same names, in any
+* order, get the same key and are one option: the parser continues a
+* repeatable option's uses across them, counts one as used when the other was,
+* and stores their values under the same names, which is how they're read.
+* Options that share only some names are different options, and each shared
+* name refers to whichever one `resolve` picks.
+*/
+function optionKey(option) {
+	let key = optionKeys.get(option);
+	if (key === void 0) {
+		key = typeof option.name === "string" ? option.name : [...option.name].sort().join("\0");
+		optionKeys.set(option, key);
+	}
+	return key;
 }
+function hasName(names, name) {
+	return typeof names === "string" ? names === name : names.includes(name);
+}
+/** The visible commands that `token` is a prefix of a name of, each listed once. */
+function prefixMatches(subcommands, token) {
+	if (token === "") return [];
+	return subcommands.filter((candidate) => !candidate.hidden && asArray(candidate.name).some((name) => name.startsWith(token)));
+}
+// src/help.ts
 function dedent(str) {
 	if (str[0] !== "\n") return str;
 	const lines = str.split("\n").slice(1, -1);
@@ -273,80 +504,53 @@ function getHelp(path, config = {}) {
 	return formatHelpSections(sections);
 }
 /**
-* Action that prints usage for commands where a subcommand must be provided.
+* Print `message` as an error, then the usage and flags of the last command on
+* `path`, suggesting the closest of `didYouMean.choices` if one is close.
+*/
+function printUsageError(path, message, didYouMean) {
+	printError(`${message}\n\n${getHelp(path, {
+		description: false,
+		didYouMean
+	})}`);
+}
+/**
+* A subcommand that prints help for its parent, or for the command the names
+* after it lead to from there, so `cli help a b` prints the help of `cli a b`.
+* It reads names until one isn't a subcommand. A token where the command takes
+* arguments, or where it has no subcommands, ends the names, so
+* `cli help completion zsh` prints the help of `completion`. Any other token
+* is an unknown command. Add `{ ...helpCommand, isPersistent: true }` instead
+* to make `cli a b help` work too.
 */
-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
+		isOptional: true,
+		isVariadic: 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;
+	action({ path, args, help }) {
+		const self = path[path.length - 1];
+		const helpPath = path.slice(0, -1);
+		const scope = CommandScope.at(helpPath);
+		for (const name of args) {
+			const command = helpPath[helpPath.length - 1];
+			if (!command.subcommands) break;
+			const match = scope.matchSubcommand(name);
+			if (match.command === self && !command.subcommands.includes(self)) break;
+			if (match.command) {
+				helpPath.push(match.command);
+				scope.enter(match.command);
+				continue;
 			}
-			printActionError(`There is no subcommand named '${commandName}'\n\n${help({
-				description: false,
-				path: helpRoot
-			})}`);
+			if (!command.requiresSubcommand && getMaxArgs(command.args) > 0) break;
+			const { message, didYouMean } = match.reason();
+			printUsageError(helpPath, message, didYouMean);
 			return 1;
 		}
-		print(help({ path: [...helpRoot, command] }));
+		print(help({ path: helpPath }));
+		return 0;
 	}
 };
 /** A persistent help option that prints help for the selected command. */
@@ -362,46 +566,60 @@ const help = {
 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 scope = CommandScope.at(commands);
+	const show = ({ option, names }) => optionToString(option, scope.forms(option, names));
 	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 = [];
+	const subcommands = visibleSubcommands(command.subcommands).map((subcommand) => [makeArray1(subcommand.name).sort((a, b) => a.length - b.length).join(", "), subcommand.description ?? defaultDesc]);
+	const visible = scope.visible();
+	let optionObjects = visible.local;
+	let persistentOptionObjects = visible.persistent;
 	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]);
+		const byOption = new Map([...optionObjects, ...persistentOptionObjects].map((v) => [v.option, v]));
+		optionObjects = (command.options ?? []).flatMap((option) => byOption.get(option) ?? []);
+		persistentOptionObjects = [];
 	}
+	const row = (visible) => {
+		const defaults = [];
+		addDefaults(defaults, asArray(visible.option.args));
+		return [show(visible), withDefaults(visible.option.description, defaults, defaultDesc)];
+	};
+	const options = optionObjects.map(row);
+	const persistentOptions = persistentOptionObjects.map(row);
+	const usage = (() => {
+		const parts = [getSubcommandPathString(commands)];
+		for (const visible of [...optionObjects, ...persistentOptionObjects]) if (visible.option.isRequired) parts.push(show(visible));
+		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(" ");
+	})();
+	const positionals = command.requiresSubcommand ? [] : asArray(command.args);
 	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(" ");
-		})(),
+		usage,
 		description,
+		args: positionals.some((arg) => arg.description !== void 0 || arg.default !== void 0) ? positionals.map((arg) => [(arg.name || "argument") + (arg.isVariadic ? "..." : ""), withDefaults(arg.description, arg.default === void 0 ? [] : [arg.default], "")]) : [],
 		persistentOptions,
 		options,
 		subcommands
 	};
 }
+/**
+* A description ending with the defaults the parser uses. They go on a line of
+* their own when the last line would be too long for the 68 characters the
+* spec checks allow.
+*/
+function withDefaults(description, defaults, defaultDesc) {
+	if (defaults.length === 0) return description ?? defaultDesc;
+	const shown = `(default: ${defaults.join(" ")})`;
+	if (description === void 0) return shown;
+	return `${description}${description.slice(description.lastIndexOf("\n") + 1).length + 1 + shown.length <= 68 ? " " : "\n"}${shown}`;
+}
 function formatHelpSections(sections) {
 	const parts = [];
 	const indent = "  ";
@@ -410,17 +628,26 @@ function formatHelpSections(sections) {
 	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 formatRows = (rows, width) => {
 		const lines = [];
-		const newline = indent + " ".repeat(longestOptionName + minSpacingBetweenNameAndDesc);
-		for (const [name, desc] of options) {
-			const spaces = " ".repeat(longestOptionName - name.length + minSpacingBetweenNameAndDesc);
+		const newline = indent + " ".repeat(width + minSpacingBetweenNameAndDesc);
+		for (const [name, desc] of rows) {
+			if (desc === "") {
+				lines.push(`${indent}${name}`);
+				continue;
+			}
+			const spaces = " ".repeat(width - 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;
 	};
+	const formatOptions = (options) => formatRows(options, longestOptionName);
+	if (sections.args.length > 0) {
+		const longestArgName = Math.max(...sections.args.map(([name]) => name.length));
+		parts.push(["Arguments:", ...formatRows(sections.args, longestArgName)].join("\n"));
+	}
 	if (sections.subcommands.length > 0) {
 		const lines = ["Commands:"];
 		const longestName = Math.max(...sections.subcommands.map(([name]) => name.length));
@@ -451,16 +678,25 @@ function getLongestString(strings) {
 	}
 	return longest;
 }
-function optionToString(option) {
-	const name = makeArray1(option.name).sort((a, b) => a.length - b.length).join(", ");
+/**
+* Show an option's names, each written with its arguments the way `forms`
+* says. Names written the same way share one copy of the arguments.
+*/
+function optionToString(option, forms) {
 	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)}`;
+	const sorted = [...forms].sort((a, b) => a.name.length - b.name.length);
+	return [...new Set(sorted.map((form) => form.join))].map((join) => {
+		return sorted.filter((form) => form.join === join).map((form) => form.name).join(", ") + argumentsAfterName(optionArgs, join);
+	}).join(", ");
+}
+/** The text after an option's name that shows its arguments, joined to the name by `join`. */
+function argumentsAfterName(args, join) {
+	if (args.length === 0) return "";
+	if (join === null) return ` ${summarizeArguments(args)}`;
+	const [first, ...rest] = args;
+	const name = first.name || "argument";
+	const joined = (first.isOptional ? `[${join}${name}]` : `${join}<${name}>`) + (first.isVariadic ? "..." : "");
+	return rest.length > 0 ? `${joined} ${summarizeArguments(rest)}` : joined;
 }
 function summarizeArguments(args) {
 	return args.map((arg) => argToString(arg)).join(" ");
@@ -477,358 +713,547 @@ function argToString(arg) {
 	if (arg.isVariadic) suffix = "...";
 	return `${lhs}${name}${rhs}${suffix}`;
 }
+// src/errors.ts
+const repr = JSON.stringify;
+/**
+* A command line the parser can't accept. `run` prints the message with the
+* help for the command at `context.path`, and suggests the closest of
+* `didYouMean.choices` if there is one.
+*/
+var ParseError = class extends Error {
+	context;
+	didYouMean;
+	constructor(context, message, didYouMean) {
+		super(message);
+		this.context = context;
+		this.didYouMean = didYouMean;
+		this.name = this.constructor.name;
+	}
+};
+var UnknownOption = class extends ParseError {
+	option;
+	constructor(option, validOptions, context) {
+		const msg = `${repr(option)} looks like a flag, but is unknown in this context`;
+		super(context, msg, {
+			input: option,
+			choices: validOptions
+		});
+		this.option = option;
+	}
+};
+var InvalidOptionArg = class extends ParseError {
+	option;
+	constructor(option, context) {
+		super(context, `Option ${option} doesn't take arguments`);
+		this.option = option;
+	}
+};
+var TooManyArguments = class extends ParseError {
+	constructor(value, context) {
+		super(context, `Too many arguments, ${repr(value)} was unexpected`);
+	}
+};
+var TooFewOptionArguments = class extends ParseError {
+	constructor(option, min, max, context) {
+		const msg = min === max ? `Option ${option} needs ${min} argument${min === 1 ? "" : "s"}` : !Number.isFinite(max) ? `Option ${option} needs at least ${min} argument${min === 1 ? "" : "s"}` : `Option ${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/parse.ts
-function hasName(names, name) {
-	return typeof names === "string" ? names === name : names.includes(name);
+/** How many times `option` can be used. */
+function repeatLimit(option) {
+	return typeof option.isRepeatable === "number" ? option.isRepeatable : Infinity;
 }
 /**
-* Find the option `name` refers to. Local options win over persistent ones, and
-* within each list a later definition wins over an earlier one.
+* Throw if the options used break a `dependsOn` or `exclusiveOn` rule, or if
+* any of `required` is missing.
 */
-function findOption(local, persistent, name) {
-	for (let i = local.length - 1; i >= 0; i--) if (hasName(local[i].name, name)) return local[i];
-	for (let i = persistent.length - 1; i >= 0; i--) if (hasName(persistent[i].name, name)) return persistent[i];
-	return null;
-}
-/** Every name that's valid as an option here, for "did you mean" suggestions. */
-function optionNames(local, persistent) {
-	const names = [];
-	for (const options of [local, persistent]) {
-		const seen = /* @__PURE__ */ new Set();
-		for (const option of options) for (const name of asArray(option.name)) if (!seen.has(name)) {
-			seen.add(name);
-			names.push(name);
-		}
+function checkOptionRules(options, seenOptions, required, context) {
+	for (const option of seenOptions) {
+		if (!option.dependsOn) continue;
+		for (const name of option.dependsOn) if (!options.has(name)) throw new ParseError(context, `${asArray(option.name).join("/")} requires ${name}, add it to fix this error`);
+	}
+	for (const option of seenOptions) {
+		if (!option.exclusiveOn) continue;
+		for (const name of option.exclusiveOn) if (options.has(name)) throw new ParseError(context, `${asArray(option.name).join("/")} can't be used together with ${name}`);
 	}
-	return names;
+	for (const option of required) for (const name of asArray(option.name)) if (!options.has(name)) throw new MissingRequiredOption(name, context);
 }
 /**
-* Read a command line against a spec in one pass.
-*
-* This is the only code that decides what each input token is. With `strict`,
-* it throws on the first problem, which is what {@link parse} needs. Without
-* it, it never throws: it skips whatever is invalid and keeps going, so
-* completion can still read a line that's wrong at the moment.
-*
-* This runs once per process, so it's written for a cold start: one loop, few
-* helper functions and plain arrays, because every extra function is compiled
-* the first time it runs.
+* The state of reading one command line, one token at a time. This is the
+* only code that decides what each input token is. It never throws: it skips
+* whatever is invalid and keeps going, so {@link readNext} can still read a
+* line that's wrong at the moment, and it keeps the first problem it finds for
+* {@link parse} to throw. Each method handles one kind of token, and says what
+* the token was read as.
 */
-function scan(input, spec, strict) {
-	const path = [spec];
-	const actions = [];
-	const optionActions = [];
-	const args = [];
-	const options = /* @__PURE__ */ new Map();
-	const seenOptions = [];
-	let argSeparatorIndex = -1;
-	let local = [];
-	const persistent = [];
-	const localRequired = [];
-	const persistentRequired = [];
-	let subcommands;
-	let commandArgsMin = 0;
-	let commandArgsMax = 0;
-	let separators = ["="];
-	let posixCompliantOptions = true;
-	let subcommandsMatchUniquePrefix = false;
-	let optionsMustPrecedeArguments = false;
-	let hasFoundArg = false;
-	let openOption = null;
-	let openOptionName = "";
-	let valueCount = 0;
-	let valueMin = 0;
-	let separateValueMax = 0;
-	let values = null;
-	let valuesStart = 0;
-	let valuesMin = 0;
-	let valuesMax = 0;
-	let requiredSeparator = false;
-	const repeatCounts = /* @__PURE__ */ new Map();
-	const ctx = () => ({ path });
-	const enterCommand = (command) => {
-		local = [];
-		localRequired.length = 0;
-		if (command.options) for (const option of command.options) if (option.isPersistent) {
-			persistent.push(option);
-			if (option.isRequired) persistentRequired.push(option);
-		} else {
-			local.push(option);
-			if (option.isRequired) localRequired.push(option);
+var Scanner = class {
+	path;
+	optionAction = void 0;
+	args = [];
+	options = /* @__PURE__ */ new Map();
+	seenOptions = [];
+	argSeparatorIndex = -1;
+	scope = new CommandScope();
+	directives = this.scope.directives;
+	hasFoundArg = false;
+	openOption = null;
+	openOptionName = "";
+	valueCount = 0;
+	valueMin = 0;
+	separateValueMax = 0;
+	values = null;
+	valuesStart = 0;
+	valuesMin = 0;
+	valuesMax = 0;
+	valueArgs = [];
+	/**
+	* Makes the error for the first token that can't be read the way it's
+	* written, like an unknown option or a value an option doesn't take.
+	* {@link parse} stops there.
+	*/
+	problem = null;
+	tooManyArgs = null;
+	repeatedUses = /* @__PURE__ */ new Map();
+	constructor(spec) {
+		this.path = [spec];
+		this.scope.enter(spec);
+	}
+	ctx() {
+		return { path: [...this.path] };
+	}
+	/** Whether the open option can take the next token as a value. */
+	get hasRoomForValue() {
+		return this.valueCount < this.separateValueMax;
+	}
+	findOption(name) {
+		return this.scope.resolve(name);
+	}
+	/**
+	* Keep the problem `make` describes if it's the first. The error is only
+	* made if {@link parse} throws it, since a lenient read never needs it and
+	* an error is slow to make. So `make` can't read anything later tokens change.
+	*/
+	fail(make) {
+		if (!this.problem) {
+			const ctx = this.ctx();
+			this.problem = () => make(ctx);
 		}
-		subcommands = command.subcommands;
-		commandArgsMin = getMinArgs(command.args);
-		commandArgsMax = getMaxArgs(command.args);
-		if (command.action) actions.push(command.action);
-		else if (command.requiresSubcommand) actions.push(usage);
-		const directives = command.parserDirectives;
-		if (directives) {
-			if (directives.optionArgSeparators) separators = asArray(directives.optionArgSeparators);
-			if (typeof directives.subcommandsMatchUniquePrefix === "boolean") subcommandsMatchUniquePrefix = directives.subcommandsMatchUniquePrefix;
-			if (typeof directives.optionsMustPrecedeArguments === "boolean") optionsMustPrecedeArguments = directives.optionsMustPrecedeArguments;
-			if (typeof directives.flagsArePosixNoncompliant === "boolean") posixCompliantOptions = !directives.flagsArePosixNoncompliant;
+	}
+	/** Keep the first argument the command has no room for, like {@link fail}. */
+	failArgs(make) {
+		if (!this.tooManyArgs) {
+			const ctx = this.ctx();
+			this.tooManyArgs = () => make(ctx);
 		}
-	};
-	const endOption = () => {
-		if (strict && values && values.length - valuesStart < valuesMin) throw new TooFewOptionArguments(valuesMin, valuesMax, ctx());
-		values = null;
-	};
-	const useOption = (option, name) => {
-		endOption();
-		openOption = option;
-		openOptionName = name;
-		valueCount = 0;
-		valueMin = getMinArgs(option.args);
-		separateValueMax = option.requiresSeparator ? 0 : getMaxArgs(option.args);
-		seenOptions.push(option);
-		if (option.action) optionActions.push(option.action);
+	}
+	unknownOption(option) {
+		if (!this.problem) {
+			const names = this.scope.suggestionNames();
+			this.fail((ctx) => new UnknownOption(option, names, ctx));
+		}
+	}
+	endOption() {
+		const values = this.values;
+		if (values) {
+			const given = values.length - this.valuesStart;
+			if (given < this.valuesMin) {
+				const { openOptionName, valuesMin, valuesMax } = this;
+				this.fail((ctx) => new TooFewOptionArguments(openOptionName, valuesMin, valuesMax, ctx));
+			} else addDefaults(values, this.valueArgs, given);
+		}
+		this.values = null;
+	}
+	/** End the open option, so no later token can be its value. */
+	closeOption() {
+		this.endOption();
+		this.openOption = null;
+		this.valueCount = this.valueMin = this.separateValueMax = 0;
+	}
+	useOption(option, name) {
+		this.endOption();
+		this.openOption = option;
+		this.openOptionName = name;
+		this.valueCount = 0;
+		this.valueMin = getMinArgs(option.args);
+		this.separateValueMax = option.requiresSeparator ? 0 : getMaxArgs(option.args);
+		this.seenOptions.push(option);
+		if (option.action) this.optionAction = option.action;
 		const names = asArray(option.name);
+		const options = this.options;
 		let optionValues;
 		if (option.isRepeatable) {
-			const maxRepeat = option.isRepeatable === true ? Infinity : option.isRepeatable;
-			const existing = options.get(names[0]);
-			let isSharedCount = true;
-			for (const other of names) if (options.get(other) !== existing) isSharedCount = false;
-			let uses = isSharedCount ? existing : void 0;
+			const key = optionKey(option);
+			let uses = this.repeatedUses.get(key);
 			if (!uses) {
-				uses = [];
-				for (const other of names) options.set(other, uses);
+				uses = {
+					values: [],
+					count: 0
+				};
+				this.repeatedUses.set(key, uses);
 			}
-			const count = repeatCounts.get(uses) ?? uses.length;
-			if (strict && count >= maxRepeat) throw new ParseError(ctx(), "Too many repetitions");
-			repeatCounts.set(uses, count + 1);
+			if (uses.count >= repeatLimit(option)) this.fail((ctx) => new ParseError(ctx, "Too many repetitions"));
+			uses.count += 1;
+			for (const other of names) options.set(other, uses.values);
 			if (!option.args) {
-				uses.push("");
+				uses.values.push("");
 				return;
 			}
-			optionValues = uses;
+			optionValues = uses.values;
 		} else {
 			optionValues = [];
 			for (const other of names) options.set(other, optionValues);
 		}
-		valuesMin = valueMin;
-		valuesMax = getMaxArgs(option.args);
-		requiredSeparator = option.requiresSeparator ?? false;
-		if (valuesMax > 0) {
-			values = optionValues;
-			valuesStart = optionValues.length;
+		this.valuesMin = this.valueMin;
+		this.valuesMax = getMaxArgs(option.args);
+		if (this.valuesMax > 0) {
+			this.values = optionValues;
+			this.valuesStart = optionValues.length;
+			this.valueArgs = asArray(option.args);
 		}
-	};
-	const addValue = (index, start, end, value, separator) => {
-		valueCount += 1;
-		if (!values) {
-			if (strict) throw new InvalidOptionArg({
-				option: openOptionName,
-				arg: value,
-				index,
-				start,
-				end
-			}, ctx());
-			return;
+	}
+	/** Add a value to the open option. Returns whether it's a value the option accepts. */
+	addValue(value, separator) {
+		this.valueCount += 1;
+		if (!this.values) {
+			const name = this.openOptionName;
+			this.fail((ctx) => new InvalidOptionArg(name, ctx));
+			return false;
 		}
-		if (strict && typeof requiredSeparator === "string" && separator !== requiredSeparator) throw new ParseError(ctx(), `Incorrect separator, use '${requiredSeparator}' instead of '${separator}'`);
-		values.push(value);
-	};
-	const addArg = (index, value) => {
-		endOption();
-		if (strict && !path[path.length - 1].requiresSubcommand && args.length >= commandArgsMax) throw new TooManyArguments({
-			value,
-			index
-		}, ctx());
-		args.push(value);
-	};
-	enterCommand(spec);
-	tokens: for (let index = 0; index < input.length; index++) {
-		const token = input[index];
-		if (token === "--") {
-			endOption();
-			if (strict && args.length >= commandArgsMax) throw new ParseError(ctx(), "Unexpected argument '--', did you mean to use an option instead?");
-			argSeparatorIndex = args.length;
-			openOption = null;
-			valueCount = valueMin = separateValueMax = 0;
-			for (index += 1; index < input.length; index++) addArg(index, input[index]);
-			break tokens;
+		const problem = this.scope.separatorProblem(this.openOption, this.openOptionName, separator);
+		if (problem) this.fail((ctx) => new ParseError(ctx, problem));
+		this.values.push(value);
+		return problem === null;
+	}
+	/** Add a separate token as a value of the open option. */
+	value(token) {
+		this.addValue(token, "");
+		return {
+			kind: "value",
+			option: this.openOption
+		};
+	}
+	/**
+	* Add a value attached to the option's own token, starting at `start`. It's
+	* the option's only value, so no later token can be one. Returns where the
+	* value starts, or null if the option doesn't accept it.
+	*/
+	addAttachedValue(start, value, separator) {
+		const option = this.openOption;
+		const accepted = this.addValue(value, separator);
+		this.valueMin = this.separateValueMax = 0;
+		return accepted ? {
+			option,
+			start
+		} : null;
+	}
+	/**
+	* Whether the command already has all the arguments it takes. A command that
+	* requires a subcommand takes none.
+	*/
+	get argsAreFull() {
+		return this.scope.command.requiresSubcommand === true || this.args.length >= this.scope.argsMax;
+	}
+	addArg(value) {
+		this.endOption();
+		if (this.argsAreFull) this.failArgs((ctx) => new TooManyArguments(value, ctx));
+		this.args.push(value);
+		return { kind: "argument" };
+	}
+	/** Read `--`. Every token after it is an argument. */
+	argSeparator() {
+		this.closeOption();
+		const command = this.scope.command;
+		if (this.argsAreFull && !command.requiresSubcommand) this.failArgs((ctx) => new ParseError(ctx, "Unexpected argument '--', did you mean to use an option instead?"));
+		this.argSeparatorIndex = this.args.length;
+		return { kind: "separator" };
+	}
+	/**
+	* How the next token can name a subcommand, its own or an inherited one, or
+	* null if it can't. It can't once an argument is found, or while the open
+	* option needs the next token as its value. A required or variadic option
+	* value takes priority over a subcommand. A short optional value could be a
+	* prefix of a subcommand's name, so only an exact name can end an option
+	* that still has room.
+	*/
+	get subcommandMatching() {
+		if (this.hasFoundArg || !this.scope.hasSubcommands) return null;
+		if (this.valueCount < this.valueMin || this.hasRoomForValue && this.separateValueMax === Infinity) return null;
+		return { exactOnly: this.hasRoomForValue };
+	}
+	/**
+	* The subcommand the next token enters if it's `token`, or why it enters
+	* none. Null if the next token can't be a subcommand at all.
+	*/
+	subcommandFor(token) {
+		const matching = this.subcommandMatching;
+		return matching && this.scope.matchSubcommand(token, matching.exactOnly);
+	}
+	enterSubcommand(command) {
+		this.closeOption();
+		this.path.push(command);
+		this.scope.enter(command);
+		return {
+			kind: "subcommand",
+			command
+		};
+	}
+	/** Read a token like `-abc`, `+x` or `-ovalue`. */
+	shortOptions(token) {
+		const leadingChar = token[0];
+		const dashOption = this.findOption(leadingChar);
+		if (dashOption?.args && !this.findOption(token.slice(0, 2))) {
+			this.useOption(dashOption, leadingChar);
+			const attached = this.addAttachedValue(1, token.slice(1), "");
+			return {
+				kind: "options",
+				options: [dashOption],
+				attached
+			};
 		}
-		const hasRoomForValue = valueCount < separateValueMax;
-		if (!hasFoundArg && !(valueCount < valueMin || hasRoomForValue && separateValueMax === Infinity) && subcommands) {
-			const allowPrefix = subcommandsMatchUniquePrefix && !hasRoomForValue && token !== "";
-			let command = null;
-			let prefixCount = 0;
-			commands: for (const candidate of subcommands) {
-				const names = candidate.name;
-				if (typeof names === "string") {
-					if (names === token) {
-						command = candidate;
-						prefixCount = -1;
-						break commands;
-					}
-					if (allowPrefix && names.startsWith(token)) {
-						command = candidate;
-						prefixCount += 1;
-					}
-					continue commands;
-				}
-				let prefixMatched = false;
-				for (const name of names) {
-					if (name === token) {
-						command = candidate;
-						prefixCount = -1;
-						break commands;
-					}
-					if (allowPrefix && !prefixMatched && name.startsWith(token)) {
-						prefixMatched = true;
-						command = candidate;
-						prefixCount += 1;
-					}
-				}
+		const used = [];
+		let attached = null;
+		for (let char = 1; char < token.length; char++) {
+			const optionName = leadingChar + token[char];
+			const option = this.findOption(optionName);
+			if (!option) {
+				if (char === 1 && this.hasRoomForValue) return this.value(token);
+				this.unknownOption(optionName);
+				continue;
 			}
-			if (command && (prefixCount === -1 || prefixCount === 1)) {
-				endOption();
-				openOption = null;
-				valueCount = valueMin = separateValueMax = 0;
-				path.push(command);
-				enterCommand(command);
-				continue tokens;
+			this.useOption(option, optionName);
+			used.push(option);
+			if (char === token.length - 1) break;
+			const sep = this.scope.leadingSeparator(token.slice(char + 1));
+			if (option.args || sep && !this.findOption(leadingChar + token[char + 1])) {
+				const argStart = char + sep.length + 1;
+				attached = this.addAttachedValue(argStart, token.slice(argStart), sep);
+				break;
 			}
 		}
-		if (!(optionsMustPrecedeArguments && hasFoundArg)) {
-			const first = token.charCodeAt(0);
-			const isDoubleDash = first === 45 && token.charCodeAt(1) === 45;
-			if (posixCompliantOptions && token.length > 1 && (first === 45 || first === 43) && !isDoubleDash) {
-				const leadingChar = token[0];
-				const dashOption = findOption(local, persistent, leadingChar);
-				if (dashOption?.args && !findOption(local, persistent, token.slice(0, 2))) {
-					useOption(dashOption, leadingChar);
-					addValue(index, 1, token.length, token.slice(1), "");
-					continue tokens;
-				}
-				for (let char = 1; char < token.length; char++) {
-					const optionName = leadingChar + token[char];
-					const option = findOption(local, persistent, optionName);
-					if (!option) {
-						if (char === 1 && valueCount < separateValueMax) {
-							addValue(index, 0, token.length, token, "");
-							continue tokens;
-						}
-						if (strict) throw new UnknownOption({
-							option: optionName,
-							validOptions: optionNames(local, persistent),
-							index,
-							start: char,
-							end: char + 1
-						}, ctx());
-						continue;
-					}
-					useOption(option, optionName);
-					if (option.args && char < token.length - 1) {
-						const remainingChars = token.slice(char + 1);
-						let sep = "";
-						for (const candidate of separators) if (remainingChars.startsWith(candidate)) {
-							sep = candidate;
-							break;
-						}
-						const argStart = char + sep.length + 1;
-						addValue(index, argStart, token.length, token.slice(argStart), sep);
-						break;
-					}
-				}
-				continue tokens;
-			}
-			if (!posixCompliantOptions || token.length > 2 && isDoubleDash) {
-				let foundSep = "";
-				let foundSepIndex = -1;
-				for (const sep of separators) {
-					const at = token.indexOf(sep);
-					if (at === -1) continue;
-					if (foundSepIndex === -1 || at < foundSepIndex || at === foundSepIndex && sep.length > foundSep.length) {
-						foundSep = sep;
-						foundSepIndex = at;
-					}
-				}
-				const optionName = foundSep ? token.slice(0, foundSepIndex) : token;
-				const option = findOption(local, persistent, optionName);
-				if (option) {
-					useOption(option, optionName);
-					if (foundSep) {
-						const valueStart = foundSepIndex + foundSep.length;
-						addValue(index, valueStart, token.length, token.slice(valueStart), foundSep);
-					}
-					continue tokens;
-				}
-				if (posixCompliantOptions) {
-					if (valueCount < separateValueMax) {
-						addValue(index, 0, token.length, token, "");
-						continue tokens;
-					}
-					if (strict) throw new UnknownOption({
-						option: optionName,
-						validOptions: optionNames(local, persistent),
-						index,
-						start: 0,
-						end: optionName.length
-					}, ctx());
-					continue tokens;
-				}
+		return used.length > 0 ? {
+			kind: "options",
+			options: used,
+			attached
+		} : { kind: "unknown" };
+	}
+	/**
+	* Read a token like `--name` or `--name=value`, or any token when options
+	* aren't POSIX compliant. Returns null if the token should be an argument.
+	*/
+	longOption(token) {
+		const found = this.scope.firstSeparator(token);
+		const optionName = found ? token.slice(0, found.index) : token;
+		const option = this.findOption(optionName);
+		if (option) {
+			this.useOption(option, optionName);
+			let attached = null;
+			if (found) {
+				const valueStart = found.index + found.separator.length;
+				attached = this.addAttachedValue(valueStart, token.slice(valueStart), found.separator);
 			}
+			return {
+				kind: "options",
+				options: [option],
+				attached
+			};
 		}
-		if (valueCount < separateValueMax) {
-			addValue(index, 0, token.length, token, "");
-			continue tokens;
-		}
-		hasFoundArg = true;
-		addArg(index, token);
-	}
-	if (strict) {
-		const hasOptionAction = optionActions.length > 0;
-		if (!hasOptionAction && args.length < commandArgsMin) throw new TooFewArguments(commandArgsMin, commandArgsMax, ctx());
-		endOption();
-		for (const option of seenOptions) {
-			if (!option.dependsOn) continue;
-			for (const name of option.dependsOn) if (!options.has(name)) throw new ParseError(ctx(), `${asArray(option.name).join("/")} requires ${name}, add it to fix this error`);
+		if (this.directives.flagsArePosixNoncompliant) return null;
+		if (this.hasRoomForValue) return this.value(token);
+		this.unknownOption(optionName);
+		return { kind: "unknown" };
+	}
+	/**
+	* Read a token that isn't `--`, a subcommand or an option. It's a value of
+	* the open option if that has room, and otherwise an argument, which stops
+	* later tokens from being subcommands. `unmatched` is why the token isn't a
+	* subcommand, if it could have been one.
+	*/
+	valueOrArg(token, unmatched) {
+		if (this.hasRoomForValue) return this.value(token);
+		if (unmatched && this.argsAreFull) {
+			const command = this.scope.command;
+			if (command.subcommands?.length || command.requiresSubcommand) this.failArgs((ctx) => {
+				const { message, didYouMean } = unmatched.reason();
+				return new ParseError(ctx, message, didYouMean);
+			});
 		}
-		for (const option of seenOptions) {
-			if (!option.exclusiveOn) continue;
-			for (const name of option.exclusiveOn) if (options.has(name)) throw new ParseError(ctx(), `${asArray(option.name).join("/")} can't be used together with ${name}`);
+		this.hasFoundArg = true;
+		return this.addArg(token);
+	}
+	/**
+	* Throw if the finished command line is missing anything. Returns what it
+	* was parsed as. Only call this when there's no {@link problem}.
+	*/
+	finish() {
+		const command = this.scope.command;
+		const showsUsage = command.requiresSubcommand && !command.action && this.args.length === 0;
+		const skipsChecks = this.optionAction !== void 0 || showsUsage;
+		if (!skipsChecks && this.tooManyArgs) throw this.tooManyArgs();
+		if (!skipsChecks && this.args.length < this.scope.argsMin) throw new TooFewArguments(this.scope.argsMin, this.scope.argsMax, this.ctx());
+		this.endOption();
+		if (this.problem) throw this.problem();
+		if (!skipsChecks) checkOptionRules(this.options, this.seenOptions, this.scope.required(), this.ctx());
+		if (!command.requiresSubcommand && this.args.length >= this.scope.argsMin) addDefaults(this.args, asArray(command.args), this.args.length);
+		return {
+			path: this.path,
+			action: this.optionAction ?? command.action ?? usage,
+			args: this.args,
+			argSeparatorIndex: this.argSeparatorIndex,
+			options: this.options,
+			defaults: (name) => this.defaults(name)
+		};
+	}
+	/** See {@link ParseResult.defaults}. */
+	defaults(name) {
+		if (this.options.has(name)) return;
+		const args = asArray(this.scope.resolve(name)?.args);
+		if (args.length === 0 || args[0].isOptional) return;
+		const values = [];
+		addDefaults(values, args);
+		return values.length > 0 ? values : void 0;
+	}
+	/** Whether using `option` next would go over its repeat limit or break an `exclusiveOn` rule. */
+	conflicts(option) {
+		if ((this.repeatedUses.get(optionKey(option))?.count ?? 0) >= repeatLimit(option)) return true;
+		const options = this.options;
+		if (option.exclusiveOn?.some((name) => options.has(name))) return true;
+		const names = asArray(option.name);
+		return this.seenOptions.some((seen) => seen.exclusiveOn?.some((name) => names.includes(name)));
+	}
+	/** The options the next token can use. See {@link NextToken.options}. */
+	usableOptions() {
+		const used = new Set(this.seenOptions.map(optionKey));
+		const { local, persistent } = this.scope.live(this.subcommandMatching);
+		const usable = [];
+		for (const { option, names } of [...local, ...persistent]) {
+			if (this.conflicts(option)) continue;
+			usable.push({
+				option,
+				forms: this.scope.forms(option, names),
+				used: used.has(optionKey(option))
+			});
 		}
-		if (!hasOptionAction) {
-			for (const required of [localRequired, persistentRequired]) for (const option of required) for (const name of asArray(option.name)) if (!options.has(name)) throw new MissingRequiredOption(name, ctx());
+		return usable;
+	}
+	/**
+	* What the next token can be. See {@link readNext}. Reading more tokens
+	* doesn't change what this returns.
+	*/
+	next() {
+		const open = this.openOption && this.hasRoomForValue ? this.openOption : null;
+		const command = this.scope.command;
+		const afterSeparator = this.argSeparatorIndex !== -1;
+		const optionsAllowed = !afterSeparator && this.optionsAllowed;
+		return {
+			path: [...this.path],
+			directives: { ...this.directives },
+			optionsAllowed,
+			subcommands: !afterSeparator && this.subcommandMatching ? this.scope.subcommands() : [],
+			options: optionsAllowed ? this.usableOptions() : [],
+			value: open && {
+				option: open,
+				arg: argAt(asArray(open.args), this.valueCount),
+				required: this.valueCount < this.valueMin
+			},
+			arg: open ? void 0 : argAt(asArray(command.args), this.args.length)
+		};
+	}
+	/** Whether the next token can be an option. Once options must stop, every token is an argument. */
+	get optionsAllowed() {
+		return !(this.directives.optionsMustPrecedeArguments && this.hasFoundArg);
+	}
+	read(token) {
+		if (this.argSeparatorIndex !== -1) return this.addArg(token);
+		const optionsAllowed = this.optionsAllowed;
+		if (token === "--" && optionsAllowed) return this.argSeparator();
+		const subcommand = this.subcommandFor(token);
+		if (subcommand?.command) return this.enterSubcommand(subcommand.command);
+		if (optionsAllowed) {
+			const flagsArePosixNoncompliant = this.directives.flagsArePosixNoncompliant;
+			const first = token.charCodeAt(0);
+			const isDoubleDash = first === 45 && token.charCodeAt(1) === 45;
+			if (!flagsArePosixNoncompliant && token.length > 1 && (first === 45 || first === 43) && !isDoubleDash) return this.shortOptions(token);
+			if (flagsArePosixNoncompliant || token.length > 2 && isDoubleDash) {
+				const reading = this.longOption(token);
+				if (reading) return reading;
+			}
 		}
+		return this.valueOrArg(token, subcommand);
+	}
+};
+/** The argument at `index`, reusing a final variadic argument. */
+function argAt(args, index) {
+	if (index < args.length) return args[index];
+	const last = args[args.length - 1];
+	return last?.isVariadic ? last : void 0;
+}
+/**
+* Work out what the token after `before` can be, and how the parser reads
+* `partial`: whether it's an option, and if so, whether it has a value
+* attached. Reads leniently, so a line that's wrong at the moment still has
+* an answer. Completion is built on this.
+*/
+function readNext(spec, before, partial) {
+	const s = new Scanner(spec);
+	for (const token of before) s.read(token);
+	const next = s.next();
+	let attached = null;
+	let partialIsOption = false;
+	if (partial !== "" && next.optionsAllowed) {
+		const reading = s.read(partial);
+		partialIsOption = reading.kind === "options" || reading.kind === "unknown" || reading.kind === "separator";
+		const found = reading.kind === "options" ? reading.attached : null;
+		const arg = found && asArray(found.option.args)[0];
+		if (found && arg) attached = {
+			option: found.option,
+			arg,
+			prefix: partial.slice(0, found.start),
+			value: partial.slice(found.start)
+		};
 	}
-	const open = openOption;
 	return {
-		path,
-		actions,
-		optionActions,
-		args,
-		argSeparatorIndex,
-		options,
-		seenOptions,
-		localOptions: local,
-		persistentOptions: persistent,
-		openOption: open && valueCount < separateValueMax ? {
-			option: open,
-			valueCount
-		} : null
+		...next,
+		attached,
+		partialIsOption
 	};
 }
 /**
 * 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.
+* subcommands used, the provided options, the arguments, and the action to
+* run.
 *
 * If parsing fails, this function throws.
-*
-* This function is exposed to make it easier to build a custom runner.
 */
 function parse(input, spec) {
-	return scan(input, spec, true);
+	const s = new Scanner(spec);
+	for (const token of input) {
+		s.read(token);
+		if (s.problem) throw s.problem();
+	}
+	return s.finish();
 }
 // src/completion.ts
 const SHELLS = [
 	"bash",
 	"zsh",
-	"fish"
+	"fish",
+	"powershell",
+	"nushell"
 ];
 function isShell(value) {
 	return SHELLS.includes(value);
@@ -844,73 +1269,30 @@ function shQuote(value) {
 function fishQuote(value) {
 	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
 }
+/** Single-quote a string for PowerShell (a quote is written twice). */
+function psQuote(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
 /**
-* Read the line typed so far with the parser in lenient mode, which skips
-* anything invalid instead of throwing.
+* Quote a string for Nushell. A single-quoted string has no escapes, so a name
+* with a quote in it is written as a double-quoted string instead.
 */
-function readLine(spec, before) {
-	const scanned = scan(before, spec, false);
-	const path = scanned.path;
-	const presentNames = /* @__PURE__ */ new Set();
-	const countByOption = /* @__PURE__ */ new Map();
-	for (const option of scanned.seenOptions) {
-		for (const name of makeArray(option.name)) presentNames.add(name);
-		countByOption.set(option, (countByOption.get(option) ?? 0) + 1);
-	}
-	const open = scanned.openOption;
-	const pending = open ? {
-		option: open.option,
-		argIndex: open.valueCount
-	} : null;
-	const availableOptions = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const list of [scanned.localOptions, scanned.persistentOptions]) {
-		const byName = /* @__PURE__ */ new Map();
-		for (const option of list) for (const name of makeArray(option.name)) byName.set(name, option);
-		for (const option of byName.values()) if (!seen.has(option)) {
-			seen.add(option);
-			availableOptions.push(option);
-		}
-	}
-	return {
-		path,
-		current: path[path.length - 1],
-		availableOptions,
-		pending,
-		positionalIndex: scanned.args.length,
-		presentNames,
-		countByOption,
-		forceArgs: scanned.argSeparatorIndex !== -1,
-		sawPositional: scanned.args.length > 0
-	};
-}
-/** A directive's value in effect (the deepest command that sets it). */
-function directiveOnPath(path, key) {
-	for (let i = path.length - 1; i >= 0; i--) {
-		const value = path[i].parserDirectives?.[key];
-		if (typeof value === "boolean") return value;
-	}
-	return false;
-}
-/** 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;
+function nuQuote(value) {
+	if (!value.includes("'")) return `'${value}'`;
+	return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
 }
 /** 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 isWindows = globalThis.process?.platform === "win32";
+	const slash = Math.max(partial.lastIndexOf("/"), isWindows ? partial.lastIndexOf("\\") : -1);
 	const dir = slash >= 0 ? partial.slice(0, slash + 1) : "";
 	const base = slash >= 0 ? partial.slice(slash + 1) : partial;
+	const separator = slash >= 0 ? partial[slash] : "/";
 	const foldersOnly = template === "folders";
 	let entries;
 	try {
-		entries = readdirSync(dir || ".", { withFileTypes: true });
+		entries = readdirSync((isWindows ? dir.replaceAll("\\", "/") : dir) || ".", { withFileTypes: true });
 	} catch {
 		return [];
 	}
@@ -919,7 +1301,7 @@ async function enumeratePaths(partial, template) {
 		if (!entry.name.startsWith(base)) continue;
 		const isDir = entry.isDirectory();
 		if (foldersOnly && !isDir) continue;
-		candidates.push({ value: `${dir}${entry.name}${isDir ? "/" : ""}` });
+		candidates.push({ value: `${dir}${entry.name}${isDir ? separator : ""}` });
 	}
 	return candidates;
 }
@@ -941,116 +1323,75 @@ async function argValues(arg, tokens, partial) {
 	if (arg.template) candidates.push(...await enumeratePaths(partial, arg.template));
 	return candidates;
 }
-/** Pick the argument at an index, reusing a final variadic argument. */
-function argAt(args, index) {
-	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;
-}
-/** Pick the argument being completed at a positional index (honors variadic). */
-function positionalArg(command, index) {
-	return argAt(asArray(command.args), index);
-}
 /** Decide which kinds of candidate the word being completed can use. */
-function wantedCandidates(state, req) {
-	const posixNoncompliant = directiveOnPath(state.path, "flagsArePosixNoncompliant");
-	const partialIsOption = !posixNoncompliant && (req.partial.startsWith("-") || req.partial.startsWith("+"));
+function wantedCandidates(next, req) {
+	if (!req.gateOptions || next.directives.flagsArePosixNoncompliant) return {
+		wantValues: true,
+		wantOptions: true,
+		wantSubcommand: () => true
+	};
+	const partial = req.partial;
+	const wantValues = !next.partialIsOption;
+	const starts = (name) => partial !== "" && name.startsWith(partial);
 	return {
-		wantValues: !(req.gateOptions && partialIsOption),
-		wantOptions: !req.gateOptions || partialIsOption || posixNoncompliant
+		wantValues,
+		wantOptions: next.options.some(({ forms }) => forms.some(({ name }) => starts(name))),
+		wantSubcommand: (name) => wantValues || starts(name)
 	};
 }
 /**
-* Resolve completion candidates for a partial command line, reading it with the
-* parser's `scan` for context. Dispatches between completing a option's value and
-* completing a fresh token (subcommand / positional / option).
+* Resolve completion candidates for a partial command line. The parser works
+* out what the word can be with {@link readNext}, and this offers candidates
+* for each of those.
 */
 async function completeRuntime(req) {
-	const state = readLine(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 next = readNext(req.spec, req.before, req.partial);
 	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}`,
+	if (next.attached) {
+		const { prefix, arg, value } = next.attached;
+		return (await argValues(arg, tokens, value)).map((candidate) => ({
+			value: prefix + candidate.value,
 			description: candidate.description
 		}));
 	}
-	if (state.pending) {
-		const { option, argIndex } = state.pending;
-		const args = asArray(option.args);
-		const arg = argAt(args, argIndex);
-		if (argIndex < args.length) return arg ? argValues(arg, tokens, req.partial) : [];
-		const { wantValues, wantOptions } = wantedCandidates(state, req);
-		return [...arg && wantValues ? await argValues(arg, tokens, req.partial) : [], ...wantOptions ? allowedOptionCandidates(state, separators) : []];
-	}
-	return null;
-}
-/** Candidates when completing a fresh token: subcommand / positional / option. */
-async function freshTokenCandidates(state, req, separators) {
+	if (next.value?.required) return next.value.arg ? argValues(next.value.arg, tokens, req.partial) : [];
 	const candidates = [];
-	const tokens = [...req.before];
-	const { wantValues, wantOptions } = wantedCandidates(state, req);
+	const { wantValues, wantOptions, wantSubcommand } = wantedCandidates(next, req);
 	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) 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;
-	if (wantOptions) candidates.push(...allowedOptionCandidates(state, separators));
+		const arg = next.value ? next.value.arg : next.arg;
+		if (arg) candidates.push(...await argValues(arg, tokens, req.partial));
+	}
+	for (const sub of visibleSubcommands(next.subcommands)) {
+		const description = firstLine(sub.description);
+		for (const token of makeArray(sub.name)) if (wantSubcommand(token)) candidates.push({
+			value: token,
+			description
+		});
+	}
+	if (wantOptions) candidates.push(...optionCandidates(next));
 	return candidates;
 }
-/** Option candidates, unless options must precede arguments and one was seen. */
-function allowedOptionCandidates(state, separators) {
-	return state.sawPositional && directiveOnPath(state.path, "optionsMustPrecedeArguments") ? [] : optionCandidates(state, separators);
-}
-/** Eligible option candidates after relationship filtering. */
-function optionCandidates(state, separators) {
+/** The options a user can use next, required ones first. */
+function optionCandidates(next) {
 	const required = [];
 	const optional = [];
-	for (const option of state.availableOptions) {
+	for (const { option, forms, used } of next.options) {
 		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;
+		if (used && !option.isRepeatable) 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
-		});
+		for (const { name, join } of forms) {
+			if (join === "") continue;
+			bucket.push({
+				value: name + (join ?? ""),
+				description
+			});
+		}
 	}
 	return [...required, ...optional];
 }
@@ -1088,6 +1429,85 @@ function renderRuntimeShim(spec, shell) {
 		`}`,
 		`_${id}_complete "$@"`
 	].join("\n");
+	if (shell === "powershell") {
+		const stringAst = "[System.Management.Automation.Language.StringConstantExpressionAst]";
+		return [
+			`Register-ArgumentCompleter -Native -CommandName ${psQuote(name)} -ScriptBlock {`,
+			`  param($wordToComplete, $commandAst, $cursorPosition)`,
+			`  $elements = $commandAst.CommandElements`,
+			`  $first = $elements[0]`,
+			`  $bin = if ($first -is ${stringAst}) { $first.Value } else { $first.Extent.Text }`,
+			`  if (-not (Get-Command $bin -ErrorAction SilentlyContinue)) { return }`,
+			`  $partial = $wordToComplete`,
+			`  if ($partial.StartsWith("'")) { $partial = $partial.Substring(1).TrimEnd("'").Replace("''", "'") }`,
+			`  elseif ($partial.StartsWith('"')) { $partial = $partial.Substring(1).TrimEnd('"') }`,
+			`  $arguments = @('completion', 'complete', '--gate-options')`,
+			`  if ($partial -eq '') { $arguments += '--empty-word' }`,
+			`  $arguments += '--'`,
+			`  for ($i = 1; $i -lt $elements.Count; $i++) {`,
+			`    $element = $elements[$i]`,
+			`    if ($element.Extent.EndOffset -ge $cursorPosition) { break }`,
+			`    if ($element -is ${stringAst}) {`,
+			`      $arguments += $element.Value`,
+			`    } else {`,
+			`      $arguments += $element.Extent.Text`,
+			`    }`,
+			`  }`,
+			`  if ($partial -ne '') { $arguments += $partial }`,
+			`  & $bin @arguments 2>$null | ForEach-Object {`,
+			"    $value, $description = $_ -split \"`t\", 2",
+			`    if (-not $value.StartsWith($partial, [System.StringComparison]::OrdinalIgnoreCase)) { return }`,
+			"    $text = if ($value -match '[\\s''\"`$&|;,(){}<>@#]') { \"'$($value.Replace(\"'\", \"''\"))'\" } else { $value }",
+			`    if (-not $description) { $description = $value }`,
+			`    [System.Management.Automation.CompletionResult]::new($text, $value, 'ParameterValue', $description)`,
+			`  }`,
+			`}`
+		].join("\n");
+	}
+	if (shell === "nushell") {
+		const previous = `$__${id}_previous_completer`;
+		const names = [
+			"",
+			".exe",
+			".cmd",
+			".bat"
+		].map((extension) => nuQuote(name + extension)).join(" ");
+		return [
+			`let __${id}_previous_completer = $env.config.completions.external.completer?`,
+			`$env.config.completions.external.completer = {|spans|`,
+			`  let words = $spans | each {|span|`,
+			`    let quote = $span | str substring 0..0`,
+			`    if $quote in ["'", '"', '\`'] { $span | str substring 1.. | str trim --right --char $quote } else { $span }`,
+			`  }`,
+			`  let command = $words.0`,
+			`  if ($command | path basename) not-in [${names}] {`,
+			`    return (if ${previous} != null { do ${previous} $spans })`,
+			`  }`,
+			`  if (which $command | is-empty) { return }`,
+			`  let args = $words | skip 1`,
+			`  let partial = $args | last | default ""`,
+			`  ^$command completion complete --gate-options -- ...$args`,
+			`    | complete`,
+			`    | get stdout`,
+			`    | lines`,
+			`    | each {|line|`,
+			`      let parts = $line | split row "\\t"`,
+			`      { value: $parts.0, description: ($parts | get 1? | default "") }`,
+			`    }`,
+			`    | where { $in.value | str starts-with --ignore-case $partial }`,
+			"    | update value {|candidate|",
+			"      let value = $candidate.value",
+			"      if ($value !~ \"[\\\\s'\\\"`$|;#()\\\\[\\\\]{}]\") {",
+			"        $value",
+			"      } else if ($value | str contains \"'\") {",
+			"        $value | to json",
+			"      } else {",
+			"        $\"'($value)'\"",
+			"      }",
+			"    }",
+			`}`
+		].join("\n");
+	}
 	return [
 		`function __${id}_complete`,
 		`  set -l toks (commandline -opc)`,
@@ -1110,7 +1530,8 @@ const completion = {
 	args: {
 		name: "shell",
 		isOptional: true,
-		suggestions: SHELLS
+		suggestions: SHELLS,
+		description: `One of: ${SHELLS.join(", ")}`
 	},
 	subcommands: [{
 		name: "complete",
@@ -1119,6 +1540,9 @@ const completion = {
 		options: [{
 			name: "--gate-options",
 			description: "Only suggest options after a leading dash"
+		}, {
+			name: "--empty-word",
+			description: "The word being completed is empty, so every token is before it"
 		}],
 		args: {
 			name: "tokens",
@@ -1127,10 +1551,11 @@ const completion = {
 		},
 		async action({ path, args, options }) {
 			const spec = path[0];
-			const partial = args.length > 0 ? args[args.length - 1] : "";
+			const emptyWord = options.has("--empty-word");
+			const partial = emptyWord || args.length === 0 ? "" : args[args.length - 1];
 			const lines = (await completeRuntime({
 				spec,
-				before: args.slice(0, -1),
+				before: emptyWord ? args : args.slice(0, -1),
 				partial,
 				gateOptions: options.has("--gate-options")
 			})).map((candidate) => candidate.description ? `${candidate.value}\t${candidate.description}` : candidate.value);
@@ -1138,19 +1563,17 @@ const completion = {
 			return 0;
 		}
 	}],
-	action({ path: [spec], args: [shell], help }) {
+	action({ path, args: [shell] }) {
+		const spec = path[0];
 		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
-				}
-			})}`);
+			printUsageError(path, `Unsupported shell '${shell}'`, {
+				input: shell,
+				choices: SHELLS
+			});
 			return 1;
 		}
 		print(getCompletion(spec, shell));
@@ -1161,31 +1584,21 @@ const completion = {
 /**
 * 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.
+* The selected command's 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. A command without an
+* action prints its help.
 */
 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 })}`);
+		if (error instanceof ParseError) printUsageError(error.context.path, error.message, error.didYouMean);
 		else printError(`${error}`);
 		return 1;
 	}
-	const action = result.optionActions.at(-1) ?? result.actions.at(-1);
-	if (!action) return 1;
-	const options = result.options;
+	const { action, options } = result;
 	const actionInit = {
 		help: (helpOptions) => getHelp(helpOptions?.path ?? result.path, helpOptions),
 		args: result.args,
@@ -1194,8 +1607,8 @@ async function run(spec, args = defaultArgs()) {
 		options: {
 			options,
 			has: (name) => options.has(name),
-			get: (name) => options.get(name)?.[0],
-			all: (name) => options.get(name),
+			get: (name) => (options.get(name) ?? result.defaults(name))?.[0],
+			all: (name) => options.get(name) ?? result.defaults(name),
 			count: (name) => options.get(name)?.length ?? 0
 		}
 	};
@@ -1204,14 +1617,22 @@ async function run(spec, args = defaultArgs()) {
 		const actionResult = action(actionInit);
 		exitCode = typeof actionResult === "object" ? await actionResult : actionResult;
 	} catch (error) {
-		printError(error instanceof Error ? error.message : String(error));
+		printError(describeThrown(error));
 		return 1;
 	}
 	return Math.min(Math.max(exitCode ?? 0, 0), 255);
 }
-/** Print `Error:` and the given values to stderr, separated by spaces. */
-function printError(...strings) {
-	output.write(2, `${["Error:", ...strings].map(String).join(" ")}\n`);
+/**
+* The message for a value an action threw. A value that isn't an Error is shown
+* as JSON where it can be, since `String` turns an object into
+* "[object Object]".
+*/
+function describeThrown(value) {
+	if (value instanceof Error) return value.message;
+	if (typeof value === "object" && value !== null) try {
+		return JSON.stringify(value);
+	} catch {}
+	return String(value);
 }
 function defaultArgs() {
 	return globalThis.process?.argv?.slice(2) ?? [];