@optique/core 1.3.0-dev.2352 → 1.3.0-dev.2357

package/dist/constructs.cjs

@@ -582,6 +582,35 @@ function createExclusiveState(parentState, index, parser, result) {
 	return require_internal_annotations.annotateFreshArray(parentState, [index, annotatedResult]);
 }
 /**
+* Detects a branch result that handled only the global options terminator.
+* Such a result advances the shared parser context, but does not identify
+* which exclusive branch matched.
+* @internal
+*/
+function isOptionsTerminatorOnlyResult(context, result) {
+	return !context.optionsTerminated && context.buffer[0] === "--" && result.success && result.next.optionsTerminated && result.consumed.length === 1 && result.consumed[0] === "--";
+}
+function isUnselectedBooleanOptionState(state) {
+	return state != null && typeof state === "object" && "success" in state && state.success === true && "value" in state && state.value === false;
+}
+function preserveExclusiveStateAfterOptionsTerminator(context, result) {
+	const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
+	return {
+		success: true,
+		next: {
+			...context,
+			buffer: result.next.buffer,
+			optionsTerminated: true,
+			state: context.state,
+			...mergedExec != null ? {
+				exec: mergedExec,
+				dependencyRegistry: mergedExec.dependencyRegistry
+			} : {}
+		},
+		consumed: result.consumed
+	};
+}
+/**
 * Creates a complete() method shared by or() and longestMatch().
 * @internal
 */
@@ -819,9 +848,15 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -1002,6 +1037,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -1015,10 +1051,16 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -1201,6 +1243,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -1302,82 +1345,122 @@ function createLongestMatch(...args) {
 			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 		})()
 	});
-	const parseSync = (context) => {
+	const commitLongestMatch = (context, match, optionsTerminatorResult) => {
+		const selectedResult = optionsTerminatorResult == null ? match.result : {
+			...match.result,
+			next: {
+				...match.result.next,
+				buffer: optionsTerminatorResult.next.buffer,
+				optionsTerminated: true
+			},
+			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
+		};
+		const parser = parsers[match.index];
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, selectedResult.next.exec);
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: selectedResult.next.buffer,
+				optionsTerminated: selectedResult.next.optionsTerminated,
+				state: createExclusiveState(context.state, match.index, parser, selectedResult),
+				...mergedExec != null ? {
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: selectedResult.consumed
+		};
+	};
+	const resolveLongestMatchOptionsTerminator = (context, bestMatch, optionsTerminatorMatches) => {
+		if (optionsTerminatorMatches.length < 1) return null;
+		if (bestMatch != null && bestMatch.consumed > 0) return null;
+		const activeState = normalizeExclusiveState(context.state);
+		if (activeState != null && activeState[1].success && activeState[1].consumed.length > 0) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+		let selected = bestMatch == null ? null : {
+			match: bestMatch,
+			fromTerminator: false
+		};
+		for (const match of optionsTerminatorMatches) {
+			if (!match.selectedAfterTerminator && (extractRequiredUsage(parsers[match.index].usage).length > 0 || isUnselectedBooleanOptionState(match.result.next.state))) continue;
+			const selectedIsProvisional = selected != null && !!selected.match.result.provisional;
+			const matchIsProvisional = !!match.result.provisional;
+			if (selected == null || selectedIsProvisional && !matchIsProvisional || selectedIsProvisional === matchIsProvisional && match.index < selected.match.index) selected = {
+				match,
+				fromTerminator: true
+			};
+		}
+		if (selected != null) return commitLongestMatch(context, selected.match, selected.fromTerminator ? void 0 : optionsTerminatorMatches[0].result);
+		return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+	};
+	const parseSyncBranches = (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
-			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const result = parser.parse(childContext);
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = require_execution_context.mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
 		};
 	};
-	const parseAsync = async (context) => {
+	const parseAsyncBranches = async (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
-			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = require_execution_context.mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
@@ -1400,7 +1483,7 @@ function createLongestMatch(...args) {
 			return extractExclusivePhase2Seed(parsers, state, exec, combinedMode);
 		},
 		parse(context) {
-			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
+			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSyncBranches(context), () => parseAsyncBranches(context));
 		},
 		getSuggestRuntimeNodes(state, path) {
 			return getExclusiveSuggestRuntimeNodes(parsers, state, path);

package/dist/constructs.js

@@ -582,6 +582,35 @@ function createExclusiveState(parentState, index, parser, result) {
 	return annotateFreshArray(parentState, [index, annotatedResult]);
 }
 /**
+* Detects a branch result that handled only the global options terminator.
+* Such a result advances the shared parser context, but does not identify
+* which exclusive branch matched.
+* @internal
+*/
+function isOptionsTerminatorOnlyResult(context, result) {
+	return !context.optionsTerminated && context.buffer[0] === "--" && result.success && result.next.optionsTerminated && result.consumed.length === 1 && result.consumed[0] === "--";
+}
+function isUnselectedBooleanOptionState(state) {
+	return state != null && typeof state === "object" && "success" in state && state.success === true && "value" in state && state.value === false;
+}
+function preserveExclusiveStateAfterOptionsTerminator(context, result) {
+	const mergedExec = mergeChildExec(context.exec, result.next.exec);
+	return {
+		success: true,
+		next: {
+			...context,
+			buffer: result.next.buffer,
+			optionsTerminated: true,
+			state: context.state,
+			...mergedExec != null ? {
+				exec: mergedExec,
+				dependencyRegistry: mergedExec.dependencyRegistry
+			} : {}
+		},
+		consumed: result.consumed
+	};
+}
+/**
 * Creates a complete() method shared by or() and longestMatch().
 * @internal
 */
@@ -819,9 +848,15 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -1002,6 +1037,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -1015,10 +1051,16 @@ function or(...args) {
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
+		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
+				optionsTerminatorResult ??= result;
+				continue;
+			}
 			if (result.success && result.consumed.length > 0) {
 				if (result.provisional) {
 					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
@@ -1201,6 +1243,7 @@ function or(...args) {
 				}
 			}
 		}
+		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
 		return {
 			...error,
 			success: false
@@ -1302,82 +1345,122 @@ function createLongestMatch(...args) {
 			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 		})()
 	});
-	const parseSync = (context) => {
+	const commitLongestMatch = (context, match, optionsTerminatorResult) => {
+		const selectedResult = optionsTerminatorResult == null ? match.result : {
+			...match.result,
+			next: {
+				...match.result.next,
+				buffer: optionsTerminatorResult.next.buffer,
+				optionsTerminated: true
+			},
+			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
+		};
+		const parser = parsers[match.index];
+		const mergedExec = mergeChildExec(context.exec, selectedResult.next.exec);
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: selectedResult.next.buffer,
+				optionsTerminated: selectedResult.next.optionsTerminated,
+				state: createExclusiveState(context.state, match.index, parser, selectedResult),
+				...mergedExec != null ? {
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: selectedResult.consumed
+		};
+	};
+	const resolveLongestMatchOptionsTerminator = (context, bestMatch, optionsTerminatorMatches) => {
+		if (optionsTerminatorMatches.length < 1) return null;
+		if (bestMatch != null && bestMatch.consumed > 0) return null;
+		const activeState = normalizeExclusiveState(context.state);
+		if (activeState != null && activeState[1].success && activeState[1].consumed.length > 0) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+		let selected = bestMatch == null ? null : {
+			match: bestMatch,
+			fromTerminator: false
+		};
+		for (const match of optionsTerminatorMatches) {
+			if (!match.selectedAfterTerminator && (extractRequiredUsage(parsers[match.index].usage).length > 0 || isUnselectedBooleanOptionState(match.result.next.state))) continue;
+			const selectedIsProvisional = selected != null && !!selected.match.result.provisional;
+			const matchIsProvisional = !!match.result.provisional;
+			if (selected == null || selectedIsProvisional && !matchIsProvisional || selectedIsProvisional === matchIsProvisional && match.index < selected.match.index) selected = {
+				match,
+				fromTerminator: true
+			};
+		}
+		if (selected != null) return commitLongestMatch(context, selected.match, selected.fromTerminator ? void 0 : optionsTerminatorMatches[0].result);
+		return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorMatches[0].result);
+	};
+	const parseSyncBranches = (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
-			const result = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const result = parser.parse(childContext);
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
 		};
 	};
-	const parseAsync = async (context) => {
+	const parseAsyncBranches = async (context) => {
 		let bestMatch = null;
+		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
-			const resultOrPromise = parser.parse(withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+			const childContext = withChildContext$1(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
+			if (isOptionsTerminatorOnlyResult(context, result)) {
+				optionsTerminatorMatches.push({
+					index: i,
+					result,
+					consumed: 1,
+					...normalizeExclusiveState(result.next.state) != null ? { selectedAfterTerminator: true } : {}
+				});
+				continue;
+			}
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
-					parser,
 					result,
 					consumed
 				};
 			} else if (error.consumed < result.consumed) error = result;
 		}
-		if (bestMatch && bestMatch.result.success) {
-			const mergedExec = mergeChildExec(context.exec, bestMatch.result.next.exec);
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: bestMatch.result.next.buffer,
-					optionsTerminated: bestMatch.result.next.optionsTerminated,
-					state: createExclusiveState(context.state, bestMatch.index, bestMatch.parser, bestMatch.result),
-					...mergedExec != null ? {
-						exec: mergedExec,
-						dependencyRegistry: mergedExec.dependencyRegistry
-					} : {}
-				},
-				consumed: bestMatch.result.consumed
-			};
-		}
+		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
+		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
 		return {
 			...error,
 			success: false
@@ -1400,7 +1483,7 @@ function createLongestMatch(...args) {
 			return extractExclusivePhase2Seed(parsers, state, exec, combinedMode);
 		},
 		parse(context) {
-			return dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
+			return dispatchByMode(combinedMode, () => parseSyncBranches(context), () => parseAsyncBranches(context));
 		},
 		getSuggestRuntimeNodes(state, path) {
 			return getExclusiveSuggestRuntimeNodes(parsers, state, path);

package/dist/facade.cjs

@@ -952,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", 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 norm = (c) => c === true ? {} : c;
@@ -1045,6 +1045,41 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
 	});
+	const helpAsCommand = helpCommandConfig != null;
+	const versionAsCommand = versionCommandConfig != null;
+	const completionAsCommand = completionCommandConfig != null;
+	const helpAsOption = helpOptionConfig != null;
+	const versionAsOption = versionOptionConfig != null;
+	const completionAsOption = completionOptionConfig != null;
+	let cachedRootHelpGeneratorParser;
+	const getRootHelpGeneratorParser = () => {
+		if (cachedRootHelpGeneratorParser != null) return cachedRootHelpGeneratorParser;
+		const commandParsers = [parser];
+		const groupedMeta = {};
+		const ungroupedMeta = [];
+		const addMeta = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMeta[groupLabel] ??= []).push(metaParser);
+			else ungroupedMeta.push(metaParser);
+		};
+		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)) commandParsers.push(require_constructs.group(label, parsers.length === 1 ? parsers[0] : require_constructs.longestMatch(...parsers)));
+		const groupedMetaOptions = {};
+		const ungroupedMetaOptions = [];
+		const addMetaOption = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(metaParser);
+			else ungroupedMetaOptions.push(metaParser);
+		};
+		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, parsers] of Object.entries(groupedMetaOptions)) commandParsers.push(require_constructs.group(label, parsers.length === 1 ? parsers[0] : require_constructs.longestMatch(...parsers)));
+		cachedRootHelpGeneratorParser = commandParsers.length === 1 ? commandParsers[0] : longestMatchForMetaCommands(...commandParsers);
+		return cachedRootHelpGeneratorParser;
+	};
 	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
@@ -1059,12 +1094,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
-				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 != null && !classified.preferUserCommandDocs && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) {
 					helpGeneratorParser = completionParsers.completionCommand;
@@ -1076,33 +1105,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					helpGeneratorParser = versionParsers.versionCommand;
 					docGeneratorParser = helpGeneratorParser;
 				} else {
-					const commandParsers = [parser];
-					const groupedMeta = {};
-					const ungroupedMeta = [];
-					const addMeta = (p, groupLabel) => {
-						if (groupLabel) (groupedMeta[groupLabel] ??= []).push(p);
-						else ungroupedMeta.push(p);
-					};
-					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(require_constructs.group(label, parsers[0]));
-					else commandParsers.push(require_constructs.group(label, require_constructs.longestMatch(...parsers)));
-					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(require_constructs.group(label, optParsers[0]));
-					else commandParsers.push(require_constructs.group(label, require_constructs.longestMatch(...optParsers)));
-					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
+					helpGeneratorParser = getRootHelpGeneratorParser();
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
@@ -1133,7 +1136,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						stdout(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1193,6 +1197,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
+						const isTopLevel = classified.commandPath.length < 1;
 						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
@@ -1201,8 +1206,10 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: author ?? doc.author,
 							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
-						}, commandList, classified.commandPath.length < 1);
-						stderr(require_doc.formatDocPage(programName, augmentedDoc, {
+						}, commandList, isTopLevel);
+						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? require_usage.normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						stderr(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1298,6 +1305,13 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
+	const customUsageLine = typeof usageLine === "function" ? usageLine(require_usage.cloneUsage(defaultUsageLine)) : usageLine;
+	return {
+		...doc,
+		usage: require_usage.normalizeUsage(customUsageLine)
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {

package/dist/facade.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { HiddenVisibility, OptionName } from "./usage.cjs";
+import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
@@ -127,6 +127,20 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * Usage line override for top-level full help.
+   *
+   * This option customizes the usage shown by `--help`, the root help command,
+   * and `aboveError: "help"` at the root.  It does not affect subcommand help,
+   * parsing, shell completion, or usage-only error preambles from
+   * `aboveError: "usage"`.
+   *
+   * The callback form receives the generated root usage after built-in help,
+   * version, and completion entries have been added.
+   *
+   * @since 1.3.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * How to render command lists in top-level help pages.
    *

package/dist/facade.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { HiddenVisibility, OptionName } from "./usage.js";
+import { HiddenVisibility, OptionName, Usage } from "./usage.js";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
@@ -127,6 +127,20 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * Usage line override for top-level full help.
+   *
+   * This option customizes the usage shown by `--help`, the root help command,
+   * and `aboveError: "help"` at the root.  It does not affect subcommand help,
+   * parsing, shell completion, or usage-only error preambles from
+   * `aboveError: "usage"`.
+   *
+   * The callback form receives the generated root usage after built-in help,
+   * version, and completion entries have been added.
+   *
+   * @since 1.3.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * How to render command lists in top-level help pages.
    *

package/dist/facade.js

@@ -1,7 +1,7 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
-import { formatUsage, isSuggestionHidden } from "./usage.js";
+import { cloneUsage, formatUsage, isSuggestionHidden, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
@@ -952,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", 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 norm = (c) => c === true ? {} : c;
@@ -1045,6 +1045,41 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
 	});
+	const helpAsCommand = helpCommandConfig != null;
+	const versionAsCommand = versionCommandConfig != null;
+	const completionAsCommand = completionCommandConfig != null;
+	const helpAsOption = helpOptionConfig != null;
+	const versionAsOption = versionOptionConfig != null;
+	const completionAsOption = completionOptionConfig != null;
+	let cachedRootHelpGeneratorParser;
+	const getRootHelpGeneratorParser = () => {
+		if (cachedRootHelpGeneratorParser != null) return cachedRootHelpGeneratorParser;
+		const commandParsers = [parser];
+		const groupedMeta = {};
+		const ungroupedMeta = [];
+		const addMeta = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMeta[groupLabel] ??= []).push(metaParser);
+			else ungroupedMeta.push(metaParser);
+		};
+		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)) commandParsers.push(group(label, parsers.length === 1 ? parsers[0] : longestMatch(...parsers)));
+		const groupedMetaOptions = {};
+		const ungroupedMetaOptions = [];
+		const addMetaOption = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(metaParser);
+			else ungroupedMetaOptions.push(metaParser);
+		};
+		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, parsers] of Object.entries(groupedMetaOptions)) commandParsers.push(group(label, parsers.length === 1 ? parsers[0] : longestMatch(...parsers)));
+		cachedRootHelpGeneratorParser = commandParsers.length === 1 ? commandParsers[0] : longestMatchForMetaCommands(...commandParsers);
+		return cachedRootHelpGeneratorParser;
+	};
 	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
@@ -1059,12 +1094,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
-				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 != null && !classified.preferUserCommandDocs && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) {
 					helpGeneratorParser = completionParsers.completionCommand;
@@ -1076,33 +1105,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					helpGeneratorParser = versionParsers.versionCommand;
 					docGeneratorParser = helpGeneratorParser;
 				} else {
-					const commandParsers = [parser];
-					const groupedMeta = {};
-					const ungroupedMeta = [];
-					const addMeta = (p, groupLabel) => {
-						if (groupLabel) (groupedMeta[groupLabel] ??= []).push(p);
-						else ungroupedMeta.push(p);
-					};
-					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)));
-					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 helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
+					helpGeneratorParser = getRootHelpGeneratorParser();
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
@@ -1133,7 +1136,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						stdout(formatDocPage(programName, augmentedDoc, {
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						stdout(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1193,6 +1197,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
+						const isTopLevel = classified.commandPath.length < 1;
 						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
@@ -1201,8 +1206,10 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: author ?? doc.author,
 							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
-						}, commandList, classified.commandPath.length < 1);
-						stderr(formatDocPage(programName, augmentedDoc, {
+						}, commandList, isTopLevel);
+						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						stderr(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1298,6 +1305,13 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
+	const customUsageLine = typeof usageLine === "function" ? usageLine(cloneUsage(defaultUsageLine)) : usageLine;
+	return {
+		...doc,
+		usage: normalizeUsage(customUsageLine)
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2352",
+  "version": "1.3.0-dev.2357",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -225,7 +225,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.3.0-dev.2352+32a63ede"
+    "@optique/env": "1.3.0-dev.2357+dcd8c5c2"
   },
   "scripts": {
     "build": "tsdown",

package/skills/optique/SKILL.md

@@ -56,6 +56,9 @@ Core rules
     discriminated union.
  -  Enable completion through `run(parser, { completion: "both" })` for CLI
     apps. Do not hand-write completion scripts from parser metadata.
+ -  Use `usageLine: [{ type: "ellipsis" }]` in runner options when a large root
+    synopsis should become a compact `Usage: myapp ...` line. This applies only
+    to root full help; use `command()`'s `usageLine` for subcommand help.
  -  Use `showUsage: false` in runner options when full help should show the
     brief and command or option sections without the `Usage:` synopsis.
     For deeply nested command trees, add `commandList: "top-level"` when root