@optique/run 0.10.7 → 1.0.0-dev.1116

package/README.md

@@ -1,9 +1,6 @@
 @optique/run
 ============
 
-> [!WARNING]
-> The API is stabilizing, but may change before the 1.0 release.
-
 Process-integrated CLI parser for Node.js, Bun, and Deno that provides a
 batteries-included interface for *@optique/core* with automatic `process.argv`
 handling, `process.exit()`, and terminal capabilities.
@@ -43,7 +40,8 @@ Quick example
 
 ~~~~ typescript
 import { run } from "@optique/run";
-import { object, option, argument } from "@optique/core/parser";
+import { option, argument } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
 import { string, integer } from "@optique/core/valueparser";
 
 const parser = object({
@@ -73,13 +71,14 @@ Verbose mode enabled.
 Shell completion
 ----------------
 
-*@optique/run* automatically supports shell completion for Bash and zsh.
-Enable completion by adding the `completion` option to your `run()`
-configuration:
+*@optique/run* automatically supports shell completion for Bash, zsh, fish,
+PowerShell, and Nushell.  Enable completion by adding the `completion` option
+to your `run()` configuration:
 
 ~~~~ typescript
 import { run } from "@optique/run";
-import { object, option, argument } from "@optique/core/parser";
+import { option, argument } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
 import { string, choice } from "@optique/core/valueparser";
 
 const parser = object({
@@ -89,19 +88,30 @@ const parser = object({
 });
 
 const config = run(parser, {
-  completion: { mode: "both" }
+  completion: "both"
 });
 ~~~~
 
 Users can then generate and install completion scripts:
 
 ~~~~ bash
-# Generate Bash completion script
+# Bash
 myapp completion bash > ~/.bashrc.d/myapp.bash
 source ~/.bashrc.d/myapp.bash
 
-# Generate zsh completion script
+# zsh
 myapp completion zsh > ~/.zsh/completions/_myapp
+
+# fish
+myapp completion fish > ~/.config/fish/completions/myapp.fish
+
+# PowerShell
+myapp completion pwsh > myapp-completion.ps1
+. ./myapp-completion.ps1
+
+# Nushell
+myapp completion nu | save myapp-completion.nu
+source myapp-completion.nu
 ~~~~
 
 The completion system automatically provides intelligent suggestions for:

package/dist/run.cjs

@@ -4,111 +4,153 @@ const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const node_process = require_rolldown_runtime.__toESM(require("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 (0, __optique_core_facade.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 ?? node_path.default.basename(node_process.default.argv[1] ?? "cli");
+	const args = options.args ?? node_process.default.argv.slice(2);
+	const stdout = options.stdout ?? ((line) => {
+		node_process.default.stdout.write(`${line}\n`);
+	});
+	const stderr = options.stderr ?? ((line) => {
+		node_process.default.stderr.write(`${line}\n`);
+	});
+	const onExit = options.onExit ?? ((exitCode) => node_process.default.exit(exitCode));
+	const colors = options.colors ?? node_process.default.stdout.isTTY;
+	const maxWidth = options.maxWidth ?? node_process.default.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 ?? node_path.default.basename(node_process.default.argv[1] || "cli"), args = node_process.default.argv.slice(2), colors = node_process.default.stdout.isTTY, maxWidth = node_process.default.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: () => node_process.default.exit(0)
-	} : {
-		mode: help.mode,
-		group: help.group,
-		onShow: () => node_process.default.exit(0)
-	} : void 0;
+	})();
 	const versionConfig = (() => {
 		if (!version) return void 0;
 		if (typeof version === "string") return {
-			mode: "option",
 			value: version,
-			onShow: () => node_process.default.exit(0)
-		};
-		const mode = version.mode ?? "option";
-		if (mode === "command" || mode === "both") return {
-			mode,
-			value: version.value,
-			group: version.group,
-			onShow: () => node_process.default.exit(0)
+			option: true,
+			onShow
 		};
 		return {
-			mode,
-			value: version.value,
-			onShow: () => node_process.default.exit(0)
+			...version,
+			onShow
 		};
 	})();
 	const completionConfig = (() => {
 		if (!completion) return void 0;
-		const onShow = () => node_process.default.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 (0, __optique_core_facade.runParser)(parser, programName, args, {
-		stderr(line) {
-			node_process.default.stderr.write(`${line}\n`);
-		},
-		stdout(line) {
-			node_process.default.stdout.write(`${line}\n`);
-		},
+	const coreOptions = {
+		stderr,
+		stdout,
 		colors,
 		maxWidth,
 		showDefault,
 		showChoices,
+		sectionOrder,
 		help: helpConfig,
 		version: versionConfig,
 		completion: completionConfig,
@@ -120,9 +162,31 @@ function runImpl(parserOrProgram, options = {}) {
 		bugs,
 		footer,
 		onError() {
-			return node_process.default.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 (0, __optique_core_facade.runWith)(parser, programName$1, contexts, runWithOptions);
+	}
+	const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
+	return (0, __optique_core_facade.runParser)(parser, programName, args, coreOptions);
 }
 
 //#endregion

package/dist/run.d.cts

@@ -1,7 +1,9 @@
 import { ShellCompletion } from "@optique/core/completion";
+import { SourceContext } from "@optique/core/context";
+import { CommandSubConfig, ContextOptionsParam, OptionSubConfig } from "@optique/core/facade";
 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";
 import { Message } from "@optique/core/message";
 
 //#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 };