@optique/run 1.0.0-dev.428 → 1.0.0-dev.431

package/dist/run.cjs

@@ -8,31 +8,54 @@ function run(parserOrProgram, options = {}) {
 	return runImpl(parserOrProgram, options);
 }
 function runSync(parserOrProgram, options = {}) {
+	const contexts = options.contexts;
+	if (contexts && contexts.length > 0) {
+		const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
+		let parser;
+		let programMetadata;
+		if (isProgram) {
+			const program = parserOrProgram;
+			parser = program.parser;
+			if (!options.programName) options = {
+				...options,
+				programName: 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
+			};
+		} else parser = parserOrProgram;
+		const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
+		const contextOptions = {};
+		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
+		const runWithOptions = {
+			...coreOptions,
+			...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
-		};
-	} 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, sectionOrder, 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;
+/**
+* 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 = 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, sectionOrder, 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)
@@ -98,7 +121,7 @@ function runImpl(parserOrProgram, options = {}) {
 			onShow
 		};
 	})();
-	return (0, __optique_core_facade.runParser)(parser, programName, args, {
+	const coreOptions = {
 		stderr(line) {
 			node_process.default.stderr.write(`${line}\n`);
 		},
@@ -123,7 +146,73 @@ function runImpl(parserOrProgram, options = {}) {
 		onError() {
 			return node_process.default.exit(errorExitCode);
 		}
-	});
+	};
+	return {
+		programName,
+		args,
+		coreOptions
+	};
+}
+/**
+* Set of known RunOptions field names.  Used by `runImpl()` to separate
+* RunOptions fields from context-required options via rest-spread.
+*/
+const knownRunOptionsKeys = new Set([
+	"programName",
+	"args",
+	"colors",
+	"maxWidth",
+	"showDefault",
+	"showChoices",
+	"sectionOrder",
+	"help",
+	"version",
+	"completion",
+	"aboveError",
+	"errorExitCode",
+	"brief",
+	"description",
+	"examples",
+	"author",
+	"bugs",
+	"footer",
+	"contexts"
+]);
+function runImpl(parserOrProgram, options = {}) {
+	const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
+	let parser;
+	let programMetadata;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		const 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
+		};
+		if (!options.programName) options = {
+			...options,
+			programName: programNameFromProgram
+		};
+	} else parser = parserOrProgram;
+	const contexts = options.contexts;
+	if (contexts && contexts.length > 0) {
+		const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
+		const contextOptions = {};
+		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
+		const runWithOptions = {
+			...coreOptions$1,
+			...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,4 +1,6 @@
 import { ShellCompletion } from "@optique/core/completion";
+import { SourceContext } from "@optique/core/context";
+import { ExtractRequiredOptions } from "@optique/core/facade";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -191,6 +193,15 @@ interface RunOptions {
    * @since 0.4.0
    */
   readonly footer?: Message;
+  /**
+   * 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 1.0.0
+   */
+  readonly contexts?: readonly SourceContext<unknown>[];
 }
 type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
 type CompletionOptionsBase = {
@@ -299,6 +310,9 @@ type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | Com
  *
  * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function run<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 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<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
@@ -317,6 +331,9 @@ 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 extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, InferValue<T>>): InferValue<T>;
 declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
 declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 /**
@@ -332,6 +349,9 @@ 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 extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 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>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;

package/dist/run.d.ts

@@ -1,5 +1,7 @@
+import { ExtractRequiredOptions } 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 { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -191,6 +193,15 @@ interface RunOptions {
    * @since 0.4.0
    */
   readonly footer?: Message;
+  /**
+   * 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 1.0.0
+   */
+  readonly contexts?: readonly SourceContext<unknown>[];
 }
 type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
 type CompletionOptionsBase = {
@@ -299,6 +310,9 @@ type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | Com
  *
  * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function run<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 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<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
@@ -317,6 +331,9 @@ 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 extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, InferValue<T>>): InferValue<T>;
 declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
 declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 /**
@@ -332,6 +349,9 @@ 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 extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
+  readonly contexts: TContexts;
+} & ExtractRequiredOptions<TContexts, InferValue<T>>): Promise<InferValue<T>>;
 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>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;

package/dist/run.js

@@ -1,4 +1,4 @@
-import { runParser } from "@optique/core/facade";
+import { runParser, runWith, runWithSync } from "@optique/core/facade";
 import path from "node:path";
 import process from "node:process";
 
@@ -7,31 +7,54 @@ function run(parserOrProgram, options = {}) {
 	return runImpl(parserOrProgram, options);
 }
 function runSync(parserOrProgram, options = {}) {
+	const contexts = options.contexts;
+	if (contexts && contexts.length > 0) {
+		const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
+		let parser;
+		let programMetadata;
+		if (isProgram) {
+			const program = parserOrProgram;
+			parser = program.parser;
+			if (!options.programName) options = {
+				...options,
+				programName: 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
+			};
+		} else parser = parserOrProgram;
+		const { programName, args, coreOptions } = buildCoreOptions(options, programMetadata);
+		const contextOptions = {};
+		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
+		const runWithOptions = {
+			...coreOptions,
+			...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
-		};
-	} 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, sectionOrder, 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;
+/**
+* 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 = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, showChoices, sectionOrder, 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)
@@ -97,7 +120,7 @@ function runImpl(parserOrProgram, options = {}) {
 			onShow
 		};
 	})();
-	return runParser(parser, programName, args, {
+	const coreOptions = {
 		stderr(line) {
 			process.stderr.write(`${line}\n`);
 		},
@@ -122,7 +145,73 @@ function runImpl(parserOrProgram, options = {}) {
 		onError() {
 			return process.exit(errorExitCode);
 		}
-	});
+	};
+	return {
+		programName,
+		args,
+		coreOptions
+	};
+}
+/**
+* Set of known RunOptions field names.  Used by `runImpl()` to separate
+* RunOptions fields from context-required options via rest-spread.
+*/
+const knownRunOptionsKeys = new Set([
+	"programName",
+	"args",
+	"colors",
+	"maxWidth",
+	"showDefault",
+	"showChoices",
+	"sectionOrder",
+	"help",
+	"version",
+	"completion",
+	"aboveError",
+	"errorExitCode",
+	"brief",
+	"description",
+	"examples",
+	"author",
+	"bugs",
+	"footer",
+	"contexts"
+]);
+function runImpl(parserOrProgram, options = {}) {
+	const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
+	let parser;
+	let programMetadata;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		const 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
+		};
+		if (!options.programName) options = {
+			...options,
+			programName: programNameFromProgram
+		};
+	} else parser = parserOrProgram;
+	const contexts = options.contexts;
+	if (contexts && contexts.length > 0) {
+		const { programName: programName$1, args: args$1, coreOptions: coreOptions$1 } = buildCoreOptions(options, programMetadata);
+		const contextOptions = {};
+		for (const key of Object.keys(options)) if (!knownRunOptionsKeys.has(key)) contextOptions[key] = options[key];
+		const runWithOptions = {
+			...coreOptions$1,
+			...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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.0.0-dev.428+d513f36f",
+  "version": "1.0.0-dev.431+01c1abaf",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.0-dev.428+d513f36f"
+    "@optique/core": "1.0.0-dev.431+01c1abaf"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",