@optique/testing 1.3.0-dev.2499 → 1.3.0-dev.2510

package/dist/cli.d.cts

@@ -1 +1,131 @@
-export { };
+import { CapturedOutput } from "./index-Cuf92ZIO.cjs";
+
+//#region src/cli.d.ts
+interface ProcessOptions {
+  /** Working directory, relative to the runner's original base directory. */
+  readonly cwd?: string | URL;
+  /**
+   * Environment overrides.  Undefined omits the variable from the supplied
+   * environment; the runtime or operating system may restore system variables.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Milliseconds including output collection; defaults to 5000.  Zero disables. */
+  readonly timeout?: number;
+  /** Cancellation signal, replacing the runner's default when supplied. */
+  readonly signal?: AbortSignal;
+  /** Failure cleanup target; defaults to the directly launched child. */
+  readonly cleanup?: "child" | "tree";
+}
+/**
+ * A current-runtime entry point or an explicit executable and fixed arguments.
+ * Relative entry points are resolved once against the factory's working
+ * directory.  Runtime arguments and permissions are never inherited implicitly.
+ *
+ * @since 1.3.0
+ */
+type CliRunnerOptions = ProcessOptions & ({
+  /** File path or file URL to execute with the current runtime. */
+  readonly entrypoint: string | URL;
+  /** Runtime flags before the entry point; Deno flags follow `run`. */
+  readonly runtimeArgs?: readonly string[];
+  readonly command?: never;
+} | {
+  /** Executable followed by fixed arguments, passed without a shell. */
+  readonly command: readonly [string, ...string[]];
+  readonly entrypoint?: never;
+  readonly runtimeArgs?: never;
+});
+/**
+ * Inputs and default overrides for one CLI invocation.
+ *
+ * @since 1.3.0
+ */
+interface CliInvocationOptions extends ProcessOptions {
+  /** Arguments appended verbatim to the runner's command. */
+  readonly args?: readonly string[];
+  /** UTF-8 input.  The input pipe is closed even when this is omitted. */
+  readonly stdin?: string;
+}
+/**
+ * Complete captured output and the runtime's reported process status.
+ * Nonzero exit codes and external signal termination are results, not errors.
+ *
+ * @since 1.3.0
+ */
+interface CliResult extends CapturedOutput {
+  /** Exit code, or null when the process terminated through a signal. */
+  readonly exitCode: number | null;
+  /** Terminating signal, or null; reporting depends on the OS and runtime. */
+  readonly signal: string | null;
+}
+/**
+ * A failure of the invocation harness, with partial output and observed status.
+ * Cleanup failures retain the original failure and cleanup errors in an
+ * `AggregateError` cause.  A status can be null when no exit was observed.
+ *
+ * @since 1.3.0
+ */
+declare class CliInvocationError extends Error implements CliResult {
+  /** Whether launching, waiting, cancellation, I/O, or cleanup failed. */
+  readonly reason: "spawn" | "timeout" | "aborted" | "io" | "cleanup";
+  /** Standard output collected before the invocation finished cleaning up. */
+  readonly stdout: string;
+  /** Standard error collected before the invocation finished cleaning up. */
+  readonly stderr: string;
+  /** Observed exit code, including during cleanup, or null. */
+  readonly exitCode: number | null;
+  /** Observed terminating signal, including during cleanup, or null. */
+  readonly signal: string | null;
+  /**
+   * Constructs a harness failure from its captured state.
+   * @param reason The stage that failed.
+   * @param message A description of the failure.
+   * @param result Captured text and observed process status.
+   * @param options The underlying cause, if any.
+   */
+  constructor(reason: CliInvocationError["reason"], message: string, result: CliResult, options?: ErrorOptions);
+}
+/**
+ * A reusable runner whose invocations have independent process state.
+ *
+ * @since 1.3.0
+ */
+interface CliRunner {
+  /**
+   * Invokes the CLI with positional arguments or explicit process inputs.
+   * @param args Arguments to append, or invocation options.
+   * @returns Exact output and process status after all output has been read.
+   * @throws {TypeError} If invocation options have an invalid shape.
+   * @throws {RangeError} If the timeout is outside its supported range.
+   * @throws {CliInvocationError} If starting, capturing, or cleaning up fails.
+   */
+  readonly invoke: {
+    (...args: readonly string[]): Promise<CliResult>;
+    (options: CliInvocationOptions): Promise<CliResult>;
+  };
+}
+/**
+ * Creates a runner for a real CLI without building or installing its target.
+ *
+ * Output is UTF-8 text, kept separate and unmodified.  The default timeout is
+ * five seconds, including output collection; zero waits indefinitely unless
+ * aborted.  Failure cleanup targets the child by default, or its ordinary
+ * process tree when requested.  Tree cleanup uses POSIX groups or Windows
+ * taskkill and cannot contain escaped or already-orphaned descendants.  Normal
+ * completion does not sweep descendants.  Abrupt termination of the test
+ * process itself is outside this cleanup contract.
+ *
+ * Deno callers must grant the harness read, environment, and subprocess
+ * permissions.  Child permissions belong in `runtimeArgs`.  No color settings,
+ * runtime flags, or parent `execArgv` are injected.
+ *
+ * @param options An entry point or command and invocation defaults.
+ * @returns A reusable runner with isolated invocations.
+ * @throws {TypeError} If the command, paths, or options are invalid.
+ * @throws {RangeError} If the timeout is outside its supported range.
+ * @throws If reading the factory's working directory is not permitted.
+ * @since 1.3.0
+ */
+declare function createCliRunner(options: CliRunnerOptions): CliRunner;
+//#endregion
+export { CliInvocationError, CliInvocationOptions, CliResult, CliRunner, CliRunnerOptions, createCliRunner };

package/dist/cli.d.ts

@@ -1 +1,131 @@
-export { };
+import { CapturedOutput } from "./index-t_PHSvz_.js";
+
+//#region src/cli.d.ts
+interface ProcessOptions {
+  /** Working directory, relative to the runner's original base directory. */
+  readonly cwd?: string | URL;
+  /**
+   * Environment overrides.  Undefined omits the variable from the supplied
+   * environment; the runtime or operating system may restore system variables.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Milliseconds including output collection; defaults to 5000.  Zero disables. */
+  readonly timeout?: number;
+  /** Cancellation signal, replacing the runner's default when supplied. */
+  readonly signal?: AbortSignal;
+  /** Failure cleanup target; defaults to the directly launched child. */
+  readonly cleanup?: "child" | "tree";
+}
+/**
+ * A current-runtime entry point or an explicit executable and fixed arguments.
+ * Relative entry points are resolved once against the factory's working
+ * directory.  Runtime arguments and permissions are never inherited implicitly.
+ *
+ * @since 1.3.0
+ */
+type CliRunnerOptions = ProcessOptions & ({
+  /** File path or file URL to execute with the current runtime. */
+  readonly entrypoint: string | URL;
+  /** Runtime flags before the entry point; Deno flags follow `run`. */
+  readonly runtimeArgs?: readonly string[];
+  readonly command?: never;
+} | {
+  /** Executable followed by fixed arguments, passed without a shell. */
+  readonly command: readonly [string, ...string[]];
+  readonly entrypoint?: never;
+  readonly runtimeArgs?: never;
+});
+/**
+ * Inputs and default overrides for one CLI invocation.
+ *
+ * @since 1.3.0
+ */
+interface CliInvocationOptions extends ProcessOptions {
+  /** Arguments appended verbatim to the runner's command. */
+  readonly args?: readonly string[];
+  /** UTF-8 input.  The input pipe is closed even when this is omitted. */
+  readonly stdin?: string;
+}
+/**
+ * Complete captured output and the runtime's reported process status.
+ * Nonzero exit codes and external signal termination are results, not errors.
+ *
+ * @since 1.3.0
+ */
+interface CliResult extends CapturedOutput {
+  /** Exit code, or null when the process terminated through a signal. */
+  readonly exitCode: number | null;
+  /** Terminating signal, or null; reporting depends on the OS and runtime. */
+  readonly signal: string | null;
+}
+/**
+ * A failure of the invocation harness, with partial output and observed status.
+ * Cleanup failures retain the original failure and cleanup errors in an
+ * `AggregateError` cause.  A status can be null when no exit was observed.
+ *
+ * @since 1.3.0
+ */
+declare class CliInvocationError extends Error implements CliResult {
+  /** Whether launching, waiting, cancellation, I/O, or cleanup failed. */
+  readonly reason: "spawn" | "timeout" | "aborted" | "io" | "cleanup";
+  /** Standard output collected before the invocation finished cleaning up. */
+  readonly stdout: string;
+  /** Standard error collected before the invocation finished cleaning up. */
+  readonly stderr: string;
+  /** Observed exit code, including during cleanup, or null. */
+  readonly exitCode: number | null;
+  /** Observed terminating signal, including during cleanup, or null. */
+  readonly signal: string | null;
+  /**
+   * Constructs a harness failure from its captured state.
+   * @param reason The stage that failed.
+   * @param message A description of the failure.
+   * @param result Captured text and observed process status.
+   * @param options The underlying cause, if any.
+   */
+  constructor(reason: CliInvocationError["reason"], message: string, result: CliResult, options?: ErrorOptions);
+}
+/**
+ * A reusable runner whose invocations have independent process state.
+ *
+ * @since 1.3.0
+ */
+interface CliRunner {
+  /**
+   * Invokes the CLI with positional arguments or explicit process inputs.
+   * @param args Arguments to append, or invocation options.
+   * @returns Exact output and process status after all output has been read.
+   * @throws {TypeError} If invocation options have an invalid shape.
+   * @throws {RangeError} If the timeout is outside its supported range.
+   * @throws {CliInvocationError} If starting, capturing, or cleaning up fails.
+   */
+  readonly invoke: {
+    (...args: readonly string[]): Promise<CliResult>;
+    (options: CliInvocationOptions): Promise<CliResult>;
+  };
+}
+/**
+ * Creates a runner for a real CLI without building or installing its target.
+ *
+ * Output is UTF-8 text, kept separate and unmodified.  The default timeout is
+ * five seconds, including output collection; zero waits indefinitely unless
+ * aborted.  Failure cleanup targets the child by default, or its ordinary
+ * process tree when requested.  Tree cleanup uses POSIX groups or Windows
+ * taskkill and cannot contain escaped or already-orphaned descendants.  Normal
+ * completion does not sweep descendants.  Abrupt termination of the test
+ * process itself is outside this cleanup contract.
+ *
+ * Deno callers must grant the harness read, environment, and subprocess
+ * permissions.  Child permissions belong in `runtimeArgs`.  No color settings,
+ * runtime flags, or parent `execArgv` are injected.
+ *
+ * @param options An entry point or command and invocation defaults.
+ * @returns A reusable runner with isolated invocations.
+ * @throws {TypeError} If the command, paths, or options are invalid.
+ * @throws {RangeError} If the timeout is outside its supported range.
+ * @throws If reading the factory's working directory is not permitted.
+ * @since 1.3.0
+ */
+declare function createCliRunner(options: CliRunnerOptions): CliRunner;
+//#endregion
+export { CliInvocationError, CliInvocationOptions, CliResult, CliRunner, CliRunnerOptions, createCliRunner };