@optique/core 0.10.7 → 1.0.0-dev.1109

package/dist/facade.js

@@ -1,8 +1,10 @@
-import { annotationKey } from "./annotations.js";
+import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
+import { dispatchByMode } from "./mode-dispatch.js";
 import { formatUsage } from "./usage.js";
 import { group, longestMatch, object } from "./constructs.js";
+import { isPlaceholderValue } from "./context.js";
 import { formatDocPage } from "./doc.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { string } from "./valueparser.js";
@@ -10,52 +12,345 @@ import { argument, command, constant, flag, option } from "./primitives.js";
 import { getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";
 
 //#region src/facade.ts
+function isPlainObject(value$1) {
+	const proto = Object.getPrototypeOf(value$1);
+	return proto === Object.prototype || proto === null;
+}
+function shouldSkipCollectionOwnKey(value$1, key) {
+	if (Array.isArray(value$1)) return key === "length" || typeof key === "string" && Number.isInteger(Number(key)) && String(Number(key)) === key;
+	return false;
+}
+function containsPlaceholderValuesInOwnProperties(value$1, seen) {
+	for (const key of Reflect.ownKeys(value$1)) {
+		if (shouldSkipCollectionOwnKey(value$1, key)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
+		if (descriptor != null && "value" in descriptor && containsPlaceholderValues(descriptor.value, seen)) return true;
+	}
+	return false;
+}
+function copySanitizedOwnProperties(source, target, seen) {
+	for (const key of Reflect.ownKeys(source)) {
+		if (shouldSkipCollectionOwnKey(source, key)) continue;
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) descriptor.value = stripPlaceholderValues(descriptor.value, seen);
+		Object.defineProperty(target, key, descriptor);
+	}
+}
+function createArrayCloneLike(value$1) {
+	try {
+		const arrayCtor = value$1.constructor;
+		return Reflect.construct(Array, [value$1.length], arrayCtor);
+	} catch {
+		return new Array(value$1.length);
+	}
+}
+function createSetCloneLike(value$1) {
+	try {
+		const setCtor = value$1.constructor;
+		return Reflect.construct(Set, [], setCtor);
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+function createMapCloneLike(value$1) {
+	try {
+		const mapCtor = value$1.constructor;
+		return Reflect.construct(Map, [], mapCtor);
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+function containsPlaceholderValues(value$1, seen = /* @__PURE__ */ new WeakSet()) {
+	if (isPlaceholderValue(value$1)) return true;
+	if (value$1 == null || typeof value$1 !== "object") return false;
+	if (seen.has(value$1)) return false;
+	seen.add(value$1);
+	if (Array.isArray(value$1)) {
+		if (value$1.some((item) => containsPlaceholderValues(item, seen))) return true;
+		return containsPlaceholderValuesInOwnProperties(value$1, seen);
+	}
+	if (value$1 instanceof Set) {
+		for (const entryValue of value$1) if (containsPlaceholderValues(entryValue, seen)) return true;
+		return containsPlaceholderValuesInOwnProperties(value$1, seen);
+	}
+	if (value$1 instanceof Map) {
+		for (const [key, entryValue] of value$1) if (containsPlaceholderValues(key, seen) || containsPlaceholderValues(entryValue, seen)) return true;
+		return containsPlaceholderValuesInOwnProperties(value$1, seen);
+	}
+	return containsPlaceholderValuesInOwnProperties(value$1, seen);
+}
+function stripPlaceholderValues(value$1, seen = /* @__PURE__ */ new WeakMap()) {
+	if (isPlaceholderValue(value$1)) return void 0;
+	if (value$1 == null || typeof value$1 !== "object") return value$1;
+	const cached = seen.get(value$1);
+	if (cached !== void 0) return cached;
+	if (Array.isArray(value$1)) {
+		if (!containsPlaceholderValues(value$1)) return value$1;
+		const clone$1 = createArrayCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (let i = 0; i < value$1.length; i++) clone$1[i] = stripPlaceholderValues(value$1[i], seen);
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (value$1 instanceof Set) {
+		if (!containsPlaceholderValues(value$1)) return value$1;
+		const clone$1 = createSetCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (const entryValue of value$1) clone$1.add(stripPlaceholderValues(entryValue, seen));
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (value$1 instanceof Map) {
+		if (!containsPlaceholderValues(value$1)) return value$1;
+		const clone$1 = createMapCloneLike(value$1);
+		seen.set(value$1, clone$1);
+		for (const [key, entryValue] of value$1) clone$1.set(stripPlaceholderValues(key, seen), stripPlaceholderValues(entryValue, seen));
+		copySanitizedOwnProperties(value$1, clone$1, seen);
+		return clone$1;
+	}
+	if (!isPlainObject(value$1)) {
+		if (!containsPlaceholderValues(value$1)) return value$1;
+		return createSanitizedNonPlainView(value$1, seen);
+	}
+	const clone = Object.create(Object.getPrototypeOf(value$1));
+	seen.set(value$1, clone);
+	for (const key of Reflect.ownKeys(value$1)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) descriptor.value = stripPlaceholderValues(descriptor.value, seen);
+		Object.defineProperty(clone, key, descriptor);
+	}
+	return clone;
+}
+function finalizeParsedForContext(context, parsed) {
+	return context.finalizeParsed != null ? context.finalizeParsed(parsed) : parsed;
+}
+const SANITIZE_FAILED = Symbol("sanitizeFailed");
+const activeSanitizations = /* @__PURE__ */ new WeakMap();
+function callWithSanitizedOwnProperties(target, fn, args, strip, seen) {
+	let active = activeSanitizations.get(target);
+	if (active != null) active.count++;
+	else {
+		const saved = /* @__PURE__ */ new Map();
+		const sanitizedValues = /* @__PURE__ */ new Map();
+		for (const key of Reflect.ownKeys(target)) {
+			const desc = Object.getOwnPropertyDescriptor(target, key);
+			if (desc != null && "value" in desc) {
+				let stripped;
+				try {
+					stripped = strip(desc.value, seen);
+				} catch {
+					for (const [k, d] of saved) try {
+						Object.defineProperty(target, k, d);
+					} catch {}
+					return SANITIZE_FAILED;
+				}
+				if (stripped !== desc.value) try {
+					Object.defineProperty(target, key, {
+						...desc,
+						value: stripped
+					});
+					saved.set(key, desc);
+					sanitizedValues.set(key, stripped);
+				} catch {
+					for (const [k, d] of saved) try {
+						Object.defineProperty(target, k, d);
+					} catch {}
+					return SANITIZE_FAILED;
+				}
+			}
+		}
+		active = {
+			saved,
+			sanitizedValues,
+			count: 1
+		};
+		activeSanitizations.set(target, active);
+	}
+	function release() {
+		active.count--;
+		if (active.count === 0) {
+			activeSanitizations.delete(target);
+			for (const [key, desc] of active.saved) try {
+				const current = Object.getOwnPropertyDescriptor(target, key);
+				if (current == null) continue;
+				if ("value" in current && current.value !== active.sanitizedValues.get(key)) continue;
+				Object.defineProperty(target, key, desc);
+			} catch {}
+		}
+	}
+	let result;
+	try {
+		result = fn.apply(target, args);
+	} catch (e) {
+		release();
+		throw e;
+	}
+	if (result instanceof Promise) return result.then((v) => {
+		release();
+		return strip(v, seen);
+	}, (e) => {
+		release();
+		throw e;
+	});
+	release();
+	return strip(result, seen);
+}
+function callMethodOnSanitizedTarget(fn, proxy, target, args, strip, seen) {
+	const result = callWithSanitizedOwnProperties(target, fn, args, strip, seen);
+	if (result !== SANITIZE_FAILED) return result;
+	const fallback = fn.apply(proxy, args);
+	if (fallback instanceof Promise) return fallback.then((v) => strip(v, seen));
+	return strip(fallback, seen);
+}
+function createSanitizedNonPlainView(value$1, seen) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const proxy = new Proxy(value$1, {
+		get(target, key, receiver) {
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor != null && "value" in descriptor) {
+				if (!descriptor.configurable && !descriptor.writable) return descriptor.value;
+				const val = stripPlaceholderValues(descriptor.value, seen);
+				if (typeof val === "function") {
+					if (!descriptor.configurable && !descriptor.writable || /^class[\s{]/.test(Function.prototype.toString.call(val))) return val;
+					const cached = methodCache.get(key);
+					if (cached != null && cached.fn === val) return cached.wrapper;
+					const wrapper = function(...args) {
+						if (this !== proxy) return stripPlaceholderValues(val.apply(this, args), seen);
+						return callMethodOnSanitizedTarget(val, proxy, target, args, stripPlaceholderValues, seen);
+					};
+					methodCache.set(key, {
+						fn: val,
+						wrapper
+					});
+					return wrapper;
+				}
+				return val;
+			}
+			let isAccessor = false;
+			for (let proto = target; proto != null; proto = Object.getPrototypeOf(proto)) {
+				const d = Object.getOwnPropertyDescriptor(proto, key);
+				if (d != null) {
+					isAccessor = "get" in d;
+					break;
+				}
+			}
+			const result = Reflect.get(target, key, receiver);
+			if (typeof result === "function") {
+				if (/^class[\s{]/.test(Function.prototype.toString.call(result))) return result;
+				if (!isAccessor) {
+					const cached = methodCache.get(key);
+					if (cached != null && cached.fn === result) return cached.wrapper;
+					const wrapper = function(...args) {
+						if (this !== proxy) return stripPlaceholderValues(result.apply(this, args), seen);
+						return callMethodOnSanitizedTarget(result, proxy, target, args, stripPlaceholderValues, seen);
+					};
+					methodCache.set(key, {
+						fn: result,
+						wrapper
+					});
+					return wrapper;
+				}
+				return function(...args) {
+					if (this !== proxy) return stripPlaceholderValues(result.apply(this, args), seen);
+					return callMethodOnSanitizedTarget(result, proxy, target, args, stripPlaceholderValues, seen);
+				};
+			}
+			return stripPlaceholderValues(result, seen);
+		},
+		getOwnPropertyDescriptor(target, key) {
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor == null || !("value" in descriptor)) return descriptor;
+			if (!descriptor.configurable && !descriptor.writable) return descriptor;
+			return {
+				...descriptor,
+				value: stripPlaceholderValues(descriptor.value, seen)
+			};
+		}
+	});
+	seen.set(value$1, proxy);
+	return proxy;
+}
+function prepareParsedForContexts(parsed) {
+	if (parsed == null || typeof parsed !== "object") return stripPlaceholderValues(parsed);
+	if (isPlaceholderValue(parsed)) return void 0;
+	if (Array.isArray(parsed) || isPlainObject(parsed) || parsed instanceof Set || parsed instanceof Map) {
+		if (!containsPlaceholderValues(parsed)) return parsed;
+		return stripPlaceholderValues(parsed);
+	}
+	if (!containsPlaceholderValues(parsed)) return parsed;
+	return createSanitizedNonPlainView(parsed, /* @__PURE__ */ new WeakMap());
+}
+function withPreparedParsedForContext(context, preparedParsed, run) {
+	return run(finalizeParsedForContext(context, preparedParsed));
+}
 /**
-* Creates help parsers based on the specified mode.
+* Creates help parsers based on the sub-config.
 */
-function createHelpParser(mode) {
-	const helpCommand = command("help", multiple(argument(string({ metavar: "COMMAND" }), { description: message`Command name to show help for.` })), { description: message`Show help information.` });
-	const helpOption = flag("--help", { description: message`Show help information.` });
-	switch (mode) {
-		case "command": return {
-			helpCommand,
-			helpOption: null
-		};
-		case "option": return {
-			helpCommand: null,
-			helpOption
-		};
-		case "both": return {
-			helpCommand,
-			helpOption
-		};
+function createHelpParser(commandConfig, optionConfig) {
+	let helpCommand = null;
+	let helpOption = null;
+	if (commandConfig) {
+		const names = commandConfig.names ?? ["help"];
+		const innerParser = multiple(argument(string({ metavar: "COMMAND" }), { description: message`Command name to show help for.` }));
+		const commandParsers = [];
+		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], innerParser, {
+			description: message`Show help information.`,
+			hidden: i === 0 ? commandConfig.hidden : true
+		}));
+		helpCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+	}
+	if (optionConfig) {
+		const names = optionConfig.names ?? ["--help"];
+		helpOption = flag(...names, {
+			description: message`Show help information.`,
+			hidden: optionConfig.hidden
+		});
 	}
+	return {
+		helpCommand,
+		helpOption
+	};
 }
 /**
-* Creates version parsers based on the specified mode.
+* Creates version parsers based on the sub-config.
 */
-function createVersionParser(mode) {
-	const versionCommand = command("version", object({}), { description: message`Show version information.` });
-	const versionOption = flag("--version", { description: message`Show version information.` });
-	switch (mode) {
-		case "command": return {
-			versionCommand,
-			versionOption: null
-		};
-		case "option": return {
-			versionCommand: null,
-			versionOption
-		};
-		case "both": return {
-			versionCommand,
-			versionOption
-		};
+function createVersionParser(commandConfig, optionConfig) {
+	let versionCommand = null;
+	let versionOption = null;
+	if (commandConfig) {
+		const names = commandConfig.names ?? ["version"];
+		const innerParser = object({});
+		const commandParsers = [];
+		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], innerParser, {
+			description: message`Show version information.`,
+			hidden: i === 0 ? commandConfig.hidden : true
+		}));
+		versionCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
 	}
+	if (optionConfig) {
+		const names = optionConfig.names ?? ["--version"];
+		versionOption = flag(...names, {
+			description: message`Show version information.`,
+			hidden: optionConfig.hidden
+		});
+	}
+	return {
+		versionCommand,
+		versionOption
+	};
+}
+const metaResultBrand = Symbol("@optique/core/facade/meta");
+function isMetaParseResult(value$1) {
+	return typeof value$1 === "object" && value$1 != null && metaResultBrand in value$1;
 }
 /**
-* Creates completion parsers based on the specified mode.
+* Creates completion parsers based on the sub-config.
 */
-function createCompletionParser(mode, programName, availableShells, name = "both", helpVisibility = name) {
+function createCompletionParser(programName, availableShells, commandConfig, optionConfig) {
+	let completionCommand = null;
+	let completionOption = null;
 	const shellList = [];
 	for (const shell in availableShells) {
 		if (shellList.length > 0) shellList.push(text(", "));
@@ -65,56 +360,44 @@ function createCompletionParser(mode, programName, availableShells, name = "both
 		shell: optional(argument(string({ metavar: "SHELL" }), { description: message`Shell type (${shellList}). Generate completion script when used alone, or provide completions when followed by arguments.` })),
 		args: multiple(argument(string({ metavar: "ARG" }), { description: message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` }))
 	});
-	const commandName = name === "plural" ? "completions" : "completion";
-	const completionCommandConfig = {
-		brief: message`Generate shell completion script or provide completions.`,
-		description: message`Generate shell completion script or provide completions.`,
-		footer: message`Examples:${lineBreak()}  Bash:       ${commandLine(`eval "$(${programName} ${commandName} bash)"`)}${lineBreak()}  zsh:        ${commandLine(`eval "$(${programName} ${commandName} zsh)"`)}${lineBreak()}  fish:       ${commandLine(`eval "$(${programName} ${commandName} fish)"`)}${lineBreak()}  PowerShell: ${commandLine(`${programName} ${commandName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}${lineBreak()}  Nushell:    ${commandLine(`${programName} ${commandName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}`
-	};
-	const completionCommands = [];
-	const showSingular = helpVisibility === "singular" || helpVisibility === "both";
-	const showPlural = helpVisibility === "plural" || helpVisibility === "both";
-	if (name === "singular" || name === "both") completionCommands.push(command("completion", completionInner, {
-		...completionCommandConfig,
-		hidden: !showSingular
-	}));
-	if (name === "plural" || name === "both") completionCommands.push(command("completions", completionInner, {
-		...completionCommandConfig,
-		hidden: !showPlural
-	}));
-	const completionCommand = longestMatch(...completionCommands);
-	const completionOptions = [];
-	if (name === "singular" || name === "both") completionOptions.push(option("--completion", string({ metavar: "SHELL" }), {
-		description: message`Generate shell completion script.`,
-		hidden: !showSingular
-	}));
-	if (name === "plural" || name === "both") completionOptions.push(option("--completions", string({ metavar: "SHELL" }), {
-		description: message`Generate shell completion script.`,
-		hidden: !showPlural
-	}));
-	const completionOption = completionOptions.length === 1 ? completionOptions[0] : longestMatch(completionOptions[0], completionOptions[1]);
-	const argsParser = withDefault(multiple(argument(string({ metavar: "ARG" }), { description: message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` })), []);
-	const optionParser = object({
-		shell: completionOption,
-		args: argsParser
-	});
-	switch (mode) {
-		case "command": return {
-			completionCommand,
-			completionOption: null
-		};
-		case "option": return {
-			completionCommand: null,
-			completionOption: optionParser
-		};
-		case "both": return {
-			completionCommand,
-			completionOption: optionParser
+	if (commandConfig) {
+		const names = commandConfig.names ?? ["completion"];
+		const displayName = names[0];
+		const completionCommandConfig = {
+			brief: message`Generate shell completion script or provide completions.`,
+			description: message`Generate shell completion script or provide completions.`,
+			footer: message`Examples:${lineBreak()}  Bash:       ${commandLine(`eval "$(${programName} ${displayName} bash)"`)}${lineBreak()}  zsh:        ${commandLine(`eval "$(${programName} ${displayName} zsh)"`)}${lineBreak()}  fish:       ${commandLine(`eval "$(${programName} ${displayName} fish)"`)}${lineBreak()}  PowerShell: ${commandLine(`${programName} ${displayName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}${lineBreak()}  Nushell:    ${commandLine(`${programName} ${displayName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}`
 		};
+		const commandParsers = [];
+		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], completionInner, {
+			...completionCommandConfig,
+			hidden: i === 0 ? commandConfig.hidden : true
+		}));
+		completionCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+	}
+	if (optionConfig) {
+		const names = optionConfig.names ?? ["--completion"];
+		const completionOptions = [];
+		for (const name of names) completionOptions.push(option(name, string({ metavar: "SHELL" }), {
+			description: message`Generate shell completion script.`,
+			hidden: optionConfig.hidden
+		}));
+		const completionOptionParser = completionOptions.length === 1 ? completionOptions[0] : longestMatch(...completionOptions);
+		const argsParser = withDefault(multiple(argument(string({ metavar: "ARG" }), { description: message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` })), []);
+		completionOption = object({
+			shell: completionOptionParser,
+			args: argsParser
+		});
 	}
+	return {
+		completionCommand,
+		completionOption
+	};
 }
-function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers, groups) {
+function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers, groups, helpOptionNames, versionOptionNames) {
 	const parsers = [];
+	const effectiveHelpOptionNames = helpOptionNames ?? ["--help"];
+	const effectiveVersionOptionNames = versionOptionNames ?? ["--version"];
 	if (helpParsers.helpOption) {
 		const lenientHelpParser = {
 			$mode: "sync",
@@ -135,11 +418,11 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 				let versionIndex = -1;
 				for (let i = 0; i < buffer.length; i++) {
 					if (buffer[i] === "--") break;
-					if (buffer[i] === "--help") {
+					if (effectiveHelpOptionNames.includes(buffer[i])) {
 						helpFound = true;
 						helpIndex = i;
 					}
-					if (buffer[i] === "--version") versionIndex = i;
+					if (effectiveVersionOptionNames.includes(buffer[i])) versionIndex = i;
 				}
 				if (helpFound && versionIndex > helpIndex) return {
 					success: false,
@@ -158,8 +441,10 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 							...context,
 							buffer: [],
 							state: {
+								[metaResultBrand]: true,
 								help: true,
 								version: false,
+								completion: false,
 								commands,
 								helpFlag: true
 							}
@@ -169,7 +454,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 				}
 				return {
 					success: false,
-					error: message`Flag ${optionName("--help")} not found.`,
+					error: message`Flag ${optionName(effectiveHelpOptionNames[0])} not found.`,
 					consumed: 0
 				};
 			},
@@ -180,16 +465,17 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 				};
 			},
 			*suggest(_context, prefix) {
-				if ("--help".startsWith(prefix)) yield {
+				for (const name of effectiveHelpOptionNames) if (name.startsWith(prefix)) yield {
 					kind: "literal",
-					text: "--help"
+					text: name
 				};
 			},
 			getDocFragments(state) {
 				return helpParsers.helpOption?.getDocFragments(state) ?? { fragments: [] };
 			}
 		};
-		parsers.push(lenientHelpParser);
+		const wrappedHelp = groups?.helpOptionGroup ? group(groups.helpOptionGroup, lenientHelpParser) : lenientHelpParser;
+		parsers.push(wrappedHelp);
 	}
 	if (versionParsers.versionOption) {
 		const lenientVersionParser = {
@@ -211,11 +497,11 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 				let helpIndex = -1;
 				for (let i = 0; i < buffer.length; i++) {
 					if (buffer[i] === "--") break;
-					if (buffer[i] === "--version") {
+					if (effectiveVersionOptionNames.includes(buffer[i])) {
 						versionFound = true;
 						versionIndex = i;
 					}
-					if (buffer[i] === "--help") helpIndex = i;
+					if (effectiveHelpOptionNames.includes(buffer[i])) helpIndex = i;
 				}
 				if (versionFound && helpIndex > versionIndex) return {
 					success: false,
@@ -228,8 +514,10 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 						...context,
 						buffer: [],
 						state: {
+							[metaResultBrand]: true,
 							help: false,
 							version: true,
+							completion: false,
 							versionFlag: true
 						}
 					},
@@ -237,7 +525,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 				};
 				return {
 					success: false,
-					error: message`Flag ${optionName("--version")} not found.`,
+					error: message`Flag ${optionName(effectiveVersionOptionNames[0])} not found.`,
 					consumed: 0
 				};
 			},
@@ -248,47 +536,52 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 				};
 			},
 			*suggest(_context, prefix) {
-				if ("--version".startsWith(prefix)) yield {
+				for (const name of effectiveVersionOptionNames) if (name.startsWith(prefix)) yield {
 					kind: "literal",
-					text: "--version"
+					text: name
 				};
 			},
 			getDocFragments(state) {
 				return versionParsers.versionOption?.getDocFragments(state) ?? { fragments: [] };
 			}
 		};
-		parsers.push(lenientVersionParser);
+		const wrappedVersion = groups?.versionOptionGroup ? group(groups.versionOptionGroup, lenientVersionParser) : lenientVersionParser;
+		parsers.push(wrappedVersion);
 	}
 	if (versionParsers.versionCommand) {
 		const versionParser = object({
+			[metaResultBrand]: constant(true),
 			help: constant(false),
 			version: constant(true),
 			completion: constant(false),
 			result: versionParsers.versionCommand,
 			helpFlag: helpParsers.helpOption ? optional(helpParsers.helpOption) : constant(false)
 		});
-		parsers.push(groups?.versionGroup ? group(groups.versionGroup, versionParser) : versionParser);
+		parsers.push(groups?.versionCommandGroup ? group(groups.versionCommandGroup, versionParser) : versionParser);
 	}
 	if (completionParsers.completionCommand) {
 		const completionParser = object({
+			[metaResultBrand]: constant(true),
 			help: constant(false),
 			version: constant(false),
 			completion: constant(true),
 			completionData: completionParsers.completionCommand,
 			helpFlag: helpParsers.helpOption ? optional(helpParsers.helpOption) : constant(false)
 		});
-		parsers.push(groups?.completionGroup ? group(groups.completionGroup, completionParser) : completionParser);
+		parsers.push(groups?.completionCommandGroup ? group(groups.completionCommandGroup, completionParser) : completionParser);
 	}
 	if (helpParsers.helpCommand) {
 		const helpParser = object({
+			[metaResultBrand]: constant(true),
 			help: constant(true),
 			version: constant(false),
 			completion: constant(false),
 			commands: helpParsers.helpCommand
 		});
-		parsers.push(groups?.helpGroup ? group(groups.helpGroup, helpParser) : helpParser);
+		parsers.push(groups?.helpCommandGroup ? group(groups.helpCommandGroup, helpParser) : helpParser);
 	}
 	parsers.push(object({
+		[metaResultBrand]: constant(true),
 		help: constant(false),
 		version: constant(false),
 		completion: constant(false),
@@ -316,29 +609,29 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	return combined;
 }
 /**
-* Classifies the parsing result into a discriminated union for cleaner handling.
+* Classifies the parsing result into a discriminated union for cleaner
+* handling.
 */
-function classifyResult(result, args) {
+function classifyResult(result, args, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionCommandNames) {
 	if (!result.success) return {
 		type: "error",
 		error: result.error
 	};
 	const value$1 = result.value;
-	if (typeof value$1 === "object" && value$1 != null && "help" in value$1 && "version" in value$1) {
+	if (isMetaParseResult(value$1)) {
 		const parsedValue = value$1;
-		const hasVersionOption = args.includes("--version");
-		const hasVersionCommand = args.length > 0 && args[0] === "version";
-		const hasHelpOption = args.includes("--help");
-		const hasHelpCommand = args.length > 0 && args[0] === "help";
-		const hasCompletionCommand = args.length > 0 && args[0] === "completion";
-		if (hasVersionOption && hasHelpOption && !hasVersionCommand && !hasHelpCommand) {}
+		const hasVersionOption = versionOptionNames.some((n) => args.includes(n));
+		const hasVersionCommand = args.length > 0 && versionCommandNames.includes(args[0]);
+		const hasCompletionCommand = args.length > 0 && completionCommandNames.includes(args[0]);
+		const hasHelpOption = hasCompletionCommand ? helpOptionNames.length > 0 && args.length >= 2 && helpOptionNames.includes(args[1]) : helpOptionNames.some((n) => args.includes(n));
+		const hasHelpCommand = args.length > 0 && helpCommandNames.includes(args[0]);
 		if (hasVersionCommand && hasHelpOption && parsedValue.helpFlag) return {
 			type: "help",
-			commands: ["version"]
+			commands: [args[0]]
 		};
 		if (hasCompletionCommand && hasHelpOption && parsedValue.helpFlag) return {
 			type: "help",
-			commands: ["completion"]
+			commands: [args[0]]
 		};
 		if (parsedValue.help && (hasHelpOption || hasHelpCommand)) {
 			let commandContext = [];
@@ -352,12 +645,12 @@ function classifyResult(result, args) {
 		if ((hasVersionOption || hasVersionCommand) && (parsedValue.version || parsedValue.versionFlag)) return { type: "version" };
 		if (parsedValue.completion && parsedValue.completionData) return {
 			type: "completion",
-			shell: parsedValue.completionData.shell || "",
-			args: parsedValue.completionData.args || []
+			shell: parsedValue.completionData.shell ?? "",
+			args: parsedValue.completionData.args ?? []
 		};
 		return {
 			type: "success",
-			value: parsedValue.result ?? value$1
+			value: "result" in parsedValue ? parsedValue.result : value$1
 		};
 	}
 	return {
@@ -369,34 +662,23 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
-	const callOnError = (code) => {
-		try {
-			return onError(code);
-		} catch {
-			return onError();
-		}
-	};
-	const callOnCompletion = (code) => {
-		try {
-			return onCompletion(code);
-		} catch {
-			return onCompletion();
-		}
-	};
+	const callOnError = (code) => onError(code);
+	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
-			const doc = getDocPage(completionParser, ["completion"]);
+			const displayName = completionCommandDisplayName ?? "completion";
+			const doc = getDocPage(completionParser, [displayName]);
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				sectionOrder
 			}));
 		}
-		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
-		return callOnError(1);
+		return dispatchByMode(parser.$mode, () => callOnError(1), () => Promise.resolve(callOnError(1)));
 	}
 	const shell = availableShells[shellName];
 	if (!shell) {
@@ -409,26 +691,24 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors
 		}));
-		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
-		return callOnError(1);
+		return dispatchByMode(parser.$mode, () => callOnError(1), () => Promise.resolve(callOnError(1)));
 	}
 	if (args.length === 0) {
-		const usePlural = completionName === "plural";
-		const completionArg = completionMode === "option" ? usePlural ? "--completions" : "--completion" : usePlural ? "completions" : "completion";
+		const completionArg = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
-		if (parser.$mode === "async") return Promise.resolve(callOnCompletion(0));
-		return callOnCompletion(0);
+		return dispatchByMode(parser.$mode, () => callOnCompletion(0), () => Promise.resolve(callOnCompletion(0)));
 	}
-	if (parser.$mode === "async") return (async () => {
-		const suggestions$1 = await suggestAsync(parser, args);
-		for (const chunk of shell.encodeSuggestions(suggestions$1)) stdout(chunk);
+	return dispatchByMode(parser.$mode, () => {
+		const syncParser = parser;
+		const suggestions = suggest(syncParser, args);
+		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 		return callOnCompletion(0);
-	})();
-	const syncParser = parser;
-	const suggestions = suggest(syncParser, args);
-	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
-	return callOnCompletion(0);
+	}, async () => {
+		const suggestions = await suggestAsync(parser, args);
+		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
+		return callOnCompletion(0);
+	});
 }
 function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
 	const isProgram = typeof programNameOrArgs !== "string";
@@ -457,21 +737,28 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
-	const helpMode = options.help?.mode ?? "option";
+	const norm = (c) => c === true ? {} : c;
+	const helpCommandConfig = norm(options.help?.command);
+	const helpOptionConfig = norm(options.help?.option);
 	const onHelp = options.help?.onShow ?? (() => ({}));
-	const helpGroup = options.help?.group;
-	const versionMode = options.version?.mode ?? "option";
+	const versionCommandConfig = norm(options.version?.command);
+	const versionOptionConfig = norm(options.version?.option);
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
-	const versionGroup = options.version?.group;
-	const completionMode = options.completion?.mode ?? "both";
-	const completionName = options.completion?.name ?? "both";
-	const completionHelpVisibility = options.completion?.helpVisibility ?? completionName;
+	const completionCommandConfig = norm(options.completion?.command);
+	const completionOptionConfig = norm(options.completion?.option);
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
-	const completionGroup = options.completion?.group;
+	const onCompletionResult = (code) => onCompletion(code);
+	const onErrorResult = (code) => onError(code);
+	const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
+	const helpCommandNames = helpCommandConfig?.names ?? ["help"];
+	const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
+	const versionCommandNames = versionCommandConfig?.names ?? ["version"];
+	const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
+	const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
 	const defaultShells = {
 		bash,
 		fish,
@@ -483,72 +770,65 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		...defaultShells,
 		...options.completion.shells
 	} : defaultShells;
-	const help = options.help ? helpMode : "none";
-	const version = options.version ? versionMode : "none";
-	const completion = options.completion ? completionMode : "none";
-	const helpParsers = help === "none" ? {
+	const helpParsers = options.help ? createHelpParser(helpCommandConfig, helpOptionConfig) : {
 		helpCommand: null,
 		helpOption: null
-	} : createHelpParser(help);
-	const versionParsers = version === "none" ? {
+	};
+	const versionParsers = options.version ? createVersionParser(versionCommandConfig, versionOptionConfig) : {
 		versionCommand: null,
 		versionOption: null
-	} : createVersionParser(version);
-	const completionParsers = completion === "none" ? {
+	};
+	const completionParsers = options.completion ? createCompletionParser(programName, availableShells, completionCommandConfig, completionOptionConfig) : {
 		completionCommand: null,
 		completionOption: null
-	} : createCompletionParser(completion, programName, availableShells, completionName, completionHelpVisibility);
+	};
 	if (options.completion) {
-		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
-		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
+		const hasHelpOption = helpOptionConfig ? completionCommandConfig && completionCommandNames.includes(args[0]) ? args.length >= 2 && helpOptionNames.includes(args[1]) : helpOptionNames.some((n) => args.includes(n)) : false;
+		if (completionCommandConfig && args.length >= 1 && completionCommandNames.includes(args[0]) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], false, sectionOrder);
+		if (completionOptionConfig) for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
-			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
-			const pluralMatch = completionName === "plural" || completionName === "both" ? arg.startsWith("--completions=") : false;
-			if (singularMatch || pluralMatch) {
-				const shell = arg.slice(arg.indexOf("=") + 1);
+			const equalsMatch = completionOptionNames.find((n) => arg.startsWith(n + "="));
+			if (equalsMatch) {
+				const shell = arg.slice(equalsMatch.length + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
-			} else {
-				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
-				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
-				if (singularMatchExact || pluralMatchExact) {
-					const shell = i + 1 < args.length ? args[i + 1] : "";
-					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
-				}
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
+			}
+			const exactMatch = completionOptionNames.includes(arg);
+			if (exactMatch) {
+				const shell = i + 1 < args.length ? args[i + 1] : "";
+				const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
 			}
 		}
 	}
-	const augmentedParser = help === "none" && version === "none" && completion === "none" ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
-		helpGroup,
-		versionGroup,
-		completionGroup
-	});
+	const augmentedParser = !options.help && !options.version && !options.completion ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
+		helpCommandGroup: helpCommandConfig?.group,
+		helpOptionGroup: helpOptionConfig?.group,
+		versionCommandGroup: versionCommandConfig?.group,
+		versionOptionGroup: versionOptionConfig?.group,
+		completionCommandGroup: completionCommandConfig?.group,
+		completionOptionGroup: completionOptionConfig?.group
+	}, helpOptionConfig ? [...helpOptionNames] : void 0, versionOptionConfig ? [...versionOptionNames] : void 0);
 	const handleResult = (result) => {
-		const classified = classifyResult(result, args);
+		const classified = classifyResult(result, args, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
 		switch (classified.type) {
 			case "success": return classified.value;
 			case "version":
 				stdout(versionValue);
-				try {
-					return onVersion(0);
-				} catch {
-					return onVersion();
-				}
+				return onVersion(0);
 			case "completion": throw new RunParserError("Completion should be handled by early return");
 			case "help": {
 				let helpGeneratorParser;
-				const helpAsCommand = help === "command" || help === "both";
-				const versionAsCommand = version === "command" || version === "both";
-				const completionAsCommand = completion === "command" || completion === "both";
-				const helpAsOption = help === "option" || help === "both";
-				const versionAsOption = version === "option" || version === "both";
-				const completionAsOption = completion === "option" || completion === "both";
+				const helpAsCommand = helpCommandConfig != null;
+				const versionAsCommand = versionCommandConfig != null;
+				const completionAsCommand = completionCommandConfig != null;
+				const helpAsOption = helpOptionConfig != null;
+				const versionAsOption = versionOptionConfig != null;
+				const completionAsOption = completionOptionConfig != null;
 				const requestedCommand = classified.commands[0];
-				if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
-				else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
-				else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
+				if (requestedCommand != null && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
+				else if (requestedCommand != null && helpCommandNames.includes(requestedCommand) && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
+				else if (requestedCommand != null && versionCommandNames.includes(requestedCommand) && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 				else {
 					const commandParsers = [parser];
 					const groupedMeta = {};
@@ -557,15 +837,24 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						if (groupLabel) (groupedMeta[groupLabel] ??= []).push(p);
 						else ungroupedMeta.push(p);
 					};
-					if (helpAsCommand && helpParsers.helpCommand) addMeta(helpParsers.helpCommand, helpGroup);
-					if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionGroup);
-					if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionGroup);
+					if (helpAsCommand && helpParsers.helpCommand) addMeta(helpParsers.helpCommand, helpCommandConfig?.group);
+					if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionCommandConfig?.group);
+					if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionCommandConfig?.group);
 					commandParsers.push(...ungroupedMeta);
 					for (const [label, parsers] of Object.entries(groupedMeta)) if (parsers.length === 1) commandParsers.push(group(label, parsers[0]));
 					else commandParsers.push(group(label, longestMatch(...parsers)));
-					if (helpAsOption && helpParsers.helpOption) commandParsers.push(helpParsers.helpOption);
-					if (versionAsOption && versionParsers.versionOption) commandParsers.push(versionParsers.versionOption);
-					if (completionAsOption && completionParsers.completionOption) commandParsers.push(completionParsers.completionOption);
+					const groupedMetaOptions = {};
+					const ungroupedMetaOptions = [];
+					const addMetaOption = (p, groupLabel) => {
+						if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(p);
+						else ungroupedMetaOptions.push(p);
+					};
+					if (helpAsOption && helpParsers.helpOption) addMetaOption(helpParsers.helpOption, helpOptionConfig?.group);
+					if (versionAsOption && versionParsers.versionOption) addMetaOption(versionParsers.versionOption, versionOptionConfig?.group);
+					if (completionAsOption && completionParsers.completionOption) addMetaOption(completionParsers.completionOption, completionOptionConfig?.group);
+					commandParsers.push(...ungroupedMetaOptions);
+					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(group(label, optParsers[0]));
+					else commandParsers.push(group(label, longestMatch(...optParsers)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
 					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = longestMatch(...commandParsers);
@@ -583,6 +872,31 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					stderr(`Error: ${errorMessage}`);
 					return onError(1);
 				};
+				const displayHelp = (doc) => {
+					if (doc != null) {
+						const isMetaCommandHelp = requestedCommand != null && completionCommandNames.includes(requestedCommand) || requestedCommand != null && helpCommandNames.includes(requestedCommand) || requestedCommand != null && versionCommandNames.includes(requestedCommand);
+						const isSubcommandHelp = classified.commands.length > 0;
+						const isTopLevel = !isSubcommandHelp;
+						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
+						const augmentedDoc = {
+							...doc,
+							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
+							description: shouldOverride ? description ?? doc.description : doc.description,
+							examples: isTopLevel && !isMetaCommandHelp ? examples ?? doc.examples : void 0,
+							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
+							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
+							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
+						};
+						stdout(formatDocPage(programName, augmentedDoc, {
+							colors,
+							maxWidth,
+							showDefault,
+							showChoices,
+							sectionOrder
+						}));
+					}
+					return onHelp(0);
+				};
 				if (classified.commands.length > 0) {
 					let validationContext = {
 						buffer: [...classified.commands],
@@ -623,34 +937,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}
 					if (validationResult != null) return reportInvalidHelpCommand(validationResult);
 				}
-				const displayHelp = (doc) => {
-					if (doc != null) {
-						const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
-						const isSubcommandHelp = classified.commands.length > 0;
-						const isTopLevel = !isSubcommandHelp;
-						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
-						const augmentedDoc = {
-							...doc,
-							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
-							description: shouldOverride ? description ?? doc.description : doc.description,
-							examples: isTopLevel && !isMetaCommandHelp ? examples ?? doc.examples : void 0,
-							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
-							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
-							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
-						};
-						stdout(formatDocPage(programName, augmentedDoc, {
-							colors,
-							maxWidth,
-							showDefault,
-							showChoices
-						}));
-					}
-					try {
-						return onHelp(0);
-					} catch {
-						return onHelp();
-					}
-				};
 				const docOrPromise = getDocPage(helpGeneratorParser, classified.commands);
 				if (docOrPromise instanceof Promise) return docOrPromise.then(displayHelp);
 				return displayHelp(docOrPromise);
@@ -699,11 +985,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			default: throw new RunParserError("Unexpected parse result type");
 		}
 	};
-	if (parser.$mode === "async") return parseAsync(augmentedParser, args).then(handleResult);
-	else {
+	const parserMode = parser.$mode;
+	return dispatchByMode(parserMode, () => {
 		const result = parseSync(augmentedParser, args);
-		return handleResult(result);
-	}
+		const handled = handleResult(result);
+		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+		return handled;
+	}, async () => {
+		const result = await parseAsync(augmentedParser, args);
+		const handled = handleResult(result);
+		return handled instanceof Promise ? await handled : handled;
+	});
 }
 /**
 * Runs a synchronous command-line parser with the given options.
@@ -772,26 +1064,31 @@ function indentLines(text$1, indent) {
 * @returns `true` if early exit should be performed, `false` otherwise.
 */
 function needsEarlyExit(args, options) {
+	const norm = (c) => c === true ? {} : c;
 	if (options.help) {
-		const helpMode = options.help.mode ?? "option";
-		if ((helpMode === "option" || helpMode === "both") && args.includes("--help")) return true;
-		if ((helpMode === "command" || helpMode === "both") && args[0] === "help") return true;
+		const helpOptionConfig = norm(options.help.option);
+		const helpCommandConfig = norm(options.help.command);
+		const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
+		const helpCommandNames = helpCommandConfig?.names ?? ["help"];
+		if (helpOptionConfig && helpOptionNames.some((n) => args.includes(n))) return true;
+		if (helpCommandConfig && helpCommandNames.includes(args[0])) return true;
 	}
 	if (options.version) {
-		const versionMode = options.version.mode ?? "option";
-		if ((versionMode === "option" || versionMode === "both") && args.includes("--version")) return true;
-		if ((versionMode === "command" || versionMode === "both") && args[0] === "version") return true;
+		const versionOptionConfig = norm(options.version.option);
+		const versionCommandConfig = norm(options.version.command);
+		const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
+		const versionCommandNames = versionCommandConfig?.names ?? ["version"];
+		if (versionOptionConfig && versionOptionNames.some((n) => args.includes(n))) return true;
+		if (versionCommandConfig && versionCommandNames.includes(args[0])) return true;
 	}
 	if (options.completion) {
-		const completionMode = options.completion.mode ?? "both";
-		const completionName = options.completion.name ?? "both";
-		if (completionMode === "command" || completionMode === "both") {
-			if ((completionName === "singular" || completionName === "both") && args[0] === "completion") return true;
-			if ((completionName === "plural" || completionName === "both") && args[0] === "completions") return true;
-		}
-		if (completionMode === "option" || completionMode === "both") for (const arg of args) {
-			if ((completionName === "singular" || completionName === "both") && (arg === "--completion" || arg.startsWith("--completion="))) return true;
-			if ((completionName === "plural" || completionName === "both") && (arg === "--completions" || arg.startsWith("--completions="))) return true;
+		const completionCommandConfig = norm(options.completion.command);
+		const completionOptionConfig = norm(options.completion.option);
+		const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
+		const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
+		if (completionCommandConfig && completionCommandNames.includes(args[0])) return true;
+		if (completionOptionConfig) {
+			for (const arg of args) for (const name of completionOptionNames) if (arg === name || arg.startsWith(name + "=")) return true;
 		}
 	}
 	return false;
@@ -818,23 +1115,22 @@ function mergeAnnotations(annotationsList) {
 * two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param options Optional context-required options to pass to each context.
 * @returns Promise with merged annotations and dynamic-context hint.
 */
-async function collectPhase1Annotations(contexts) {
+async function collectPhase1Annotations(contexts, options) {
 	const annotationsList = [];
 	let hasDynamic = false;
 	for (const context of contexts) {
-		const result = context.getAnnotations();
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		const result = context.getAnnotations(void 0, options);
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		const annotations = result instanceof Promise ? await result : result;
+		const internalAnnotations = context.getInternalAnnotations?.(void 0, annotations);
+		annotationsList.push(internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]));
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
+		annotationsList,
 		hasDynamic
 	};
 }
@@ -843,54 +1139,131 @@ async function collectPhase1Annotations(contexts) {
 *
 * @param contexts Source contexts to collect annotations from.
 * @param parsed Optional parsed result from a previous parse pass.
+* @param options Optional context-required options to pass to each context.
 * @returns Promise that resolves to merged annotations.
 */
-async function collectAnnotations(contexts, parsed) {
+async function collectAnnotations(contexts, parsed, options) {
 	const annotationsList = [];
+	const preparedParsed = prepareParsedForContexts(parsed);
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed);
-		annotationsList.push(result instanceof Promise ? await result : result);
+		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
+			const result = context.getAnnotations(contextParsed, options);
+			const annotations = result instanceof Promise ? await result : result;
+			const internalAnnotations = context.getInternalAnnotations?.(contextParsed, annotations);
+			return internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
+		});
+		annotationsList.push(mergedAnnotations);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		annotationsList
+	};
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
 * whether two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param options Optional context-required options to pass to each context.
 * @returns Merged annotations with dynamic-context hint.
 * @throws Error if any context returns a Promise.
 */
-function collectPhase1AnnotationsSync(contexts) {
+function collectPhase1AnnotationsSync(contexts, options) {
 	const annotationsList = [];
 	let hasDynamic = false;
 	for (const context of contexts) {
-		const result = context.getAnnotations();
+		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-		annotationsList.push(result);
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		const internalAnnotations = context.getInternalAnnotations?.(void 0, result);
+		annotationsList.push(internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]));
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
+		annotationsList,
 		hasDynamic
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.
 * @param parsed Optional parsed result from a previous parse pass.
+* @param options Optional context-required options to pass to each context.
 * @returns Merged annotations.
 * @throws Error if any context returns a Promise.
 */
-function collectAnnotationsSync(contexts, parsed) {
+function collectAnnotationsSync(contexts, parsed, options) {
 	const annotationsList = [];
+	const preparedParsed = prepareParsedForContexts(parsed);
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed);
-		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		annotationsList.push(result);
+		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
+			const result = context.getAnnotations(contextParsed, options);
+			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+			const internalAnnotations = context.getInternalAnnotations?.(contextParsed, result);
+			return internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
+		});
+		annotationsList.push(mergedAnnotations);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		annotationsList
+	};
+}
+function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
+	const mergedPerContext = [];
+	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
+	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
+	return mergeAnnotations(mergedPerContext);
+}
+/**
+* Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
+* Prefers `[Symbol.asyncDispose]` over `[Symbol.dispose]`.
+*
+* @param contexts Source contexts to dispose.
+*/
+async function disposeContexts(contexts) {
+	const errors = [];
+	for (const context of contexts) try {
+		if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") await context[Symbol.asyncDispose]();
+		else if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
+}
+/**
+* Disposes all contexts that implement `Disposable` synchronously.
+* Falls back to `[Symbol.asyncDispose]` when it completes synchronously.
+*
+* @param contexts Source contexts to dispose.
+*/
+function disposeContextsSync(contexts) {
+	const errors = [];
+	for (const context of contexts) try {
+		if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+		else if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") {
+			const result = context[Symbol.asyncDispose]();
+			if (typeof result === "object" && result !== null && "then" in result && typeof result.then === "function") throw new TypeError(`Context ${String(context.id)} returned a Promise from Symbol.asyncDispose in sync mode. Use runWith() or runWithAsync() for async disposal.`);
+		}
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
 * Runs a parser with multiple source contexts.
@@ -950,36 +1323,41 @@ async function runWith(parser, programName, contexts, options) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
-	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts);
-	if (!needsTwoPhase) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser, programName, args, options));
-	}
-	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-	let firstPassResult;
-	let firstPassFailed = false;
 	try {
-		if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
-		else firstPassResult = parseSync(augmentedParser1, args);
-		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
-			const result = firstPassResult;
-			if (result.success) firstPassResult = result.value;
-			else firstPassFailed = true;
+		const ctxOptions = options?.contextOptions;
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+		if (!needsTwoPhase) {
+			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+			return Promise.resolve(runParser(augmentedParser, programName, args, options));
 		}
-	} catch {
-		firstPassFailed = true;
-	}
-	if (firstPassFailed) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+		let firstPassResult;
+		let firstPassFailed = false;
+		try {
+			if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
+			else firstPassResult = parseSync(augmentedParser1, args);
+			if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
+				const result = firstPassResult;
+				if (result.success) firstPassResult = result.value;
+				else firstPassFailed = true;
+			}
+		} catch {
+			firstPassFailed = true;
+		}
+		if (firstPassFailed) {
+			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+			return Promise.resolve(runParser(augmentedParser, programName, args, options));
+		}
+		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions);
+		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+	} finally {
+		await disposeContexts(contexts);
 	}
-	const phase2Annotations = await collectAnnotations(contexts, firstPassResult);
-	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
-	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
-	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
 }
 /**
 * Runs a synchronous parser with multiple source contexts.
@@ -995,31 +1373,37 @@ async function runWith(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns The parsed result.
-* @throws Error if any context returns a Promise.
+* @throws Error if any context returns a Promise or if a context's
+* `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
-	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts);
-	if (!needsTwoPhase) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		return runParser(augmentedParser, programName, args, options);
-	}
-	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-	let firstPassResult;
 	try {
-		const result = parseSync(augmentedParser1, args);
-		if (result.success) firstPassResult = result.value;
-		else return runParser(augmentedParser1, programName, args, options);
-	} catch {
-		return runParser(augmentedParser1, programName, args, options);
+		const ctxOptions = options?.contextOptions;
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
+		if (!needsTwoPhase) {
+			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+			return runParser(augmentedParser, programName, args, options);
+		}
+		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+		let firstPassResult;
+		try {
+			const result = parseSync(augmentedParser1, args);
+			if (result.success) firstPassResult = result.value;
+			else return runParser(augmentedParser1, programName, args, options);
+		} catch {
+			return runParser(augmentedParser1, programName, args, options);
+		}
+		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions);
+		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+		return runParser(augmentedParser2, programName, args, options);
+	} finally {
+		disposeContextsSync(contexts);
 	}
-	const phase2Annotations = collectAnnotationsSync(contexts, firstPassResult);
-	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
-	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	return runParser(augmentedParser2, programName, args, options);
 }
 /**
 * Runs any parser asynchronously with multiple source contexts.
@@ -1048,11 +1432,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	if (parser.initialState == null) return parser;
-	const newInitialState = {
-		...parser.initialState,
-		[annotationKey]: annotations
-	};
+	const newInitialState = injectAnnotations(parser.initialState, annotations);
 	return {
 		...parser,
 		initialState: newInitialState