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

package/dist/facade.d.cts

@@ -32,6 +32,7 @@ interface CommandSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }
@@ -55,6 +56,7 @@ interface OptionSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }

package/dist/facade.d.ts

@@ -32,6 +32,7 @@ interface CommandSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }
@@ -55,6 +56,7 @@ interface OptionSubConfig {
    * - `true`: Hidden from usage, documentation, and suggestions.
    * - `"usage"`: Hidden from usage lines only.
    * - `"doc"`: Hidden from documentation only.
+   * - `"help"`: Hidden from usage and documentation only.
    */
   readonly hidden?: HiddenVisibility;
 }

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";
@@ -52,6 +52,7 @@ interface OptionOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -166,6 +167,7 @@ interface FlagOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -255,6 +257,7 @@ interface ArgumentOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -323,12 +326,26 @@ 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:
    *
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -416,6 +433,7 @@ interface PassThroughOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */

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";
@@ -52,6 +52,7 @@ interface OptionOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -166,6 +167,7 @@ interface FlagOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -255,6 +257,7 @@ interface ArgumentOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -323,12 +326,26 @@ 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:
    *
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */
@@ -416,6 +433,7 @@ interface PassThroughOptions {
    * - `true`: hide from usage, docs, and suggestions
    * - `"usage"`: hide from usage only
    * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
    *
    * @since 0.9.0
    */

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

@@ -4,13 +4,13 @@
 * Returns whether the term should be hidden from usage output.
 */
 function isUsageHidden(hidden) {
-	return hidden === true || hidden === "usage";
+	return hidden === true || hidden === "usage" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from documentation output.
 */
 function isDocHidden(hidden) {
-	return hidden === true || hidden === "doc";
+	return hidden === true || hidden === "doc" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from suggestion/error candidates.
@@ -25,7 +25,11 @@ function mergeHidden(a, b) {
 	if (a == null) return b;
 	if (b == null) return a;
 	if (a === true || b === true) return true;
-	if (a !== b) return true;
+	if (a === false) return b;
+	if (b === false) return a;
+	if (a === b) return a;
+	if (a === "help" || b === "help") return "help";
+	if ((a === "usage" || a === "doc") && (b === "usage" || b === "doc")) return "help";
 	return a;
 }
 /**
@@ -415,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

@@ -18,8 +18,9 @@ type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
  * - `true`: hidden from usage, documentation, and suggestions
  * - `"usage"`: hidden from usage only
  * - `"doc"`: hidden from documentation only
+ * - `"help"`: hidden from usage and documentation, but shown in suggestions
  */
-type HiddenVisibility = boolean | "usage" | "doc";
+type HiddenVisibility = boolean | "usage" | "doc" | "help";
 /**
  * Returns whether the term should be hidden from usage output.
  */
@@ -97,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
@@ -180,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

@@ -18,8 +18,9 @@ type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
  * - `true`: hidden from usage, documentation, and suggestions
  * - `"usage"`: hidden from usage only
  * - `"doc"`: hidden from documentation only
+ * - `"help"`: hidden from usage and documentation, but shown in suggestions
  */
-type HiddenVisibility = boolean | "usage" | "doc";
+type HiddenVisibility = boolean | "usage" | "doc" | "help";
 /**
  * Returns whether the term should be hidden from usage output.
  */
@@ -97,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
@@ -180,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

@@ -3,13 +3,13 @@
 * Returns whether the term should be hidden from usage output.
 */
 function isUsageHidden(hidden) {
-	return hidden === true || hidden === "usage";
+	return hidden === true || hidden === "usage" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from documentation output.
 */
 function isDocHidden(hidden) {
-	return hidden === true || hidden === "doc";
+	return hidden === true || hidden === "doc" || hidden === "help";
 }
 /**
 * Returns whether the term should be hidden from suggestion/error candidates.
@@ -24,7 +24,11 @@ function mergeHidden(a, b) {
 	if (a == null) return b;
 	if (b == null) return a;
 	if (a === true || b === true) return true;
-	if (a !== b) return true;
+	if (a === false) return b;
+	if (b === false) return a;
+	if (a === b) return a;
+	if (a === "help" || b === "help") return "help";
+	if ((a === "usage" || a === "doc") && (b === "usage" || b === "doc")) return "help";
 	return a;
 }
 /**
@@ -414,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.488+690cf201",
+  "version": "1.0.0-dev.490+fe0b9010",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",