@optique/run 0.1.0-dev.1

package/README.md

@@ -0,0 +1,134 @@
+@optique/run
+============
+
+> [!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.
+
+*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.
+
+
+When to use @optique/run
+------------------------
+
+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:
+
+ -  Building web applications or libraries
+ -  You need full control over argument sources and error handling
+ -  Working in environments without `process` (browsers, web workers)
+ -  Building reusable parser components
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/run jsr:@optique/core
+npm  add     @optique/run     @optique/core
+pnpm add     @optique/run     @optique/core
+yarn add     @optique/run     @optique/core
+~~~~
+
+
+Quick example
+-------------
+
+~~~~ typescript
+import { run } from "@optique/run";
+import { object, option, argument } from "@optique/core/parser";
+import { string, integer } from "@optique/core/valueparser";
+
+const parser = object({
+  name: argument(string()),
+  age: option("-a", "--age", integer()),
+  verbose: option("-v", "--verbose"),
+});
+
+// Automatically uses process.argv, handles errors and help, exits on completion
+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.");
+}
+~~~~
+
+Run it:
+
+~~~~ bash
+$ node cli.js Alice --age 25 --verbose
+Hello Alice!
+You are 25 years old.
+Verbose mode enabled.
+~~~~
+
+
+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()`)

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,25 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+exports.__toESM = __toESM;

package/dist/index.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/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;

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+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 };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+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 };

package/dist/index.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/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 };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@optique/run",
+  "version": "0.1.0-dev.1+4d43eddd",
+  "description": "Type-safe combinatorial command-line interface parser",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "getopt",
+    "optparse"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/run/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@optique/core": ""
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}