@optique/core 1.0.0-dev.489 → 1.0.0-dev.490

package/dist/parser.cjs

@@ -416,14 +416,26 @@ function buildDocPage(parser, context, args) {
 	}
 	const sections = buildingSections;
 	const usage = [...require_usage.normalizeUsage(parser.usage)];
+	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
+		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
+		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
+		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
+	};
 	let i = 0;
-	for (const arg of args) {
+	for (let argIndex = 0; argIndex < args.length; argIndex++) {
+		const arg = args[argIndex];
 		if (i >= usage.length) break;
-		const term = usage[i];
+		let term = usage[i];
 		if (term.type === "exclusive") {
 			const found = findCommandInExclusive(term, arg);
-			if (found) usage.splice(i, 1, ...found);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				term = usage[i];
+			}
 		}
+		maybeApplyCommandUsageLine(term, arg, argIndex === args.length - 1, i);
 		i++;
 	}
 	return {

package/dist/parser.js

@@ -416,14 +416,26 @@ function buildDocPage(parser, context, args) {
 	}
 	const sections = buildingSections;
 	const usage = [...normalizeUsage(parser.usage)];
+	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
+		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
+		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
+		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
+		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
+	};
 	let i = 0;
-	for (const arg of args) {
+	for (let argIndex = 0; argIndex < args.length; argIndex++) {
+		const arg = args[argIndex];
 		if (i >= usage.length) break;
-		const term = usage[i];
+		let term = usage[i];
 		if (term.type === "exclusive") {
 			const found = findCommandInExclusive(term, arg);
-			if (found) usage.splice(i, 1, ...found);
+			if (found) {
+				usage.splice(i, 1, ...found);
+				term = usage[i];
+			}
 		}
+		maybeApplyCommandUsageLine(term, arg, argIndex === args.length - 1, i);
 		i++;
 	}
 	return {

package/dist/primitives.cjs

@@ -927,6 +927,7 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
+			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
 		initialState: void 0,

package/dist/primitives.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 { ValueParser, ValueParserResult } from "./valueparser.cjs";
 import { DeferredParseState, PendingDependencySourceState } from "./dependency.cjs";
 import { Mode, Parser } from "./parser.cjs";
@@ -326,6 +326,19 @@ interface CommandOptions {
    * @since 0.6.0
    */
   readonly footer?: Message;
+  /**
+   * Usage line override for this command's own help page.
+   *
+   * This option customizes the usage tail shown when rendering help for this
+   * command itself (e.g., `myapp config --help`). It does not change parsing
+   * behavior or shell completion.
+   *
+   * - `Usage`: Replaces the default usage tail.
+   * - `(defaultUsageLine) => Usage`: Computes the usage tail from the default.
+   *
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * Controls command visibility:
    *

package/dist/primitives.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 { ValueParser, ValueParserResult } from "./valueparser.js";
 import { DeferredParseState, PendingDependencySourceState } from "./dependency.js";
 import { Mode, Parser } from "./parser.js";
@@ -326,6 +326,19 @@ interface CommandOptions {
    * @since 0.6.0
    */
   readonly footer?: Message;
+  /**
+   * Usage line override for this command's own help page.
+   *
+   * This option customizes the usage tail shown when rendering help for this
+   * command itself (e.g., `myapp config --help`). It does not change parsing
+   * behavior or shell completion.
+   *
+   * - `Usage`: Replaces the default usage tail.
+   * - `(defaultUsageLine) => Usage`: Computes the usage tail from the default.
+   *
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * Controls command visibility:
    *

package/dist/primitives.js

@@ -927,6 +927,7 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
+			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
 		initialState: void 0,

package/dist/usage.cjs

@@ -419,6 +419,12 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
 			width: 5
 		};
+	} else if (term.type === "ellipsis") {
+		const text = "...";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 3
+		};
 	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 

package/dist/usage.d.cts

@@ -98,6 +98,12 @@ type UsageTerm =
    * in the command-line usage.
    */
   readonly name: string;
+  /**
+   * Optional usage line override for this command's own help page.
+   * This affects help/documentation rendering only.
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * Visibility controls for this term.
    * @since 0.9.0
@@ -181,6 +187,17 @@ type UsageTerm =
    * @since 0.9.0
    */
   readonly hidden?: HiddenVisibility;
+}
+/**
+ * An ellipsis term, which represents a summary placeholder in usage output.
+ * Unlike {@link passthrough}, this term has no parsing semantics and is used
+ * only for display.
+ * @since 1.0.0
+ */ | {
+  /**
+   * The type of the term, which is always `"ellipsis"` for this term.
+   */
+  readonly type: "ellipsis";
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.d.ts

@@ -98,6 +98,12 @@ type UsageTerm =
    * in the command-line usage.
    */
   readonly name: string;
+  /**
+   * Optional usage line override for this command's own help page.
+   * This affects help/documentation rendering only.
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
   /**
    * Visibility controls for this term.
    * @since 0.9.0
@@ -181,6 +187,17 @@ type UsageTerm =
    * @since 0.9.0
    */
   readonly hidden?: HiddenVisibility;
+}
+/**
+ * An ellipsis term, which represents a summary placeholder in usage output.
+ * Unlike {@link passthrough}, this term has no parsing semantics and is used
+ * only for display.
+ * @since 1.0.0
+ */ | {
+  /**
+   * The type of the term, which is always `"ellipsis"` for this term.
+   */
+  readonly type: "ellipsis";
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.js

@@ -418,6 +418,12 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
 			width: 5
 		};
+	} else if (term.type === "ellipsis") {
+		const text = "...";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 3
+		};
 	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.489+709d13c5",
+  "version": "1.0.0-dev.490+fe0b9010",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",