@optique/core 1.3.0-dev.2352 → 1.3.0-dev.2353

package/dist/facade.cjs

@@ -952,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, 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;
@@ -1045,6 +1045,41 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
 	});
+	const helpAsCommand = helpCommandConfig != null;
+	const versionAsCommand = versionCommandConfig != null;
+	const completionAsCommand = completionCommandConfig != null;
+	const helpAsOption = helpOptionConfig != null;
+	const versionAsOption = versionOptionConfig != null;
+	const completionAsOption = completionOptionConfig != null;
+	let cachedRootHelpGeneratorParser;
+	const getRootHelpGeneratorParser = () => {
+		if (cachedRootHelpGeneratorParser != null) return cachedRootHelpGeneratorParser;
+		const commandParsers = [parser];
+		const groupedMeta = {};
+		const ungroupedMeta = [];
+		const addMeta = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMeta[groupLabel] ??= []).push(metaParser);
+			else ungroupedMeta.push(metaParser);
+		};
+		if (helpAsCommand && helpParsers.helpCommand) addMeta(helpParsers.helpCommand, helpCommandConfig?.group);
+		if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionCommandConfig?.group);
+		if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionCommandConfig?.group);
+		commandParsers.push(...ungroupedMeta);
+		for (const [label, parsers] of Object.entries(groupedMeta)) commandParsers.push(require_constructs.group(label, parsers.length === 1 ? parsers[0] : require_constructs.longestMatch(...parsers)));
+		const groupedMetaOptions = {};
+		const ungroupedMetaOptions = [];
+		const addMetaOption = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(metaParser);
+			else ungroupedMetaOptions.push(metaParser);
+		};
+		if (helpAsOption && helpParsers.helpOption) addMetaOption(helpParsers.helpOption, helpOptionConfig?.group);
+		if (versionAsOption && versionParsers.versionOption) addMetaOption(versionParsers.versionOption, versionOptionConfig?.group);
+		if (completionAsOption && completionParsers.completionOption) addMetaOption(completionParsers.completionOption, completionOptionConfig?.group);
+		commandParsers.push(...ungroupedMetaOptions);
+		for (const [label, parsers] of Object.entries(groupedMetaOptions)) commandParsers.push(require_constructs.group(label, parsers.length === 1 ? parsers[0] : require_constructs.longestMatch(...parsers)));
+		cachedRootHelpGeneratorParser = commandParsers.length === 1 ? commandParsers[0] : longestMatchForMetaCommands(...commandParsers);
+		return cachedRootHelpGeneratorParser;
+	};
 	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
@@ -1059,12 +1094,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
-				const helpAsCommand = helpCommandConfig != null;
-				const versionAsCommand = versionCommandConfig != null;
-				const completionAsCommand = completionCommandConfig != null;
-				const helpAsOption = helpOptionConfig != null;
-				const versionAsOption = versionOptionConfig != null;
-				const completionAsOption = completionOptionConfig != null;
 				const requestedCommand = classified.commands[0];
 				if (requestedCommand != null && !classified.preferUserCommandDocs && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) {
 					helpGeneratorParser = completionParsers.completionCommand;
@@ -1076,33 +1105,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					helpGeneratorParser = versionParsers.versionCommand;
 					docGeneratorParser = helpGeneratorParser;
 				} else {
-					const commandParsers = [parser];
-					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, helpCommandConfig?.group);
-					if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionCommandConfig?.group);
-					if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionCommandConfig?.group);
-					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)));
-					const groupedMetaOptions = {};
-					const ungroupedMetaOptions = [];
-					const addMetaOption = (p, groupLabel) => {
-						if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(p);
-						else ungroupedMetaOptions.push(p);
-					};
-					if (helpAsOption && helpParsers.helpOption) addMetaOption(helpParsers.helpOption, helpOptionConfig?.group);
-					if (versionAsOption && versionParsers.versionOption) addMetaOption(versionParsers.versionOption, versionOptionConfig?.group);
-					if (completionAsOption && completionParsers.completionOption) addMetaOption(completionParsers.completionOption, completionOptionConfig?.group);
-					commandParsers.push(...ungroupedMetaOptions);
-					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(require_constructs.group(label, optParsers[0]));
-					else commandParsers.push(require_constructs.group(label, require_constructs.longestMatch(...optParsers)));
-					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
+					helpGeneratorParser = getRootHelpGeneratorParser();
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
@@ -1133,7 +1136,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						stdout(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1193,6 +1197,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
+						const isTopLevel = classified.commandPath.length < 1;
 						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
@@ -1201,8 +1206,10 @@ 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, {
+						}, commandList, isTopLevel);
+						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? require_usage.normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						stderr(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1298,6 +1305,13 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
+	const customUsageLine = typeof usageLine === "function" ? usageLine(require_usage.cloneUsage(defaultUsageLine)) : usageLine;
+	return {
+		...doc,
+		usage: require_usage.normalizeUsage(customUsageLine)
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {

package/dist/facade.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { HiddenVisibility, OptionName } from "./usage.cjs";
+import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
@@ -127,6 +127,20 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * Usage line override for top-level full help.
+   *
+   * This option customizes the usage shown by `--help`, the root help command,
+   * and `aboveError: "help"` at the root.  It does not affect subcommand help,
+   * parsing, shell completion, or usage-only error preambles from
+   * `aboveError: "usage"`.
+   *
+   * The callback form receives the generated root usage after built-in help,
+   * version, and completion entries have been added.
+   *
+   * @since 1.3.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * How to render command lists in top-level help pages.
    *

package/dist/facade.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { HiddenVisibility, OptionName } from "./usage.js";
+import { HiddenVisibility, OptionName, Usage } from "./usage.js";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./internal/parser.js";
 import { ShellCompletion } from "./completion.js";
@@ -127,6 +127,20 @@ interface RunOptions<THelp, TError> {
    * @since 1.2.0
    */
   readonly showUsage?: boolean;
+  /**
+   * Usage line override for top-level full help.
+   *
+   * This option customizes the usage shown by `--help`, the root help command,
+   * and `aboveError: "help"` at the root.  It does not affect subcommand help,
+   * parsing, shell completion, or usage-only error preambles from
+   * `aboveError: "usage"`.
+   *
+   * The callback form receives the generated root usage after built-in help,
+   * version, and completion entries have been added.
+   *
+   * @since 1.3.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * How to render command lists in top-level help pages.
    *

package/dist/facade.js

@@ -1,7 +1,7 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
-import { formatUsage, isSuggestionHidden } from "./usage.js";
+import { cloneUsage, formatUsage, isSuggestionHidden, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
@@ -952,7 +952,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, 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;
@@ -1045,6 +1045,41 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
 	});
+	const helpAsCommand = helpCommandConfig != null;
+	const versionAsCommand = versionCommandConfig != null;
+	const completionAsCommand = completionCommandConfig != null;
+	const helpAsOption = helpOptionConfig != null;
+	const versionAsOption = versionOptionConfig != null;
+	const completionAsOption = completionOptionConfig != null;
+	let cachedRootHelpGeneratorParser;
+	const getRootHelpGeneratorParser = () => {
+		if (cachedRootHelpGeneratorParser != null) return cachedRootHelpGeneratorParser;
+		const commandParsers = [parser];
+		const groupedMeta = {};
+		const ungroupedMeta = [];
+		const addMeta = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMeta[groupLabel] ??= []).push(metaParser);
+			else ungroupedMeta.push(metaParser);
+		};
+		if (helpAsCommand && helpParsers.helpCommand) addMeta(helpParsers.helpCommand, helpCommandConfig?.group);
+		if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionCommandConfig?.group);
+		if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionCommandConfig?.group);
+		commandParsers.push(...ungroupedMeta);
+		for (const [label, parsers] of Object.entries(groupedMeta)) commandParsers.push(group(label, parsers.length === 1 ? parsers[0] : longestMatch(...parsers)));
+		const groupedMetaOptions = {};
+		const ungroupedMetaOptions = [];
+		const addMetaOption = (metaParser, groupLabel) => {
+			if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(metaParser);
+			else ungroupedMetaOptions.push(metaParser);
+		};
+		if (helpAsOption && helpParsers.helpOption) addMetaOption(helpParsers.helpOption, helpOptionConfig?.group);
+		if (versionAsOption && versionParsers.versionOption) addMetaOption(versionParsers.versionOption, versionOptionConfig?.group);
+		if (completionAsOption && completionParsers.completionOption) addMetaOption(completionParsers.completionOption, completionOptionConfig?.group);
+		commandParsers.push(...ungroupedMetaOptions);
+		for (const [label, parsers] of Object.entries(groupedMetaOptions)) commandParsers.push(group(label, parsers.length === 1 ? parsers[0] : longestMatch(...parsers)));
+		cachedRootHelpGeneratorParser = commandParsers.length === 1 ? commandParsers[0] : longestMatchForMetaCommands(...commandParsers);
+		return cachedRootHelpGeneratorParser;
+	};
 	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
@@ -1059,12 +1094,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
-				const helpAsCommand = helpCommandConfig != null;
-				const versionAsCommand = versionCommandConfig != null;
-				const completionAsCommand = completionCommandConfig != null;
-				const helpAsOption = helpOptionConfig != null;
-				const versionAsOption = versionOptionConfig != null;
-				const completionAsOption = completionOptionConfig != null;
 				const requestedCommand = classified.commands[0];
 				if (requestedCommand != null && !classified.preferUserCommandDocs && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) {
 					helpGeneratorParser = completionParsers.completionCommand;
@@ -1076,33 +1105,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					helpGeneratorParser = versionParsers.versionCommand;
 					docGeneratorParser = helpGeneratorParser;
 				} else {
-					const commandParsers = [parser];
-					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, helpCommandConfig?.group);
-					if (versionAsCommand && versionParsers.versionCommand) addMeta(versionParsers.versionCommand, versionCommandConfig?.group);
-					if (completionAsCommand && completionParsers.completionCommand) addMeta(completionParsers.completionCommand, completionCommandConfig?.group);
-					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)));
-					const groupedMetaOptions = {};
-					const ungroupedMetaOptions = [];
-					const addMetaOption = (p, groupLabel) => {
-						if (groupLabel) (groupedMetaOptions[groupLabel] ??= []).push(p);
-						else ungroupedMetaOptions.push(p);
-					};
-					if (helpAsOption && helpParsers.helpOption) addMetaOption(helpParsers.helpOption, helpOptionConfig?.group);
-					if (versionAsOption && versionParsers.versionOption) addMetaOption(versionParsers.versionOption, versionOptionConfig?.group);
-					if (completionAsOption && completionParsers.completionOption) addMetaOption(completionParsers.completionOption, completionOptionConfig?.group);
-					commandParsers.push(...ungroupedMetaOptions);
-					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(group(label, optParsers[0]));
-					else commandParsers.push(group(label, longestMatch(...optParsers)));
-					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
+					helpGeneratorParser = getRootHelpGeneratorParser();
 					docGeneratorParser = classified.commands.length > 0 ? parser : helpGeneratorParser;
 				}
 				const reportInvalidHelpCommand = (validationError) => {
@@ -1133,7 +1136,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							bugs: isTopLevel && !isMetaCommandHelp ? bugs ?? doc.bugs : void 0,
 							footer: shouldOverride ? footer ?? doc.footer : doc.footer ?? footer
 						}, commandList, isTopLevel);
-						stdout(formatDocPage(programName, augmentedDoc, {
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine) : augmentedDoc;
+						stdout(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1193,6 +1197,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					let effectiveAboveError = currentAboveError;
 					if (effectiveAboveError === "help") if (doc == null) effectiveAboveError = "usage";
 					else {
+						const isTopLevel = classified.commandPath.length < 1;
 						const augmentedDoc = maybeCollapseCommandList({
 							...doc,
 							brief: brief ?? doc.brief,
@@ -1201,8 +1206,10 @@ 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, {
+						}, commandList, isTopLevel);
+						const defaultRootUsage = typeof usageLine === "function" && (options.help || options.version || options.completion) ? normalizeUsage(getRootHelpGeneratorParser().usage) : augmentedDoc.usage ?? [];
+						const renderedDoc = isTopLevel && usageLine != null ? applyUsageLine(augmentedDoc, usageLine, defaultRootUsage) : augmentedDoc;
+						stderr(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
 							showDefault,
@@ -1298,6 +1305,13 @@ function runParserAsync(parser, programName, args, options) {
 	const result = runParser(parser, programName, args, options);
 	return Promise.resolve(result);
 }
+function applyUsageLine(doc, usageLine, defaultUsageLine = doc.usage ?? []) {
+	const customUsageLine = typeof usageLine === "function" ? usageLine(cloneUsage(defaultUsageLine)) : usageLine;
+	return {
+		...doc,
+		usage: normalizeUsage(customUsageLine)
+	};
+}
 function maybeCollapseCommandList(doc, commandList, isTopLevel) {
 	if (commandList !== "top-level" || !isTopLevel) return doc;
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2352",
+  "version": "1.3.0-dev.2353",
   "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.3.0-dev.2352+32a63ede"
+    "@optique/env": "1.3.0-dev.2353+1e07f6ab"
   },
   "scripts": {
     "build": "tsdown",

package/skills/optique/SKILL.md

@@ -56,6 +56,9 @@ Core rules
     discriminated union.
  -  Enable completion through `run(parser, { completion: "both" })` for CLI
     apps. Do not hand-write completion scripts from parser metadata.
+ -  Use `usageLine: [{ type: "ellipsis" }]` in runner options when a large root
+    synopsis should become a compact `Usage: myapp ...` line. This applies only
+    to root full help; use `command()`'s `usageLine` for subcommand help.
  -  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