@optique/core 0.9.0-dev.183 → 0.9.0-dev.184

package/dist/primitives.cjs

@@ -67,12 +67,14 @@ function option(...args) {
 			type: "optional",
 			terms: [{
 				type: "option",
-				names: optionNames$1
+				names: optionNames$1,
+				...options.hidden && { hidden: true }
 			}]
 		} : {
 			type: "option",
 			names: optionNames$1,
-			metavar: valueParser.metavar
+			metavar: valueParser.metavar,
+			...options.hidden && { hidden: true }
 		}],
 		initialState: valueParser == null ? {
 			success: true,
@@ -218,6 +220,7 @@ function option(...args) {
 			};
 		},
 		suggest(context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			const equalsIndex = prefix.indexOf("=");
 			if (equalsIndex >= 0) {
@@ -263,6 +266,10 @@ function option(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -328,7 +335,8 @@ function flag(...args) {
 		priority: 10,
 		usage: [{
 			type: "option",
-			names: optionNames$1
+			names: optionNames$1,
+			...options.hidden && { hidden: true }
 		}],
 		initialState: void 0,
 		parse(context) {
@@ -435,6 +443,7 @@ function flag(...args) {
 			};
 		},
 		suggest(_context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
@@ -448,6 +457,10 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -482,7 +495,8 @@ function argument(valueParser, options = {}) {
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
-		metavar: valueParser.metavar
+		metavar: valueParser.metavar,
+		...options.hidden && { hidden: true }
 	};
 	return {
 		$valueType: [],
@@ -542,6 +556,7 @@ function argument(valueParser, options = {}) {
 			};
 		},
 		suggest(_context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			if (valueParser.suggest) {
 				const valueSuggestions = valueParser.suggest(prefix);
@@ -550,6 +565,10 @@ function argument(valueParser, options = {}) {
 			return suggestions;
 		},
 		getDocFragments(_state, defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			const fragments = [{
 				type: "entry",
 				term,
@@ -586,7 +605,8 @@ function command(name, parser, options = {}) {
 		priority: 15,
 		usage: [{
 			type: "command",
-			name
+			name,
+			...options.hidden && { hidden: true }
 		}, ...parser.usage],
 		initialState: void 0,
 		parse(context) {
@@ -673,6 +693,7 @@ function command(name, parser, options = {}) {
 			};
 		},
 		suggest(context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			if (context.state === void 0) {
 				if (name.startsWith(prefix)) suggestions.push({
@@ -696,6 +717,10 @@ function command(name, parser, options = {}) {
 			return suggestions;
 		},
 		getDocFragments(state, defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
 				description: options.description,
 				fragments: [{
@@ -777,7 +802,10 @@ function passThrough(options = {}) {
 		$valueType: [],
 		$stateType: [],
 		priority: -10,
-		usage: [{ type: "passthrough" }],
+		usage: [{
+			type: "passthrough",
+			...options.hidden && { hidden: true }
+		}],
 		initialState: [],
 		parse(context) {
 			if (context.buffer.length < 1) return {
@@ -874,6 +902,10 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			return {
 				fragments: [{
 					type: "entry",

package/dist/primitives.d.cts

@@ -19,6 +19,13 @@ interface OptionOptions {
    * The description of the option, which can be used for help messages.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the option from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions. The option
+   * remains fully functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -118,6 +125,13 @@ interface FlagOptions {
    * The description of the flag, which can be used for help messages.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the flag from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions. The flag
+   * remains fully functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -197,6 +211,13 @@ interface ArgumentOptions {
    * The description of the argument, which can be used for help messages.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the argument from help text, shell completion
+   * suggestions, and error suggestions. The argument remains fully
+   * functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -260,6 +281,13 @@ interface CommandOptions {
    * @since 0.6.0
    */
   readonly footer?: Message;
+  /**
+   * When `true`, hides the command from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions. The command
+   * remains fully functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -336,6 +364,12 @@ interface PassThroughOptions {
    * A description of what pass-through options are used for.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the pass-through from help text and shell
+   * completion suggestions. The parser remains fully functional.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * Creates a parser that collects unrecognized options and passes them through.

package/dist/primitives.d.ts

@@ -19,6 +19,13 @@ interface OptionOptions {
    * The description of the option, which can be used for help messages.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the option from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions. The option
+   * remains fully functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -118,6 +125,13 @@ interface FlagOptions {
    * The description of the flag, which can be used for help messages.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the flag from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions. The flag
+   * remains fully functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -197,6 +211,13 @@ interface ArgumentOptions {
    * The description of the argument, which can be used for help messages.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the argument from help text, shell completion
+   * suggestions, and error suggestions. The argument remains fully
+   * functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error message customization options.
    * @since 0.5.0
@@ -260,6 +281,13 @@ interface CommandOptions {
    * @since 0.6.0
    */
   readonly footer?: Message;
+  /**
+   * When `true`, hides the command from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions. The command
+   * remains fully functional for parsing.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
   /**
    * Error messages customization.
    * @since 0.5.0
@@ -336,6 +364,12 @@ interface PassThroughOptions {
    * A description of what pass-through options are used for.
    */
   readonly description?: Message;
+  /**
+   * When `true`, hides the pass-through from help text and shell
+   * completion suggestions. The parser remains fully functional.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * Creates a parser that collects unrecognized options and passes them through.

package/dist/primitives.js

@@ -67,12 +67,14 @@ function option(...args) {
 			type: "optional",
 			terms: [{
 				type: "option",
-				names: optionNames$1
+				names: optionNames$1,
+				...options.hidden && { hidden: true }
 			}]
 		} : {
 			type: "option",
 			names: optionNames$1,
-			metavar: valueParser.metavar
+			metavar: valueParser.metavar,
+			...options.hidden && { hidden: true }
 		}],
 		initialState: valueParser == null ? {
 			success: true,
@@ -218,6 +220,7 @@ function option(...args) {
 			};
 		},
 		suggest(context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			const equalsIndex = prefix.indexOf("=");
 			if (equalsIndex >= 0) {
@@ -263,6 +266,10 @@ function option(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -328,7 +335,8 @@ function flag(...args) {
 		priority: 10,
 		usage: [{
 			type: "option",
-			names: optionNames$1
+			names: optionNames$1,
+			...options.hidden && { hidden: true }
 		}],
 		initialState: void 0,
 		parse(context) {
@@ -435,6 +443,7 @@ function flag(...args) {
 			};
 		},
 		suggest(_context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
@@ -448,6 +457,10 @@ function flag(...args) {
 			return suggestions;
 		},
 		getDocFragments(_state, _defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -482,7 +495,8 @@ function argument(valueParser, options = {}) {
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
-		metavar: valueParser.metavar
+		metavar: valueParser.metavar,
+		...options.hidden && { hidden: true }
 	};
 	return {
 		$valueType: [],
@@ -542,6 +556,7 @@ function argument(valueParser, options = {}) {
 			};
 		},
 		suggest(_context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			if (valueParser.suggest) {
 				const valueSuggestions = valueParser.suggest(prefix);
@@ -550,6 +565,10 @@ function argument(valueParser, options = {}) {
 			return suggestions;
 		},
 		getDocFragments(_state, defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			const fragments = [{
 				type: "entry",
 				term,
@@ -586,7 +605,8 @@ function command(name, parser, options = {}) {
 		priority: 15,
 		usage: [{
 			type: "command",
-			name
+			name,
+			...options.hidden && { hidden: true }
 		}, ...parser.usage],
 		initialState: void 0,
 		parse(context) {
@@ -673,6 +693,7 @@ function command(name, parser, options = {}) {
 			};
 		},
 		suggest(context, prefix) {
+			if (options.hidden) return [];
 			const suggestions = [];
 			if (context.state === void 0) {
 				if (name.startsWith(prefix)) suggestions.push({
@@ -696,6 +717,10 @@ function command(name, parser, options = {}) {
 			return suggestions;
 		},
 		getDocFragments(state, defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
 				description: options.description,
 				fragments: [{
@@ -777,7 +802,10 @@ function passThrough(options = {}) {
 		$valueType: [],
 		$stateType: [],
 		priority: -10,
-		usage: [{ type: "passthrough" }],
+		usage: [{
+			type: "passthrough",
+			...options.hidden && { hidden: true }
+		}],
 		initialState: [],
 		parse(context) {
 			if (context.buffer.length < 1) return {
@@ -874,6 +902,10 @@ function passThrough(options = {}) {
 			return [];
 		},
 		getDocFragments(_state, _defaultValue) {
+			if (options.hidden) return {
+				fragments: [],
+				description: options.description
+			};
 			return {
 				fragments: [{
 					type: "entry",

package/dist/usage.cjs

@@ -24,8 +24,10 @@ function extractOptionNames(usage) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) if (term.type === "option") for (const name of term.names) names.add(name);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		for (const term of terms) if (term.type === "option") {
+			if (term.hidden) continue;
+			for (const name of term.names) names.add(name);
+		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -55,8 +57,10 @@ function extractCommandNames(usage) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) if (term.type === "command") names.add(term.name);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		for (const term of terms) if (term.type === "command") {
+			if (term.hidden) continue;
+			names.add(term.name);
+		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -87,8 +91,10 @@ function extractArgumentMetavars(usage) {
 	const metavars = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) if (term.type === "argument") metavars.add(term.metavar);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		for (const term of terms) if (term.type === "argument") {
+			if (term.hidden) continue;
+			metavars.add(term.metavar);
+		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);

package/dist/usage.d.cts

@@ -27,6 +27,12 @@ type UsageTerm =
    * the command-line usage.
    */
   readonly metavar: string;
+  /**
+   * When `true`, hides the argument from help text, shell completion
+   * suggestions, and error suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * An option term, which represents a command-line option that can
@@ -46,6 +52,12 @@ type UsageTerm =
    * to indicate what value the option expects.
    */
   readonly metavar?: string;
+  /**
+   * When `true`, hides the option from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * A command term, which represents a subcommand in the command-line
@@ -60,6 +72,12 @@ type UsageTerm =
    * in the command-line usage.
    */
   readonly name: string;
+  /**
+   * When `true`, hides the command from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * An optional term, which represents an optional component
@@ -133,6 +151,12 @@ type UsageTerm =
    * The type of the term, which is always `"passthrough"` for this term.
    */
   readonly type: "passthrough";
+  /**
+   * When `true`, hides the pass-through from help text and shell
+   * completion suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.d.ts

@@ -27,6 +27,12 @@ type UsageTerm =
    * the command-line usage.
    */
   readonly metavar: string;
+  /**
+   * When `true`, hides the argument from help text, shell completion
+   * suggestions, and error suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * An option term, which represents a command-line option that can
@@ -46,6 +52,12 @@ type UsageTerm =
    * to indicate what value the option expects.
    */
   readonly metavar?: string;
+  /**
+   * When `true`, hides the option from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * A command term, which represents a subcommand in the command-line
@@ -60,6 +72,12 @@ type UsageTerm =
    * in the command-line usage.
    */
   readonly name: string;
+  /**
+   * When `true`, hides the command from help text, shell completion
+   * suggestions, and "Did you mean?" error suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 }
 /**
  * An optional term, which represents an optional component
@@ -133,6 +151,12 @@ type UsageTerm =
    * The type of the term, which is always `"passthrough"` for this term.
    */
   readonly type: "passthrough";
+  /**
+   * When `true`, hides the pass-through from help text and shell
+   * completion suggestions.
+   * @since 0.9.0
+   */
+  readonly hidden?: boolean;
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.js

@@ -23,8 +23,10 @@ function extractOptionNames(usage) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) if (term.type === "option") for (const name of term.names) names.add(name);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		for (const term of terms) if (term.type === "option") {
+			if (term.hidden) continue;
+			for (const name of term.names) names.add(name);
+		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -54,8 +56,10 @@ function extractCommandNames(usage) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) if (term.type === "command") names.add(term.name);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		for (const term of terms) if (term.type === "command") {
+			if (term.hidden) continue;
+			names.add(term.name);
+		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);
@@ -86,8 +90,10 @@ function extractArgumentMetavars(usage) {
 	const metavars = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
-		for (const term of terms) if (term.type === "argument") metavars.add(term.metavar);
-		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		for (const term of terms) if (term.type === "argument") {
+			if (term.hidden) continue;
+			metavars.add(term.metavar);
+		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
 	}
 	traverseUsage(usage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.9.0-dev.183+8536868c",
+  "version": "0.9.0-dev.184+a94f89b9",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",