@optique/core 0.10.7-dev.485 → 1.0.0-dev.1109

package/dist/parser.cjs

@@ -1,11 +1,17 @@
 const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
+const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
 
 //#region src/parser.ts
+function injectAnnotationsIntoState(state, options) {
+	const annotations = options?.annotations;
+	if (annotations == null) return state;
+	return require_annotations.injectAnnotations(state, annotations);
+}
 /**
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
@@ -29,11 +35,8 @@ const require_primitives = require('./primitives.cjs');
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parseSync(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -56,7 +59,7 @@ function parseSync(parser, args, options) {
 	const endResult = parser.complete(context.state);
 	return endResult.success ? {
 		success: true,
-		value: endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	} : {
 		success: false,
 		error: endResult.error
@@ -82,11 +85,8 @@ function parseSync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 async function parseAsync(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -109,7 +109,7 @@ async function parseAsync(parser, args, options) {
 	const endResult = await parser.complete(context.state);
 	return endResult.success ? {
 		success: true,
-		value: endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	} : {
 		success: false,
 		error: endResult.error
@@ -138,8 +138,7 @@ async function parseAsync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parse(parser, args, options) {
-	if (parser.$mode === "async") return parseAsync(parser, args, options);
-	return parseSync(parser, args, options);
+	return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(parser, args, options), () => parseAsync(parser, args, options));
 }
 /**
 * Generates command-line suggestions based on current parsing state.
@@ -180,11 +179,7 @@ function parse(parser, args, options) {
 function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
@@ -223,11 +218,7 @@ function suggestSync(parser, args, options) {
 async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
@@ -273,8 +264,7 @@ async function suggestAsync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function suggest(parser, args, options) {
-	if (parser.$mode === "async") return suggestAsync(parser, args, options);
-	return suggestSync(parser, args, options);
+	return require_mode_dispatch.dispatchByMode(parser.$mode, () => suggestSync(parser, args, options), () => suggestAsync(parser, args, options));
 }
 /**
 * Recursively searches for a command within nested exclusive usage terms.
@@ -339,11 +329,7 @@ function getDocPage(parser, args = [], options) {
 * Internal sync implementation of getDocPage.
 */
 function getDocPageSyncImpl(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -361,11 +347,7 @@ function getDocPageSyncImpl(parser, args, options) {
 * Internal async implementation of getDocPage.
 */
 async function getDocPageAsyncImpl(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[require_annotations.annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -384,29 +366,79 @@ async function getDocPageAsyncImpl(parser, args, options) {
 * Shared by both sync and async implementations.
 */
 function buildDocPage(parser, context, args) {
-	const { brief, description, fragments, footer } = parser.getDocFragments({
+	let effectiveArgs = args;
+	let { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
-	const entries = fragments.filter((f) => f.type === "entry");
-	const sections = [];
-	for (const fragment of fragments) {
-		if (fragment.type !== "section") continue;
-		if (fragment.title == null) entries.push(...fragment.entries);
-		else sections.push(fragment);
+	if (args.length === 0 && Reflect.get(parser, Symbol.for("@optique/core/commandParser")) === true && fragments.length === 1 && fragments[0].type === "entry" && fragments[0].term.type === "command") {
+		const cmdName = fragments[0].term.name;
+		const matched = parser.getDocFragments({
+			kind: "available",
+			state: ["matched", cmdName]
+		}, void 0);
+		({brief, description, fragments, footer} = matched);
+		effectiveArgs = [cmdName];
 	}
-	if (entries.length > 0) sections.push({ entries });
+	const buildingSections = [];
+	let untitledSection = null;
+	const titledSectionMap = /* @__PURE__ */ new Map();
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(fragment);
+	} else if (fragment.type === "section") if (fragment.title == null) {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(...fragment.entries);
+	} else {
+		let section = titledSectionMap.get(fragment.title);
+		if (section == null) {
+			section = {
+				title: fragment.title,
+				entries: []
+			};
+			titledSectionMap.set(fragment.title, section);
+			buildingSections.push(section);
+		}
+		section.entries.push(...fragment.entries);
+	}
+	const sections = buildingSections;
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
+	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
+		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
+		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
+		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
+	};
 	let i = 0;
-	for (const arg of args) {
+	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
+		const arg = effectiveArgs[argIndex];
 		if (i >= usage.length) break;
-		const term = usage[i];
+		let term = usage[i];
 		if (term.type === "exclusive") {
 			const found = findCommandInExclusive(term, arg);
-			if (found) usage.splice(i, 1, ...found);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				term = usage[i];
+			}
 		}
+		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
 		i++;
 	}
+	if (effectiveArgs.length === 0 && usage.length > 0) {
+		const first = usage[0];
+		if (first.type === "command" && first.usageLine != null) {
+			const defaultUsageLine = usage.slice(1);
+			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
+			usage.splice(1, usage.length - 1, ...require_usage.normalizeUsage(customUsageLine));
+		}
+	}
 	return {
 		usage,
 		sections,
@@ -424,6 +456,7 @@ exports.command = require_primitives.command;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
+exports.fail = require_primitives.fail;
 exports.flag = require_primitives.flag;
 exports.getDocPage = getDocPage;
 exports.getDocPageAsync = getDocPageAsync;

package/dist/parser.d.cts

@@ -4,9 +4,9 @@ import { Usage } from "./usage.cjs";
 import { DocFragments, DocPage } from "./doc.cjs";
 import { DependencyRegistryLike } from "./registry-types.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
-import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
 
 //#region src/parser.d.ts
 
@@ -158,6 +158,21 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    *          fragments for this parser.
    */
   getDocFragments(state: DocState<TState>, defaultValue?: TValue): DocFragments;
+  /**
+   * Optional predicate that determines whether completion should be
+   * deferred for the given parser state.
+   *
+   * When present, combinator wrappers ({@link optional}, {@link withDefault},
+   * {@link group}) forward this field to the outer parser.  This enables
+   * packages like *\@optique/inquirer* to detect when interactive prompting
+   * should be deferred until an outer context (like a configuration file
+   * source) has resolved.
+   *
+   * @param state The current parser state.
+   * @returns `true` if completion should be deferred.
+   * @since 1.0.0
+   */
+  shouldDeferCompletion?(state: TState): boolean;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.
@@ -534,4 +549,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: rea
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.d.ts

@@ -4,9 +4,9 @@ import { Usage } from "./usage.js";
 import { DocFragments, DocPage } from "./doc.js";
 import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
-import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.d.ts
 
@@ -158,6 +158,21 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    *          fragments for this parser.
    */
   getDocFragments(state: DocState<TState>, defaultValue?: TValue): DocFragments;
+  /**
+   * Optional predicate that determines whether completion should be
+   * deferred for the given parser state.
+   *
+   * When present, combinator wrappers ({@link optional}, {@link withDefault},
+   * {@link group}) forward this field to the outer parser.  This enables
+   * packages like *\@optique/inquirer* to detect when interactive prompting
+   * should be deferred until an outer context (like a configuration file
+   * source) has resolved.
+   *
+   * @param state The current parser state.
+   * @returns `true` if completion should be deferred.
+   * @since 1.0.0
+   */
+  shouldDeferCompletion?(state: TState): boolean;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.
@@ -534,4 +549,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: rea
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.js

@@ -1,11 +1,17 @@
-import { annotationKey } from "./annotations.js";
+import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { message } from "./message.js";
+import { dispatchByMode } from "./mode-dispatch.js";
 import { normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
-import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
+import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.ts
+function injectAnnotationsIntoState(state, options) {
+	const annotations = options?.annotations;
+	if (annotations == null) return state;
+	return injectAnnotations(state, annotations);
+}
 /**
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
@@ -29,11 +35,8 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parseSync(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -56,7 +59,7 @@ function parseSync(parser, args, options) {
 	const endResult = parser.complete(context.state);
 	return endResult.success ? {
 		success: true,
-		value: endResult.value
+		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	} : {
 		success: false,
 		error: endResult.error
@@ -82,11 +85,8 @@ function parseSync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 async function parseAsync(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
+	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -109,7 +109,7 @@ async function parseAsync(parser, args, options) {
 	const endResult = await parser.complete(context.state);
 	return endResult.success ? {
 		success: true,
-		value: endResult.value
+		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	} : {
 		success: false,
 		error: endResult.error
@@ -138,8 +138,7 @@ async function parseAsync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parse(parser, args, options) {
-	if (parser.$mode === "async") return parseAsync(parser, args, options);
-	return parseSync(parser, args, options);
+	return dispatchByMode(parser.$mode, () => parseSync(parser, args, options), () => parseAsync(parser, args, options));
 }
 /**
 * Generates command-line suggestions based on current parsing state.
@@ -180,11 +179,7 @@ function parse(parser, args, options) {
 function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
@@ -223,11 +218,7 @@ function suggestSync(parser, args, options) {
 async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
@@ -273,8 +264,7 @@ async function suggestAsync(parser, args, options) {
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function suggest(parser, args, options) {
-	if (parser.$mode === "async") return suggestAsync(parser, args, options);
-	return suggestSync(parser, args, options);
+	return dispatchByMode(parser.$mode, () => suggestSync(parser, args, options), () => suggestAsync(parser, args, options));
 }
 /**
 * Recursively searches for a command within nested exclusive usage terms.
@@ -339,11 +329,7 @@ function getDocPage(parser, args = [], options) {
 * Internal sync implementation of getDocPage.
 */
 function getDocPageSyncImpl(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -361,11 +347,7 @@ function getDocPageSyncImpl(parser, args, options) {
 * Internal async implementation of getDocPage.
 */
 async function getDocPageAsyncImpl(parser, args, options) {
-	let initialState = parser.initialState;
-	if (options?.annotations && initialState != null) initialState = {
-		...typeof initialState === "object" ? initialState : {},
-		[annotationKey]: options.annotations
-	};
+	const initialState = injectAnnotationsIntoState(parser.initialState, options);
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -384,29 +366,79 @@ async function getDocPageAsyncImpl(parser, args, options) {
 * Shared by both sync and async implementations.
 */
 function buildDocPage(parser, context, args) {
-	const { brief, description, fragments, footer } = parser.getDocFragments({
+	let effectiveArgs = args;
+	let { brief, description, fragments, footer } = parser.getDocFragments({
 		kind: "available",
 		state: context.state
 	}, void 0);
-	const entries = fragments.filter((f) => f.type === "entry");
-	const sections = [];
-	for (const fragment of fragments) {
-		if (fragment.type !== "section") continue;
-		if (fragment.title == null) entries.push(...fragment.entries);
-		else sections.push(fragment);
+	if (args.length === 0 && Reflect.get(parser, Symbol.for("@optique/core/commandParser")) === true && fragments.length === 1 && fragments[0].type === "entry" && fragments[0].term.type === "command") {
+		const cmdName = fragments[0].term.name;
+		const matched = parser.getDocFragments({
+			kind: "available",
+			state: ["matched", cmdName]
+		}, void 0);
+		({brief, description, fragments, footer} = matched);
+		effectiveArgs = [cmdName];
 	}
-	if (entries.length > 0) sections.push({ entries });
+	const buildingSections = [];
+	let untitledSection = null;
+	const titledSectionMap = /* @__PURE__ */ new Map();
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(fragment);
+	} else if (fragment.type === "section") if (fragment.title == null) {
+		if (untitledSection == null) {
+			untitledSection = { entries: [] };
+			buildingSections.push(untitledSection);
+		}
+		untitledSection.entries.push(...fragment.entries);
+	} else {
+		let section = titledSectionMap.get(fragment.title);
+		if (section == null) {
+			section = {
+				title: fragment.title,
+				entries: []
+			};
+			titledSectionMap.set(fragment.title, section);
+			buildingSections.push(section);
+		}
+		section.entries.push(...fragment.entries);
+	}
+	const sections = buildingSections;
 	const usage = [...normalizeUsage(parser.usage)];
+	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
+		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
+		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
+		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
+	};
 	let i = 0;
-	for (const arg of args) {
+	for (let argIndex = 0; argIndex < effectiveArgs.length; argIndex++) {
+		const arg = effectiveArgs[argIndex];
 		if (i >= usage.length) break;
-		const term = usage[i];
+		let term = usage[i];
 		if (term.type === "exclusive") {
 			const found = findCommandInExclusive(term, arg);
-			if (found) usage.splice(i, 1, ...found);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				term = usage[i];
+			}
 		}
+		maybeApplyCommandUsageLine(term, arg, argIndex === effectiveArgs.length - 1, i);
 		i++;
 	}
+	if (effectiveArgs.length === 0 && usage.length > 0) {
+		const first = usage[0];
+		if (first.type === "command" && first.usageLine != null) {
+			const defaultUsageLine = usage.slice(1);
+			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
+			usage.splice(1, usage.length - 1, ...normalizeUsage(customUsageLine));
+		}
+	}
 	return {
 		usage,
 		sections,
@@ -417,4 +449,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };