@optique/core 0.8.0-dev.164 → 0.8.0-dev.165

package/dist/index.cjs

@@ -50,6 +50,7 @@ exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = require_parser.parse;
+exports.passThrough = require_primitives.passThrough;
 exports.pwsh = require_completion.pwsh;
 exports.run = require_facade.run;
 exports.string = require_valueparser.string;

package/dist/index.d.cts

@@ -3,9 +3,9 @@ import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOption
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.cjs";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,9 +3,9 @@ import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOption
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.js";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.js";
 import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -5,8 +5,8 @@ import { formatDocPage } from "./doc.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { argument, command, constant, flag, option } from "./primitives.js";
+import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { getDocPage, parse, suggest } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/parser.cjs

@@ -190,6 +190,7 @@ exports.option = require_primitives.option;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = parse;
+exports.passThrough = require_primitives.passThrough;
 exports.suggest = suggest;
 exports.tuple = require_constructs.tuple;
 exports.withDefault = require_modifiers.withDefault;

package/dist/parser.d.cts

@@ -3,7 +3,7 @@ import { Usage } from "./usage.cjs";
 import { DocFragments, DocPage } from "./doc.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.cjs";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 
 //#region src/parser.d.ts
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };

package/dist/parser.d.ts

@@ -3,7 +3,7 @@ import { Usage } from "./usage.js";
 import { DocFragments, DocPage } from "./doc.js";
 import { ValueParserResult } from "./valueparser.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.js";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#region src/parser.d.ts
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };

package/dist/parser.js

@@ -2,7 +2,7 @@ import { message } from "./message.js";
 import { normalizeUsage } from "./usage.js";
 import { concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
-import { argument, command, constant, flag, option } from "./primitives.js";
+import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.ts
 /**
@@ -172,4 +172,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };

package/dist/primitives.cjs

@@ -723,10 +723,176 @@ function command(name, parser, options = {}) {
 		}
 	};
 }
+/**
+* Creates a parser that collects unrecognized options and passes them through.
+* This is useful for building wrapper CLI tools that need to forward unknown
+* options to an underlying tool.
+*
+* **Important**: This parser intentionally weakens Optique's strict parsing
+* philosophy where "all input must be recognized." The benefit is enabling
+* legitimate wrapper/proxy tool patterns, but the trade-off is that typos
+* in pass-through options won't be caught.
+*
+* @param options Configuration for how to capture options.
+* @returns A {@link Parser} that captures unrecognized options as an array
+*          of strings.
+*
+* @example
+* ```typescript
+* // Default format: only captures --opt=val
+* const parser = object({
+*   debug: option("--debug"),
+*   extra: passThrough(),
+* });
+*
+* // mycli --debug --foo=bar --baz=qux
+* // → { debug: true, extra: ["--foo=bar", "--baz=qux"] }
+*
+* // nextToken format: captures --opt val pairs
+* const parser = object({
+*   debug: option("--debug"),
+*   extra: passThrough({ format: "nextToken" }),
+* });
+*
+* // mycli --debug --foo bar
+* // → { debug: true, extra: ["--foo", "bar"] }
+*
+* // greedy format: captures all remaining tokens
+* const parser = command("exec", object({
+*   container: argument(string()),
+*   args: passThrough({ format: "greedy" }),
+* }));
+*
+* // myproxy exec mycontainer --verbose -it bash
+* // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+* ```
+*
+* @since 0.8.0
+*/
+function passThrough(options = {}) {
+	const format = options.format ?? "equalsOnly";
+	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
+	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: -10,
+		usage: [{ type: "passthrough" }],
+		initialState: [],
+		parse(context) {
+			if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`No input to pass through.`
+			};
+			const token = context.buffer[0];
+			if (format === "greedy") {
+				const captured = [...context.buffer];
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: [],
+						state: [...context.state, ...captured]
+					},
+					consumed: captured
+				};
+			}
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`Options terminated; cannot capture pass-through options.`
+			};
+			if (format === "equalsOnly") {
+				if (!equalsOptionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: require_message.message`Expected --option=value format, but got: ${token}.`
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+			}
+			if (format === "nextToken") {
+				if (!optionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: require_message.message`Expected option, but got: ${token}.`
+				};
+				if (token.includes("=")) return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+				const nextToken = context.buffer[1];
+				if (nextToken !== void 0 && !optionPattern.test(nextToken)) return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(2),
+						state: [
+							...context.state,
+							token,
+							nextToken
+						]
+					},
+					consumed: [token, nextToken]
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`Unknown passThrough format: ${format}.`
+			};
+		},
+		complete(state) {
+			return {
+				success: true,
+				value: state
+			};
+		},
+		suggest(_context, _prefix) {
+			return [];
+		},
+		getDocFragments(_state, _defaultValue) {
+			return {
+				fragments: [{
+					type: "entry",
+					term: { type: "passthrough" },
+					description: options.description
+				}],
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `passThrough(${format})`;
+		}
+	};
+}
 
 //#endregion
 exports.argument = argument;
 exports.command = command;
 exports.constant = constant;
 exports.flag = flag;
-exports.option = option;
+exports.option = option;
+exports.passThrough = passThrough;

package/dist/primitives.d.cts

@@ -307,5 +307,82 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  */
 declare function command<T, TState>(name: string, parser: Parser<T, TState>, options?: CommandOptions): Parser<T, CommandState<TState>>;
+/**
+ * Format options for how {@link passThrough} captures options.
+ * @since 0.8.0
+ */
+type PassThroughFormat = "equalsOnly" | "nextToken" | "greedy";
+/**
+ * Options for the {@link passThrough} parser.
+ * @since 0.8.0
+ */
+interface PassThroughOptions {
+  /**
+   * How to capture option values:
+   *
+   * - `"equalsOnly"`: Only capture `--opt=val` format (default, safest).
+   *   Values with spaces (`--opt val`) are not captured.
+   *
+   * - `"nextToken"`: Capture `--opt` and its value as separate tokens
+   *   (`--opt val`). The next token is captured if it doesn't start with `-`.
+   *
+   * - `"greedy"`: Capture *all* remaining tokens from first unrecognized token.
+   *   This is useful for wrapper/proxy tools that pass everything through.
+   *
+   * @default `"equalsOnly"`
+   */
+  readonly format?: PassThroughFormat;
+  /**
+   * A description of what pass-through options are used for.
+   */
+  readonly description?: Message;
+}
+/**
+ * Creates a parser that collects unrecognized options and passes them through.
+ * This is useful for building wrapper CLI tools that need to forward unknown
+ * options to an underlying tool.
+ *
+ * **Important**: This parser intentionally weakens Optique's strict parsing
+ * philosophy where "all input must be recognized." The benefit is enabling
+ * legitimate wrapper/proxy tool patterns, but the trade-off is that typos
+ * in pass-through options won't be caught.
+ *
+ * @param options Configuration for how to capture options.
+ * @returns A {@link Parser} that captures unrecognized options as an array
+ *          of strings.
+ *
+ * @example
+ * ```typescript
+ * // Default format: only captures --opt=val
+ * const parser = object({
+ *   debug: option("--debug"),
+ *   extra: passThrough(),
+ * });
+ *
+ * // mycli --debug --foo=bar --baz=qux
+ * // → { debug: true, extra: ["--foo=bar", "--baz=qux"] }
+ *
+ * // nextToken format: captures --opt val pairs
+ * const parser = object({
+ *   debug: option("--debug"),
+ *   extra: passThrough({ format: "nextToken" }),
+ * });
+ *
+ * // mycli --debug --foo bar
+ * // → { debug: true, extra: ["--foo", "bar"] }
+ *
+ * // greedy format: captures all remaining tokens
+ * const parser = command("exec", object({
+ *   container: argument(string()),
+ *   args: passThrough({ format: "greedy" }),
+ * }));
+ *
+ * // myproxy exec mycontainer --verbose -it bash
+ * // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function passThrough(options?: PassThroughOptions): Parser<readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };

package/dist/primitives.d.ts

@@ -307,5 +307,82 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  *          to the inner parser for the remaining arguments.
  */
 declare function command<T, TState>(name: string, parser: Parser<T, TState>, options?: CommandOptions): Parser<T, CommandState<TState>>;
+/**
+ * Format options for how {@link passThrough} captures options.
+ * @since 0.8.0
+ */
+type PassThroughFormat = "equalsOnly" | "nextToken" | "greedy";
+/**
+ * Options for the {@link passThrough} parser.
+ * @since 0.8.0
+ */
+interface PassThroughOptions {
+  /**
+   * How to capture option values:
+   *
+   * - `"equalsOnly"`: Only capture `--opt=val` format (default, safest).
+   *   Values with spaces (`--opt val`) are not captured.
+   *
+   * - `"nextToken"`: Capture `--opt` and its value as separate tokens
+   *   (`--opt val`). The next token is captured if it doesn't start with `-`.
+   *
+   * - `"greedy"`: Capture *all* remaining tokens from first unrecognized token.
+   *   This is useful for wrapper/proxy tools that pass everything through.
+   *
+   * @default `"equalsOnly"`
+   */
+  readonly format?: PassThroughFormat;
+  /**
+   * A description of what pass-through options are used for.
+   */
+  readonly description?: Message;
+}
+/**
+ * Creates a parser that collects unrecognized options and passes them through.
+ * This is useful for building wrapper CLI tools that need to forward unknown
+ * options to an underlying tool.
+ *
+ * **Important**: This parser intentionally weakens Optique's strict parsing
+ * philosophy where "all input must be recognized." The benefit is enabling
+ * legitimate wrapper/proxy tool patterns, but the trade-off is that typos
+ * in pass-through options won't be caught.
+ *
+ * @param options Configuration for how to capture options.
+ * @returns A {@link Parser} that captures unrecognized options as an array
+ *          of strings.
+ *
+ * @example
+ * ```typescript
+ * // Default format: only captures --opt=val
+ * const parser = object({
+ *   debug: option("--debug"),
+ *   extra: passThrough(),
+ * });
+ *
+ * // mycli --debug --foo=bar --baz=qux
+ * // → { debug: true, extra: ["--foo=bar", "--baz=qux"] }
+ *
+ * // nextToken format: captures --opt val pairs
+ * const parser = object({
+ *   debug: option("--debug"),
+ *   extra: passThrough({ format: "nextToken" }),
+ * });
+ *
+ * // mycli --debug --foo bar
+ * // → { debug: true, extra: ["--foo", "bar"] }
+ *
+ * // greedy format: captures all remaining tokens
+ * const parser = command("exec", object({
+ *   container: argument(string()),
+ *   args: passThrough({ format: "greedy" }),
+ * }));
+ *
+ * // myproxy exec mycontainer --verbose -it bash
+ * // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+ * ```
+ *
+ * @since 0.8.0
+ */
+declare function passThrough(options?: PassThroughOptions): Parser<readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };

package/dist/primitives.js

@@ -723,6 +723,171 @@ function command(name, parser, options = {}) {
 		}
 	};
 }
+/**
+* Creates a parser that collects unrecognized options and passes them through.
+* This is useful for building wrapper CLI tools that need to forward unknown
+* options to an underlying tool.
+*
+* **Important**: This parser intentionally weakens Optique's strict parsing
+* philosophy where "all input must be recognized." The benefit is enabling
+* legitimate wrapper/proxy tool patterns, but the trade-off is that typos
+* in pass-through options won't be caught.
+*
+* @param options Configuration for how to capture options.
+* @returns A {@link Parser} that captures unrecognized options as an array
+*          of strings.
+*
+* @example
+* ```typescript
+* // Default format: only captures --opt=val
+* const parser = object({
+*   debug: option("--debug"),
+*   extra: passThrough(),
+* });
+*
+* // mycli --debug --foo=bar --baz=qux
+* // → { debug: true, extra: ["--foo=bar", "--baz=qux"] }
+*
+* // nextToken format: captures --opt val pairs
+* const parser = object({
+*   debug: option("--debug"),
+*   extra: passThrough({ format: "nextToken" }),
+* });
+*
+* // mycli --debug --foo bar
+* // → { debug: true, extra: ["--foo", "bar"] }
+*
+* // greedy format: captures all remaining tokens
+* const parser = command("exec", object({
+*   container: argument(string()),
+*   args: passThrough({ format: "greedy" }),
+* }));
+*
+* // myproxy exec mycontainer --verbose -it bash
+* // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
+* ```
+*
+* @since 0.8.0
+*/
+function passThrough(options = {}) {
+	const format = options.format ?? "equalsOnly";
+	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
+	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: -10,
+		usage: [{ type: "passthrough" }],
+		initialState: [],
+		parse(context) {
+			if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: message`No input to pass through.`
+			};
+			const token = context.buffer[0];
+			if (format === "greedy") {
+				const captured = [...context.buffer];
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: [],
+						state: [...context.state, ...captured]
+					},
+					consumed: captured
+				};
+			}
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: message`Options terminated; cannot capture pass-through options.`
+			};
+			if (format === "equalsOnly") {
+				if (!equalsOptionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: message`Expected --option=value format, but got: ${token}.`
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+			}
+			if (format === "nextToken") {
+				if (!optionPattern.test(token)) return {
+					success: false,
+					consumed: 0,
+					error: message`Expected option, but got: ${token}.`
+				};
+				if (token.includes("=")) return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+				const nextToken = context.buffer[1];
+				if (nextToken !== void 0 && !optionPattern.test(nextToken)) return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(2),
+						state: [
+							...context.state,
+							token,
+							nextToken
+						]
+					},
+					consumed: [token, nextToken]
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: [...context.state, token]
+					},
+					consumed: [token]
+				};
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: message`Unknown passThrough format: ${format}.`
+			};
+		},
+		complete(state) {
+			return {
+				success: true,
+				value: state
+			};
+		},
+		suggest(_context, _prefix) {
+			return [];
+		},
+		getDocFragments(_state, _defaultValue) {
+			return {
+				fragments: [{
+					type: "entry",
+					term: { type: "passthrough" },
+					description: options.description
+				}],
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `passThrough(${format})`;
+		}
+	};
+}
 
 //#endregion
-export { argument, command, constant, flag, option };
+export { argument, command, constant, flag, option, passThrough };

package/dist/usage.cjs

@@ -331,7 +331,13 @@ function* formatUsageTermInternal(term, options) {
 		text: term.value,
 		width: term.value.length
 	};
-	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+	else if (term.type === "passthrough") {
+		const text = "[...]";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 5
+		};
+	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

package/dist/usage.d.cts

@@ -123,6 +123,16 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+}
+/**
+ * A pass-through term, which represents unrecognized options that are
+ * collected and passed through to an underlying tool or command.
+ * @since 0.8.0
+ */ | {
+  /**
+   * The type of the term, which is always `"passthrough"` for this term.
+   */
+  readonly type: "passthrough";
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.d.ts

@@ -123,6 +123,16 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+}
+/**
+ * A pass-through term, which represents unrecognized options that are
+ * collected and passed through to an underlying tool or command.
+ * @since 0.8.0
+ */ | {
+  /**
+   * The type of the term, which is always `"passthrough"` for this term.
+   */
+  readonly type: "passthrough";
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.js

@@ -330,7 +330,13 @@ function* formatUsageTermInternal(term, options) {
 		text: term.value,
 		width: term.value.length
 	};
-	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+	else if (term.type === "passthrough") {
+		const text = "[...]";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 5
+		};
+	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.8.0-dev.164+250237ef",
+  "version": "0.8.0-dev.165+f4b6fb65",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",