@optique/run 1.4.0-dev.2614 → 1.4.0-dev.2618

package/dist/run.cjs

@@ -83,6 +83,7 @@ function buildCoreOptions(options, programMetadata) {
 	const usageLine = options.usageLine;
 	const commandList = options.commandList;
 	const sectionOrder = options.sectionOrder;
+	const helpSections = options.helpSections;
 	const help = options.help;
 	const version = options.version;
 	const completion = options.completion;
@@ -165,6 +166,7 @@ function buildCoreOptions(options, programMetadata) {
 		usageLine,
 		commandList,
 		sectionOrder,
+		helpSections,
 		help: helpConfig,
 		version: versionConfig,
 		completion: completionConfig,

package/dist/run.d.cts

@@ -2,7 +2,7 @@ import { Message, MessageFormatter } from "@optique/core/message";
 import { TerminalTheme } from "@optique/core/terminal";
 import { ShellCompletion } from "@optique/core/completion";
 import { SourceContext } from "@optique/core/context";
-import { CommandListMode, CommandSubConfig, ContextOptionsParam, OptionSubConfig, RunOptions as RunOptions$1 } from "@optique/core/facade";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, HelpSectionsOptions, OptionSubConfig, RunOptions as RunOptions$1 } from "@optique/core/facade";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -156,6 +156,16 @@ interface RunOptions {
    * @since 1.0.0
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * Groups untitled command and option entries on help pages with visible
+   * commands. Pages without commands receive no automatic headings. Explicit
+   * titles are preserved; matching automatic entries join the existing section.
+   * Supplied labels must be nonempty and contain no control characters.
+   * Also applies to full help displayed above errors.
+   *
+   * @since 1.4.0
+   */
+  readonly helpSections?: HelpSectionsOptions;
   /**
    * Help configuration. Determines how help is made available:
    *
@@ -354,6 +364,7 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  *                See {@link RunOptions} for available settings.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns The parsed result if successful. On help display or parse errors,
  *          the function will call `process.exit()` and not return.
  *
@@ -435,6 +446,7 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
  * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
@@ -462,6 +474,7 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import { CommandListMode, CommandSubConfig, ContextOptionsParam, OptionSubConfig, RunOptions as RunOptions$1 } from "@optique/core/facade";
+import { CommandListMode, CommandSubConfig, ContextOptionsParam, HelpSectionsOptions, OptionSubConfig, RunOptions as RunOptions$1 } from "@optique/core/facade";
 import { Message, MessageFormatter } from "@optique/core/message";
 import { TerminalTheme } from "@optique/core/terminal";
 import { ShellCompletion } from "@optique/core/completion";
@@ -156,6 +156,16 @@ interface RunOptions {
    * @since 1.0.0
    */
   readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
+  /**
+   * Groups untitled command and option entries on help pages with visible
+   * commands. Pages without commands receive no automatic headings. Explicit
+   * titles are preserved; matching automatic entries join the existing section.
+   * Supplied labels must be nonempty and contain no control characters.
+   * Also applies to full help displayed above errors.
+   *
+   * @since 1.4.0
+   */
+  readonly helpSections?: HelpSectionsOptions;
   /**
    * Help configuration. Determines how help is made available:
    *
@@ -354,6 +364,7 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  *                See {@link RunOptions} for available settings.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns The parsed result if successful. On help display or parse errors,
  *          the function will call `process.exit()` and not return.
  *
@@ -435,6 +446,7 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
  * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
@@ -462,6 +474,7 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * @param options Configuration options for customizing behavior.
  * @throws {RangeError} If rendering help or errors encounters an invalid theme
  * color, even when colors are disabled.
+ * @throws {TypeError} If a `helpSections` label is invalid.
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */

package/dist/run.js

@@ -82,6 +82,7 @@ function buildCoreOptions(options, programMetadata) {
 	const usageLine = options.usageLine;
 	const commandList = options.commandList;
 	const sectionOrder = options.sectionOrder;
+	const helpSections = options.helpSections;
 	const help = options.help;
 	const version = options.version;
 	const completion = options.completion;
@@ -164,6 +165,7 @@ function buildCoreOptions(options, programMetadata) {
 		usageLine,
 		commandList,
 		sectionOrder,
+		helpSections,
 		help: helpConfig,
 		version: versionConfig,
 		completion: completionConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.4.0-dev.2614",
+  "version": "1.4.0-dev.2618",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -76,11 +76,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2614+5915742e"
+    "@optique/core": "1.4.0-dev.2618+2cb27efe"
   },
   "devDependencies": {
-    "@optique/config": "1.4.0-dev.2614+5915742e",
-    "@optique/env": "1.4.0-dev.2614+5915742e",
+    "@optique/config": "1.4.0-dev.2618+2cb27efe",
+    "@optique/env": "1.4.0-dev.2618+2cb27efe",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",