@optique/core 1.2.0-dev.2298 → 1.2.0-dev.2301

package/dist/facade.cjs

@@ -539,7 +539,8 @@ function getHelpCommandContext(commandPath, args, helpIndex) {
 function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionOptionNames, completionCommandNames) {
 	if (failure.remainingArgs.length < 1) return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 	const hasConsumedPrefix = failure.consumedCount > 0;
 	const firstArg = failure.remainingArgs[0];
@@ -571,7 +572,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 		if (secondArg == null || isCompletionImmediatelyAfter || lastHelpVersion?.index === 1 && lastHelpVersion.kind === "version") return { type: "version" };
 		return {
 			type: "error",
-			error: failure.error
+			error: failure.error,
+			commandPath: failure.commandPath
 		};
 	}
 	let commandAction;
@@ -601,7 +603,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 	};
 	return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 }
 /**
@@ -949,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, 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;
@@ -1121,7 +1124,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const isSubcommandHelp = classified.commands.length > 0;
 						const isTopLevel = !isSubcommandHelp;
 						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
 							description: shouldOverride ? description ?? doc.description : doc.description,
@@ -1129,7 +1132,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
-						};
+						}, commandList, isTopLevel);
 						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
@@ -1190,7 +1193,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
@@ -1198,7 +1201,7 @@ 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, {
 							colors,
 							maxWidth,
@@ -1295,6 +1298,42 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function maybeCollapseCommandList(doc, commandList, isTopLevel) {
+	if (commandList !== "top-level" || !isTopLevel) return doc;
+	return {
+		...doc,
+		sections: doc.sections.map((section) => ({
+			...section,
+			entries: collapseTopLevelCommandEntries(section.entries)
+		}))
+	};
+}
+function collapseTopLevelCommandEntries(entries) {
+	const collapsed = [];
+	const commandIndexes = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.term.type !== "command") {
+			collapsed.push(entry);
+			continue;
+		}
+		const topLevelName = getTopLevelCommandName(entry.term.name);
+		const existingIndex = commandIndexes.get(topLevelName);
+		const isTopLevel = entry.term.name === topLevelName;
+		if (existingIndex == null) {
+			commandIndexes.set(topLevelName, collapsed.length);
+			collapsed.push(isTopLevel ? entry : { term: {
+				...entry.term,
+				name: topLevelName
+			} });
+			continue;
+		}
+		if (isTopLevel) collapsed[existingIndex] = entry;
+	}
+	return collapsed;
+}
+function getTopLevelCommandName(name) {
+	return name.split(" ", 1)[0] ?? name;
+}
 /**
 * An error class used to indicate that the command line arguments
 * could not be parsed successfully.

package/dist/facade.d.cts

@@ -8,6 +8,17 @@ import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
 
+/**
+ * Controls how command lists are rendered in top-level help pages.
+ *
+ * - `"recursive"`: Shows the full flattened command list, including nested
+ *   leaf commands such as `remote add`.
+ * - `"top-level"`: Shows only first-level command names such as `remote`,
+ *   letting users drill down with `remote --help`.
+ *
+ * @since 1.2.0
+ */
+type CommandListMode = "recursive" | "top-level";
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -116,6 +127,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * How to render command lists in top-level help pages.
+   *
+   * Pass `"top-level"` to show only first-level commands in the command menu
+   * while keeping nested command help available through `<command> --help`.
+   *
+   * @default `"recursive"`
+   * @since 1.2.0
+   */
+  readonly commandList?: CommandListMode;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart
@@ -534,4 +555,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -8,6 +8,17 @@ import { Program } from "./program.js";
 
 //#region src/facade.d.ts
 
+/**
+ * Controls how command lists are rendered in top-level help pages.
+ *
+ * - `"recursive"`: Shows the full flattened command list, including nested
+ *   leaf commands such as `remote add`.
+ * - `"top-level"`: Shows only first-level command names such as `remote`,
+ *   letting users drill down with `remote --help`.
+ *
+ * @since 1.2.0
+ */
+type CommandListMode = "recursive" | "top-level";
 /**
  * Sub-configuration for a meta command's command form.
  *
@@ -116,6 +127,16 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * How to render command lists in top-level help pages.
+   *
+   * Pass `"top-level"` to show only first-level commands in the command menu
+   * while keeping nested command help available through `<command> --help`.
+   *
+   * @default `"recursive"`
+   * @since 1.2.0
+   */
+  readonly commandList?: CommandListMode;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart
@@ -534,4 +555,4 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, type SourceContextRequest, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -539,7 +539,8 @@ function getHelpCommandContext(commandPath, args, helpIndex) {
 function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionOptionNames, completionCommandNames) {
 	if (failure.remainingArgs.length < 1) return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 	const hasConsumedPrefix = failure.consumedCount > 0;
 	const firstArg = failure.remainingArgs[0];
@@ -571,7 +572,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 		if (secondArg == null || isCompletionImmediatelyAfter || lastHelpVersion?.index === 1 && lastHelpVersion.kind === "version") return { type: "version" };
 		return {
 			type: "error",
-			error: failure.error
+			error: failure.error,
+			commandPath: failure.commandPath
 		};
 	}
 	let commandAction;
@@ -601,7 +603,8 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 	};
 	return {
 		type: "error",
-		error: failure.error
+		error: failure.error,
+		commandPath: failure.commandPath
 	};
 }
 /**
@@ -949,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, 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;
@@ -1121,7 +1124,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						const isSubcommandHelp = classified.commands.length > 0;
 						const isTopLevel = !isSubcommandHelp;
 						const shouldOverride = !isMetaCommandHelp && !isSubcommandHelp;
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: shouldOverride ? brief ?? doc.brief : doc.brief,
 							description: shouldOverride ? description ?? doc.description : doc.description,
@@ -1129,7 +1132,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							author: isTopLevel && !isMetaCommandHelp ? author ?? doc.author : void 0,
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
-						};
+						}, commandList, isTopLevel);
 						stdout(formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
@@ -1190,7 +1193,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
-						const augmentedDoc = {
+						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
@@ -1198,7 +1201,7 @@ 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, {
 							colors,
 							maxWidth,
@@ -1295,6 +1298,42 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function maybeCollapseCommandList(doc, commandList, isTopLevel) {
+	if (commandList !== "top-level" || !isTopLevel) return doc;
+	return {
+		...doc,
+		sections: doc.sections.map((section) => ({
+			...section,
+			entries: collapseTopLevelCommandEntries(section.entries)
+		}))
+	};
+}
+function collapseTopLevelCommandEntries(entries) {
+	const collapsed = [];
+	const commandIndexes = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.term.type !== "command") {
+			collapsed.push(entry);
+			continue;
+		}
+		const topLevelName = getTopLevelCommandName(entry.term.name);
+		const existingIndex = commandIndexes.get(topLevelName);
+		const isTopLevel = entry.term.name === topLevelName;
+		if (existingIndex == null) {
+			commandIndexes.set(topLevelName, collapsed.length);
+			collapsed.push(isTopLevel ? entry : { term: {
+				...entry.term,
+				name: topLevelName
+			} });
+			continue;
+		}
+		if (isTopLevel) collapsed[existingIndex] = entry;
+	}
+	return collapsed;
+}
+function getTopLevelCommandName(name) {
+	return name.split(" ", 1)[0] ?? name;
+}
 /**
 * An error class used to indicate that the command line arguments
 * could not be parsed successfully.

package/dist/index.d.cts

@@ -10,6 +10,6 @@ import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser,
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
-import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -10,6 +10,6 @@ import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser,
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
-import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2298",
+  "version": "1.2.0-dev.2301",
   "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.2.0-dev.2298+a0394b06"
+    "@optique/env": "1.2.0-dev.2301+7cd22796"
   },
   "scripts": {
     "build": "tsdown",

package/skills/optique/SKILL.md

@@ -55,6 +55,8 @@ Core rules
     apps. Do not hand-write completion scripts from parser metadata.
  -  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
+    help should list only first-level command groups.
 
 
 Canonical app shape