@optique/run 0.10.7 → 1.0.0-dev.1116

package/dist/run.d.ts

@@ -1,8 +1,10 @@
+import { CommandSubConfig, ContextOptionsParam, OptionSubConfig } from "@optique/core/facade";
 import { Message } from "@optique/core/message";
 import { ShellCompletion } from "@optique/core/completion";
+import { SourceContext } from "@optique/core/context";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
-import { ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
+import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
 
 //#region src/run.d.ts
 
@@ -22,6 +24,26 @@ interface RunOptions {
    * @default `process.argv.slice(2)` (arguments after the script name)
    */
   readonly args?: readonly string[];
+  /**
+   * Function used to output help and usage messages.  Assumes it prints the
+   * ending newline.
+   *
+   * @default Writes to `process.stdout` with a trailing newline
+   */
+  readonly stdout?: (text: string) => void;
+  /**
+   * Function used to output error messages.  Assumes it prints the ending
+   * newline.
+   *
+   * @default Writes to `process.stderr` with a trailing newline
+   */
+  readonly stderr?: (text: string) => void;
+  /**
+   * Function used to exit the process on help/version display or parse error.
+   *
+   * @default `process.exit`
+   */
+  readonly onExit?: (exitCode: number) => never;
   /**
    * Whether to enable colored output in help and error messages.
    *
@@ -62,69 +84,86 @@ interface RunOptions {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order.
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   */
+  readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
    * Help configuration. Determines how help is made available:
    *
    * - `"command"`: Only the `help` subcommand is available
    * - `"option"`: Only the `--help` option is available
    * - `"both"`: Both `help` subcommand and `--help` option are available
-   * - `object`: Advanced configuration with mode and group
-   *   - `mode`: "command" | "both"
-   *   - `group`: Group label for help command in help output (optional)
+   * - `object`: Advanced configuration with `command` and/or `option`
+   *   sub-configs.  At least one of `command` or `option` must be specified.
    *
    * When not provided, help functionality is disabled.
+   *
+   * @since 1.0.0
    */
-  readonly help?: "command" | "option" | "both" | {
-    readonly mode: "command" | "both";
-    /**
-     * Group label for the help command in help output.
-     * @since 0.10.0
-     */
-    readonly group?: string;
-  };
+  readonly help?: "command" | "option" | "both" | (({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
+  } | {
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  }));
   /**
    * Version configuration. Determines how version is made available:
    *
    * - `string`: Version value with default `"option"` mode (--version only)
-   * - `object`: Advanced configuration with version value and mode
-   *   - `value`: The version string to display
-   *   - `mode`: "command" | "option" | "both" (default: "option")
-   *   - `group`: Group label for version command in help output (only
-   *     when mode is "command" or "both")
+   * - `object`: Advanced configuration with version value and `command`
+   *   and/or `option` sub-configs.  At least one of `command` or `option`
+   *   must be specified.
    *
    * When not provided, version functionality is disabled.
+   *
+   * @since 1.0.0
    */
-  readonly version?: string | {
+  readonly version?: string | ({
     readonly value: string;
-    readonly mode: "command" | "both";
-    /**
-     * Group label for the version command in help output.
-     * @since 0.10.0
-     */
-    readonly group?: string;
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
   } | {
-    readonly value: string;
-    readonly mode?: "option";
-    readonly group?: never;
-  };
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  }));
   /**
-   * Completion configuration. Determines how shell completion is made available:
+   * Completion configuration. Determines how shell completion is made
+   * available:
    *
    * - `"command"`: Only the `completion` subcommand is available
    * - `"option"`: Only the `--completion` option is available
-   * - `"both"`: Both `completion` subcommand and `--completion` option are available
-   * - `object`: Advanced configuration with mode and custom shells
-   *   - `mode`: "command" | "option" | "both" (default: "both")
-   *   - `name`: "singular" | "plural" | "both" (default: "both")
-   *   - `helpVisibility`: "singular" | "plural" | "both" | "none"
-   *      (default: matches `name`)
-   *   - `shells`: Custom shell completions (optional)
+   * - `"both"`: Both `completion` subcommand and `--completion` option
+   *   are available
+   * - `object`: Advanced configuration with `command` and/or `option`
+   *   sub-configs and optional custom shells.  At least one of `command`
+   *   or `option` must be specified.
    *
    * When not provided, completion functionality is disabled.
    *
-   * @since 0.6.0
+   * @since 1.0.0
    */
-  readonly completion?: "command" | "option" | "both" | CompletionOptions;
+  readonly completion?: "command" | "option" | "both" | ({
+    readonly shells?: Record<string, ShellCompletion>;
+  } & ({
+    readonly command: true | CommandSubConfig;
+    readonly option?: true | OptionSubConfig;
+  } | {
+    readonly option: true | OptionSubConfig;
+    readonly command?: true | CommandSubConfig;
+  }));
   /**
    * What to display above error messages:
    *
@@ -177,49 +216,59 @@ interface RunOptions {
    * @since 0.4.0
    */
   readonly footer?: Message;
-}
-type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
-type CompletionOptionsBase = {
-  readonly mode?: "command" | "both";
-  /**
-   * Group label for the completion command in help output.
-   * @since 0.10.0
-   */
-  readonly group?: string;
-  readonly shells?: Record<string, ShellCompletion>;
-} | {
-  readonly mode: "option";
-  readonly group?: never;
-  readonly shells?: Record<string, ShellCompletion>;
-};
-type CompletionOptionsBoth = CompletionOptionsBase & {
-  readonly name?: "both";
-  /**
-   * Controls which completion aliases are shown in help and usage output.
-   *
-   * @since 0.10.0
-   */
-  readonly helpVisibility?: CompletionHelpVisibility;
-};
-type CompletionOptionsSingular = CompletionOptionsBase & {
-  readonly name: "singular";
   /**
-   * Controls which completion aliases are shown in help and usage output.
+   * Source contexts to use for two-phase parsing.  When provided, the
+   * runner delegates to `runWith()` (or `runWithSync()` for sync parsers)
+   * from `@optique/core/facade`, which handles annotation collection and
+   * multi-phase parsing automatically.
    *
-   * @since 0.10.0
+   * @since 1.0.0
    */
-  readonly helpVisibility?: "singular" | "none";
-};
-type CompletionOptionsPlural = CompletionOptionsBase & {
-  readonly name: "plural";
+  readonly contexts?: readonly SourceContext<unknown>[];
   /**
-   * Controls which completion aliases are shown in help and usage output.
+   * Options to forward to source contexts.  When contexts declare
+   * required options (via `$requiredOptions`), pass them here to
+   * avoid name collisions with runner-level options such as `help`,
+   * `programName`, or `version`.
    *
-   * @since 0.10.0
+   * @since 1.0.0
    */
-  readonly helpVisibility?: "plural" | "none";
-};
-type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | CompletionOptionsPlural;
+  readonly contextOptions?: Record<string, unknown>;
+}
+/**
+ * Rejects context tuples that are statically known to be empty so those calls
+ * fall back to the no-context overloads.
+ */
+type RejectEmptyContexts<TContexts extends readonly SourceContext<unknown>[]> = TContexts extends readonly [] ? never : unknown;
+/**
+ * Represents a context tuple that is statically known to contain at least one
+ * source context.
+ */
+type NonEmptySourceContexts = readonly [SourceContext<unknown>, ...SourceContext<unknown>[]];
+/**
+ * Rejects option shapes that may carry a non-empty `contexts` array so plain
+ * Program overloads do not bypass the context-aware overloads.
+ */
+type ContextsFromOptions<TOptions> = [Exclude<TOptions, undefined>] extends [never] ? undefined : Exclude<TOptions, undefined> extends {
+  readonly contexts?: infer TContexts extends readonly SourceContext<unknown>[] | undefined;
+} ? TContexts : undefined;
+type RejectContextfulOptions<TOptions> = [ContextsFromOptions<TOptions>] extends [undefined | readonly []] ? unknown : never;
+/**
+ * Rejects option shapes that introduce keys outside the public `RunOptions`
+ * contract, preserving typo detection for direct object literals and wider
+ * option variables.
+ */
+type RejectUnknownRunOptionKeys<TOptions> = [TOptions] extends [undefined] ? unknown : Exclude<keyof TOptions, keyof RunOptions> extends never ? unknown : never;
+/**
+ * Accepts only values typed exactly as `RunOptions`, which are widened to the
+ * conservative fallback overloads because they may hide context presence.
+ */
+type AcceptExactRunOptions<TOptions> = [TOptions] extends [RunOptions] ? [RunOptions] extends [TOptions] ? unknown : never : never;
+/**
+ * Accepts only values typed exactly as `RunOptions | undefined`, which model
+ * optional forwarding wrappers without widening generic Program overloads.
+ */
+type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions | undefined] ? [RunOptions | undefined] extends [TOptions] ? unknown : never : never;
 /**
  * Runs a command-line parser with automatic process integration.
  *
@@ -285,8 +334,25 @@ type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | Com
  *
  * @since 0.11.0 Added support for {@link Program} objects.
  */
-declare function run<T>(program: Program<"sync", T>, options?: RunOptions): T;
-declare function run<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
+declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends NonEmptySourceContexts>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<InferValue<T>>;
+declare function run<T extends Parser<Mode, unknown, unknown>, const TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, InferValue<T>>): ModeValue<InferMode<T>, InferValue<T>> | Promise<InferValue<T>>;
+declare function run<M extends Mode, T, const TContexts extends NonEmptySourceContexts>(program: Program<M, T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ContextOptionsParam<TContexts, T>): Promise<T>;
+declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): T | Promise<T>;
+declare function run<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"async", T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<T>;
+declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;
+declare function run<T, TOptions extends RunOptions>(program: Program<"sync", T>, options: TOptions & AcceptExactRunOptions<TOptions>): T | Promise<T>;
+declare function run<T, const TOptions extends RunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
+declare function run<T, TOptions extends RunOptions>(program: Program<"async", T>, options: TOptions & AcceptExactRunOptions<TOptions>): Promise<T>;
 declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 declare function run<T extends Parser<"async", unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): ModeValue<InferMode<T>, InferValue<T>>;
@@ -303,7 +369,15 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @returns The parsed result if successful.
  * @since 0.9.0
  */
-declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
+declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ContextOptionsParam<TContexts, InferValue<T>>): InferValue<T>;
+declare function runSync<T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<"sync", T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): T;
+declare function runSync<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): T;
+declare function runSync<T, TOptions extends RunOptions>(program: Program<"sync", T>, options: TOptions & AcceptExactRunOptions<TOptions>): T;
+declare function runSync<T, TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options: TOptions & AcceptExactOptionalRunOptions<TOptions>): T;
 declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 /**
  * Runs an asynchronous command-line parser with automatic process integration.
@@ -318,8 +392,16 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
-declare function runAsync<T>(program: Program<"sync", T>, options?: RunOptions): Promise<T>;
-declare function runAsync<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
+declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<InferValue<T>>;
+declare function runAsync<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: RunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<T>;
+declare function runAsync<T, const TOptions extends RunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
+declare function runAsync<T, const TOptions extends RunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownRunOptionKeys<TOptions>): Promise<T>;
+declare function runAsync<T, TOptions extends RunOptions>(program: Program<Mode, T>, options: TOptions & AcceptExactRunOptions<TOptions>): Promise<T>;
+declare function runAsync<T, TOptions extends RunOptions | undefined>(program: Program<Mode, T>, options: TOptions & AcceptExactOptionalRunOptions<TOptions>): Promise<T>;
 declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 //#endregion
 export { RunOptions, run, runAsync, runSync };

package/dist/run.js

@@ -1,113 +1,155 @@
-import { runParser } from "@optique/core/facade";
+import { runParser, runWith, runWithSync } from "@optique/core/facade";
 import path from "node:path";
 import process from "node:process";
 
 //#region src/run.ts
+function getProgramHelpMetadata(metadata) {
+	return {
+		brief: metadata.brief,
+		description: metadata.description,
+		examples: metadata.examples,
+		author: metadata.author,
+		bugs: metadata.bugs,
+		footer: metadata.footer
+	};
+}
+function resolveProgramInput(parserOrProgram, options) {
+	if ("parser" in parserOrProgram && "metadata" in parserOrProgram) return {
+		parser: parserOrProgram.parser,
+		options: options.programName == null ? {
+			...options,
+			programName: parserOrProgram.metadata.name
+		} : options,
+		programMetadata: getProgramHelpMetadata(parserOrProgram.metadata)
+	};
+	return {
+		parser: parserOrProgram,
+		options
+	};
+}
 function run(parserOrProgram, options = {}) {
 	return runImpl(parserOrProgram, options);
 }
 function runSync(parserOrProgram, options = {}) {
+	const contexts = options.contexts;
+	if (contexts && contexts.length > 0) {
+		const resolved = resolveProgramInput(parserOrProgram, options);
+		const { parser, programMetadata } = resolved;
+		options = resolved.options;
+		const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
+		const runWithOptions = {
+			...coreOptions,
+			contextOptions: options.contextOptions,
+			args
+		};
+		return runWithSync(parser, programName, contexts, runWithOptions);
+	}
 	return runImpl(parserOrProgram, options);
 }
 function runAsync(parserOrProgram, options = {}) {
 	const result = runImpl(parserOrProgram, options);
 	return Promise.resolve(result);
 }
-function runImpl(parserOrProgram, options = {}) {
-	const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
-	let parser;
-	let programNameFromProgram;
-	let programMetadata;
-	if (isProgram) {
-		const program = parserOrProgram;
-		parser = program.parser;
-		programNameFromProgram = program.metadata.name;
-		programMetadata = {
-			brief: program.metadata.brief,
-			description: program.metadata.description,
-			examples: program.metadata.examples,
-			author: program.metadata.author,
-			bugs: program.metadata.bugs,
-			footer: program.metadata.footer
+/**
+* Builds core run options from the simplified RunOptions format.
+*
+* Converts the user-friendly RunOptions (string-based help/version/completion)
+* into the verbose CoreRunOptions format expected by `runParser()`, `runWith()`,
+* and `runWithSync()` from `@optique/core/facade`.
+*
+* @internal
+*/
+function buildCoreOptions(options, programMetadata) {
+	const programName = options.programName ?? path.basename(process.argv[1] ?? "cli");
+	const args = options.args ?? process.argv.slice(2);
+	const stdout = options.stdout ?? ((line) => {
+		process.stdout.write(`${line}\n`);
+	});
+	const stderr = options.stderr ?? ((line) => {
+		process.stderr.write(`${line}\n`);
+	});
+	const onExit = options.onExit ?? ((exitCode) => process.exit(exitCode));
+	const colors = options.colors ?? process.stdout.isTTY;
+	const maxWidth = options.maxWidth ?? process.stdout.columns;
+	const showDefault = options.showDefault;
+	const showChoices = options.showChoices;
+	const sectionOrder = options.sectionOrder;
+	const help = options.help;
+	const version = options.version;
+	const completion = options.completion;
+	const aboveError = options.aboveError ?? "usage";
+	const errorExitCode = options.errorExitCode ?? 1;
+	const brief = options.brief ?? programMetadata?.brief;
+	const description = options.description ?? programMetadata?.description;
+	const examples = options.examples ?? programMetadata?.examples;
+	const author = options.author ?? programMetadata?.author;
+	const bugs = options.bugs ?? programMetadata?.bugs;
+	const footer = options.footer ?? programMetadata?.footer;
+	const onShow = () => onExit(0);
+	const helpConfig = (() => {
+		if (!help) return void 0;
+		if (typeof help === "string") switch (help) {
+			case "command": return {
+				command: true,
+				onShow
+			};
+			case "option": return {
+				option: true,
+				onShow
+			};
+			case "both": return {
+				command: true,
+				option: true,
+				onShow
+			};
+		}
+		return {
+			...help,
+			onShow
 		};
-	} else parser = parserOrProgram;
-	const { programName = programNameFromProgram ?? path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, showChoices, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
-	const helpConfig = help ? typeof help === "string" ? {
-		mode: help,
-		onShow: () => process.exit(0)
-	} : {
-		mode: help.mode,
-		group: help.group,
-		onShow: () => process.exit(0)
-	} : void 0;
+	})();
 	const versionConfig = (() => {
 		if (!version) return void 0;
 		if (typeof version === "string") return {
-			mode: "option",
 			value: version,
-			onShow: () => process.exit(0)
-		};
-		const mode = version.mode ?? "option";
-		if (mode === "command" || mode === "both") return {
-			mode,
-			value: version.value,
-			group: version.group,
-			onShow: () => process.exit(0)
+			option: true,
+			onShow
 		};
 		return {
-			mode,
-			value: version.value,
-			onShow: () => process.exit(0)
+			...version,
+			onShow
 		};
 	})();
 	const completionConfig = (() => {
 		if (!completion) return void 0;
-		const onShow = () => process.exit(0);
-		if (typeof completion === "string") return {
-			mode: completion,
-			name: "both",
-			helpVisibility: "both",
-			onShow
-		};
-		const mode = completion.mode ?? "both";
-		const shells = completion.shells;
-		const cGroup = completion.group;
-		if (completion.name === "singular") return {
-			mode,
-			shells,
-			...cGroup != null && { group: cGroup },
-			name: "singular",
-			helpVisibility: completion.helpVisibility ?? "singular",
-			onShow
-		};
-		if (completion.name === "plural") return {
-			mode,
-			shells,
-			...cGroup != null && { group: cGroup },
-			name: "plural",
-			helpVisibility: completion.helpVisibility ?? "plural",
-			onShow
-		};
+		if (typeof completion === "string") switch (completion) {
+			case "command": return {
+				command: true,
+				onShow
+			};
+			case "option": return {
+				option: true,
+				onShow
+			};
+			case "both": return {
+				command: true,
+				option: true,
+				onShow
+			};
+		}
 		return {
-			mode,
-			shells,
-			...cGroup != null && { group: cGroup },
-			name: "both",
-			helpVisibility: completion.helpVisibility ?? "both",
+			...completion,
 			onShow
 		};
 	})();
-	return runParser(parser, programName, args, {
-		stderr(line) {
-			process.stderr.write(`${line}\n`);
-		},
-		stdout(line) {
-			process.stdout.write(`${line}\n`);
-		},
+	const coreOptions = {
+		stderr,
+		stdout,
 		colors,
 		maxWidth,
 		showDefault,
 		showChoices,
+		sectionOrder,
 		help: helpConfig,
 		version: versionConfig,
 		completion: completionConfig,
@@ -119,9 +161,31 @@ function runImpl(parserOrProgram, options = {}) {
 		bugs,
 		footer,
 		onError() {
-			return process.exit(errorExitCode);
+			return onExit(errorExitCode);
 		}
-	});
+	};
+	return {
+		programName,
+		args,
+		coreOptions
+	};
+}
+function runImpl(parserOrProgram, options = {}) {
+	const resolved = resolveProgramInput(parserOrProgram, options);
+	const { parser, programMetadata } = resolved;
+	options = resolved.options;
+	const contexts = options.contexts;
+	if (contexts && contexts.length > 0) {
+		const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
+		const runWithOptions = {
+			...coreOptions$1,
+			contextOptions: options.contextOptions,
+			args: args$1
+		};
+		return runWith(parser, programName$1, contexts, runWithOptions);
+	}
+	const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
+	return runParser(parser, programName, args, coreOptions);
 }
 
 //#endregion

package/dist/valueparser.cjs

@@ -14,6 +14,17 @@ const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 *
 * @param options Configuration options for path validation.
 * @returns A ValueParser that validates and returns string paths.
+* @throws {TypeError} If {@link PathOptionsBase.type} is not one of
+*   `"file"`, `"directory"`, or `"either"`.
+* @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
+*   not start with a dot (e.g., `"json"` instead of `".json"`).
+* @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
+* @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
+*   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
 *
 * @example
 * ```typescript
@@ -43,16 +54,30 @@ const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 function path(options = {}) {
 	const { metavar = "PATH", type = "either", allowCreate = false, extensions } = options;
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
+	if (type !== "file" && type !== "directory" && type !== "either") throw new TypeError(`Unsupported path type: ${JSON.stringify(type)}. Expected "file", "directory", or "either".`);
+	if (extensions) {
+		for (const ext of extensions) if (!ext.startsWith(".")) throw new TypeError(`Each extension must start with a dot, got: ${JSON.stringify(ext)}`);
+	}
+	if (options.allowCreate !== void 0 && typeof options.allowCreate !== "boolean") throw new TypeError(`Expected allowCreate to be a boolean, but got ${typeof options.allowCreate}: ${String(options.allowCreate)}.`);
+	const rawOptions = options;
+	if ("mustExist" in options && rawOptions.mustExist !== void 0 && typeof rawOptions.mustExist !== "boolean") throw new TypeError(`Expected mustExist to be a boolean, but got ${typeof rawOptions.mustExist}: ${String(rawOptions.mustExist)}.`);
+	if ("mustNotExist" in options && rawOptions.mustNotExist !== void 0 && typeof rawOptions.mustNotExist !== "boolean") throw new TypeError(`Expected mustNotExist to be a boolean, but got ${typeof rawOptions.mustNotExist}: ${String(rawOptions.mustNotExist)}.`);
 	const mustExist = "mustExist" in options ? options.mustExist : false;
 	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
+	if (mustExist && mustNotExist) throw new TypeError("Options mustExist and mustNotExist are mutually exclusive.");
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
-			if (extensions && extensions.length > 0) {
-				const ext = (0, node_path.extname)(input);
-				if (!extensions.includes(ext)) {
-					const actualExt = ext || "no extension";
+			if (input.trim() === "") return {
+				success: false,
+				error: options.errors?.emptyPath ? typeof options.errors.emptyPath === "function" ? options.errors.emptyPath(input) : options.errors.emptyPath : __optique_core_message.message`Path must not be empty.`
+			};
+			if (type !== "directory" && extensions && extensions.length > 0) {
+				const base = /[/\\]$/.test(input) ? "" : (0, node_path.basename)(input);
+				if (!extensions.some((ext) => base.endsWith(ext))) {
+					const ext = (0, node_path.extname)(input);
+					const actualExt = ext || (base.startsWith(".") ? base : "no extension");
 					return {
 						success: false,
 						error: options.errors?.invalidExtension ? typeof options.errors.invalidExtension === "function" ? options.errors.invalidExtension(input, extensions, actualExt) : options.errors.invalidExtension : __optique_core_message.message`Expected file with extension ${(0, __optique_core_message.text)(extensions.join(", "))}, got ${(0, __optique_core_message.text)(actualExt)}.`
@@ -112,7 +137,7 @@ function path(options = {}) {
 				pattern: prefix,
 				type: type === "either" ? "any" : type,
 				extensions,
-				includeHidden: prefix.startsWith("."),
+				includeHidden: (0, node_path.basename)(prefix).startsWith("."),
 				description: type === "directory" ? __optique_core_message.message`Directory` : type === "file" ? __optique_core_message.message`File` : __optique_core_message.message`File or directory`
 			};
 		}