@optique/core 0.10.0-dev.331 → 0.10.0-dev.332

package/dist/context.cjs

@@ -0,0 +1,21 @@
+
+//#region src/context.ts
+/**
+* Checks whether a context is static (returns annotations without needing
+* parsed results).
+*
+* A context is considered static if `getAnnotations()` called without
+* arguments returns a non-empty annotations object synchronously.
+*
+* @param context The source context to check.
+* @returns `true` if the context is static, `false` otherwise.
+* @since 0.10.0
+*/
+function isStaticContext(context) {
+	const result = context.getAnnotations();
+	if (result instanceof Promise) return false;
+	return Object.getOwnPropertySymbols(result).length > 0;
+}
+
+//#endregion
+exports.isStaticContext = isStaticContext;

package/dist/context.d.cts

@@ -0,0 +1,87 @@
+import { Annotations } from "./annotations.cjs";
+
+//#region src/context.d.ts
+
+/**
+ * A source context that can provide data to parsers via annotations.
+ *
+ * Source contexts are used to inject external data (like environment variables
+ * or config files) into the parsing process. They can be either:
+ *
+ * - *Static*: Data is immediately available (e.g., environment variables)
+ * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
+ *   is determined by a CLI option)
+ *
+ * @example
+ * ```typescript
+ * // Static context example (environment variables)
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return {
+ *       [Symbol.for("@myapp/env")]: {
+ *         HOST: process.env.HOST,
+ *         PORT: process.env.PORT,
+ *       }
+ *     };
+ *   }
+ * };
+ *
+ * // Dynamic context example (config file)
+ * const configContext: SourceContext = {
+ *   id: Symbol.for("@myapp/config"),
+ *   async getAnnotations(parsed?: unknown) {
+ *     if (!parsed) return {}; // Return empty on first pass
+ *     const result = parsed as { config?: string };
+ *     if (!result.config) return {};
+ *     const data = await loadConfigFile(result.config);
+ *     return {
+ *       [Symbol.for("@myapp/config")]: data
+ *     };
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.10.0
+ */
+interface SourceContext {
+  /**
+   * Unique identifier for this context.
+   *
+   * This symbol is typically the same as the annotation key used by parsers
+   * that consume this context's data.
+   */
+  readonly id: symbol;
+  /**
+   * Get annotations to inject into parsing.
+   *
+   * This method is called twice during `runWith()` execution:
+   *
+   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
+   *    their annotations, while dynamic contexts should return an empty object.
+   * 2. *Second call*: `parsed` contains the result from the first parse pass.
+   *    Dynamic contexts can use this to load external data (e.g., reading
+   *    a config file whose path was determined in the first pass).
+   *
+   * @param parsed Optional parsed result from a previous parse pass.
+   *               Static contexts can ignore this parameter.
+   *               Dynamic contexts use this to extract necessary data.
+   * @returns Annotations to merge into the parsing session. Can be a Promise
+   *          for async operations (e.g., loading config files).
+   */
+  getAnnotations(parsed?: unknown): Promise<Annotations> | Annotations;
+}
+/**
+ * Checks whether a context is static (returns annotations without needing
+ * parsed results).
+ *
+ * A context is considered static if `getAnnotations()` called without
+ * arguments returns a non-empty annotations object synchronously.
+ *
+ * @param context The source context to check.
+ * @returns `true` if the context is static, `false` otherwise.
+ * @since 0.10.0
+ */
+declare function isStaticContext(context: SourceContext): boolean;
+//#endregion
+export { type Annotations, SourceContext, isStaticContext };

package/dist/context.d.ts

@@ -0,0 +1,87 @@
+import { Annotations } from "./annotations.js";
+
+//#region src/context.d.ts
+
+/**
+ * A source context that can provide data to parsers via annotations.
+ *
+ * Source contexts are used to inject external data (like environment variables
+ * or config files) into the parsing process. They can be either:
+ *
+ * - *Static*: Data is immediately available (e.g., environment variables)
+ * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
+ *   is determined by a CLI option)
+ *
+ * @example
+ * ```typescript
+ * // Static context example (environment variables)
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return {
+ *       [Symbol.for("@myapp/env")]: {
+ *         HOST: process.env.HOST,
+ *         PORT: process.env.PORT,
+ *       }
+ *     };
+ *   }
+ * };
+ *
+ * // Dynamic context example (config file)
+ * const configContext: SourceContext = {
+ *   id: Symbol.for("@myapp/config"),
+ *   async getAnnotations(parsed?: unknown) {
+ *     if (!parsed) return {}; // Return empty on first pass
+ *     const result = parsed as { config?: string };
+ *     if (!result.config) return {};
+ *     const data = await loadConfigFile(result.config);
+ *     return {
+ *       [Symbol.for("@myapp/config")]: data
+ *     };
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.10.0
+ */
+interface SourceContext {
+  /**
+   * Unique identifier for this context.
+   *
+   * This symbol is typically the same as the annotation key used by parsers
+   * that consume this context's data.
+   */
+  readonly id: symbol;
+  /**
+   * Get annotations to inject into parsing.
+   *
+   * This method is called twice during `runWith()` execution:
+   *
+   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
+   *    their annotations, while dynamic contexts should return an empty object.
+   * 2. *Second call*: `parsed` contains the result from the first parse pass.
+   *    Dynamic contexts can use this to load external data (e.g., reading
+   *    a config file whose path was determined in the first pass).
+   *
+   * @param parsed Optional parsed result from a previous parse pass.
+   *               Static contexts can ignore this parameter.
+   *               Dynamic contexts use this to extract necessary data.
+   * @returns Annotations to merge into the parsing session. Can be a Promise
+   *          for async operations (e.g., loading config files).
+   */
+  getAnnotations(parsed?: unknown): Promise<Annotations> | Annotations;
+}
+/**
+ * Checks whether a context is static (returns annotations without needing
+ * parsed results).
+ *
+ * A context is considered static if `getAnnotations()` called without
+ * arguments returns a non-empty annotations object synchronously.
+ *
+ * @param context The source context to check.
+ * @returns `true` if the context is static, `false` otherwise.
+ * @since 0.10.0
+ */
+declare function isStaticContext(context: SourceContext): boolean;
+//#endregion
+export { type Annotations, SourceContext, isStaticContext };

package/dist/context.js

@@ -0,0 +1,20 @@
+//#region src/context.ts
+/**
+* Checks whether a context is static (returns annotations without needing
+* parsed results).
+*
+* A context is considered static if `getAnnotations()` called without
+* arguments returns a non-empty annotations object synchronously.
+*
+* @param context The source context to check.
+* @returns `true` if the context is static, `false` otherwise.
+* @since 0.10.0
+*/
+function isStaticContext(context) {
+	const result = context.getAnnotations();
+	if (result instanceof Promise) return false;
+	return Object.getOwnPropertySymbols(result).length > 0;
+}
+
+//#endregion
+export { isStaticContext };

package/dist/facade.cjs

@@ -1,3 +1,4 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
 const require_usage = require('./usage.cjs');
@@ -658,9 +659,244 @@ var RunParserError = class extends Error {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Merges multiple annotation objects, with earlier contexts having priority.
+*
+* When the same symbol key exists in multiple annotations, the value from
+* the earlier context (lower index in the array) takes precedence.
+*
+* @param annotationsList Array of annotations to merge.
+* @returns Merged annotations object.
+*/
+function mergeAnnotations(annotationsList) {
+	const result = {};
+	for (let i = annotationsList.length - 1; i >= 0; i--) {
+		const annotations = annotationsList[i];
+		for (const key of Object.getOwnPropertySymbols(annotations)) result[key] = annotations[key];
+	}
+	return result;
+}
+/**
+* Collects annotations from all contexts.
+*
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Promise that resolves to merged annotations.
+*/
+async function collectAnnotations(contexts, parsed) {
+	const annotationsList = [];
+	for (const context of contexts) {
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) annotationsList.push(await result);
+		else annotationsList.push(result);
+	}
+	return mergeAnnotations(annotationsList);
+}
+/**
+* Collects annotations from all contexts synchronously.
+*
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Merged annotations.
+* @throws Error if any context returns a Promise.
+*/
+function collectAnnotationsSync(contexts, parsed) {
+	const annotationsList = [];
+	for (const context of contexts) {
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		annotationsList.push(result);
+	}
+	return mergeAnnotations(annotationsList);
+}
+/**
+* Checks if any context has dynamic behavior (returns different annotations
+* when called with parsed results).
+*
+* A context is considered dynamic if:
+* - It returns a Promise
+* - It returns empty annotations without parsed results but may return
+*   non-empty annotations with parsed results
+*
+* @param contexts Source contexts to check.
+* @returns `true` if any context appears to be dynamic.
+*/
+function hasDynamicContexts(contexts) {
+	for (const context of contexts) {
+		const result = context.getAnnotations();
+		if (result instanceof Promise) return true;
+		if (Object.getOwnPropertySymbols(result).length === 0) return true;
+	}
+	return false;
+}
+/**
+* Runs a parser with multiple source contexts.
+*
+* This function automatically handles static and dynamic contexts with proper
+* priority. Earlier contexts in the array override later ones.
+*
+* The function uses a smart two-phase approach:
+*
+* 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+*    their data, dynamic contexts may return empty).
+* 2. *First parse*: Parse with Phase 1 annotations.
+* 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+*    parse result.
+* 4. *Second parse*: Parse again with merged annotations from both phases.
+*
+* If all contexts are static (no dynamic contexts), the second parse is skipped
+* for optimization.
+*
+* @template TParser The parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns Promise that resolves to the parsed result.
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* import { runWith } from "@optique/core/facade";
+* import type { SourceContext } from "@optique/core/context";
+*
+* const envContext: SourceContext = {
+*   id: Symbol.for("@myapp/env"),
+*   getAnnotations() {
+*     return { [Symbol.for("@myapp/env")]: process.env };
+*   }
+* };
+*
+* const result = await runWith(
+*   parser,
+*   "myapp",
+*   [envContext],
+*   { args: process.argv.slice(2) }
+* );
+* ```
+*/
+async function runWith(parser, programName, contexts, options) {
+	const args = options?.args ?? [];
+	if (contexts.length === 0) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
+	const phase1Annotations = await collectAnnotations(contexts);
+	const needsTwoPhase = hasDynamicContexts(contexts);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	try {
+		if (parser.$mode === "async") firstPassResult = await require_parser.parseAsync(augmentedParser1, args);
+		else firstPassResult = require_parser.parseSync(augmentedParser1, args);
+		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
+			const result = firstPassResult;
+			if (result.success) firstPassResult = result.value;
+			else {
+				const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+				if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+				return Promise.resolve(runParser(augmentedParser, programName, args, options));
+			}
+		}
+	} catch {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const phase2Annotations = await collectAnnotations(contexts, firstPassResult);
+	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+}
+/**
+* Runs a synchronous parser with multiple source contexts.
+*
+* This is the sync-only variant of {@link runWith}. All contexts must return
+* annotations synchronously (not Promises).
+*
+* @template TParser The sync parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The synchronous parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns The parsed result.
+* @throws Error if any context returns a Promise.
+* @since 0.10.0
+*/
+function runWithSync(parser, programName, contexts, options) {
+	const args = options?.args ?? [];
+	if (contexts.length === 0) return runParser(parser, programName, args, options);
+	const phase1Annotations = collectAnnotationsSync(contexts);
+	const needsTwoPhase = hasDynamicContexts(contexts);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	try {
+		const result = require_parser.parseSync(augmentedParser1, args);
+		if (result.success) firstPassResult = result.value;
+		else return runParser(augmentedParser1, programName, args, options);
+	} catch {
+		return runParser(augmentedParser1, programName, args, options);
+	}
+	const phase2Annotations = collectAnnotationsSync(contexts, firstPassResult);
+	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	return runParser(augmentedParser2, programName, args, options);
+}
+/**
+* Runs any parser asynchronously with multiple source contexts.
+*
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with async contexts or parsers.
+*
+* @template TParser The parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns Promise that resolves to the parsed result.
+* @since 0.10.0
+*/
+function runWithAsync(parser, programName, contexts, options) {
+	return runWith(parser, programName, contexts, options);
+}
+/**
+* Creates a new parser with annotations injected into its initial state.
+*
+* @param parser The original parser.
+* @param annotations Annotations to inject.
+* @returns A new parser with annotations in its initial state.
+*/
+function injectAnnotationsIntoParser(parser, annotations) {
+	const newInitialState = {
+		...parser.initialState,
+		[require_annotations.annotationKey]: annotations
+	};
+	return {
+		...parser,
+		initialState: newInitialState
+	};
+}
 
 //#endregion
 exports.RunParserError = RunParserError;
 exports.runParser = runParser;
 exports.runParserAsync = runParserAsync;
-exports.runParserSync = runParserSync;
+exports.runParserSync = runParserSync;
+exports.runWith = runWith;
+exports.runWithAsync = runWithAsync;
+exports.runWithSync = runWithSync;

package/dist/facade.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
+import { SourceContext } from "./context.cjs";
 import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
@@ -282,5 +283,104 @@ declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>,
 declare class RunParserError extends Error {
   constructor(message: string);
 }
+/**
+ * Options for runWith functions.
+ * Extends RunOptions with additional context-related settings.
+ *
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
+ * @since 0.10.0
+ */
+interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
+  /**
+   * Command-line arguments to parse. If not provided, defaults to
+   * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
+   */
+  readonly args?: readonly string[];
+}
+/**
+ * Runs a parser with multiple source contexts.
+ *
+ * This function automatically handles static and dynamic contexts with proper
+ * priority. Earlier contexts in the array override later ones.
+ *
+ * The function uses a smart two-phase approach:
+ *
+ * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+ *    their data, dynamic contexts may return empty).
+ * 2. *First parse*: Parse with Phase 1 annotations.
+ * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+ *    parse result.
+ * 4. *Second parse*: Parse again with merged annotations from both phases.
+ *
+ * If all contexts are static (no dynamic contexts), the second parse is skipped
+ * for optimization.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { runWith } from "@optique/core/facade";
+ * import type { SourceContext } from "@optique/core/context";
+ *
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return { [Symbol.for("@myapp/env")]: process.env };
+ *   }
+ * };
+ *
+ * const result = await runWith(
+ *   parser,
+ *   "myapp",
+ *   [envContext],
+ *   { args: process.argv.slice(2) }
+ * );
+ * ```
+ */
+declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
+/**
+ * Runs a synchronous parser with multiple source contexts.
+ *
+ * This is the sync-only variant of {@link runWith}. All contexts must return
+ * annotations synchronously (not Promises).
+ *
+ * @template TParser The sync parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The synchronous parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns The parsed result.
+ * @throws Error if any context returns a Promise.
+ * @since 0.10.0
+ */
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * Runs any parser asynchronously with multiple source contexts.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with async contexts or parsers.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ */
+declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
 //#endregion
-export { RunOptions, RunParserError, runParser, runParserAsync, runParserSync };
+export { RunOptions, RunParserError, RunWithOptions, type SourceContext, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
+import { SourceContext } from "./context.js";
 import { Program } from "./program.js";
 
 //#region src/facade.d.ts
@@ -282,5 +283,104 @@ declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>,
 declare class RunParserError extends Error {
   constructor(message: string);
 }
+/**
+ * Options for runWith functions.
+ * Extends RunOptions with additional context-related settings.
+ *
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
+ * @since 0.10.0
+ */
+interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
+  /**
+   * Command-line arguments to parse. If not provided, defaults to
+   * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
+   */
+  readonly args?: readonly string[];
+}
+/**
+ * Runs a parser with multiple source contexts.
+ *
+ * This function automatically handles static and dynamic contexts with proper
+ * priority. Earlier contexts in the array override later ones.
+ *
+ * The function uses a smart two-phase approach:
+ *
+ * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+ *    their data, dynamic contexts may return empty).
+ * 2. *First parse*: Parse with Phase 1 annotations.
+ * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+ *    parse result.
+ * 4. *Second parse*: Parse again with merged annotations from both phases.
+ *
+ * If all contexts are static (no dynamic contexts), the second parse is skipped
+ * for optimization.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { runWith } from "@optique/core/facade";
+ * import type { SourceContext } from "@optique/core/context";
+ *
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return { [Symbol.for("@myapp/env")]: process.env };
+ *   }
+ * };
+ *
+ * const result = await runWith(
+ *   parser,
+ *   "myapp",
+ *   [envContext],
+ *   { args: process.argv.slice(2) }
+ * );
+ * ```
+ */
+declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
+/**
+ * Runs a synchronous parser with multiple source contexts.
+ *
+ * This is the sync-only variant of {@link runWith}. All contexts must return
+ * annotations synchronously (not Promises).
+ *
+ * @template TParser The sync parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The synchronous parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns The parsed result.
+ * @throws Error if any context returns a Promise.
+ * @since 0.10.0
+ */
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * Runs any parser asynchronously with multiple source contexts.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with async contexts or parsers.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ */
+declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
 //#endregion
-export { RunOptions, RunParserError, runParser, runParserAsync, runParserSync };
+export { RunOptions, RunParserError, RunWithOptions, type SourceContext, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -1,3 +1,4 @@
+import { annotationKey } from "./annotations.js";
 import { commandLine, formatMessage, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { formatUsage } from "./usage.js";
@@ -658,6 +659,238 @@ var RunParserError = class extends Error {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Merges multiple annotation objects, with earlier contexts having priority.
+*
+* When the same symbol key exists in multiple annotations, the value from
+* the earlier context (lower index in the array) takes precedence.
+*
+* @param annotationsList Array of annotations to merge.
+* @returns Merged annotations object.
+*/
+function mergeAnnotations(annotationsList) {
+	const result = {};
+	for (let i = annotationsList.length - 1; i >= 0; i--) {
+		const annotations = annotationsList[i];
+		for (const key of Object.getOwnPropertySymbols(annotations)) result[key] = annotations[key];
+	}
+	return result;
+}
+/**
+* Collects annotations from all contexts.
+*
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Promise that resolves to merged annotations.
+*/
+async function collectAnnotations(contexts, parsed) {
+	const annotationsList = [];
+	for (const context of contexts) {
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) annotationsList.push(await result);
+		else annotationsList.push(result);
+	}
+	return mergeAnnotations(annotationsList);
+}
+/**
+* Collects annotations from all contexts synchronously.
+*
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Merged annotations.
+* @throws Error if any context returns a Promise.
+*/
+function collectAnnotationsSync(contexts, parsed) {
+	const annotationsList = [];
+	for (const context of contexts) {
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		annotationsList.push(result);
+	}
+	return mergeAnnotations(annotationsList);
+}
+/**
+* Checks if any context has dynamic behavior (returns different annotations
+* when called with parsed results).
+*
+* A context is considered dynamic if:
+* - It returns a Promise
+* - It returns empty annotations without parsed results but may return
+*   non-empty annotations with parsed results
+*
+* @param contexts Source contexts to check.
+* @returns `true` if any context appears to be dynamic.
+*/
+function hasDynamicContexts(contexts) {
+	for (const context of contexts) {
+		const result = context.getAnnotations();
+		if (result instanceof Promise) return true;
+		if (Object.getOwnPropertySymbols(result).length === 0) return true;
+	}
+	return false;
+}
+/**
+* Runs a parser with multiple source contexts.
+*
+* This function automatically handles static and dynamic contexts with proper
+* priority. Earlier contexts in the array override later ones.
+*
+* The function uses a smart two-phase approach:
+*
+* 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+*    their data, dynamic contexts may return empty).
+* 2. *First parse*: Parse with Phase 1 annotations.
+* 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+*    parse result.
+* 4. *Second parse*: Parse again with merged annotations from both phases.
+*
+* If all contexts are static (no dynamic contexts), the second parse is skipped
+* for optimization.
+*
+* @template TParser The parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns Promise that resolves to the parsed result.
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* import { runWith } from "@optique/core/facade";
+* import type { SourceContext } from "@optique/core/context";
+*
+* const envContext: SourceContext = {
+*   id: Symbol.for("@myapp/env"),
+*   getAnnotations() {
+*     return { [Symbol.for("@myapp/env")]: process.env };
+*   }
+* };
+*
+* const result = await runWith(
+*   parser,
+*   "myapp",
+*   [envContext],
+*   { args: process.argv.slice(2) }
+* );
+* ```
+*/
+async function runWith(parser, programName, contexts, options) {
+	const args = options?.args ?? [];
+	if (contexts.length === 0) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
+	const phase1Annotations = await collectAnnotations(contexts);
+	const needsTwoPhase = hasDynamicContexts(contexts);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	try {
+		if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
+		else firstPassResult = parseSync(augmentedParser1, args);
+		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
+			const result = firstPassResult;
+			if (result.success) firstPassResult = result.value;
+			else {
+				const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+				if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+				return Promise.resolve(runParser(augmentedParser, programName, args, options));
+			}
+		}
+	} catch {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const phase2Annotations = await collectAnnotations(contexts, firstPassResult);
+	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+}
+/**
+* Runs a synchronous parser with multiple source contexts.
+*
+* This is the sync-only variant of {@link runWith}. All contexts must return
+* annotations synchronously (not Promises).
+*
+* @template TParser The sync parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The synchronous parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns The parsed result.
+* @throws Error if any context returns a Promise.
+* @since 0.10.0
+*/
+function runWithSync(parser, programName, contexts, options) {
+	const args = options?.args ?? [];
+	if (contexts.length === 0) return runParser(parser, programName, args, options);
+	const phase1Annotations = collectAnnotationsSync(contexts);
+	const needsTwoPhase = hasDynamicContexts(contexts);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	try {
+		const result = parseSync(augmentedParser1, args);
+		if (result.success) firstPassResult = result.value;
+		else return runParser(augmentedParser1, programName, args, options);
+	} catch {
+		return runParser(augmentedParser1, programName, args, options);
+	}
+	const phase2Annotations = collectAnnotationsSync(contexts, firstPassResult);
+	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	return runParser(augmentedParser2, programName, args, options);
+}
+/**
+* Runs any parser asynchronously with multiple source contexts.
+*
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with async contexts or parsers.
+*
+* @template TParser The parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns Promise that resolves to the parsed result.
+* @since 0.10.0
+*/
+function runWithAsync(parser, programName, contexts, options) {
+	return runWith(parser, programName, contexts, options);
+}
+/**
+* Creates a new parser with annotations injected into its initial state.
+*
+* @param parser The original parser.
+* @param annotations Annotations to inject.
+* @returns A new parser with annotations in its initial state.
+*/
+function injectAnnotationsIntoParser(parser, annotations) {
+	const newInitialState = {
+		...parser.initialState,
+		[annotationKey]: annotations
+	};
+	return {
+		...parser,
+		initialState: newInitialState
+	};
+}
 
 //#endregion
-export { RunParserError, runParser, runParserAsync, runParserSync };
+export { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/index.cjs

@@ -95,6 +95,9 @@ exports.pwsh = require_completion.pwsh;
 exports.runParser = require_facade.runParser;
 exports.runParserAsync = require_facade.runParserAsync;
 exports.runParserSync = require_facade.runParserSync;
+exports.runWith = require_facade.runWith;
+exports.runWithAsync = require_facade.runWithAsync;
+exports.runWithSync = require_facade.runWithSync;
 exports.string = require_valueparser.string;
 exports.suggest = require_parser.suggest;
 exports.suggestAsync = require_parser.suggestAsync;

package/dist/index.d.cts

@@ -10,5 +10,6 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParse
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
-import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+import { SourceContext } from "./context.cjs";
+import { RunOptions, RunParserError, RunWithOptions, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -10,5 +10,6 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParse
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+import { SourceContext } from "./context.js";
+import { RunOptions, RunParserError, RunWithOptions, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -10,6 +10,6 @@ import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
-import { RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
+import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.331+425449c7",
+  "version": "0.10.0-dev.332+be2882ab",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -67,6 +67,14 @@
       "import": "./dist/completion.js",
       "require": "./dist/completion.cjs"
     },
+    "./context": {
+      "types": {
+        "import": "./dist/context.d.ts",
+        "require": "./dist/context.d.cts"
+      },
+      "import": "./dist/context.js",
+      "require": "./dist/context.cjs"
+    },
     "./constructs": {
       "types": {
         "import": "./dist/constructs.d.ts",