@optique/config 0.10.0-dev.343 → 0.10.0-dev.345

package/dist/{index-D_lTcz4s.d.ts → index-CYn_0yAG.d.ts}

@@ -1,6 +1,6 @@
-import { Parser } from "@optique/core/parser";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 import { ParserValuePlaceholder, SourceContext } from "@optique/core/context";
+import { Parser } from "@optique/core/parser";
 
 //#region src/index.d.ts
 

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_src = require('./src-CTH1AjFs.cjs');
+const require_src = require('./src-8nvtohSm.cjs');
 
 exports.bindConfig = require_src.bindConfig;
 exports.clearActiveConfig = require_src.clearActiveConfig;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-D_lTcz4s.js";
+import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-CYn_0yAG.js";
 export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./src-C9h3sfAM.js";
+import { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./src-CLJCVbow.js";
 
 export { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/run.cjs

@@ -1,9 +1,71 @@
-const require_src = require('./src-CTH1AjFs.cjs');
+const require_src = require('./src-8nvtohSm.cjs');
 const node_fs_promises = require_src.__toESM(require("node:fs/promises"));
-const __optique_core_parser = require_src.__toESM(require("@optique/core/parser"));
+const node_path = require_src.__toESM(require("node:path"));
+const node_process = require_src.__toESM(require("node:process"));
+const __optique_core_facade = require_src.__toESM(require("@optique/core/facade"));
 
 //#region src/run.ts
 /**
+* Helper function to create a wrapper SourceContext for config loading.
+* @internal
+*/
+function createConfigSourceContext(context, options) {
+	return {
+		id: context.id,
+		async getAnnotations(parsed) {
+			if (!parsed) return {};
+			let configData;
+			if ("load" in options) {
+				const customOptions = options;
+				try {
+					const rawData = await Promise.resolve(customOptions.load(parsed));
+					const validation = context.schema["~standard"].validate(rawData);
+					let validationResult;
+					if (validation instanceof Promise) validationResult = await validation;
+					else validationResult = validation;
+					if (validationResult.issues) {
+						const firstIssue = validationResult.issues[0];
+						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+					}
+					configData = validationResult.value;
+				} catch (error) {
+					if (error instanceof Error && error.message.includes("validation")) throw error;
+					throw error;
+				}
+			} else {
+				const singleFileOptions = options;
+				const configPath = singleFileOptions.getConfigPath(parsed);
+				if (configPath) try {
+					const contents = await (0, node_fs_promises.readFile)(configPath);
+					let rawData;
+					if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
+					else {
+						const text = new TextDecoder().decode(contents);
+						rawData = JSON.parse(text);
+					}
+					const validation = context.schema["~standard"].validate(rawData);
+					let validationResult;
+					if (validation instanceof Promise) validationResult = await validation;
+					else validationResult = validation;
+					if (validationResult.issues) {
+						const firstIssue = validationResult.issues[0];
+						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+					}
+					configData = validationResult.value;
+				} catch (error) {
+					if (error instanceof Error && error.message.includes("validation")) throw error;
+					configData = void 0;
+				}
+			}
+			if (configData) {
+				require_src.setActiveConfig(context.id, configData);
+				return { [require_src.configKey]: configData };
+			}
+			return {};
+		}
+	};
+}
+/**
 * Runs a parser with configuration file support using two-pass parsing.
 *
 * This function performs the following steps:
@@ -13,10 +75,16 @@ const __optique_core_parser = require_src.__toESM(require("@optique/core/parser"
 *
 * The priority order for values is: CLI > config file > default.
 *
+* The function also supports help, version, and completion features. When these
+* special commands are detected, config loading is skipped entirely, ensuring
+* these features work even when config files don't exist.
+*
 * @template M The parser mode (sync or async).
 * @template TValue The parser value type.
 * @template TState The parser state type.
 * @template T The config data type.
+* @template THelp The return type when help is shown.
+* @template TError The return type when an error occurs.
 * @param parser The parser to execute.
 * @param context The config context with schema.
 * @param options Run options - either SingleFileOptions or CustomLoadOptions.
@@ -49,6 +117,8 @@ const __optique_core_parser = require_src.__toESM(require("@optique/core/parser"
 * const result = await runWithConfig(parser, context, {
 *   getConfigPath: (parsed) => parsed.config,
 *   args: process.argv.slice(2),
+*   help: { mode: "option", onShow: () => process.exit(0) },
+*   version: { value: "1.0.0", onShow: () => process.exit(0) },
 * });
 * ```
 *
@@ -66,82 +136,33 @@ const __optique_core_parser = require_src.__toESM(require("@optique/core/parser"
 *     return deepMerge(...configs);
 *   },
 *   args: process.argv.slice(2),
+*   help: { mode: "option", onShow: () => process.exit(0) },
 * });
 * ```
 */
 async function runWithConfig(parser, context, options) {
-	const args = options.args ?? [];
-	const firstPass = (0, __optique_core_parser.parse)(parser, args);
-	let firstPassResult;
-	if (firstPass instanceof Promise) firstPassResult = await firstPass;
-	else firstPassResult = firstPass;
-	if (!firstPassResult.success) {
-		const errorParts = firstPassResult.error.map((part) => {
-			if (part.type === "text") return part.text;
-			if (part.type === "optionName") return part.optionName;
-			if (part.type === "optionNames") return part.optionNames.join(", ");
-			if (part.type === "metavar") return part.metavar;
-			if (part.type === "value") return part.value;
-			if (part.type === "values") return part.values.join(", ");
-			if (part.type === "envVar") return part.envVar;
-			if (part.type === "commandLine") return part.commandLine;
-			if (part.type === "url") return part.url;
-			return "";
-		});
-		throw new Error(`Parsing failed: ${errorParts.join("")}`);
-	}
-	let configData;
-	if ("load" in options) {
-		const customOptions = options;
-		try {
-			const rawData = await Promise.resolve(customOptions.load(firstPassResult.value));
-			const validation = context.schema["~standard"].validate(rawData);
-			let validationResult;
-			if (validation instanceof Promise) validationResult = await validation;
-			else validationResult = validation;
-			if (validationResult.issues) {
-				const firstIssue = validationResult.issues[0];
-				throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-			}
-			configData = validationResult.value;
-		} catch (error) {
-			if (error instanceof Error && error.message.includes("validation")) throw error;
-			throw error;
-		}
-	} else {
-		const singleFileOptions = options;
-		const configPath = singleFileOptions.getConfigPath(firstPassResult.value);
-		if (configPath) try {
-			const contents = await (0, node_fs_promises.readFile)(configPath);
-			let rawData;
-			if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
-			else {
-				const text = new TextDecoder().decode(contents);
-				rawData = JSON.parse(text);
-			}
-			const validation = context.schema["~standard"].validate(rawData);
-			let validationResult;
-			if (validation instanceof Promise) validationResult = await validation;
-			else validationResult = validation;
-			if (validationResult.issues) {
-				const firstIssue = validationResult.issues[0];
-				throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-			}
-			configData = validationResult.value;
-		} catch (error) {
-			if (error instanceof Error && error.message.includes("validation")) throw error;
-			configData = void 0;
-		}
-	}
-	const annotations = configData ? { [require_src.configKey]: configData } : {};
-	if (configData) require_src.setActiveConfig(context.id, configData);
+	const effectiveProgramName = options.programName ?? (typeof node_process.default !== "undefined" && node_process.default.argv?.[1] ? (0, node_path.basename)(node_process.default.argv[1]) : "cli");
+	const wrapperContext = createConfigSourceContext(context, options);
 	try {
-		const secondPass = (0, __optique_core_parser.parse)(parser, args, { annotations });
-		let secondPassResult;
-		if (secondPass instanceof Promise) secondPassResult = await secondPass;
-		else secondPassResult = secondPass;
-		if (!secondPassResult.success) throw new Error(`Parsing failed: ${String(secondPassResult.error)}`);
-		return secondPassResult.value;
+		return await (0, __optique_core_facade.runWith)(parser, effectiveProgramName, [wrapperContext], {
+			args: options.args ?? [],
+			help: options.help,
+			version: options.version,
+			completion: options.completion,
+			stdout: options.stdout,
+			stderr: options.stderr,
+			colors: options.colors,
+			maxWidth: options.maxWidth,
+			showDefault: options.showDefault,
+			aboveError: options.aboveError,
+			brief: options.brief,
+			description: options.description,
+			examples: options.examples,
+			author: options.author,
+			bugs: options.bugs,
+			footer: options.footer,
+			onError: options.onError
+		});
 	} finally {
 		require_src.clearActiveConfig(context.id);
 	}

package/dist/run.d.cts

@@ -1,5 +1,6 @@
 import { ConfigContext } from "./index-D25zYfjf.cjs";
 import { Parser } from "@optique/core/parser";
+import { RunOptions } from "@optique/core/facade";
 
 //#region src/run.d.ts
 
@@ -7,9 +8,11 @@ import { Parser } from "@optique/core/parser";
  * Options for single-file config loading.
  *
  * @template TValue The parser value type, inferred from the parser.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-interface SingleFileOptions<TValue> {
+interface SingleFileOptions<TValue, THelp = void, TError = never> {
   /**
    * Function to extract the config file path from parsed CLI arguments.
    * This function receives the result of the first parse pass and should
@@ -32,14 +35,85 @@ interface SingleFileOptions<TValue> {
    * If not provided, defaults to an empty array.
    */
   readonly args?: readonly string[];
+  /**
+   * Name of the program for help/error output.
+   * If not provided, inferred from process.argv[1].
+   */
+  readonly programName?: string;
+  /**
+   * Help configuration. See RunOptions for details.
+   */
+  readonly help?: RunOptions<THelp, TError>["help"];
+  /**
+   * Version configuration. See RunOptions for details.
+   */
+  readonly version?: RunOptions<THelp, TError>["version"];
+  /**
+   * Completion configuration. See RunOptions for details.
+   */
+  readonly completion?: RunOptions<THelp, TError>["completion"];
+  /**
+   * Output function for standard output. See RunOptions for details.
+   */
+  readonly stdout?: RunOptions<THelp, TError>["stdout"];
+  /**
+   * Output function for standard error. See RunOptions for details.
+   */
+  readonly stderr?: RunOptions<THelp, TError>["stderr"];
+  /**
+   * Whether to enable colored output. See RunOptions for details.
+   */
+  readonly colors?: RunOptions<THelp, TError>["colors"];
+  /**
+   * Maximum width for output formatting. See RunOptions for details.
+   */
+  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
+  /**
+   * Whether and how to display default values. See RunOptions for details.
+   */
+  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
+  /**
+   * What to display above error messages. See RunOptions for details.
+   */
+  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
+  /**
+   * Brief description for help text. See RunOptions for details.
+   */
+  readonly brief?: RunOptions<THelp, TError>["brief"];
+  /**
+   * Detailed description for help text. See RunOptions for details.
+   */
+  readonly description?: RunOptions<THelp, TError>["description"];
+  /**
+   * Usage examples for help text. See RunOptions for details.
+   */
+  readonly examples?: RunOptions<THelp, TError>["examples"];
+  /**
+   * Author information for help text. See RunOptions for details.
+   */
+  readonly author?: RunOptions<THelp, TError>["author"];
+  /**
+   * Bug reporting information for help text. See RunOptions for details.
+   */
+  readonly bugs?: RunOptions<THelp, TError>["bugs"];
+  /**
+   * Footer text for help. See RunOptions for details.
+   */
+  readonly footer?: RunOptions<THelp, TError>["footer"];
+  /**
+   * Error handler. See RunOptions for details.
+   */
+  readonly onError?: RunOptions<THelp, TError>["onError"];
 }
 /**
  * Options for custom config loading with multi-file merging support.
  *
  * @template TValue The parser value type, inferred from the parser.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-interface CustomLoadOptions<TValue> {
+interface CustomLoadOptions<TValue, THelp = void, TError = never> {
   /**
    * Custom loader function that receives the first-pass parse result and
    * returns the config data (or a Promise of it). This allows full control
@@ -56,14 +130,85 @@ interface CustomLoadOptions<TValue> {
    * If not provided, defaults to an empty array.
    */
   readonly args?: readonly string[];
+  /**
+   * Name of the program for help/error output.
+   * If not provided, inferred from process.argv[1].
+   */
+  readonly programName?: string;
+  /**
+   * Help configuration. See RunOptions for details.
+   */
+  readonly help?: RunOptions<THelp, TError>["help"];
+  /**
+   * Version configuration. See RunOptions for details.
+   */
+  readonly version?: RunOptions<THelp, TError>["version"];
+  /**
+   * Completion configuration. See RunOptions for details.
+   */
+  readonly completion?: RunOptions<THelp, TError>["completion"];
+  /**
+   * Output function for standard output. See RunOptions for details.
+   */
+  readonly stdout?: RunOptions<THelp, TError>["stdout"];
+  /**
+   * Output function for standard error. See RunOptions for details.
+   */
+  readonly stderr?: RunOptions<THelp, TError>["stderr"];
+  /**
+   * Whether to enable colored output. See RunOptions for details.
+   */
+  readonly colors?: RunOptions<THelp, TError>["colors"];
+  /**
+   * Maximum width for output formatting. See RunOptions for details.
+   */
+  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
+  /**
+   * Whether and how to display default values. See RunOptions for details.
+   */
+  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
+  /**
+   * What to display above error messages. See RunOptions for details.
+   */
+  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
+  /**
+   * Brief description for help text. See RunOptions for details.
+   */
+  readonly brief?: RunOptions<THelp, TError>["brief"];
+  /**
+   * Detailed description for help text. See RunOptions for details.
+   */
+  readonly description?: RunOptions<THelp, TError>["description"];
+  /**
+   * Usage examples for help text. See RunOptions for details.
+   */
+  readonly examples?: RunOptions<THelp, TError>["examples"];
+  /**
+   * Author information for help text. See RunOptions for details.
+   */
+  readonly author?: RunOptions<THelp, TError>["author"];
+  /**
+   * Bug reporting information for help text. See RunOptions for details.
+   */
+  readonly bugs?: RunOptions<THelp, TError>["bugs"];
+  /**
+   * Footer text for help. See RunOptions for details.
+   */
+  readonly footer?: RunOptions<THelp, TError>["footer"];
+  /**
+   * Error handler. See RunOptions for details.
+   */
+  readonly onError?: RunOptions<THelp, TError>["onError"];
 }
 /**
  * Options for runWithConfig.
  *
  * @template TValue The parser value type, inferred from the parser.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOptions<TValue>;
+type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, THelp, TError>;
 /**
  * Runs a parser with configuration file support using two-pass parsing.
  *
@@ -74,10 +219,16 @@ type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOption
  *
  * The priority order for values is: CLI > config file > default.
  *
+ * The function also supports help, version, and completion features. When these
+ * special commands are detected, config loading is skipped entirely, ensuring
+ * these features work even when config files don't exist.
+ *
  * @template M The parser mode (sync or async).
  * @template TValue The parser value type.
  * @template TState The parser state type.
  * @template T The config data type.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @param parser The parser to execute.
  * @param context The config context with schema.
  * @param options Run options - either SingleFileOptions or CustomLoadOptions.
@@ -110,6 +261,8 @@ type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOption
  * const result = await runWithConfig(parser, context, {
  *   getConfigPath: (parsed) => parsed.config,
  *   args: process.argv.slice(2),
+ *   help: { mode: "option", onShow: () => process.exit(0) },
+ *   version: { value: "1.0.0", onShow: () => process.exit(0) },
  * });
  * ```
  *
@@ -127,9 +280,10 @@ type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOption
  *     return deepMerge(...configs);
  *   },
  *   args: process.argv.slice(2),
+ *   help: { mode: "option", onShow: () => process.exit(0) },
  * });
  * ```
  */
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue>): Promise<TValue>;
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue, THelp, TError>): Promise<TValue>;
 //#endregion
 export { CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };

package/dist/run.d.ts

@@ -1,4 +1,5 @@
-import { ConfigContext } from "./index-D_lTcz4s.js";
+import { ConfigContext } from "./index-CYn_0yAG.js";
+import { RunOptions } from "@optique/core/facade";
 import { Parser } from "@optique/core/parser";
 
 //#region src/run.d.ts
@@ -7,9 +8,11 @@ import { Parser } from "@optique/core/parser";
  * Options for single-file config loading.
  *
  * @template TValue The parser value type, inferred from the parser.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-interface SingleFileOptions<TValue> {
+interface SingleFileOptions<TValue, THelp = void, TError = never> {
   /**
    * Function to extract the config file path from parsed CLI arguments.
    * This function receives the result of the first parse pass and should
@@ -32,14 +35,85 @@ interface SingleFileOptions<TValue> {
    * If not provided, defaults to an empty array.
    */
   readonly args?: readonly string[];
+  /**
+   * Name of the program for help/error output.
+   * If not provided, inferred from process.argv[1].
+   */
+  readonly programName?: string;
+  /**
+   * Help configuration. See RunOptions for details.
+   */
+  readonly help?: RunOptions<THelp, TError>["help"];
+  /**
+   * Version configuration. See RunOptions for details.
+   */
+  readonly version?: RunOptions<THelp, TError>["version"];
+  /**
+   * Completion configuration. See RunOptions for details.
+   */
+  readonly completion?: RunOptions<THelp, TError>["completion"];
+  /**
+   * Output function for standard output. See RunOptions for details.
+   */
+  readonly stdout?: RunOptions<THelp, TError>["stdout"];
+  /**
+   * Output function for standard error. See RunOptions for details.
+   */
+  readonly stderr?: RunOptions<THelp, TError>["stderr"];
+  /**
+   * Whether to enable colored output. See RunOptions for details.
+   */
+  readonly colors?: RunOptions<THelp, TError>["colors"];
+  /**
+   * Maximum width for output formatting. See RunOptions for details.
+   */
+  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
+  /**
+   * Whether and how to display default values. See RunOptions for details.
+   */
+  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
+  /**
+   * What to display above error messages. See RunOptions for details.
+   */
+  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
+  /**
+   * Brief description for help text. See RunOptions for details.
+   */
+  readonly brief?: RunOptions<THelp, TError>["brief"];
+  /**
+   * Detailed description for help text. See RunOptions for details.
+   */
+  readonly description?: RunOptions<THelp, TError>["description"];
+  /**
+   * Usage examples for help text. See RunOptions for details.
+   */
+  readonly examples?: RunOptions<THelp, TError>["examples"];
+  /**
+   * Author information for help text. See RunOptions for details.
+   */
+  readonly author?: RunOptions<THelp, TError>["author"];
+  /**
+   * Bug reporting information for help text. See RunOptions for details.
+   */
+  readonly bugs?: RunOptions<THelp, TError>["bugs"];
+  /**
+   * Footer text for help. See RunOptions for details.
+   */
+  readonly footer?: RunOptions<THelp, TError>["footer"];
+  /**
+   * Error handler. See RunOptions for details.
+   */
+  readonly onError?: RunOptions<THelp, TError>["onError"];
 }
 /**
  * Options for custom config loading with multi-file merging support.
  *
  * @template TValue The parser value type, inferred from the parser.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-interface CustomLoadOptions<TValue> {
+interface CustomLoadOptions<TValue, THelp = void, TError = never> {
   /**
    * Custom loader function that receives the first-pass parse result and
    * returns the config data (or a Promise of it). This allows full control
@@ -56,14 +130,85 @@ interface CustomLoadOptions<TValue> {
    * If not provided, defaults to an empty array.
    */
   readonly args?: readonly string[];
+  /**
+   * Name of the program for help/error output.
+   * If not provided, inferred from process.argv[1].
+   */
+  readonly programName?: string;
+  /**
+   * Help configuration. See RunOptions for details.
+   */
+  readonly help?: RunOptions<THelp, TError>["help"];
+  /**
+   * Version configuration. See RunOptions for details.
+   */
+  readonly version?: RunOptions<THelp, TError>["version"];
+  /**
+   * Completion configuration. See RunOptions for details.
+   */
+  readonly completion?: RunOptions<THelp, TError>["completion"];
+  /**
+   * Output function for standard output. See RunOptions for details.
+   */
+  readonly stdout?: RunOptions<THelp, TError>["stdout"];
+  /**
+   * Output function for standard error. See RunOptions for details.
+   */
+  readonly stderr?: RunOptions<THelp, TError>["stderr"];
+  /**
+   * Whether to enable colored output. See RunOptions for details.
+   */
+  readonly colors?: RunOptions<THelp, TError>["colors"];
+  /**
+   * Maximum width for output formatting. See RunOptions for details.
+   */
+  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
+  /**
+   * Whether and how to display default values. See RunOptions for details.
+   */
+  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
+  /**
+   * What to display above error messages. See RunOptions for details.
+   */
+  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
+  /**
+   * Brief description for help text. See RunOptions for details.
+   */
+  readonly brief?: RunOptions<THelp, TError>["brief"];
+  /**
+   * Detailed description for help text. See RunOptions for details.
+   */
+  readonly description?: RunOptions<THelp, TError>["description"];
+  /**
+   * Usage examples for help text. See RunOptions for details.
+   */
+  readonly examples?: RunOptions<THelp, TError>["examples"];
+  /**
+   * Author information for help text. See RunOptions for details.
+   */
+  readonly author?: RunOptions<THelp, TError>["author"];
+  /**
+   * Bug reporting information for help text. See RunOptions for details.
+   */
+  readonly bugs?: RunOptions<THelp, TError>["bugs"];
+  /**
+   * Footer text for help. See RunOptions for details.
+   */
+  readonly footer?: RunOptions<THelp, TError>["footer"];
+  /**
+   * Error handler. See RunOptions for details.
+   */
+  readonly onError?: RunOptions<THelp, TError>["onError"];
 }
 /**
  * Options for runWithConfig.
  *
  * @template TValue The parser value type, inferred from the parser.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOptions<TValue>;
+type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, THelp, TError>;
 /**
  * Runs a parser with configuration file support using two-pass parsing.
  *
@@ -74,10 +219,16 @@ type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOption
  *
  * The priority order for values is: CLI > config file > default.
  *
+ * The function also supports help, version, and completion features. When these
+ * special commands are detected, config loading is skipped entirely, ensuring
+ * these features work even when config files don't exist.
+ *
  * @template M The parser mode (sync or async).
  * @template TValue The parser value type.
  * @template TState The parser state type.
  * @template T The config data type.
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
  * @param parser The parser to execute.
  * @param context The config context with schema.
  * @param options Run options - either SingleFileOptions or CustomLoadOptions.
@@ -110,6 +261,8 @@ type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOption
  * const result = await runWithConfig(parser, context, {
  *   getConfigPath: (parsed) => parsed.config,
  *   args: process.argv.slice(2),
+ *   help: { mode: "option", onShow: () => process.exit(0) },
+ *   version: { value: "1.0.0", onShow: () => process.exit(0) },
  * });
  * ```
  *
@@ -127,9 +280,10 @@ type RunWithConfigOptions<TValue> = SingleFileOptions<TValue> | CustomLoadOption
  *     return deepMerge(...configs);
  *   },
  *   args: process.argv.slice(2),
+ *   help: { mode: "option", onShow: () => process.exit(0) },
  * });
  * ```
  */
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue>): Promise<TValue>;
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue, THelp, TError>): Promise<TValue>;
 //#endregion
 export { CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };

package/dist/run.js

@@ -1,9 +1,71 @@
-import { clearActiveConfig, configKey, setActiveConfig } from "./src-C9h3sfAM.js";
+import { clearActiveConfig, configKey, setActiveConfig } from "./src-CLJCVbow.js";
 import { readFile } from "node:fs/promises";
-import { parse } from "@optique/core/parser";
+import { basename } from "node:path";
+import process from "node:process";
+import { runWith } from "@optique/core/facade";
 
 //#region src/run.ts
 /**
+* Helper function to create a wrapper SourceContext for config loading.
+* @internal
+*/
+function createConfigSourceContext(context, options) {
+	return {
+		id: context.id,
+		async getAnnotations(parsed) {
+			if (!parsed) return {};
+			let configData;
+			if ("load" in options) {
+				const customOptions = options;
+				try {
+					const rawData = await Promise.resolve(customOptions.load(parsed));
+					const validation = context.schema["~standard"].validate(rawData);
+					let validationResult;
+					if (validation instanceof Promise) validationResult = await validation;
+					else validationResult = validation;
+					if (validationResult.issues) {
+						const firstIssue = validationResult.issues[0];
+						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+					}
+					configData = validationResult.value;
+				} catch (error) {
+					if (error instanceof Error && error.message.includes("validation")) throw error;
+					throw error;
+				}
+			} else {
+				const singleFileOptions = options;
+				const configPath = singleFileOptions.getConfigPath(parsed);
+				if (configPath) try {
+					const contents = await readFile(configPath);
+					let rawData;
+					if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
+					else {
+						const text = new TextDecoder().decode(contents);
+						rawData = JSON.parse(text);
+					}
+					const validation = context.schema["~standard"].validate(rawData);
+					let validationResult;
+					if (validation instanceof Promise) validationResult = await validation;
+					else validationResult = validation;
+					if (validationResult.issues) {
+						const firstIssue = validationResult.issues[0];
+						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+					}
+					configData = validationResult.value;
+				} catch (error) {
+					if (error instanceof Error && error.message.includes("validation")) throw error;
+					configData = void 0;
+				}
+			}
+			if (configData) {
+				setActiveConfig(context.id, configData);
+				return { [configKey]: configData };
+			}
+			return {};
+		}
+	};
+}
+/**
 * Runs a parser with configuration file support using two-pass parsing.
 *
 * This function performs the following steps:
@@ -13,10 +75,16 @@ import { parse } from "@optique/core/parser";
 *
 * The priority order for values is: CLI > config file > default.
 *
+* The function also supports help, version, and completion features. When these
+* special commands are detected, config loading is skipped entirely, ensuring
+* these features work even when config files don't exist.
+*
 * @template M The parser mode (sync or async).
 * @template TValue The parser value type.
 * @template TState The parser state type.
 * @template T The config data type.
+* @template THelp The return type when help is shown.
+* @template TError The return type when an error occurs.
 * @param parser The parser to execute.
 * @param context The config context with schema.
 * @param options Run options - either SingleFileOptions or CustomLoadOptions.
@@ -49,6 +117,8 @@ import { parse } from "@optique/core/parser";
 * const result = await runWithConfig(parser, context, {
 *   getConfigPath: (parsed) => parsed.config,
 *   args: process.argv.slice(2),
+*   help: { mode: "option", onShow: () => process.exit(0) },
+*   version: { value: "1.0.0", onShow: () => process.exit(0) },
 * });
 * ```
 *
@@ -66,82 +136,33 @@ import { parse } from "@optique/core/parser";
 *     return deepMerge(...configs);
 *   },
 *   args: process.argv.slice(2),
+*   help: { mode: "option", onShow: () => process.exit(0) },
 * });
 * ```
 */
 async function runWithConfig(parser, context, options) {
-	const args = options.args ?? [];
-	const firstPass = parse(parser, args);
-	let firstPassResult;
-	if (firstPass instanceof Promise) firstPassResult = await firstPass;
-	else firstPassResult = firstPass;
-	if (!firstPassResult.success) {
-		const errorParts = firstPassResult.error.map((part) => {
-			if (part.type === "text") return part.text;
-			if (part.type === "optionName") return part.optionName;
-			if (part.type === "optionNames") return part.optionNames.join(", ");
-			if (part.type === "metavar") return part.metavar;
-			if (part.type === "value") return part.value;
-			if (part.type === "values") return part.values.join(", ");
-			if (part.type === "envVar") return part.envVar;
-			if (part.type === "commandLine") return part.commandLine;
-			if (part.type === "url") return part.url;
-			return "";
-		});
-		throw new Error(`Parsing failed: ${errorParts.join("")}`);
-	}
-	let configData;
-	if ("load" in options) {
-		const customOptions = options;
-		try {
-			const rawData = await Promise.resolve(customOptions.load(firstPassResult.value));
-			const validation = context.schema["~standard"].validate(rawData);
-			let validationResult;
-			if (validation instanceof Promise) validationResult = await validation;
-			else validationResult = validation;
-			if (validationResult.issues) {
-				const firstIssue = validationResult.issues[0];
-				throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-			}
-			configData = validationResult.value;
-		} catch (error) {
-			if (error instanceof Error && error.message.includes("validation")) throw error;
-			throw error;
-		}
-	} else {
-		const singleFileOptions = options;
-		const configPath = singleFileOptions.getConfigPath(firstPassResult.value);
-		if (configPath) try {
-			const contents = await readFile(configPath);
-			let rawData;
-			if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
-			else {
-				const text = new TextDecoder().decode(contents);
-				rawData = JSON.parse(text);
-			}
-			const validation = context.schema["~standard"].validate(rawData);
-			let validationResult;
-			if (validation instanceof Promise) validationResult = await validation;
-			else validationResult = validation;
-			if (validationResult.issues) {
-				const firstIssue = validationResult.issues[0];
-				throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-			}
-			configData = validationResult.value;
-		} catch (error) {
-			if (error instanceof Error && error.message.includes("validation")) throw error;
-			configData = void 0;
-		}
-	}
-	const annotations = configData ? { [configKey]: configData } : {};
-	if (configData) setActiveConfig(context.id, configData);
+	const effectiveProgramName = options.programName ?? (typeof process !== "undefined" && process.argv?.[1] ? basename(process.argv[1]) : "cli");
+	const wrapperContext = createConfigSourceContext(context, options);
 	try {
-		const secondPass = parse(parser, args, { annotations });
-		let secondPassResult;
-		if (secondPass instanceof Promise) secondPassResult = await secondPass;
-		else secondPassResult = secondPass;
-		if (!secondPassResult.success) throw new Error(`Parsing failed: ${String(secondPassResult.error)}`);
-		return secondPassResult.value;
+		return await runWith(parser, effectiveProgramName, [wrapperContext], {
+			args: options.args ?? [],
+			help: options.help,
+			version: options.version,
+			completion: options.completion,
+			stdout: options.stdout,
+			stderr: options.stderr,
+			colors: options.colors,
+			maxWidth: options.maxWidth,
+			showDefault: options.showDefault,
+			aboveError: options.aboveError,
+			brief: options.brief,
+			description: options.description,
+			examples: options.examples,
+			author: options.author,
+			bugs: options.bugs,
+			footer: options.footer,
+			onError: options.onError
+		});
 	} finally {
 		clearActiveConfig(context.id);
 	}

package/dist/{src-CTH1AjFs.cjs → src-8nvtohSm.cjs}

@@ -83,8 +83,9 @@ function clearActiveConfig(contextId) {
 * ```
 */
 function createConfigContext(options) {
+	const contextId = Symbol.for(`@optique/config:${Math.random()}`);
 	return {
-		id: configKey,
+		id: contextId,
 		schema: options.schema,
 		getAnnotations(parsed) {
 			if (!parsed) return {};

package/dist/{src-C9h3sfAM.js → src-CLJCVbow.js}

@@ -60,8 +60,9 @@ function clearActiveConfig(contextId) {
 * ```
 */
 function createConfigContext(options) {
+	const contextId = Symbol.for(`@optique/config:${Math.random()}`);
 	return {
-		id: configKey,
+		id: contextId,
 		schema: options.schema,
 		getAnnotations(parsed) {
 			if (!parsed) return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "0.10.0-dev.343+2ef903e6",
+  "version": "0.10.0-dev.345+f0eac28c",
   "description": "Configuration file support for Optique with Standard Schema validation",
   "keywords": [
     "CLI",