@optique/core 0.10.0-dev.370 → 0.10.0-dev.375

package/dist/facade.cjs

@@ -113,10 +113,7 @@ function createCompletionParser(mode, programName, availableShells, name = "both
 		};
 	}
 }
-/**
-* Systematically combines the original parser with help, version, and completion parsers.
-*/
-function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers) {
+function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers, groups) {
 	const parsers = [];
 	if (helpParsers.helpOption) {
 		const lenientHelpParser = {
@@ -262,35 +259,61 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 		};
 		parsers.push(lenientVersionParser);
 	}
-	if (versionParsers.versionCommand) parsers.push(require_constructs.object({
-		help: require_primitives.constant(false),
-		version: require_primitives.constant(true),
-		completion: require_primitives.constant(false),
-		result: versionParsers.versionCommand,
-		helpFlag: helpParsers.helpOption ? require_modifiers.optional(helpParsers.helpOption) : require_primitives.constant(false)
-	}));
-	if (completionParsers.completionCommand) parsers.push(require_constructs.object({
-		help: require_primitives.constant(false),
-		version: require_primitives.constant(false),
-		completion: require_primitives.constant(true),
-		completionData: completionParsers.completionCommand,
-		helpFlag: helpParsers.helpOption ? require_modifiers.optional(helpParsers.helpOption) : require_primitives.constant(false)
-	}));
-	if (helpParsers.helpCommand) parsers.push(require_constructs.object({
-		help: require_primitives.constant(true),
-		version: require_primitives.constant(false),
-		completion: require_primitives.constant(false),
-		commands: helpParsers.helpCommand
-	}));
+	if (versionParsers.versionCommand) {
+		const versionParser = require_constructs.object({
+			help: require_primitives.constant(false),
+			version: require_primitives.constant(true),
+			completion: require_primitives.constant(false),
+			result: versionParsers.versionCommand,
+			helpFlag: helpParsers.helpOption ? require_modifiers.optional(helpParsers.helpOption) : require_primitives.constant(false)
+		});
+		parsers.push(groups?.versionGroup ? require_constructs.group(groups.versionGroup, versionParser) : versionParser);
+	}
+	if (completionParsers.completionCommand) {
+		const completionParser = require_constructs.object({
+			help: require_primitives.constant(false),
+			version: require_primitives.constant(false),
+			completion: require_primitives.constant(true),
+			completionData: completionParsers.completionCommand,
+			helpFlag: helpParsers.helpOption ? require_modifiers.optional(helpParsers.helpOption) : require_primitives.constant(false)
+		});
+		parsers.push(groups?.completionGroup ? require_constructs.group(groups.completionGroup, completionParser) : completionParser);
+	}
+	if (helpParsers.helpCommand) {
+		const helpParser = require_constructs.object({
+			help: require_primitives.constant(true),
+			version: require_primitives.constant(false),
+			completion: require_primitives.constant(false),
+			commands: helpParsers.helpCommand
+		});
+		parsers.push(groups?.helpGroup ? require_constructs.group(groups.helpGroup, helpParser) : helpParser);
+	}
 	parsers.push(require_constructs.object({
 		help: require_primitives.constant(false),
 		version: require_primitives.constant(false),
 		completion: require_primitives.constant(false),
 		result: originalParser
 	}));
+	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return require_constructs.longestMatch(parsers[0], parsers[1]);
-	else return require_constructs.longestMatch(...parsers);
+	let combined;
+	if (parsers.length === 2) combined = require_constructs.longestMatch(parsers[0], parsers[1]);
+	else combined = require_constructs.longestMatch(...parsers);
+	const topUsage = combined.usage[0];
+	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
+		const terms = [...topUsage.terms];
+		const [mainTerm] = terms.splice(mainParserIndex, 1);
+		const lenientCount = (helpParsers.helpOption ? 1 : 0) + (versionParsers.versionOption ? 1 : 0);
+		terms.splice(lenientCount, 0, mainTerm);
+		combined = {
+			...combined,
+			usage: [{
+				...topUsage,
+				terms
+			}]
+		};
+	}
+	return combined;
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -439,13 +462,16 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
+	const helpGroup = options.help?.group;
 	const versionMode = options.version?.mode ?? "option";
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
+	const versionGroup = options.version?.group;
 	const completionMode = options.completion?.mode ?? "both";
 	const completionName = options.completion?.name ?? "both";
 	const completionHelpVisibility = options.completion?.helpVisibility ?? completionName;
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
+	const completionGroup = options.completion?.group;
 	const defaultShells = {
 		bash: require_completion.bash,
 		fish: require_completion.fish,
@@ -494,7 +520,11 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			}
 		}
 	}
-	const augmentedParser = help === "none" && version === "none" && completion === "none" ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers);
+	const augmentedParser = help === "none" && version === "none" && completion === "none" ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
+		helpGroup,
+		versionGroup,
+		completionGroup
+	});
 	const handleResult = (result) => {
 		const classified = classifyResult(result, args);
 		switch (classified.type) {
@@ -518,15 +548,18 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 				else {
 					const commandParsers = [parser];
-					if (helpAsCommand) {
-						if (helpParsers.helpCommand) commandParsers.push(helpParsers.helpCommand);
-					}
-					if (versionAsCommand) {
-						if (versionParsers.versionCommand) commandParsers.push(versionParsers.versionCommand);
-					}
-					if (completionAsCommand) {
-						if (completionParsers.completionCommand) commandParsers.push(completionParsers.completionCommand);
-					}
+					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, helpGroup);
+					if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionGroup);
+					if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionGroup);
+					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)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
 					else if (commandParsers.length === 2) helpGeneratorParser = require_constructs.longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = require_constructs.longestMatch(...commandParsers);

package/dist/facade.d.cts

@@ -24,30 +24,51 @@ type CompletionConfigBase<THelp> = {
    * Determines how completion is made available:
    *
    * - `"command"`: Only the `completion` subcommand is available
-   * - `"option"`: Only the `--completion` option is available
-   * - `"both"`: Both `completion` subcommand and `--completion` option are available
+   * - `"both"`: Both `completion` subcommand and `--completion` option
+   *   are available
    *
    * @default `"both"`
    */
-  readonly mode?: "command" | "option" | "both";
+  readonly mode?: "command" | "both";
+  /**
+   * Group label for the completion command in help output. When specified,
+   * the completion command appears under a titled section with this name
+   * instead of alongside user-defined commands.
+   *
+   * @since 0.10.0
+   */
+  readonly group?: string;
   /**
    * Available shell completions. By default, includes `bash`, `fish`, `nu`,
-   * `pwsh`, and `zsh`. You can provide additional custom shell completions or
-   * override the defaults.
+   * `pwsh`, and `zsh`. You can provide additional custom shell completions
+   * or override the defaults.
    *
    * @default `{ bash, fish, nu, pwsh, zsh }`
    */
   readonly shells?: Record<string, ShellCompletion>;
   /**
-   * Callback function invoked when completion is requested. The function can
-   * optionally receive an exit code parameter.
+   * Callback function invoked when completion is requested. The function
+   * can optionally receive an exit code parameter.
    *
-   * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
-   * on Deno to this option.
+   * You usually want to pass `process.exit` on Node.js or Bun and
+   * `Deno.exit` on Deno to this option.
    *
    * @default Returns `void` when completion is shown.
    */
   readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+} | {
+  /**
+   * Determines how completion is made available:
+   *
+   * - `"option"`: Only the `--completion` option is available
+   */
+  readonly mode: "option";
+  /** @since 0.10.0 */
+  readonly group?: never;
+  /** @default `{ bash, fish, nu, pwsh, zsh }` */
+  readonly shells?: Record<string, ShellCompletion>;
+  /** @default Returns `void` when completion is shown. */
+  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
 };
 type CompletionConfigBoth<THelp> = CompletionConfigBase<THelp> & {
   /**
@@ -135,18 +156,46 @@ interface RunOptions<THelp, TError> {
      * Determines how help is made available:
      *
      * - `"command"`: Only the `help` subcommand is available
-     * - `"option"`: Only the `--help` option is available
      * - `"both"`: Both `help` subcommand and `--help` option are available
      *
      * @default `"option"`
      */
-    readonly mode?: "command" | "option" | "both";
+    readonly mode: "command" | "both";
+    /**
+     * Group label for the help command in help output. When specified,
+     * the help command appears under a titled section with this name
+     * instead of alongside user-defined commands.
+     *
+     * @since 0.10.0
+     */
+    readonly group?: string;
     /**
      * Callback function invoked when help is requested. The function can
      * optionally receive an exit code parameter.
      *
-     * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
-     * on Deno to this option.
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
+     *
+     * @default Returns `void` when help is shown.
+     */
+    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } | {
+    /**
+     * Determines how help is made available:
+     *
+     * - `"option"`: Only the `--help` option is available
+     *
+     * @default `"option"`
+     */
+    readonly mode?: "option";
+    /** @since 0.10.0 */
+    readonly group?: never;
+    /**
+     * Callback function invoked when help is requested. The function can
+     * optionally receive an exit code parameter.
+     *
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
      *
      * @default Returns `void` when help is shown.
      */
@@ -160,22 +209,55 @@ interface RunOptions<THelp, TError> {
      * Determines how version is made available:
      *
      * - `"command"`: Only the `version` subcommand is available
+     * - `"both"`: Both `version` subcommand and `--version` option are
+     *   available
+     *
+     * @default `"option"`
+     */
+    readonly mode: "command" | "both";
+    /**
+     * The version string to display when version is requested.
+     */
+    readonly value: string;
+    /**
+     * Group label for the version command in help output. When specified,
+     * the version command appears under a titled section with this name
+     * instead of alongside user-defined commands.
+     *
+     * @since 0.10.0
+     */
+    readonly group?: string;
+    /**
+     * Callback function invoked when version is requested. The function can
+     * optionally receive an exit code parameter.
+     *
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
+     *
+     * @default Returns `void` when version is shown.
+     */
+    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } | {
+    /**
+     * Determines how version is made available:
+     *
      * - `"option"`: Only the `--version` option is available
-     * - `"both"`: Both `version` subcommand and `--version` option are available
      *
      * @default `"option"`
      */
-    readonly mode?: "command" | "option" | "both";
+    readonly mode?: "option";
     /**
      * The version string to display when version is requested.
      */
     readonly value: string;
+    /** @since 0.10.0 */
+    readonly group?: never;
     /**
      * Callback function invoked when version is requested. The function can
      * optionally receive an exit code parameter.
      *
-     * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
-     * on Deno to this option.
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
      *
      * @default Returns `void` when version is shown.
      */

package/dist/facade.d.ts

@@ -24,30 +24,51 @@ type CompletionConfigBase<THelp> = {
    * Determines how completion is made available:
    *
    * - `"command"`: Only the `completion` subcommand is available
-   * - `"option"`: Only the `--completion` option is available
-   * - `"both"`: Both `completion` subcommand and `--completion` option are available
+   * - `"both"`: Both `completion` subcommand and `--completion` option
+   *   are available
    *
    * @default `"both"`
    */
-  readonly mode?: "command" | "option" | "both";
+  readonly mode?: "command" | "both";
+  /**
+   * Group label for the completion command in help output. When specified,
+   * the completion command appears under a titled section with this name
+   * instead of alongside user-defined commands.
+   *
+   * @since 0.10.0
+   */
+  readonly group?: string;
   /**
    * Available shell completions. By default, includes `bash`, `fish`, `nu`,
-   * `pwsh`, and `zsh`. You can provide additional custom shell completions or
-   * override the defaults.
+   * `pwsh`, and `zsh`. You can provide additional custom shell completions
+   * or override the defaults.
    *
    * @default `{ bash, fish, nu, pwsh, zsh }`
    */
   readonly shells?: Record<string, ShellCompletion>;
   /**
-   * Callback function invoked when completion is requested. The function can
-   * optionally receive an exit code parameter.
+   * Callback function invoked when completion is requested. The function
+   * can optionally receive an exit code parameter.
    *
-   * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
-   * on Deno to this option.
+   * You usually want to pass `process.exit` on Node.js or Bun and
+   * `Deno.exit` on Deno to this option.
    *
    * @default Returns `void` when completion is shown.
    */
   readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+} | {
+  /**
+   * Determines how completion is made available:
+   *
+   * - `"option"`: Only the `--completion` option is available
+   */
+  readonly mode: "option";
+  /** @since 0.10.0 */
+  readonly group?: never;
+  /** @default `{ bash, fish, nu, pwsh, zsh }` */
+  readonly shells?: Record<string, ShellCompletion>;
+  /** @default Returns `void` when completion is shown. */
+  readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
 };
 type CompletionConfigBoth<THelp> = CompletionConfigBase<THelp> & {
   /**
@@ -135,18 +156,46 @@ interface RunOptions<THelp, TError> {
      * Determines how help is made available:
      *
      * - `"command"`: Only the `help` subcommand is available
-     * - `"option"`: Only the `--help` option is available
      * - `"both"`: Both `help` subcommand and `--help` option are available
      *
      * @default `"option"`
      */
-    readonly mode?: "command" | "option" | "both";
+    readonly mode: "command" | "both";
+    /**
+     * Group label for the help command in help output. When specified,
+     * the help command appears under a titled section with this name
+     * instead of alongside user-defined commands.
+     *
+     * @since 0.10.0
+     */
+    readonly group?: string;
     /**
      * Callback function invoked when help is requested. The function can
      * optionally receive an exit code parameter.
      *
-     * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
-     * on Deno to this option.
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
+     *
+     * @default Returns `void` when help is shown.
+     */
+    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } | {
+    /**
+     * Determines how help is made available:
+     *
+     * - `"option"`: Only the `--help` option is available
+     *
+     * @default `"option"`
+     */
+    readonly mode?: "option";
+    /** @since 0.10.0 */
+    readonly group?: never;
+    /**
+     * Callback function invoked when help is requested. The function can
+     * optionally receive an exit code parameter.
+     *
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
      *
      * @default Returns `void` when help is shown.
      */
@@ -160,22 +209,55 @@ interface RunOptions<THelp, TError> {
      * Determines how version is made available:
      *
      * - `"command"`: Only the `version` subcommand is available
+     * - `"both"`: Both `version` subcommand and `--version` option are
+     *   available
+     *
+     * @default `"option"`
+     */
+    readonly mode: "command" | "both";
+    /**
+     * The version string to display when version is requested.
+     */
+    readonly value: string;
+    /**
+     * Group label for the version command in help output. When specified,
+     * the version command appears under a titled section with this name
+     * instead of alongside user-defined commands.
+     *
+     * @since 0.10.0
+     */
+    readonly group?: string;
+    /**
+     * Callback function invoked when version is requested. The function can
+     * optionally receive an exit code parameter.
+     *
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
+     *
+     * @default Returns `void` when version is shown.
+     */
+    readonly onShow?: (() => THelp) | ((exitCode: number) => THelp);
+  } | {
+    /**
+     * Determines how version is made available:
+     *
      * - `"option"`: Only the `--version` option is available
-     * - `"both"`: Both `version` subcommand and `--version` option are available
      *
      * @default `"option"`
      */
-    readonly mode?: "command" | "option" | "both";
+    readonly mode?: "option";
     /**
      * The version string to display when version is requested.
      */
     readonly value: string;
+    /** @since 0.10.0 */
+    readonly group?: never;
     /**
      * Callback function invoked when version is requested. The function can
      * optionally receive an exit code parameter.
      *
-     * You usually want to pass `process.exit` on Node.js or Bun and `Deno.exit`
-     * on Deno to this option.
+     * You usually want to pass `process.exit` on Node.js or Bun and
+     * `Deno.exit` on Deno to this option.
      *
      * @default Returns `void` when version is shown.
      */

package/dist/facade.js

@@ -2,7 +2,7 @@ import { annotationKey } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { formatUsage } from "./usage.js";
-import { longestMatch, object } from "./constructs.js";
+import { group, longestMatch, object } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { string } from "./valueparser.js";
@@ -113,10 +113,7 @@ function createCompletionParser(mode, programName, availableShells, name = "both
 		};
 	}
 }
-/**
-* Systematically combines the original parser with help, version, and completion parsers.
-*/
-function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers) {
+function combineWithHelpVersion(originalParser, helpParsers, versionParsers, completionParsers, groups) {
 	const parsers = [];
 	if (helpParsers.helpOption) {
 		const lenientHelpParser = {
@@ -262,35 +259,61 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 		};
 		parsers.push(lenientVersionParser);
 	}
-	if (versionParsers.versionCommand) parsers.push(object({
-		help: constant(false),
-		version: constant(true),
-		completion: constant(false),
-		result: versionParsers.versionCommand,
-		helpFlag: helpParsers.helpOption ? optional(helpParsers.helpOption) : constant(false)
-	}));
-	if (completionParsers.completionCommand) parsers.push(object({
-		help: constant(false),
-		version: constant(false),
-		completion: constant(true),
-		completionData: completionParsers.completionCommand,
-		helpFlag: helpParsers.helpOption ? optional(helpParsers.helpOption) : constant(false)
-	}));
-	if (helpParsers.helpCommand) parsers.push(object({
-		help: constant(true),
-		version: constant(false),
-		completion: constant(false),
-		commands: helpParsers.helpCommand
-	}));
+	if (versionParsers.versionCommand) {
+		const versionParser = object({
+			help: constant(false),
+			version: constant(true),
+			completion: constant(false),
+			result: versionParsers.versionCommand,
+			helpFlag: helpParsers.helpOption ? optional(helpParsers.helpOption) : constant(false)
+		});
+		parsers.push(groups?.versionGroup ? group(groups.versionGroup, versionParser) : versionParser);
+	}
+	if (completionParsers.completionCommand) {
+		const completionParser = object({
+			help: constant(false),
+			version: constant(false),
+			completion: constant(true),
+			completionData: completionParsers.completionCommand,
+			helpFlag: helpParsers.helpOption ? optional(helpParsers.helpOption) : constant(false)
+		});
+		parsers.push(groups?.completionGroup ? group(groups.completionGroup, completionParser) : completionParser);
+	}
+	if (helpParsers.helpCommand) {
+		const helpParser = object({
+			help: constant(true),
+			version: constant(false),
+			completion: constant(false),
+			commands: helpParsers.helpCommand
+		});
+		parsers.push(groups?.helpGroup ? group(groups.helpGroup, helpParser) : helpParser);
+	}
 	parsers.push(object({
 		help: constant(false),
 		version: constant(false),
 		completion: constant(false),
 		result: originalParser
 	}));
+	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return longestMatch(parsers[0], parsers[1]);
-	else return longestMatch(...parsers);
+	let combined;
+	if (parsers.length === 2) combined = longestMatch(parsers[0], parsers[1]);
+	else combined = longestMatch(...parsers);
+	const topUsage = combined.usage[0];
+	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
+		const terms = [...topUsage.terms];
+		const [mainTerm] = terms.splice(mainParserIndex, 1);
+		const lenientCount = (helpParsers.helpOption ? 1 : 0) + (versionParsers.versionOption ? 1 : 0);
+		terms.splice(lenientCount, 0, mainTerm);
+		combined = {
+			...combined,
+			usage: [{
+				...topUsage,
+				terms
+			}]
+		};
+	}
+	return combined;
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -439,13 +462,16 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
+	const helpGroup = options.help?.group;
 	const versionMode = options.version?.mode ?? "option";
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
+	const versionGroup = options.version?.group;
 	const completionMode = options.completion?.mode ?? "both";
 	const completionName = options.completion?.name ?? "both";
 	const completionHelpVisibility = options.completion?.helpVisibility ?? completionName;
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
+	const completionGroup = options.completion?.group;
 	const defaultShells = {
 		bash,
 		fish,
@@ -494,7 +520,11 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			}
 		}
 	}
-	const augmentedParser = help === "none" && version === "none" && completion === "none" ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers);
+	const augmentedParser = help === "none" && version === "none" && completion === "none" ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
+		helpGroup,
+		versionGroup,
+		completionGroup
+	});
 	const handleResult = (result) => {
 		const classified = classifyResult(result, args);
 		switch (classified.type) {
@@ -518,15 +548,18 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 				else {
 					const commandParsers = [parser];
-					if (helpAsCommand) {
-						if (helpParsers.helpCommand) commandParsers.push(helpParsers.helpCommand);
-					}
-					if (versionAsCommand) {
-						if (versionParsers.versionCommand) commandParsers.push(versionParsers.versionCommand);
-					}
-					if (completionAsCommand) {
-						if (completionParsers.completionCommand) commandParsers.push(completionParsers.completionCommand);
-					}
+					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, helpGroup);
+					if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionGroup);
+					if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionGroup);
+					commandParsers.push(...ungroupedMeta);
+					for (const [label, parsers] of Object.entries(groupedMeta)) if (parsers.length === 1) commandParsers.push(group(label, parsers[0]));
+					else commandParsers.push(group(label, longestMatch(...parsers)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
 					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
 					else helpGeneratorParser = longestMatch(...commandParsers);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.370+bae705cb",
+  "version": "0.10.0-dev.375+fffd225e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",