@optique/run 0.1.0-dev.2 → 0.1.0-dev.27

package/README.md

@@ -2,30 +2,25 @@
 ============
 
 > [!CAUTION]
-> Optique is currently in early development for proof of concept purposes,
-> and is not yet ready for production use.  The API is subject to change,
-> and there may be bugs or missing features.
+> Optique is currently in early development and may change significantly.
+> Expect breaking changes as we refine the API and features.
 
-*Process-integrated CLI parser for Node.js, Bun, and Deno.*
-
-*@optique/run* provides a convenient high-level interface for *@optique/core*
-that automatically handles `process.argv`, `process.exit()`, and terminal
-capabilities.  It eliminates the manual setup required by the core library,
-making it perfect for building CLI applications in server-side JavaScript
-runtimes.
+Process-integrated CLI parser for Node.js, Bun, and Deno that provides a
+batteries-included interface for *@optique/core* with automatic `process.argv`
+handling, `process.exit()`, and terminal capabilities.
 
 
 When to use @optique/run
 ------------------------
 
-Use `@optique/run` when:
+Use *@optique/run* when:
 
  -  Building CLI applications for Node.js, Bun, or Deno
  -  You want automatic `process.argv` parsing and `process.exit()` handling
  -  You need automatic terminal capability detection (colors, width)
  -  You prefer a simple, batteries-included approach
 
-Use `@optique/core` instead when:
+Use *@optique/core* instead when:
 
  -  Building web applications or libraries
  -  You need full control over argument sources and error handling
@@ -62,12 +57,8 @@ const parser = object({
 const config = run(parser);
 
 console.log(`Hello ${config.name}!`);
-if (config.age) {
-  console.log(`You are ${config.age} years old.`);
-}
-if (config.verbose) {
-  console.log("Verbose mode enabled.");
-}
+if (config.age) console.log(`You are ${config.age} years old.`);
+if (config.verbose) console.log("Verbose mode enabled.");
 ~~~~
 
 Run it:
@@ -79,56 +70,6 @@ You are 25 years old.
 Verbose mode enabled.
 ~~~~
 
+For more resources, see the [docs] and the [*examples/*](/examples/) directory.
 
-API differences from @optique/core
-----------------------------------
-
-| Feature            | @optique/core                           | @optique/run                     |
-|--------------------|-----------------------------------------|----------------------------------|
-| Argument source    | Manual (`run(parser, "program", args)`) | Automatic (`process.argv`)       |
-| Error handling     | Return value or callback                | Automatic `process.exit()`       |
-| Help display       | Manual implementation                   | Automatic help option/command    |
-| Terminal detection | Manual specification                    | Automatic TTY/width detection    |
-| Program name       | Manual parameter                        | Automatic from `process.argv[1]` |
-
-
-Configuration options
----------------------
-
-~~~~ typescript
-const result = run(parser, {
-  programName: "my-cli",           // Override detected program name
-  args: ["custom", "args"],        // Override process.argv
-  colors: true,                    // Force colored output
-  maxWidth: 100,                   // Set output width
-  help: "both",                    // Enable --help and help command
-  aboveError: "usage",             // Show usage on errors
-  errorExitCode: 1,                // Exit code for errors
-});
-~~~~
-
-
-Help system
------------
-
-Enable built-in help functionality:
-
-~~~~ typescript
-const result = run(parser, {
-  help: "option",    // Adds --help option
-  help: "command",   // Adds help subcommand
-  help: "both",      // Adds both --help and help command
-  help: "none",      // No help (default)
-});
-~~~~
-
-
-Error handling
---------------
-
-The `run()` function automatically:
-
- -  Prints usage information and error messages to stderr
- -  Exits with code `0` for help requests
- -  Exits with code `1` (or custom) for parse errors
- -  Never returns on errors (always calls `process.exit()`)
+[docs]: https://optique.dev/

package/dist/index.cjs

@@ -1,71 +1,5 @@
-const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
-const __optique_core_facade = require_rolldown_runtime.__toESM(require("@optique/core/facade"));
-const node_path = require_rolldown_runtime.__toESM(require("node:path"));
-const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+const require_run = require('./run.cjs');
+const require_valueparser = require('./valueparser.cjs');
 
-//#region src/index.ts
-/**
-* Runs a command-line parser with automatic process integration.
-*
-* This function provides a convenient high-level interface for parsing
-* command-line arguments in Node.js, Bun, and Deno environments. It
-* automatically handles `process.argv`, `process.exit()`, and terminal
-* output formatting, eliminating the need to manually pass these values
-* as the lower-level `run()` function (from `@optique/core/facade`) requires.
-*
-* The function will automatically:
-*
-* - Extract arguments from `process.argv`
-* - Detect terminal capabilities for colors and width
-* - Exit the process with appropriate codes on help or error
-* - Format output according to terminal capabilities
-*
-* @template T The parser type being executed.
-* @param parser The command-line parser to execute.
-* @param options Configuration options for customizing behavior.
-*                See {@link RunOptions} for available settings.
-* @returns The parsed result if successful. On help display or parse errors,
-*          the function will call `process.exit()` and not return.
-*
-* @example
-* ```typescript
-* import { object, option, run } from "@optique/run";
-* import { string, integer } from "@optique/core/valueparser";
-*
-* const parser = object({
-*   name: option("-n", "--name", string()),
-*   port: option("-p", "--port", integer()),
-* });
-*
-* // Automatically uses process.argv, handles errors/help, exits on completion
-* const config = run(parser);
-* console.log(`Starting server ${config.name} on port ${config.port}`);
-* ```
-*
-* @example
-* ```typescript
-* // With custom options
-* const result = run(parser, {
-*   programName: "myapp",
-*   help: "both",           // Enable both --help option and help command
-*   colors: true,           // Force colored output
-*   errorExitCode: 2,       // Exit with code 2 on errors
-* });
-* ```
-*/
-function run(parser, options = {}) {
-	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, help = "none", aboveError = "usage", errorExitCode = 1 } = options;
-	return (0, __optique_core_facade.run)(parser, programName, args, {
-		colors,
-		maxWidth,
-		help,
-		aboveError,
-		onHelp: node_process.default.exit,
-		onError() {
-			return node_process.default.exit(errorExitCode);
-		}
-	});
-}
-
-//#endregion
-exports.run = run;
+exports.path = require_valueparser.path;
+exports.run = require_run.run;

package/dist/index.d.cts

@@ -1,113 +1,3 @@
-import { InferValue, Parser } from "@optique/core/parser";
-
-//#region src/index.d.ts
-
-/**
- * Configuration options for the {@link run} function.
- */
-interface RunOptions {
-  /**
-   * The name of the program to display in usage and help messages.
-   *
-   * @default The basename of `process.argv[1]` (the script filename)
-   */
-  readonly programName?: string;
-  /**
-   * The command-line arguments to parse.
-   *
-   * @default `process.argv.slice(2)` (arguments after the script name)
-   */
-  readonly args?: readonly string[];
-  /**
-   * Whether to enable colored output in help and error messages.
-   *
-   * @default `process.stdout.isTTY` (auto-detect based on terminal)
-   */
-  readonly colors?: boolean;
-  /**
-   * Maximum width for output formatting. Text will be wrapped to fit within
-   * this width. If not specified, uses the terminal width.
-   *
-   * @default `process.stdout.columns` (auto-detect terminal width)
-   */
-  readonly maxWidth?: number;
-  /**
-   * Determines how help functionality is made available:
-   *
-   * - `"command"`: Only the `help` subcommand is available
-   * - `"option"`: Only the `--help` option is available
-   * - `"both"`: Both `help` subcommand and `--help` option are available
-   * - `"none"`: No help functionality is provided
-   *
-   * @default `"none"`
-   */
-  readonly help?: "command" | "option" | "both" | "none";
-  /**
-   * What to display above error messages:
-   *
-   * - `"usage"`: Show usage line before error message
-   * - `"help"`: Show full help page before error message
-   * - `"none"`: Show only the error message
-   *
-   * @default `"usage"`
-   */
-  readonly aboveError?: "usage" | "help" | "none";
-  /**
-   * The exit code to use when the parser encounters an error.
-   *
-   * @default `1`
-   */
-  readonly errorExitCode?: number;
-}
-/**
- * Runs a command-line parser with automatic process integration.
- *
- * This function provides a convenient high-level interface for parsing
- * command-line arguments in Node.js, Bun, and Deno environments. It
- * automatically handles `process.argv`, `process.exit()`, and terminal
- * output formatting, eliminating the need to manually pass these values
- * as the lower-level `run()` function (from `@optique/core/facade`) requires.
- *
- * The function will automatically:
- *
- * - Extract arguments from `process.argv`
- * - Detect terminal capabilities for colors and width
- * - Exit the process with appropriate codes on help or error
- * - Format output according to terminal capabilities
- *
- * @template T The parser type being executed.
- * @param parser The command-line parser to execute.
- * @param options Configuration options for customizing behavior.
- *                See {@link RunOptions} for available settings.
- * @returns The parsed result if successful. On help display or parse errors,
- *          the function will call `process.exit()` and not return.
- *
- * @example
- * ```typescript
- * import { object, option, run } from "@optique/run";
- * import { string, integer } from "@optique/core/valueparser";
- *
- * const parser = object({
- *   name: option("-n", "--name", string()),
- *   port: option("-p", "--port", integer()),
- * });
- *
- * // Automatically uses process.argv, handles errors/help, exits on completion
- * const config = run(parser);
- * console.log(`Starting server ${config.name} on port ${config.port}`);
- * ```
- *
- * @example
- * ```typescript
- * // With custom options
- * const result = run(parser, {
- *   programName: "myapp",
- *   help: "both",           // Enable both --help option and help command
- *   colors: true,           // Force colored output
- *   errorExitCode: 2,       // Exit with code 2 on errors
- * });
- * ```
- */
-declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
-//#endregion
-export { RunOptions, run };
+import { RunOptions, run } from "./run.cjs";
+import { PathOptions, path } from "./valueparser.cjs";
+export { PathOptions, RunOptions, path, run };

package/dist/index.d.ts

@@ -1,113 +1,3 @@
-import { InferValue, Parser } from "@optique/core/parser";
-
-//#region src/index.d.ts
-
-/**
- * Configuration options for the {@link run} function.
- */
-interface RunOptions {
-  /**
-   * The name of the program to display in usage and help messages.
-   *
-   * @default The basename of `process.argv[1]` (the script filename)
-   */
-  readonly programName?: string;
-  /**
-   * The command-line arguments to parse.
-   *
-   * @default `process.argv.slice(2)` (arguments after the script name)
-   */
-  readonly args?: readonly string[];
-  /**
-   * Whether to enable colored output in help and error messages.
-   *
-   * @default `process.stdout.isTTY` (auto-detect based on terminal)
-   */
-  readonly colors?: boolean;
-  /**
-   * Maximum width for output formatting. Text will be wrapped to fit within
-   * this width. If not specified, uses the terminal width.
-   *
-   * @default `process.stdout.columns` (auto-detect terminal width)
-   */
-  readonly maxWidth?: number;
-  /**
-   * Determines how help functionality is made available:
-   *
-   * - `"command"`: Only the `help` subcommand is available
-   * - `"option"`: Only the `--help` option is available
-   * - `"both"`: Both `help` subcommand and `--help` option are available
-   * - `"none"`: No help functionality is provided
-   *
-   * @default `"none"`
-   */
-  readonly help?: "command" | "option" | "both" | "none";
-  /**
-   * What to display above error messages:
-   *
-   * - `"usage"`: Show usage line before error message
-   * - `"help"`: Show full help page before error message
-   * - `"none"`: Show only the error message
-   *
-   * @default `"usage"`
-   */
-  readonly aboveError?: "usage" | "help" | "none";
-  /**
-   * The exit code to use when the parser encounters an error.
-   *
-   * @default `1`
-   */
-  readonly errorExitCode?: number;
-}
-/**
- * Runs a command-line parser with automatic process integration.
- *
- * This function provides a convenient high-level interface for parsing
- * command-line arguments in Node.js, Bun, and Deno environments. It
- * automatically handles `process.argv`, `process.exit()`, and terminal
- * output formatting, eliminating the need to manually pass these values
- * as the lower-level `run()` function (from `@optique/core/facade`) requires.
- *
- * The function will automatically:
- *
- * - Extract arguments from `process.argv`
- * - Detect terminal capabilities for colors and width
- * - Exit the process with appropriate codes on help or error
- * - Format output according to terminal capabilities
- *
- * @template T The parser type being executed.
- * @param parser The command-line parser to execute.
- * @param options Configuration options for customizing behavior.
- *                See {@link RunOptions} for available settings.
- * @returns The parsed result if successful. On help display or parse errors,
- *          the function will call `process.exit()` and not return.
- *
- * @example
- * ```typescript
- * import { object, option, run } from "@optique/run";
- * import { string, integer } from "@optique/core/valueparser";
- *
- * const parser = object({
- *   name: option("-n", "--name", string()),
- *   port: option("-p", "--port", integer()),
- * });
- *
- * // Automatically uses process.argv, handles errors/help, exits on completion
- * const config = run(parser);
- * console.log(`Starting server ${config.name} on port ${config.port}`);
- * ```
- *
- * @example
- * ```typescript
- * // With custom options
- * const result = run(parser, {
- *   programName: "myapp",
- *   help: "both",           // Enable both --help option and help command
- *   colors: true,           // Force colored output
- *   errorExitCode: 2,       // Exit with code 2 on errors
- * });
- * ```
- */
-declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
-//#endregion
-export { RunOptions, run };
+import { RunOptions, run } from "./run.js";
+import { PathOptions, path } from "./valueparser.js";
+export { PathOptions, RunOptions, path, run };

package/dist/index.js

@@ -1,70 +1,4 @@
-import { run as run$1 } from "@optique/core/facade";
-import path from "node:path";
-import process from "node:process";
+import { run } from "./run.js";
+import { path } from "./valueparser.js";
 
-//#region src/index.ts
-/**
-* Runs a command-line parser with automatic process integration.
-*
-* This function provides a convenient high-level interface for parsing
-* command-line arguments in Node.js, Bun, and Deno environments. It
-* automatically handles `process.argv`, `process.exit()`, and terminal
-* output formatting, eliminating the need to manually pass these values
-* as the lower-level `run()` function (from `@optique/core/facade`) requires.
-*
-* The function will automatically:
-*
-* - Extract arguments from `process.argv`
-* - Detect terminal capabilities for colors and width
-* - Exit the process with appropriate codes on help or error
-* - Format output according to terminal capabilities
-*
-* @template T The parser type being executed.
-* @param parser The command-line parser to execute.
-* @param options Configuration options for customizing behavior.
-*                See {@link RunOptions} for available settings.
-* @returns The parsed result if successful. On help display or parse errors,
-*          the function will call `process.exit()` and not return.
-*
-* @example
-* ```typescript
-* import { object, option, run } from "@optique/run";
-* import { string, integer } from "@optique/core/valueparser";
-*
-* const parser = object({
-*   name: option("-n", "--name", string()),
-*   port: option("-p", "--port", integer()),
-* });
-*
-* // Automatically uses process.argv, handles errors/help, exits on completion
-* const config = run(parser);
-* console.log(`Starting server ${config.name} on port ${config.port}`);
-* ```
-*
-* @example
-* ```typescript
-* // With custom options
-* const result = run(parser, {
-*   programName: "myapp",
-*   help: "both",           // Enable both --help option and help command
-*   colors: true,           // Force colored output
-*   errorExitCode: 2,       // Exit with code 2 on errors
-* });
-* ```
-*/
-function run(parser, options = {}) {
-	const { programName = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, help = "none", aboveError = "usage", errorExitCode = 1 } = options;
-	return run$1(parser, programName, args, {
-		colors,
-		maxWidth,
-		help,
-		aboveError,
-		onHelp: process.exit,
-		onError() {
-			return process.exit(errorExitCode);
-		}
-	});
-}
-
-//#endregion
-export { run };
+export { path, run };

package/dist/run.cjs

@@ -0,0 +1,71 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __optique_core_facade = require_rolldown_runtime.__toESM(require("@optique/core/facade"));
+const node_path = require_rolldown_runtime.__toESM(require("node:path"));
+const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+
+//#region src/run.ts
+/**
+* Runs a command-line parser with automatic process integration.
+*
+* This function provides a convenient high-level interface for parsing
+* command-line arguments in Node.js, Bun, and Deno environments. It
+* automatically handles `process.argv`, `process.exit()`, and terminal
+* output formatting, eliminating the need to manually pass these values
+* as the lower-level `run()` function (from `@optique/core/facade`) requires.
+*
+* The function will automatically:
+*
+* - Extract arguments from `process.argv`
+* - Detect terminal capabilities for colors and width
+* - Exit the process with appropriate codes on help or error
+* - Format output according to terminal capabilities
+*
+* @template T The parser type being executed.
+* @param parser The command-line parser to execute.
+* @param options Configuration options for customizing behavior.
+*                See {@link RunOptions} for available settings.
+* @returns The parsed result if successful. On help display or parse errors,
+*          the function will call `process.exit()` and not return.
+*
+* @example
+* ```typescript
+* import { object, option, run } from "@optique/run";
+* import { string, integer } from "@optique/core/valueparser";
+*
+* const parser = object({
+*   name: option("-n", "--name", string()),
+*   port: option("-p", "--port", integer()),
+* });
+*
+* // Automatically uses process.argv, handles errors/help, exits on completion
+* const config = run(parser);
+* console.log(`Starting server ${config.name} on port ${config.port}`);
+* ```
+*
+* @example
+* ```typescript
+* // With custom options
+* const result = run(parser, {
+*   programName: "myapp",
+*   help: "both",           // Enable both --help option and help command
+*   colors: true,           // Force colored output
+*   errorExitCode: 2,       // Exit with code 2 on errors
+* });
+* ```
+*/
+function run(parser, options = {}) {
+	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, help = "none", aboveError = "usage", errorExitCode = 1 } = options;
+	return (0, __optique_core_facade.run)(parser, programName, args, {
+		colors,
+		maxWidth,
+		help,
+		aboveError,
+		onHelp: node_process.default.exit,
+		onError() {
+			return node_process.default.exit(errorExitCode);
+		}
+	});
+}
+
+//#endregion
+exports.run = run;

package/dist/run.d.cts

@@ -0,0 +1,113 @@
+import { InferValue, Parser } from "@optique/core/parser";
+
+//#region src/run.d.ts
+
+/**
+ * Configuration options for the {@link run} function.
+ */
+interface RunOptions {
+  /**
+   * The name of the program to display in usage and help messages.
+   *
+   * @default The basename of `process.argv[1]` (the script filename)
+   */
+  readonly programName?: string;
+  /**
+   * The command-line arguments to parse.
+   *
+   * @default `process.argv.slice(2)` (arguments after the script name)
+   */
+  readonly args?: readonly string[];
+  /**
+   * Whether to enable colored output in help and error messages.
+   *
+   * @default `process.stdout.isTTY` (auto-detect based on terminal)
+   */
+  readonly colors?: boolean;
+  /**
+   * Maximum width for output formatting. Text will be wrapped to fit within
+   * this width. If not specified, uses the terminal width.
+   *
+   * @default `process.stdout.columns` (auto-detect terminal width)
+   */
+  readonly maxWidth?: number;
+  /**
+   * Determines how help functionality is made available:
+   *
+   * - `"command"`: Only the `help` subcommand is available
+   * - `"option"`: Only the `--help` option is available
+   * - `"both"`: Both `help` subcommand and `--help` option are available
+   * - `"none"`: No help functionality is provided
+   *
+   * @default `"none"`
+   */
+  readonly help?: "command" | "option" | "both" | "none";
+  /**
+   * What to display above error messages:
+   *
+   * - `"usage"`: Show usage line before error message
+   * - `"help"`: Show full help page before error message
+   * - `"none"`: Show only the error message
+   *
+   * @default `"usage"`
+   */
+  readonly aboveError?: "usage" | "help" | "none";
+  /**
+   * The exit code to use when the parser encounters an error.
+   *
+   * @default `1`
+   */
+  readonly errorExitCode?: number;
+}
+/**
+ * Runs a command-line parser with automatic process integration.
+ *
+ * This function provides a convenient high-level interface for parsing
+ * command-line arguments in Node.js, Bun, and Deno environments. It
+ * automatically handles `process.argv`, `process.exit()`, and terminal
+ * output formatting, eliminating the need to manually pass these values
+ * as the lower-level `run()` function (from `@optique/core/facade`) requires.
+ *
+ * The function will automatically:
+ *
+ * - Extract arguments from `process.argv`
+ * - Detect terminal capabilities for colors and width
+ * - Exit the process with appropriate codes on help or error
+ * - Format output according to terminal capabilities
+ *
+ * @template T The parser type being executed.
+ * @param parser The command-line parser to execute.
+ * @param options Configuration options for customizing behavior.
+ *                See {@link RunOptions} for available settings.
+ * @returns The parsed result if successful. On help display or parse errors,
+ *          the function will call `process.exit()` and not return.
+ *
+ * @example
+ * ```typescript
+ * import { object, option, run } from "@optique/run";
+ * import { string, integer } from "@optique/core/valueparser";
+ *
+ * const parser = object({
+ *   name: option("-n", "--name", string()),
+ *   port: option("-p", "--port", integer()),
+ * });
+ *
+ * // Automatically uses process.argv, handles errors/help, exits on completion
+ * const config = run(parser);
+ * console.log(`Starting server ${config.name} on port ${config.port}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const result = run(parser, {
+ *   programName: "myapp",
+ *   help: "both",           // Enable both --help option and help command
+ *   colors: true,           // Force colored output
+ *   errorExitCode: 2,       // Exit with code 2 on errors
+ * });
+ * ```
+ */
+declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+//#endregion
+export { RunOptions, run };

package/dist/run.d.ts

@@ -0,0 +1,113 @@
+import { InferValue, Parser } from "@optique/core/parser";
+
+//#region src/run.d.ts
+
+/**
+ * Configuration options for the {@link run} function.
+ */
+interface RunOptions {
+  /**
+   * The name of the program to display in usage and help messages.
+   *
+   * @default The basename of `process.argv[1]` (the script filename)
+   */
+  readonly programName?: string;
+  /**
+   * The command-line arguments to parse.
+   *
+   * @default `process.argv.slice(2)` (arguments after the script name)
+   */
+  readonly args?: readonly string[];
+  /**
+   * Whether to enable colored output in help and error messages.
+   *
+   * @default `process.stdout.isTTY` (auto-detect based on terminal)
+   */
+  readonly colors?: boolean;
+  /**
+   * Maximum width for output formatting. Text will be wrapped to fit within
+   * this width. If not specified, uses the terminal width.
+   *
+   * @default `process.stdout.columns` (auto-detect terminal width)
+   */
+  readonly maxWidth?: number;
+  /**
+   * Determines how help functionality is made available:
+   *
+   * - `"command"`: Only the `help` subcommand is available
+   * - `"option"`: Only the `--help` option is available
+   * - `"both"`: Both `help` subcommand and `--help` option are available
+   * - `"none"`: No help functionality is provided
+   *
+   * @default `"none"`
+   */
+  readonly help?: "command" | "option" | "both" | "none";
+  /**
+   * What to display above error messages:
+   *
+   * - `"usage"`: Show usage line before error message
+   * - `"help"`: Show full help page before error message
+   * - `"none"`: Show only the error message
+   *
+   * @default `"usage"`
+   */
+  readonly aboveError?: "usage" | "help" | "none";
+  /**
+   * The exit code to use when the parser encounters an error.
+   *
+   * @default `1`
+   */
+  readonly errorExitCode?: number;
+}
+/**
+ * Runs a command-line parser with automatic process integration.
+ *
+ * This function provides a convenient high-level interface for parsing
+ * command-line arguments in Node.js, Bun, and Deno environments. It
+ * automatically handles `process.argv`, `process.exit()`, and terminal
+ * output formatting, eliminating the need to manually pass these values
+ * as the lower-level `run()` function (from `@optique/core/facade`) requires.
+ *
+ * The function will automatically:
+ *
+ * - Extract arguments from `process.argv`
+ * - Detect terminal capabilities for colors and width
+ * - Exit the process with appropriate codes on help or error
+ * - Format output according to terminal capabilities
+ *
+ * @template T The parser type being executed.
+ * @param parser The command-line parser to execute.
+ * @param options Configuration options for customizing behavior.
+ *                See {@link RunOptions} for available settings.
+ * @returns The parsed result if successful. On help display or parse errors,
+ *          the function will call `process.exit()` and not return.
+ *
+ * @example
+ * ```typescript
+ * import { object, option, run } from "@optique/run";
+ * import { string, integer } from "@optique/core/valueparser";
+ *
+ * const parser = object({
+ *   name: option("-n", "--name", string()),
+ *   port: option("-p", "--port", integer()),
+ * });
+ *
+ * // Automatically uses process.argv, handles errors/help, exits on completion
+ * const config = run(parser);
+ * console.log(`Starting server ${config.name} on port ${config.port}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const result = run(parser, {
+ *   programName: "myapp",
+ *   help: "both",           // Enable both --help option and help command
+ *   colors: true,           // Force colored output
+ *   errorExitCode: 2,       // Exit with code 2 on errors
+ * });
+ * ```
+ */
+declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+//#endregion
+export { RunOptions, run };

package/dist/run.js

@@ -0,0 +1,70 @@
+import { run as run$1 } from "@optique/core/facade";
+import path from "node:path";
+import process from "node:process";
+
+//#region src/run.ts
+/**
+* Runs a command-line parser with automatic process integration.
+*
+* This function provides a convenient high-level interface for parsing
+* command-line arguments in Node.js, Bun, and Deno environments. It
+* automatically handles `process.argv`, `process.exit()`, and terminal
+* output formatting, eliminating the need to manually pass these values
+* as the lower-level `run()` function (from `@optique/core/facade`) requires.
+*
+* The function will automatically:
+*
+* - Extract arguments from `process.argv`
+* - Detect terminal capabilities for colors and width
+* - Exit the process with appropriate codes on help or error
+* - Format output according to terminal capabilities
+*
+* @template T The parser type being executed.
+* @param parser The command-line parser to execute.
+* @param options Configuration options for customizing behavior.
+*                See {@link RunOptions} for available settings.
+* @returns The parsed result if successful. On help display or parse errors,
+*          the function will call `process.exit()` and not return.
+*
+* @example
+* ```typescript
+* import { object, option, run } from "@optique/run";
+* import { string, integer } from "@optique/core/valueparser";
+*
+* const parser = object({
+*   name: option("-n", "--name", string()),
+*   port: option("-p", "--port", integer()),
+* });
+*
+* // Automatically uses process.argv, handles errors/help, exits on completion
+* const config = run(parser);
+* console.log(`Starting server ${config.name} on port ${config.port}`);
+* ```
+*
+* @example
+* ```typescript
+* // With custom options
+* const result = run(parser, {
+*   programName: "myapp",
+*   help: "both",           // Enable both --help option and help command
+*   colors: true,           // Force colored output
+*   errorExitCode: 2,       // Exit with code 2 on errors
+* });
+* ```
+*/
+function run(parser, options = {}) {
+	const { programName = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, help = "none", aboveError = "usage", errorExitCode = 1 } = options;
+	return run$1(parser, programName, args, {
+		colors,
+		maxWidth,
+		help,
+		aboveError,
+		onHelp: process.exit,
+		onError() {
+			return process.exit(errorExitCode);
+		}
+	});
+}
+
+//#endregion
+export { run };

package/dist/valueparser.cjs

@@ -0,0 +1,88 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_path = require_rolldown_runtime.__toESM(require("node:path"));
+const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
+const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
+
+//#region src/valueparser.ts
+/**
+* Creates a ValueParser for file system paths with validation options.
+*
+* This parser provides filesystem validation and type checking for command-line
+* path arguments. It can validate existence, file vs directory types, parent
+* directory existence for new files, and file extensions.
+*
+* @param options Configuration options for path validation.
+* @returns A ValueParser that validates and returns string paths.
+*
+* @example
+* ```typescript
+* import { path } from "@optique/run";
+* import { argument, object } from "@optique/core/parser";
+*
+* // Basic path parser (any path, no validation)
+* const configFile = argument(path());
+*
+* // File must exist
+* const inputFile = argument(path({ mustExist: true }));
+*
+* // Directory must exist
+* const outputDir = argument(path({ mustExist: true, type: "directory" }));
+*
+* // File can be created (parent directory must exist)
+* const logFile = argument(path({ type: "file", allowCreate: true }));
+*
+* // Config files with specific extensions
+* const config = argument(path({
+*   mustExist: true,
+*   type: "file",
+*   extensions: [".json", ".yaml", ".yml"]
+* }));
+* ```
+*/
+function path(options = {}) {
+	const { metavar = "PATH", mustExist = false, type = "either", allowCreate = false, extensions } = options;
+	return {
+		metavar,
+		parse(input) {
+			if (extensions && extensions.length > 0) {
+				const ext = (0, node_path.extname)(input);
+				if (!extensions.includes(ext)) return {
+					success: false,
+					error: __optique_core_message.message`Expected file with extension ${(0, __optique_core_message.text)(extensions.join(", "))}, got ${(0, __optique_core_message.text)(ext || "no extension")}.`
+				};
+			}
+			if (mustExist) {
+				if (!(0, node_fs.existsSync)(input)) return {
+					success: false,
+					error: __optique_core_message.message`Path ${(0, __optique_core_message.text)(input)} does not exist.`
+				};
+				const stats = (0, node_fs.statSync)(input);
+				if (type === "file" && !stats.isFile()) return {
+					success: false,
+					error: __optique_core_message.message`Expected a file, but ${(0, __optique_core_message.text)(input)} is not a file.`
+				};
+				if (type === "directory" && !stats.isDirectory()) return {
+					success: false,
+					error: __optique_core_message.message`Expected a directory, but ${(0, __optique_core_message.text)(input)} is not a directory.`
+				};
+			}
+			if (allowCreate && !mustExist) {
+				const parentDir = (0, node_path.dirname)(input);
+				if (!(0, node_fs.existsSync)(parentDir)) return {
+					success: false,
+					error: __optique_core_message.message`Parent directory ${(0, __optique_core_message.text)(parentDir)} does not exist.`
+				};
+			}
+			return {
+				success: true,
+				value: input
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+
+//#endregion
+exports.path = path;

package/dist/valueparser.d.cts

@@ -0,0 +1,74 @@
+import { ValueParser } from "@optique/core/valueparser";
+
+//#region src/valueparser.d.ts
+
+/**
+ * Configuration options for the {@link path} value parser.
+ */
+interface PathOptions {
+  /**
+   * The metavariable name for this parser, e.g., `"FILE"`, `"DIR"`.
+   * @default "PATH"
+   */
+  readonly metavar?: string;
+  /**
+   * Whether the path must exist on the filesystem.
+   * @default false
+   */
+  readonly mustExist?: boolean;
+  /**
+   * Expected type of path (file, directory, or either).
+   * Only checked when {@link mustExist} is true.
+   * @default "either"
+   */
+  readonly type?: "file" | "directory" | "either";
+  /**
+   * Whether to allow creating new files/directories.
+   * When true and mustExist is false, validates that parent directory exists.
+   * @default false
+   */
+  readonly allowCreate?: boolean;
+  /**
+   * File extensions to accept (for files only).  Each extension must
+   * start with a dot (e.g. `".json"`, `".yaml"`).
+   */
+  readonly extensions?: readonly string[];
+}
+/**
+ * Creates a ValueParser for file system paths with validation options.
+ *
+ * This parser provides filesystem validation and type checking for command-line
+ * path arguments. It can validate existence, file vs directory types, parent
+ * directory existence for new files, and file extensions.
+ *
+ * @param options Configuration options for path validation.
+ * @returns A ValueParser that validates and returns string paths.
+ *
+ * @example
+ * ```typescript
+ * import { path } from "@optique/run";
+ * import { argument, object } from "@optique/core/parser";
+ *
+ * // Basic path parser (any path, no validation)
+ * const configFile = argument(path());
+ *
+ * // File must exist
+ * const inputFile = argument(path({ mustExist: true }));
+ *
+ * // Directory must exist
+ * const outputDir = argument(path({ mustExist: true, type: "directory" }));
+ *
+ * // File can be created (parent directory must exist)
+ * const logFile = argument(path({ type: "file", allowCreate: true }));
+ *
+ * // Config files with specific extensions
+ * const config = argument(path({
+ *   mustExist: true,
+ *   type: "file",
+ *   extensions: [".json", ".yaml", ".yml"]
+ * }));
+ * ```
+ */
+declare function path(options?: PathOptions): ValueParser<string>;
+//#endregion
+export { PathOptions, path };

package/dist/valueparser.d.ts

@@ -0,0 +1,74 @@
+import { ValueParser } from "@optique/core/valueparser";
+
+//#region src/valueparser.d.ts
+
+/**
+ * Configuration options for the {@link path} value parser.
+ */
+interface PathOptions {
+  /**
+   * The metavariable name for this parser, e.g., `"FILE"`, `"DIR"`.
+   * @default "PATH"
+   */
+  readonly metavar?: string;
+  /**
+   * Whether the path must exist on the filesystem.
+   * @default false
+   */
+  readonly mustExist?: boolean;
+  /**
+   * Expected type of path (file, directory, or either).
+   * Only checked when {@link mustExist} is true.
+   * @default "either"
+   */
+  readonly type?: "file" | "directory" | "either";
+  /**
+   * Whether to allow creating new files/directories.
+   * When true and mustExist is false, validates that parent directory exists.
+   * @default false
+   */
+  readonly allowCreate?: boolean;
+  /**
+   * File extensions to accept (for files only).  Each extension must
+   * start with a dot (e.g. `".json"`, `".yaml"`).
+   */
+  readonly extensions?: readonly string[];
+}
+/**
+ * Creates a ValueParser for file system paths with validation options.
+ *
+ * This parser provides filesystem validation and type checking for command-line
+ * path arguments. It can validate existence, file vs directory types, parent
+ * directory existence for new files, and file extensions.
+ *
+ * @param options Configuration options for path validation.
+ * @returns A ValueParser that validates and returns string paths.
+ *
+ * @example
+ * ```typescript
+ * import { path } from "@optique/run";
+ * import { argument, object } from "@optique/core/parser";
+ *
+ * // Basic path parser (any path, no validation)
+ * const configFile = argument(path());
+ *
+ * // File must exist
+ * const inputFile = argument(path({ mustExist: true }));
+ *
+ * // Directory must exist
+ * const outputDir = argument(path({ mustExist: true, type: "directory" }));
+ *
+ * // File can be created (parent directory must exist)
+ * const logFile = argument(path({ type: "file", allowCreate: true }));
+ *
+ * // Config files with specific extensions
+ * const config = argument(path({
+ *   mustExist: true,
+ *   type: "file",
+ *   extensions: [".json", ".yaml", ".yml"]
+ * }));
+ * ```
+ */
+declare function path(options?: PathOptions): ValueParser<string>;
+//#endregion
+export { PathOptions, path };

package/dist/valueparser.js

@@ -0,0 +1,87 @@
+import { dirname, extname } from "node:path";
+import { message, text } from "@optique/core/message";
+import { existsSync, statSync } from "node:fs";
+
+//#region src/valueparser.ts
+/**
+* Creates a ValueParser for file system paths with validation options.
+*
+* This parser provides filesystem validation and type checking for command-line
+* path arguments. It can validate existence, file vs directory types, parent
+* directory existence for new files, and file extensions.
+*
+* @param options Configuration options for path validation.
+* @returns A ValueParser that validates and returns string paths.
+*
+* @example
+* ```typescript
+* import { path } from "@optique/run";
+* import { argument, object } from "@optique/core/parser";
+*
+* // Basic path parser (any path, no validation)
+* const configFile = argument(path());
+*
+* // File must exist
+* const inputFile = argument(path({ mustExist: true }));
+*
+* // Directory must exist
+* const outputDir = argument(path({ mustExist: true, type: "directory" }));
+*
+* // File can be created (parent directory must exist)
+* const logFile = argument(path({ type: "file", allowCreate: true }));
+*
+* // Config files with specific extensions
+* const config = argument(path({
+*   mustExist: true,
+*   type: "file",
+*   extensions: [".json", ".yaml", ".yml"]
+* }));
+* ```
+*/
+function path(options = {}) {
+	const { metavar = "PATH", mustExist = false, type = "either", allowCreate = false, extensions } = options;
+	return {
+		metavar,
+		parse(input) {
+			if (extensions && extensions.length > 0) {
+				const ext = extname(input);
+				if (!extensions.includes(ext)) return {
+					success: false,
+					error: message`Expected file with extension ${text(extensions.join(", "))}, got ${text(ext || "no extension")}.`
+				};
+			}
+			if (mustExist) {
+				if (!existsSync(input)) return {
+					success: false,
+					error: message`Path ${text(input)} does not exist.`
+				};
+				const stats = statSync(input);
+				if (type === "file" && !stats.isFile()) return {
+					success: false,
+					error: message`Expected a file, but ${text(input)} is not a file.`
+				};
+				if (type === "directory" && !stats.isDirectory()) return {
+					success: false,
+					error: message`Expected a directory, but ${text(input)} is not a directory.`
+				};
+			}
+			if (allowCreate && !mustExist) {
+				const parentDir = dirname(input);
+				if (!existsSync(parentDir)) return {
+					success: false,
+					error: message`Parent directory ${text(parentDir)} does not exist.`
+				};
+			}
+			return {
+				success: true,
+				value: input
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+
+//#endregion
+export { path };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "0.1.0-dev.2+f542cb87",
+  "version": "0.1.0-dev.27+836bb5a6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -50,6 +50,22 @@
       },
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./run": {
+      "types": {
+        "import": "./dist/run.d.ts",
+        "require": "./dist/run.cts"
+      },
+      "import": "./dist/run.js",
+      "require": "./dist/run.cjs"
+    },
+    "./valueparser": {
+      "types": {
+        "import": "./dist/valueparser.d.ts",
+        "require": "./dist/valueparser.cts"
+      },
+      "import": "./dist/valueparser.js",
+      "require": "./dist/valueparser.cjs"
     }
   },
   "sideEffects": false,