@optique/testing 1.3.0-dev.2488 → 1.3.0-dev.2497

package/README.md

@@ -18,6 +18,60 @@ visible from its import:
 The package root holds only the contracts that mean the same thing at more than
 one boundary.  It depends on no test framework and no assertion library.
 
+The parser layer is available through `parseArgs()` and `parseArgsSync()`:
+
+~~~~ typescript
+import { option } from "@optique/core/primitives";
+import { parseArgsSync } from "@optique/testing/parser";
+
+const result = parseArgsSync(option("--verbose"), ["--verbose"]);
+if (result.success) {
+  console.log(result.value);
+} else {
+  console.error(result.error, result.remainingArgs, result.commandPath);
+}
+~~~~
+
+The runner layer is available through `captureRun()`:
+
+~~~~ typescript
+import { argument } from "@optique/core/primitives";
+import { string } from "@optique/core/valueparser";
+import { captureRun } from "@optique/testing/run";
+
+const result = await captureRun(argument(string()), {
+  args: ["--help"],
+  programName: "greet",
+  help: "option",
+  colors: false,
+  maxWidth: 80,
+});
+
+console.log(result.kind, result.exitCode, result.stdout, result.stderr);
+~~~~
+
+Use `captureProgramRun()` to include command discovery and handler dispatch:
+
+~~~~ typescript
+import { captureProgramRun } from "@optique/testing/discover";
+
+const result = await captureProgramRun({
+  dir: new URL("./commands/", import.meta.url),
+  metadata: { name: "example" },
+  args: ["--help"],
+  colors: false,
+  maxWidth: 80,
+});
+
+console.log(result.exitCode, result.stdout, result.stderr);
+~~~~
+
+The helper runs real command modules, hooks, and handlers.  It captures
+Optique's output callbacks; direct console or process-stream writes bypass
+capture.  Unexpected errors reject the promise.
+
+The child-process entry point remains reserved while its helpers are developed.
+
 [Optique]: https://optique.dev/
 
 

package/dist/chunk-CUT6urMc.cjs

@@ -0,0 +1,30 @@
+//#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
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/discover.cjs

@@ -0,0 +1,66 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const __optique_discover = require_chunk.__toESM(require("@optique/discover"));
+
+//#region src/discover.ts
+/**
+* Runs a command program in process and captures Optique-controlled output.
+*
+* Discovery, hooks, and command handlers execute normally.  Help, version,
+* completion, and parse-error exits become results; other errors continue to
+* reject as they do in `runProgram()`.  Writes through `console.log()`,
+* `print()`, or process streams bypass the injected callbacks and are not
+* captured.  Each callback write includes the default writer's trailing newline.
+*
+* Options retain `runProgram()`'s defaults, including process arguments and
+* terminal-dependent colors and width.  Set `args`, `colors`, and `maxWidth`
+* explicitly for deterministic tests.
+*
+* @template R The resource made available by program-level lifecycle hooks.
+* @param options Program options other than the captured callbacks.
+* @returns Captured output and the exit code after execution completes.
+* @throws Any error propagated by `runProgram()`, including discovery, parser,
+*         hook, handler, callback, and context disposal failures.
+* @since 1.3.0
+*/
+async function captureProgramRun(options) {
+	class ProgramExit extends Error {
+		exitCode;
+		constructor(exitCode) {
+			super(`Program exited with code ${exitCode}.`);
+			this.name = "ProgramExit";
+			this.exitCode = exitCode;
+		}
+	}
+	let stdout = "";
+	let stderr = "";
+	const runOptions = {
+		...options,
+		stdout(text) {
+			stdout += `${text}\n`;
+		},
+		stderr(text) {
+			stderr += `${text}\n`;
+		},
+		onExit(exitCode) {
+			throw new ProgramExit(exitCode);
+		}
+	};
+	try {
+		await (0, __optique_discover.runProgram)(runOptions);
+		return {
+			exitCode: 0,
+			stdout,
+			stderr
+		};
+	} catch (error) {
+		if (!(error instanceof ProgramExit)) throw error;
+		return {
+			exitCode: error.exitCode,
+			stdout,
+			stderr
+		};
+	}
+}
+
+//#endregion
+exports.captureProgramRun = captureProgramRun;

package/dist/discover.d.cts

@@ -1 +1,54 @@
-export { };
+import { CapturedOutput } from "./index-Cuf92ZIO.cjs";
+import { RunProgramOptions } from "@optique/discover";
+
+//#region src/discover.d.ts
+
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * Options for {@link captureProgramRun}, preserving the command source union
+ * and program hook resource type of `RunProgramOptions`.
+ *
+ * Output and exit callbacks are controlled by the capture helper.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.3.0
+ */
+type CaptureProgramRunOptions<R = unknown> = DistributiveOmit<RunProgramOptions<R>, "stdout" | "stderr" | "onExit"> & {
+  readonly stdout?: never;
+  readonly stderr?: never;
+  readonly onExit?: never;
+};
+/**
+ * Captured output and exit code from a command program execution.
+ *
+ * @since 1.3.0
+ */
+interface ProgramRunResult extends CapturedOutput {
+  /**
+   * Zero after normal completion, or the code requested by an intentional exit.
+   */
+  readonly exitCode: number;
+}
+/**
+ * Runs a command program in process and captures Optique-controlled output.
+ *
+ * Discovery, hooks, and command handlers execute normally.  Help, version,
+ * completion, and parse-error exits become results; other errors continue to
+ * reject as they do in `runProgram()`.  Writes through `console.log()`,
+ * `print()`, or process streams bypass the injected callbacks and are not
+ * captured.  Each callback write includes the default writer's trailing newline.
+ *
+ * Options retain `runProgram()`'s defaults, including process arguments and
+ * terminal-dependent colors and width.  Set `args`, `colors`, and `maxWidth`
+ * explicitly for deterministic tests.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @param options Program options other than the captured callbacks.
+ * @returns Captured output and the exit code after execution completes.
+ * @throws Any error propagated by `runProgram()`, including discovery, parser,
+ *         hook, handler, callback, and context disposal failures.
+ * @since 1.3.0
+ */
+declare function captureProgramRun<R = unknown>(options: CaptureProgramRunOptions<R>): Promise<ProgramRunResult>;
+//#endregion
+export { CaptureProgramRunOptions, ProgramRunResult, captureProgramRun };

package/dist/discover.d.ts

@@ -1 +1,54 @@
-export { };
+import { CapturedOutput } from "./index-t_PHSvz_.js";
+import { RunProgramOptions } from "@optique/discover";
+
+//#region src/discover.d.ts
+
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * Options for {@link captureProgramRun}, preserving the command source union
+ * and program hook resource type of `RunProgramOptions`.
+ *
+ * Output and exit callbacks are controlled by the capture helper.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @since 1.3.0
+ */
+type CaptureProgramRunOptions<R = unknown> = DistributiveOmit<RunProgramOptions<R>, "stdout" | "stderr" | "onExit"> & {
+  readonly stdout?: never;
+  readonly stderr?: never;
+  readonly onExit?: never;
+};
+/**
+ * Captured output and exit code from a command program execution.
+ *
+ * @since 1.3.0
+ */
+interface ProgramRunResult extends CapturedOutput {
+  /**
+   * Zero after normal completion, or the code requested by an intentional exit.
+   */
+  readonly exitCode: number;
+}
+/**
+ * Runs a command program in process and captures Optique-controlled output.
+ *
+ * Discovery, hooks, and command handlers execute normally.  Help, version,
+ * completion, and parse-error exits become results; other errors continue to
+ * reject as they do in `runProgram()`.  Writes through `console.log()`,
+ * `print()`, or process streams bypass the injected callbacks and are not
+ * captured.  Each callback write includes the default writer's trailing newline.
+ *
+ * Options retain `runProgram()`'s defaults, including process arguments and
+ * terminal-dependent colors and width.  Set `args`, `colors`, and `maxWidth`
+ * explicitly for deterministic tests.
+ *
+ * @template R The resource made available by program-level lifecycle hooks.
+ * @param options Program options other than the captured callbacks.
+ * @returns Captured output and the exit code after execution completes.
+ * @throws Any error propagated by `runProgram()`, including discovery, parser,
+ *         hook, handler, callback, and context disposal failures.
+ * @since 1.3.0
+ */
+declare function captureProgramRun<R = unknown>(options: CaptureProgramRunOptions<R>): Promise<ProgramRunResult>;
+//#endregion
+export { CaptureProgramRunOptions, ProgramRunResult, captureProgramRun };

package/dist/discover.js

@@ -0,0 +1,65 @@
+import { runProgram } from "@optique/discover";
+
+//#region src/discover.ts
+/**
+* Runs a command program in process and captures Optique-controlled output.
+*
+* Discovery, hooks, and command handlers execute normally.  Help, version,
+* completion, and parse-error exits become results; other errors continue to
+* reject as they do in `runProgram()`.  Writes through `console.log()`,
+* `print()`, or process streams bypass the injected callbacks and are not
+* captured.  Each callback write includes the default writer's trailing newline.
+*
+* Options retain `runProgram()`'s defaults, including process arguments and
+* terminal-dependent colors and width.  Set `args`, `colors`, and `maxWidth`
+* explicitly for deterministic tests.
+*
+* @template R The resource made available by program-level lifecycle hooks.
+* @param options Program options other than the captured callbacks.
+* @returns Captured output and the exit code after execution completes.
+* @throws Any error propagated by `runProgram()`, including discovery, parser,
+*         hook, handler, callback, and context disposal failures.
+* @since 1.3.0
+*/
+async function captureProgramRun(options) {
+	class ProgramExit extends Error {
+		exitCode;
+		constructor(exitCode) {
+			super(`Program exited with code ${exitCode}.`);
+			this.name = "ProgramExit";
+			this.exitCode = exitCode;
+		}
+	}
+	let stdout = "";
+	let stderr = "";
+	const runOptions = {
+		...options,
+		stdout(text) {
+			stdout += `${text}\n`;
+		},
+		stderr(text) {
+			stderr += `${text}\n`;
+		},
+		onExit(exitCode) {
+			throw new ProgramExit(exitCode);
+		}
+	};
+	try {
+		await runProgram(runOptions);
+		return {
+			exitCode: 0,
+			stdout,
+			stderr
+		};
+	} catch (error) {
+		if (!(error instanceof ProgramExit)) throw error;
+		return {
+			exitCode: error.exitCode,
+			stdout,
+			stderr
+		};
+	}
+}
+
+//#endregion
+export { captureProgramRun };

package/dist/index-Cuf92ZIO.d.cts

@@ -0,0 +1,46 @@
+//#region src/index.d.ts
+/**
+ * Testing support for Optique command-line interfaces.
+ *
+ * An Optique application can be exercised at four distinct execution
+ * boundaries, and this package gives each one its own entry point:
+ *
+ * - `@optique/testing/parser` runs a parser against an argument list without
+ *   help rendering, process integration, or command dispatch.
+ * - `@optique/testing/run` captures what `run()` and `runAsync()` write
+ *   through their injected output callbacks, along with intentional exits.
+ * - `@optique/testing/discover` captures a `runProgram()` invocation,
+ *   including command discovery and handler dispatch.
+ * - `@optique/testing/cli` invokes a real CLI entry point in a child process.
+ *
+ * This module holds only the contracts that mean the same thing at more than
+ * one of those boundaries.  Results that differ by layer—parsed values,
+ * intentional exits, terminating signals—belong to the subpath that produces
+ * them.
+ *
+ * @module
+ * @since 1.3.0
+ */
+/**
+ * Text captured from a program's standard output and standard error streams.
+ *
+ * The two streams are kept apart and their text is preserved exactly, so a
+ * test can assert on trailing newlines and on which stream a message reached.
+ * Each layer documents how it fills these fields: the in-process layers
+ * accumulate the text their injected writers receive, while the subprocess
+ * layer decodes whatever the child actually wrote.
+ *
+ * @since 1.3.0
+ */
+interface CapturedOutput {
+  /**
+   * The text written to standard output.  Empty when nothing was written.
+   */
+  readonly stdout: string;
+  /**
+   * The text written to standard error.  Empty when nothing was written.
+   */
+  readonly stderr: string;
+}
+//#endregion
+export { CapturedOutput };

package/dist/index-t_PHSvz_.d.ts

@@ -0,0 +1,46 @@
+//#region src/index.d.ts
+/**
+ * Testing support for Optique command-line interfaces.
+ *
+ * An Optique application can be exercised at four distinct execution
+ * boundaries, and this package gives each one its own entry point:
+ *
+ * - `@optique/testing/parser` runs a parser against an argument list without
+ *   help rendering, process integration, or command dispatch.
+ * - `@optique/testing/run` captures what `run()` and `runAsync()` write
+ *   through their injected output callbacks, along with intentional exits.
+ * - `@optique/testing/discover` captures a `runProgram()` invocation,
+ *   including command discovery and handler dispatch.
+ * - `@optique/testing/cli` invokes a real CLI entry point in a child process.
+ *
+ * This module holds only the contracts that mean the same thing at more than
+ * one of those boundaries.  Results that differ by layer—parsed values,
+ * intentional exits, terminating signals—belong to the subpath that produces
+ * them.
+ *
+ * @module
+ * @since 1.3.0
+ */
+/**
+ * Text captured from a program's standard output and standard error streams.
+ *
+ * The two streams are kept apart and their text is preserved exactly, so a
+ * test can assert on trailing newlines and on which stream a message reached.
+ * Each layer documents how it fills these fields: the in-process layers
+ * accumulate the text their injected writers receive, while the subprocess
+ * layer decodes whatever the child actually wrote.
+ *
+ * @since 1.3.0
+ */
+interface CapturedOutput {
+  /**
+   * The text written to standard output.  Empty when nothing was written.
+   */
+  readonly stdout: string;
+  /**
+   * The text written to standard error.  Empty when nothing was written.
+   */
+  readonly stderr: string;
+}
+//#endregion
+export { CapturedOutput };

package/dist/index.d.cts

@@ -1,46 +1,2 @@
-//#region src/index.d.ts
-/**
- * Testing support for Optique command-line interfaces.
- *
- * An Optique application can be exercised at four distinct execution
- * boundaries, and this package gives each one its own entry point:
- *
- * - `@optique/testing/parser` runs a parser against an argument list without
- *   help rendering, process integration, or command dispatch.
- * - `@optique/testing/run` captures what `run()` and `runAsync()` write
- *   through their injected output callbacks, along with intentional exits.
- * - `@optique/testing/discover` captures a `runProgram()` invocation,
- *   including command discovery and handler dispatch.
- * - `@optique/testing/cli` invokes a real CLI entry point in a child process.
- *
- * This module holds only the contracts that mean the same thing at more than
- * one of those boundaries.  Results that differ by layer—parsed values,
- * intentional exits, terminating signals—belong to the subpath that produces
- * them.
- *
- * @module
- * @since 1.3.0
- */
-/**
- * Text captured from a program's standard output and standard error streams.
- *
- * The two streams are kept apart and their text is preserved exactly, so a
- * test can assert on trailing newlines and on which stream a message reached.
- * Each layer documents how it fills these fields: the in-process layers
- * accumulate the text their injected writers receive, while the subprocess
- * layer decodes whatever the child actually wrote.
- *
- * @since 1.3.0
- */
-interface CapturedOutput {
-  /**
-   * The text written to standard output.  Empty when nothing was written.
-   */
-  readonly stdout: string;
-  /**
-   * The text written to standard error.  Empty when nothing was written.
-   */
-  readonly stderr: string;
-}
-//#endregion
+import { CapturedOutput } from "./index-Cuf92ZIO.cjs";
 export { CapturedOutput };

package/dist/index.d.ts

@@ -1,46 +1,2 @@
-//#region src/index.d.ts
-/**
- * Testing support for Optique command-line interfaces.
- *
- * An Optique application can be exercised at four distinct execution
- * boundaries, and this package gives each one its own entry point:
- *
- * - `@optique/testing/parser` runs a parser against an argument list without
- *   help rendering, process integration, or command dispatch.
- * - `@optique/testing/run` captures what `run()` and `runAsync()` write
- *   through their injected output callbacks, along with intentional exits.
- * - `@optique/testing/discover` captures a `runProgram()` invocation,
- *   including command discovery and handler dispatch.
- * - `@optique/testing/cli` invokes a real CLI entry point in a child process.
- *
- * This module holds only the contracts that mean the same thing at more than
- * one of those boundaries.  Results that differ by layer—parsed values,
- * intentional exits, terminating signals—belong to the subpath that produces
- * them.
- *
- * @module
- * @since 1.3.0
- */
-/**
- * Text captured from a program's standard output and standard error streams.
- *
- * The two streams are kept apart and their text is preserved exactly, so a
- * test can assert on trailing newlines and on which stream a message reached.
- * Each layer documents how it fills these fields: the in-process layers
- * accumulate the text their injected writers receive, while the subprocess
- * layer decodes whatever the child actually wrote.
- *
- * @since 1.3.0
- */
-interface CapturedOutput {
-  /**
-   * The text written to standard output.  Empty when nothing was written.
-   */
-  readonly stdout: string;
-  /**
-   * The text written to standard error.  Empty when nothing was written.
-   */
-  readonly stderr: string;
-}
-//#endregion
+import { CapturedOutput } from "./index-t_PHSvz_.js";
 export { CapturedOutput };

package/dist/parser.cjs

@@ -0,0 +1,44 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const __optique_core_parser = require_chunk.__toESM(require("@optique/core/parser"));
+
+//#region src/parser.ts
+/**
+* Parses a complete argument list and always returns a promise.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser, or rejections from an asynchronous parser, reject the returned
+* promise.
+*
+* @template TParser The parser type, including its inferred result value.
+* @param parser The parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns A promise resolving to the parsed value or structured failure.
+* @since 1.3.0
+*/
+async function parseArgs(parser, args, options) {
+	return await (0, __optique_core_parser.parseDetailed)(parser, args, options);
+}
+/**
+* Parses a complete argument list with a synchronous parser.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser propagate to the caller.
+*
+* @template TParser The synchronous parser type, including its inferred result
+*                   value.
+* @param parser The synchronous parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns The parsed value or structured failure.
+* @throws {TypeError} When called with an asynchronous parser at runtime.
+* @since 1.3.0
+*/
+function parseArgsSync(parser, args, options) {
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with parseArgsSync(). Use parseArgs() instead.");
+	return (0, __optique_core_parser.parseDetailed)(parser, args, options);
+}
+
+//#endregion
+exports.parseArgs = parseArgs;
+exports.parseArgsSync = parseArgsSync;

package/dist/parser.d.cts

@@ -1 +1,44 @@
-export { };
+import { DetailedParseResult, InferValue, Mode, ParseOptions, Parser } from "@optique/core/parser";
+
+//#region src/parser.d.ts
+
+/**
+ * The result of parsing a complete argument list in a parser-layer test.
+ *
+ * @template T The inferred parser value type.
+ * @since 1.3.0
+ */
+type ParseArgsResult<T> = DetailedParseResult<T>;
+/**
+ * Parses a complete argument list and always returns a promise.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser, or rejections from an asynchronous parser, reject the returned
+ * promise.
+ *
+ * @template TParser The parser type, including its inferred result value.
+ * @param parser The parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns A promise resolving to the parsed value or structured failure.
+ * @since 1.3.0
+ */
+declare function parseArgs<TParser extends Parser<Mode, unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): Promise<ParseArgsResult<InferValue<TParser>>>;
+/**
+ * Parses a complete argument list with a synchronous parser.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser propagate to the caller.
+ *
+ * @template TParser The synchronous parser type, including its inferred result
+ *                   value.
+ * @param parser The synchronous parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns The parsed value or structured failure.
+ * @throws {TypeError} When called with an asynchronous parser at runtime.
+ * @since 1.3.0
+ */
+declare function parseArgsSync<TParser extends Parser<"sync", unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): ParseArgsResult<InferValue<TParser>>;
+//#endregion
+export { ParseArgsResult, parseArgs, parseArgsSync };

package/dist/parser.d.ts

@@ -1 +1,44 @@
-export { };
+import { DetailedParseResult, InferValue, Mode, ParseOptions, Parser } from "@optique/core/parser";
+
+//#region src/parser.d.ts
+
+/**
+ * The result of parsing a complete argument list in a parser-layer test.
+ *
+ * @template T The inferred parser value type.
+ * @since 1.3.0
+ */
+type ParseArgsResult<T> = DetailedParseResult<T>;
+/**
+ * Parses a complete argument list and always returns a promise.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser, or rejections from an asynchronous parser, reject the returned
+ * promise.
+ *
+ * @template TParser The parser type, including its inferred result value.
+ * @param parser The parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns A promise resolving to the parsed value or structured failure.
+ * @since 1.3.0
+ */
+declare function parseArgs<TParser extends Parser<Mode, unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): Promise<ParseArgsResult<InferValue<TParser>>>;
+/**
+ * Parses a complete argument list with a synchronous parser.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser propagate to the caller.
+ *
+ * @template TParser The synchronous parser type, including its inferred result
+ *                   value.
+ * @param parser The synchronous parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns The parsed value or structured failure.
+ * @throws {TypeError} When called with an asynchronous parser at runtime.
+ * @since 1.3.0
+ */
+declare function parseArgsSync<TParser extends Parser<"sync", unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): ParseArgsResult<InferValue<TParser>>;
+//#endregion
+export { ParseArgsResult, parseArgs, parseArgsSync };

package/dist/parser.js

@@ -0,0 +1,42 @@
+import { parseDetailed } from "@optique/core/parser";
+
+//#region src/parser.ts
+/**
+* Parses a complete argument list and always returns a promise.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser, or rejections from an asynchronous parser, reject the returned
+* promise.
+*
+* @template TParser The parser type, including its inferred result value.
+* @param parser The parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns A promise resolving to the parsed value or structured failure.
+* @since 1.3.0
+*/
+async function parseArgs(parser, args, options) {
+	return await parseDetailed(parser, args, options);
+}
+/**
+* Parses a complete argument list with a synchronous parser.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser propagate to the caller.
+*
+* @template TParser The synchronous parser type, including its inferred result
+*                   value.
+* @param parser The synchronous parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns The parsed value or structured failure.
+* @throws {TypeError} When called with an asynchronous parser at runtime.
+* @since 1.3.0
+*/
+function parseArgsSync(parser, args, options) {
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with parseArgsSync(). Use parseArgs() instead.");
+	return parseDetailed(parser, args, options);
+}
+
+//#endregion
+export { parseArgs, parseArgsSync };

package/dist/run.cjs

@@ -0,0 +1,49 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const __optique_run = require_chunk.__toESM(require("@optique/run"));
+
+//#region src/run.ts
+async function captureRun(parserOrProgram, options = {}) {
+	let stdout = "";
+	let stderr = "";
+	const runOptions = {
+		...options,
+		stdout(text) {
+			stdout += `${text}\n`;
+		},
+		stderr(text) {
+			stderr += `${text}\n`;
+		},
+		onExit(exitCode) {
+			throw new CapturedExit(exitCode);
+		}
+	};
+	try {
+		const value = "parser" in parserOrProgram && "metadata" in parserOrProgram ? await (0, __optique_run.runAsync)(parserOrProgram, runOptions) : await (0, __optique_run.runAsync)(parserOrProgram, runOptions);
+		return {
+			kind: "returned",
+			value,
+			exitCode: 0,
+			stdout,
+			stderr
+		};
+	} catch (error) {
+		if (!(error instanceof CapturedExit)) throw error;
+		return {
+			kind: "exited",
+			exitCode: error.exitCode,
+			stdout,
+			stderr
+		};
+	}
+}
+var CapturedExit = class extends Error {
+	exitCode;
+	constructor(exitCode) {
+		super(`Runner exited with code ${exitCode}.`);
+		this.name = "CapturedExit";
+		this.exitCode = exitCode;
+	}
+};
+
+//#endregion
+exports.captureRun = captureRun;

package/dist/run.d.cts

@@ -1 +1,80 @@
-export { };
+import { CapturedOutput } from "./index-Cuf92ZIO.cjs";
+import { InferValue, Mode, Parser } from "@optique/core/parser";
+import { SourceContext } from "@optique/core/context";
+import { ContextOptionsParam } from "@optique/core/facade";
+import { Program } from "@optique/core/program";
+import { RunOptions } from "@optique/run";
+
+//#region src/run.d.ts
+
+/**
+ * Options for {@link captureRun}.
+ *
+ * These are the options accepted by `runAsync()`, except for the output and
+ * exit callbacks controlled by the capture helper.
+ *
+ * @since 1.3.0
+ */
+type CaptureRunOptions = Omit<RunOptions, "stdout" | "stderr" | "onExit"> & {
+  readonly stdout?: never;
+  readonly stderr?: never;
+  readonly onExit?: never;
+};
+/**
+ * The result of an in-process runner execution.
+ *
+ * A normal parser return includes its inferred value.  Help, version,
+ * completion, and parse-error exits instead include the requested exit code.
+ * Both variants preserve the output written through the runner callbacks.
+ *
+ * @template T The inferred parser value type.
+ * @since 1.3.0
+ */
+type CapturedRunResult<T> = CapturedOutput & ({
+  readonly kind: "returned";
+  readonly value: T;
+  readonly exitCode: 0;
+} | {
+  readonly kind: "exited";
+  readonly exitCode: number;
+});
+type RejectEmptyContexts<TContexts extends readonly SourceContext<unknown>[]> = TContexts extends readonly [] ? never : unknown;
+type ContextsFromOptions<TOptions> = [Exclude<TOptions, undefined>] extends [never] ? undefined : Exclude<TOptions, undefined> extends {
+  readonly contexts?: infer TContexts extends readonly SourceContext<unknown>[] | undefined;
+} ? TContexts : undefined;
+type RejectContextfulOptions<TOptions> = [ContextsFromOptions<TOptions>] extends [undefined | readonly []] ? unknown : never;
+type RejectUnknownCaptureRunOptionKeys<TOptions> = [TOptions] extends [undefined] ? unknown : Exclude<keyof TOptions, keyof CaptureRunOptions> extends never ? unknown : never;
+type AcceptExactCaptureRunOptions<TOptions> = [TOptions] extends [CaptureRunOptions] ? [CaptureRunOptions] extends [TOptions] ? unknown : never : never;
+type AcceptExactOptionalCaptureRunOptions<TOptions> = [TOptions] extends [CaptureRunOptions | undefined] ? [CaptureRunOptions | undefined] extends [TOptions] ? unknown : never : never;
+/**
+ * Runs a parser or program in process and captures runner-controlled output.
+ *
+ * The helper always returns a promise.  Parser returns become `returned`
+ * results, while intentional help, version, completion, and parse-error exits
+ * become `exited` results.  Writes that bypass the injected callbacks, such as
+ * `console.log()` or direct process-stream writes, are not captured.
+ * `colors` and `maxWidth` retain `runAsync()`'s terminal-dependent defaults,
+ * so set both explicitly when asserting rendered text.
+ *
+ * @template T The parser or program result type.
+ * @param parser The parser or `Program` to execute.
+ * @param options Runner options other than the captured callbacks.
+ * @returns A promise resolving to the returned value or intentional exit,
+ *          together with captured standard output and standard error.
+ * @throws Any unexpected parser, context, callback, or disposal error.  Promise
+ *         rejections from asynchronous parsers and contexts also propagate.
+ * @since 1.3.0
+ */
+declare function captureRun<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: CaptureRunOptions & {
+  readonly contexts: TContexts;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<CapturedRunResult<InferValue<T>>>;
+declare function captureRun<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: CaptureRunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, const TOptions extends CaptureRunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownCaptureRunOptionKeys<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, const TOptions extends CaptureRunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownCaptureRunOptionKeys<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, TOptions extends CaptureRunOptions>(program: Program<Mode, T>, options: TOptions & AcceptExactCaptureRunOptions<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, TOptions extends CaptureRunOptions | undefined>(program: Program<Mode, T>, options: TOptions & AcceptExactOptionalCaptureRunOptions<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: CaptureRunOptions): Promise<CapturedRunResult<InferValue<T>>>;
+//#endregion
+export { CaptureRunOptions, CapturedRunResult, captureRun };

package/dist/run.d.ts

@@ -1 +1,80 @@
-export { };
+import { CapturedOutput } from "./index-t_PHSvz_.js";
+import { InferValue, Mode, Parser } from "@optique/core/parser";
+import { RunOptions } from "@optique/run";
+import { SourceContext } from "@optique/core/context";
+import { ContextOptionsParam } from "@optique/core/facade";
+import { Program } from "@optique/core/program";
+
+//#region src/run.d.ts
+
+/**
+ * Options for {@link captureRun}.
+ *
+ * These are the options accepted by `runAsync()`, except for the output and
+ * exit callbacks controlled by the capture helper.
+ *
+ * @since 1.3.0
+ */
+type CaptureRunOptions = Omit<RunOptions, "stdout" | "stderr" | "onExit"> & {
+  readonly stdout?: never;
+  readonly stderr?: never;
+  readonly onExit?: never;
+};
+/**
+ * The result of an in-process runner execution.
+ *
+ * A normal parser return includes its inferred value.  Help, version,
+ * completion, and parse-error exits instead include the requested exit code.
+ * Both variants preserve the output written through the runner callbacks.
+ *
+ * @template T The inferred parser value type.
+ * @since 1.3.0
+ */
+type CapturedRunResult<T> = CapturedOutput & ({
+  readonly kind: "returned";
+  readonly value: T;
+  readonly exitCode: 0;
+} | {
+  readonly kind: "exited";
+  readonly exitCode: number;
+});
+type RejectEmptyContexts<TContexts extends readonly SourceContext<unknown>[]> = TContexts extends readonly [] ? never : unknown;
+type ContextsFromOptions<TOptions> = [Exclude<TOptions, undefined>] extends [never] ? undefined : Exclude<TOptions, undefined> extends {
+  readonly contexts?: infer TContexts extends readonly SourceContext<unknown>[] | undefined;
+} ? TContexts : undefined;
+type RejectContextfulOptions<TOptions> = [ContextsFromOptions<TOptions>] extends [undefined | readonly []] ? unknown : never;
+type RejectUnknownCaptureRunOptionKeys<TOptions> = [TOptions] extends [undefined] ? unknown : Exclude<keyof TOptions, keyof CaptureRunOptions> extends never ? unknown : never;
+type AcceptExactCaptureRunOptions<TOptions> = [TOptions] extends [CaptureRunOptions] ? [CaptureRunOptions] extends [TOptions] ? unknown : never : never;
+type AcceptExactOptionalCaptureRunOptions<TOptions> = [TOptions] extends [CaptureRunOptions | undefined] ? [CaptureRunOptions | undefined] extends [TOptions] ? unknown : never : never;
+/**
+ * Runs a parser or program in process and captures runner-controlled output.
+ *
+ * The helper always returns a promise.  Parser returns become `returned`
+ * results, while intentional help, version, completion, and parse-error exits
+ * become `exited` results.  Writes that bypass the injected callbacks, such as
+ * `console.log()` or direct process-stream writes, are not captured.
+ * `colors` and `maxWidth` retain `runAsync()`'s terminal-dependent defaults,
+ * so set both explicitly when asserting rendered text.
+ *
+ * @template T The parser or program result type.
+ * @param parser The parser or `Program` to execute.
+ * @param options Runner options other than the captured callbacks.
+ * @returns A promise resolving to the returned value or intentional exit,
+ *          together with captured standard output and standard error.
+ * @throws Any unexpected parser, context, callback, or disposal error.  Promise
+ *         rejections from asynchronous parsers and contexts also propagate.
+ * @since 1.3.0
+ */
+declare function captureRun<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: CaptureRunOptions & {
+  readonly contexts: TContexts;
+} & ContextOptionsParam<TContexts, InferValue<T>>): Promise<CapturedRunResult<InferValue<T>>>;
+declare function captureRun<M extends Mode, T, const TContexts extends readonly SourceContext<unknown>[]>(program: Program<M, T>, options: CaptureRunOptions & {
+  readonly contexts: TContexts;
+} & RejectEmptyContexts<TContexts> & ContextOptionsParam<TContexts, T>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, const TOptions extends CaptureRunOptions | undefined>(program: Program<"sync", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownCaptureRunOptionKeys<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, const TOptions extends CaptureRunOptions | undefined>(program: Program<"async", T>, options?: TOptions & RejectContextfulOptions<TOptions> & RejectUnknownCaptureRunOptionKeys<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, TOptions extends CaptureRunOptions>(program: Program<Mode, T>, options: TOptions & AcceptExactCaptureRunOptions<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T, TOptions extends CaptureRunOptions | undefined>(program: Program<Mode, T>, options: TOptions & AcceptExactOptionalCaptureRunOptions<TOptions>): Promise<CapturedRunResult<T>>;
+declare function captureRun<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: CaptureRunOptions): Promise<CapturedRunResult<InferValue<T>>>;
+//#endregion
+export { CaptureRunOptions, CapturedRunResult, captureRun };

package/dist/run.js

@@ -0,0 +1,48 @@
+import { runAsync } from "@optique/run";
+
+//#region src/run.ts
+async function captureRun(parserOrProgram, options = {}) {
+	let stdout = "";
+	let stderr = "";
+	const runOptions = {
+		...options,
+		stdout(text) {
+			stdout += `${text}\n`;
+		},
+		stderr(text) {
+			stderr += `${text}\n`;
+		},
+		onExit(exitCode) {
+			throw new CapturedExit(exitCode);
+		}
+	};
+	try {
+		const value = "parser" in parserOrProgram && "metadata" in parserOrProgram ? await runAsync(parserOrProgram, runOptions) : await runAsync(parserOrProgram, runOptions);
+		return {
+			kind: "returned",
+			value,
+			exitCode: 0,
+			stdout,
+			stderr
+		};
+	} catch (error) {
+		if (!(error instanceof CapturedExit)) throw error;
+		return {
+			kind: "exited",
+			exitCode: error.exitCode,
+			stdout,
+			stderr
+		};
+	}
+}
+var CapturedExit = class extends Error {
+	exitCode;
+	constructor(exitCode) {
+		super(`Runner exited with code ${exitCode}.`);
+		this.name = "CapturedExit";
+		this.exitCode = exitCode;
+	}
+};
+
+//#endregion
+export { captureRun };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/testing",
-  "version": "1.3.0-dev.2488",
+  "version": "1.3.0-dev.2497",
   "description": "Testing support for Optique command-line interfaces",
   "keywords": [
     "CLI",
@@ -85,6 +85,11 @@
     }
   },
   "sideEffects": false,
+  "dependencies": {
+    "@optique/core": "1.3.0-dev.2497+23bea5fb",
+    "@optique/discover": "1.3.0-dev.2497+23bea5fb",
+    "@optique/run": "1.3.0-dev.2497+23bea5fb"
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",