@optique/run 0.10.0-dev.324 → 0.10.0-dev.328

package/dist/run.cjs

@@ -4,44 +4,35 @@ const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
 
 //#region src/run.ts
-function run(parser, options = {}) {
-	return runImpl(parser, options);
+function run(parserOrProgram, options = {}) {
+	return runImpl(parserOrProgram, options);
 }
-/**
-* Runs a synchronous command-line parser with automatic process integration.
-*
-* This is a type-safe version of {@link run} that only accepts sync parsers.
-* Use this when you know your parser is sync-only to get direct return values
-* without Promise wrappers.
-*
-* @template T The sync parser type being executed.
-* @param parser The synchronous command-line parser to execute.
-* @param options Configuration options for customizing behavior.
-* @returns The parsed result if successful.
-* @since 0.9.0
-*/
-function runSync(parser, options = {}) {
-	return runImpl(parser, options);
+function runSync(parserOrProgram, options = {}) {
+	return runImpl(parserOrProgram, options);
 }
-/**
-* Runs an asynchronous command-line parser with automatic process integration.
-*
-* This function accepts any parser (sync or async) and always returns a
-* Promise. Use this when working with parsers that may contain async
-* value parsers.
-*
-* @template T The parser type being executed.
-* @param parser The command-line parser to execute.
-* @param options Configuration options for customizing behavior.
-* @returns A Promise of the parsed result if successful.
-* @since 0.9.0
-*/
-function runAsync(parser, options = {}) {
-	const result = runImpl(parser, options);
+function runAsync(parserOrProgram, options = {}) {
+	const result = runImpl(parserOrProgram, options);
 	return Promise.resolve(result);
 }
-function runImpl(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, showDefault, help, version, completion, aboveError = "usage", errorExitCode = 1, brief, description, footer } = options;
+function runImpl(parserOrProgram, options = {}) {
+	const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
+	let parser;
+	let programNameFromProgram;
+	let programMetadata;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programNameFromProgram = program.metadata.name;
+		programMetadata = {
+			brief: program.metadata.brief,
+			description: program.metadata.description,
+			examples: program.metadata.examples,
+			author: program.metadata.author,
+			bugs: program.metadata.bugs,
+			footer: program.metadata.footer
+		};
+	} else parser = parserOrProgram;
+	const { programName = programNameFromProgram ?? node_path.default.basename(node_process.default.argv[1] || "cli"), args = node_process.default.argv.slice(2), colors = node_process.default.stdout.isTTY, maxWidth = node_process.default.stdout.columns, showDefault, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
 	const helpConfig = help ? {
 		mode: help,
 		onShow: () => node_process.default.exit(0)
@@ -73,6 +64,9 @@ function runImpl(parser, options = {}) {
 		aboveError,
 		brief,
 		description,
+		examples,
+		author,
+		bugs,
 		footer,
 		onError() {
 			return node_process.default.exit(errorExitCode);

package/dist/run.d.cts

@@ -1,5 +1,6 @@
 import { ShellCompletion } from "@optique/core/completion";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
+import { Program } from "@optique/core/program";
 import { ShowDefaultOptions } from "@optique/core/doc";
 import { Message } from "@optique/core/message";
 
@@ -117,6 +118,24 @@ interface RunOptions {
    * @since 0.4.0
    */
   readonly description?: Message;
+  /**
+   * Usage examples for the program.
+   *
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   *
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   *
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   /**
    * Footer text shown at the bottom of help text.
    *
@@ -186,7 +205,11 @@ interface RunOptions {
  * // source ~/.bash_completion.d/myapp                   # Enable completion
  * // myapp --format=<TAB>                                # Use completion
  * ```
+ *
+ * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function run<T>(program: Program<"sync", T>, options?: RunOptions): T;
+declare function run<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
 declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 declare function run<T extends Parser<"async", unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): ModeValue<InferMode<T>, InferValue<T>>;
@@ -203,6 +226,7 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @returns The parsed result if successful.
  * @since 0.9.0
  */
+declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
 declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 /**
  * Runs an asynchronous command-line parser with automatic process integration.
@@ -217,6 +241,8 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
+declare function runAsync<T>(program: Program<"sync", T>, options?: RunOptions): Promise<T>;
+declare function runAsync<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
 declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 //#endregion
 export { RunOptions, run, runAsync, runSync };

package/dist/run.d.ts

@@ -1,6 +1,7 @@
 import { Message } from "@optique/core/message";
 import { ShellCompletion } from "@optique/core/completion";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
+import { Program } from "@optique/core/program";
 import { ShowDefaultOptions } from "@optique/core/doc";
 
 //#region src/run.d.ts
@@ -117,6 +118,24 @@ interface RunOptions {
    * @since 0.4.0
    */
   readonly description?: Message;
+  /**
+   * Usage examples for the program.
+   *
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   *
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   *
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   /**
    * Footer text shown at the bottom of help text.
    *
@@ -186,7 +205,11 @@ interface RunOptions {
  * // source ~/.bash_completion.d/myapp                   # Enable completion
  * // myapp --format=<TAB>                                # Use completion
  * ```
+ *
+ * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function run<T>(program: Program<"sync", T>, options?: RunOptions): T;
+declare function run<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
 declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 declare function run<T extends Parser<"async", unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): ModeValue<InferMode<T>, InferValue<T>>;
@@ -203,6 +226,7 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * @returns The parsed result if successful.
  * @since 0.9.0
  */
+declare function runSync<T>(program: Program<"sync", T>, options?: RunOptions): T;
 declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 /**
  * Runs an asynchronous command-line parser with automatic process integration.
@@ -217,6 +241,8 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * @returns A Promise of the parsed result if successful.
  * @since 0.9.0
  */
+declare function runAsync<T>(program: Program<"sync", T>, options?: RunOptions): Promise<T>;
+declare function runAsync<T>(program: Program<"async", T>, options?: RunOptions): Promise<T>;
 declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 //#endregion
 export { RunOptions, run, runAsync, runSync };

package/dist/run.js

@@ -3,44 +3,35 @@ import path from "node:path";
 import process from "node:process";
 
 //#region src/run.ts
-function run(parser, options = {}) {
-	return runImpl(parser, options);
+function run(parserOrProgram, options = {}) {
+	return runImpl(parserOrProgram, options);
 }
-/**
-* Runs a synchronous command-line parser with automatic process integration.
-*
-* This is a type-safe version of {@link run} that only accepts sync parsers.
-* Use this when you know your parser is sync-only to get direct return values
-* without Promise wrappers.
-*
-* @template T The sync parser type being executed.
-* @param parser The synchronous command-line parser to execute.
-* @param options Configuration options for customizing behavior.
-* @returns The parsed result if successful.
-* @since 0.9.0
-*/
-function runSync(parser, options = {}) {
-	return runImpl(parser, options);
+function runSync(parserOrProgram, options = {}) {
+	return runImpl(parserOrProgram, options);
 }
-/**
-* Runs an asynchronous command-line parser with automatic process integration.
-*
-* This function accepts any parser (sync or async) and always returns a
-* Promise. Use this when working with parsers that may contain async
-* value parsers.
-*
-* @template T The parser type being executed.
-* @param parser The command-line parser to execute.
-* @param options Configuration options for customizing behavior.
-* @returns A Promise of the parsed result if successful.
-* @since 0.9.0
-*/
-function runAsync(parser, options = {}) {
-	const result = runImpl(parser, options);
+function runAsync(parserOrProgram, options = {}) {
+	const result = runImpl(parserOrProgram, options);
 	return Promise.resolve(result);
 }
-function runImpl(parser, options = {}) {
-	const { programName = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, help, version, completion, aboveError = "usage", errorExitCode = 1, brief, description, footer } = options;
+function runImpl(parserOrProgram, options = {}) {
+	const isProgram = "parser" in parserOrProgram && "metadata" in parserOrProgram;
+	let parser;
+	let programNameFromProgram;
+	let programMetadata;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programNameFromProgram = program.metadata.name;
+		programMetadata = {
+			brief: program.metadata.brief,
+			description: program.metadata.description,
+			examples: program.metadata.examples,
+			author: program.metadata.author,
+			bugs: program.metadata.bugs,
+			footer: program.metadata.footer
+		};
+	} else parser = parserOrProgram;
+	const { programName = programNameFromProgram ?? path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
 	const helpConfig = help ? {
 		mode: help,
 		onShow: () => process.exit(0)
@@ -72,6 +63,9 @@ function runImpl(parser, options = {}) {
 		aboveError,
 		brief,
 		description,
+		examples,
+		author,
+		bugs,
 		footer,
 		onError() {
 			return process.exit(errorExitCode);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "0.10.0-dev.324+5bba27e5",
+  "version": "0.10.0-dev.328+4e5f40d5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "0.10.0-dev.324+5bba27e5"
+    "@optique/core": "0.10.0-dev.328+4e5f40d5"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",