@optique/core 1.3.0-dev.2375 → 1.3.0-dev.2379

package/dist/doc.cjs

@@ -213,7 +213,6 @@ function defaultSectionOrder(a, b) {
 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) => ({
@@ -232,9 +231,32 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const automaticTermWidth = () => {
+		let widest;
+		for (const section of page.sections) for (const entry of section.entries) {
+			if (!needsDescriptionColumn(entry)) continue;
+			const rendered = require_usage.formatUsageTerm(entry.term, {
+				colors: options.colors,
+				optionsSeparator: ", ",
+				context: "doc"
+			});
+			const width = Math.max(...rendered.split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
+			widest = widest == null ? width : Math.max(widest, width);
+		}
+		return widest;
+	};
+	const termWidth = options.termWidth === "auto" ? automaticTermWidth() ?? 26 : options.termWidth ?? 26;
+	const hasEntries = page.sections.some((s) => s.entries.length > 0);
+	const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some(needsDescriptionColumn));
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		const evenlySplitTermWidth = Math.max(1, Math.floor(availableForColumns / 2));
+		effectiveTermWidth = options.termWidth === "auto" && needsDescColumn ? Math.min(termWidth, evenlySplitTermWidth) : availableForColumns >= termWidth + 1 ? termWidth : evenlySplitTermWidth;
+	}
 	if (options.maxWidth != null) {
-		const hasEntries = page.sections.some((s) => s.entries.length > 0);
-		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
@@ -260,20 +282,13 @@ function formatDocPage(programName, page, options = {}) {
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
-			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
-			const descW = avail - effTW;
+			const descW = avail - effectiveTermWidth;
 			if (descW < minDescWidth) {
-				const needed = termIndent + termWidth + 2 + minDescWidth;
+				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
 				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
 			}
 		}
 	}
-	let effectiveTermWidth;
-	if (options.maxWidth == null) effectiveTermWidth = termWidth;
-	else {
-		const availableForColumns = options.maxWidth - termIndent - 2;
-		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
-	}
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += require_message.formatMessage(page.brief, {

package/dist/doc.d.cts

@@ -217,10 +217,14 @@ interface DocPageFormatOptions {
    */
   termIndent?: number;
   /**
-   * Width allocated for terms before descriptions start.
+   * Width allocated for terms before descriptions start.  Set to `"auto"`
+   * to align descriptions after the widest visible term that has content.
+   * Terminal display width is used for automatic measurement.
+   *
    * @default `26`
+   * @since 1.3.0 Added automatic term width.
    */
-  termWidth?: number;
+  termWidth?: number | "auto";
   /**
    * Maximum width of the entire formatted output.
    */

package/dist/doc.d.ts

@@ -217,10 +217,14 @@ interface DocPageFormatOptions {
    */
   termIndent?: number;
   /**
-   * Width allocated for terms before descriptions start.
+   * Width allocated for terms before descriptions start.  Set to `"auto"`
+   * to align descriptions after the widest visible term that has content.
+   * Terminal display width is used for automatic measurement.
+   *
    * @default `26`
+   * @since 1.3.0 Added automatic term width.
    */
-  termWidth?: number;
+  termWidth?: number | "auto";
   /**
    * Maximum width of the entire formatted output.
    */

package/dist/doc.js

@@ -213,7 +213,6 @@ function defaultSectionOrder(a, b) {
 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) => ({
@@ -232,9 +231,32 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const automaticTermWidth = () => {
+		let widest;
+		for (const section of page.sections) for (const entry of section.entries) {
+			if (!needsDescriptionColumn(entry)) continue;
+			const rendered = formatUsageTerm(entry.term, {
+				colors: options.colors,
+				optionsSeparator: ", ",
+				context: "doc"
+			});
+			const width = Math.max(...rendered.split("\n").map((line) => getDisplayWidth(line)));
+			widest = widest == null ? width : Math.max(widest, width);
+		}
+		return widest;
+	};
+	const termWidth = options.termWidth === "auto" ? automaticTermWidth() ?? 26 : options.termWidth ?? 26;
+	const hasEntries = page.sections.some((s) => s.entries.length > 0);
+	const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some(needsDescriptionColumn));
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		const evenlySplitTermWidth = Math.max(1, Math.floor(availableForColumns / 2));
+		effectiveTermWidth = options.termWidth === "auto" && needsDescColumn ? Math.min(termWidth, evenlySplitTermWidth) : availableForColumns >= termWidth + 1 ? termWidth : evenlySplitTermWidth;
+	}
 	if (options.maxWidth != null) {
-		const hasEntries = page.sections.some((s) => s.entries.length > 0);
-		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
@@ -260,20 +282,13 @@ function formatDocPage(programName, page, options = {}) {
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
-			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
-			const descW = avail - effTW;
+			const descW = avail - effectiveTermWidth;
 			if (descW < minDescWidth) {
-				const needed = termIndent + termWidth + 2 + minDescWidth;
+				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
 				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
 			}
 		}
 	}
-	let effectiveTermWidth;
-	if (options.maxWidth == null) effectiveTermWidth = termWidth;
-	else {
-		const availableForColumns = options.maxWidth - termIndent - 2;
-		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
-	}
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += formatMessage(page.brief, {

package/dist/facade.cjs

@@ -611,7 +611,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, showUsage, rootOptionSuggestions = []) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -624,6 +624,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
+				termWidth,
 				sectionOrder,
 				showUsage
 			}));
@@ -952,7 +953,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, termWidth, 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;
@@ -1090,7 +1091,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, showUsage, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1140,6 +1141,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stdout(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,
@@ -1212,6 +1214,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stderr(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,

package/dist/facade.d.cts

@@ -89,6 +89,14 @@ interface RunOptions<THelp, TError> {
    * this width.  If not specified, text will not be wrapped.
    */
   readonly maxWidth?: number;
+  /**
+   * Width allocated for help terms before descriptions start.  Set to
+   * `"auto"` to align descriptions after the widest visible term.
+   *
+   * @default `26`
+   * @since 1.3.0
+   */
+  readonly termWidth?: number | "auto";
   /**
    * Whether and how to display default values for options and arguments.
    *

package/dist/facade.d.ts

@@ -89,6 +89,14 @@ interface RunOptions<THelp, TError> {
    * this width.  If not specified, text will not be wrapped.
    */
   readonly maxWidth?: number;
+  /**
+   * Width allocated for help terms before descriptions start.  Set to
+   * `"auto"` to align descriptions after the widest visible term.
+   *
+   * @default `26`
+   * @since 1.3.0
+   */
+  readonly termWidth?: number | "auto";
   /**
    * Whether and how to display default values for options and arguments.
    *

package/dist/facade.js

@@ -611,7 +611,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, showUsage, rootOptionSuggestions = []) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -624,6 +624,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
+				termWidth,
 				sectionOrder,
 				showUsage
 			}));
@@ -952,7 +953,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, termWidth, 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;
@@ -1090,7 +1091,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, showUsage, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1140,6 +1141,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stdout(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,
@@ -1212,6 +1214,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stderr(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2375",
+  "version": "1.3.0-dev.2379",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2375+820d01c0",
+    "@optique/env": "1.3.0-dev.2379+3e20cbf3",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -64,6 +64,9 @@ Core rules
     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.
+ -  Use `termWidth: "auto"` in runner options when descriptions should align
+    after the widest visible help term. Optique measures terminal display
+    width after adding built-in help/version/completion entries.
 
 
 Canonical app shape
@@ -97,6 +100,7 @@ const config = run(parser, {
   brief: message`Process a file.`,
   completion: "both",
   showDefault: true,
+  termWidth: "auto",
 });
 
 console.log(`Processing ${config.input} on port ${config.port}.`);