@optique/core 1.2.0-dev.2282 → 1.2.0-dev.2287

package/dist/doc.cjs

@@ -214,6 +214,7 @@ function formatDocPage(programName, page, options = {}) {
 	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
+	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
 		...s,
@@ -250,7 +251,7 @@ function formatDocPage(programName, page, options = {}) {
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
 		const programNameWidth = require_displaywidth.getDisplayWidth(programName);
-		const usageMin = page.usage != null ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
+		const usageMin = page.usage != null && showUsage ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
 		let sectionMin = 1;
 		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, 9);
 		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, 7);
@@ -282,7 +283,7 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	if (page.usage != null) {
+	if (page.usage != null && showUsage) {
 		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
 		output += usageLabel;
 		output += indentLines(require_usage.formatUsage(programName, page.usage, {

package/dist/doc.d.cts

@@ -225,6 +225,13 @@ interface DocPageFormatOptions {
    * Maximum width of the entire formatted output.
    */
   maxWidth?: number;
+  /**
+   * Whether to include the usage synopsis in the output.
+   *
+   * @default `true`
+   * @since 1.2.0
+   */
+  showUsage?: boolean;
   /**
    * Whether and how to display default values for options and arguments.
    *

package/dist/doc.d.ts

@@ -225,6 +225,13 @@ interface DocPageFormatOptions {
    * Maximum width of the entire formatted output.
    */
   maxWidth?: number;
+  /**
+   * Whether to include the usage synopsis in the output.
+   *
+   * @default `true`
+   * @since 1.2.0
+   */
+  showUsage?: boolean;
   /**
    * Whether and how to display default values for options and arguments.
    *

package/dist/doc.js

@@ -214,6 +214,7 @@ function formatDocPage(programName, page, options = {}) {
 	validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
+	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
 		...s,
@@ -250,7 +251,7 @@ function formatDocPage(programName, page, options = {}) {
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
 		const programNameWidth = getDisplayWidth(programName);
-		const usageMin = page.usage != null ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
+		const usageMin = page.usage != null && showUsage ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
 		let sectionMin = 1;
 		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, 9);
 		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, 7);
@@ -282,7 +283,7 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	if (page.usage != null) {
+	if (page.usage != null && showUsage) {
 		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
 		output += usageLabel;
 		output += indentLines(formatUsage(programName, page.usage, {

package/dist/facade.cjs

@@ -608,7 +608,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, rootOptionSuggestions = []) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -621,7 +621,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
-				sectionOrder
+				sectionOrder,
+				showUsage
 			}));
 		}
 		return require_mode_dispatch.dispatchByMode(parser.mode, () => {
@@ -948,7 +949,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, 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;
@@ -1051,7 +1052,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1134,7 +1135,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							maxWidth,
 							showDefault,
 							showChoices,
-							sectionOrder
+							sectionOrder,
+							showUsage
 						}));
 					}
 					return onHelp(0);
@@ -1201,7 +1203,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder,
+							showUsage
 						}));
 					}
 					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {

package/dist/facade.d.cts

@@ -105,6 +105,17 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Whether to include the usage synopsis in full help output.
+   *
+   * This affects help pages produced by `--help`, the help command, and
+   * `aboveError: "help"`.  It does not suppress usage-only error preambles
+   * from `aboveError: "usage"`.
+   *
+   * @default `true`
+   * @since 1.2.0
+   */
+  readonly showUsage?: boolean;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart

package/dist/facade.d.ts

@@ -105,6 +105,17 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * Whether to include the usage synopsis in full help output.
+   *
+   * This affects help pages produced by `--help`, the help command, and
+   * `aboveError: "help"`.  It does not suppress usage-only error preambles
+   * from `aboveError: "usage"`.
+   *
+   * @default `true`
+   * @since 1.2.0
+   */
+  readonly showUsage?: boolean;
   /**
    * A custom comparator function to control the order of sections in the
    * help output.  When provided, it is used instead of the default smart

package/dist/facade.js

@@ -608,7 +608,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, rootOptionSuggestions = []) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -621,7 +621,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
-				sectionOrder
+				sectionOrder,
+				showUsage
 			}));
 		}
 		return dispatchByMode(parser.mode, () => {
@@ -948,7 +949,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, 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;
@@ -1051,7 +1052,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1134,7 +1135,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							maxWidth,
 							showDefault,
 							showChoices,
-							sectionOrder
+							sectionOrder,
+							showUsage
 						}));
 					}
 					return onHelp(0);
@@ -1201,7 +1203,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder,
+							showUsage
 						}));
 					}
 					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2282",
+  "version": "1.2.0-dev.2287",
   "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.2282+c9c50098"
+    "@optique/env": "1.2.0-dev.2287+86d0fd20"
   },
   "scripts": {
     "build": "tsdown",

package/skills/optique/SKILL.md

@@ -22,7 +22,7 @@ they cover the parts agents most often get wrong.
 Core rules
 ----------
 
- -  Use `run()` from `@optique/run` for real CLI applications. It reads
+ -  Use `run()` from *@optique/run* for real CLI applications. It reads
     `process.argv`/`Deno.args`, handles help, version output, errors, exit
     codes, colors, terminal width, and shell completion. Use `parse()` from
     `@optique/core/parser` or `runParser()` from `@optique/core/facade` when
@@ -37,7 +37,7 @@ Core rules
     `undefined`; `withDefault(p, value)` yields a fallback value. For Boolean
     flags, use `withDefault(flag("--name"), false)` when absence should mean
     `false`.
- -  Use `message` from `@optique/core/message` for descriptions, help text, and
+ -  Use `message` from *@optique/core/message* for descriptions, help text, and
     custom errors. Prefer semantic message helpers such as `optionName()` and
     `metavar()` over string concatenation when naming CLI elements.
  -  Use value parsers such as `integer()`, `choice()`, `url()`, and `uuid()`
@@ -46,13 +46,15 @@ Core rules
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.
  -  Async value parsers make the containing parser async. If you use packages
-    such as `@optique/git`, remember to `await run(...)`, `await parse(...)`, or
+    such as *@optique/git*, remember to `await run(...)`, `await parse(...)`, or
     `await runParser(...)` as appropriate.
  -  Build subcommands with `command()` combined by `or()`. Put a literal field
     such as `command: constant("serve")` in each branch when you want a
     discriminated union.
  -  Enable completion through `run(parser, { completion: "both" })` for CLI
     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.
 
 
 Canonical app shape