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

package/README.md

@@ -70,9 +70,29 @@ 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.
+Use `createCliRunner()` to capture the complete process, including direct
+console writes and application exit codes:
+
+~~~~ typescript
+import { createCliRunner } from "@optique/testing/cli";
+
+const cli = createCliRunner({
+  entrypoint: new URL("./cli.mjs", import.meta.url),
+});
+const result = await cli.invoke("--help");
+console.log(result.exitCode, result.signal, result.stdout, result.stderr);
+~~~~
+
+The runner uses the current runtime.  Set `runtimeArgs` for explicit runtime
+flags, including Deno permissions, or use `command: ["node", "./cli.mjs"]`
+for a specific executable.  Calls accept stdin, cwd, environment overrides,
+and cancellation.  The default timeout is five seconds; `timeout: 0` disables
+it.  Nonzero exits return results; execution failures, timeouts, and
+cancellation reject with `CliInvocationError`, including partial output.
+See the [testing guide] for process-tree cleanup and runtime details.
 
 [Optique]: https://optique.dev/
+[testing guide]: https://optique.dev/concepts/testing
 
 
 Installation
@@ -92,5 +112,3 @@ Documentation
 
 For full documentation, visit the [testing guide], which explains what each
 layer does and does not execute, and how to choose between them.
-
-[testing guide]: https://optique.dev/concepts/testing

package/dist/cli.cjs

@@ -0,0 +1,551 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const node_child_process = require_chunk.__toESM(require("node:child_process"));
+const node_path = require_chunk.__toESM(require("node:path"));
+const node_process = require_chunk.__toESM(require("node:process"));
+const node_url = require_chunk.__toESM(require("node:url"));
+const node_events = require_chunk.__toESM(require("node:events"));
+const node_stream = require_chunk.__toESM(require("node:stream"));
+
+//#region src/cli-process.ts
+function isDenoRuntime(value) {
+	return typeof value === "object" && value !== null && "Command" in value && typeof value.Command === "function";
+}
+/**
+* Uses Deno's native asynchronous pipes when available.
+* Kept separate so its real I/O can also be tested on non-Windows Deno hosts.
+* @param command Executable path.
+* @param args Literal command arguments.
+* @param options Working directory and complete child environment.
+* @returns A process adapter, or undefined outside Deno.
+* @throws If Deno cannot start the requested executable.
+*/
+function spawnDenoProcess(command, args, options) {
+	const runtime = "Deno" in globalThis ? globalThis.Deno : void 0;
+	if (!isDenoRuntime(runtime)) return;
+	const native = new runtime.Command(command, {
+		args,
+		cwd: options.cwd,
+		env: options.env,
+		clearEnv: true,
+		stdin: "piped",
+		stdout: "piped",
+		stderr: "piped",
+		windowsHide: true
+	}).spawn();
+	const stdin = node_stream.Writable.fromWeb(native.stdin);
+	const stdout = node_stream.Readable.fromWeb(native.stdout);
+	const stderr = node_stream.Readable.fromWeb(native.stderr);
+	const child = Object.assign(new node_events.EventEmitter(), {
+		pid: native.pid,
+		stdin,
+		stdout,
+		stderr,
+		kill(signal = "SIGTERM") {
+			native.kill(signal);
+			return true;
+		},
+		unref() {
+			native.unref();
+		}
+	});
+	let exited = false;
+	let closed = false;
+	let closedStreams = 0;
+	const maybeClose = () => {
+		if (exited && closedStreams === 3 && !closed) {
+			closed = true;
+			child.emit("close");
+		}
+	};
+	for (const stream of [
+		stdin,
+		stdout,
+		stderr
+	]) stream.once("close", () => {
+		closedStreams++;
+		maybeClose();
+	});
+	queueMicrotask(() => child.emit("spawn"));
+	native.status.then((status) => {
+		exited = true;
+		child.emit("exit", status.signal === null ? status.code : null, status.signal);
+		stdin.destroy();
+		maybeClose();
+	}, (error) => {
+		exited = true;
+		child.emit("error", error);
+		maybeClose();
+	});
+	return child;
+}
+/**
+* Launches a CLI with pipes that leave the host event loop responsive.
+* @param command Executable path.
+* @param args Literal command arguments.
+* @param options Working directory, environment, and process group settings.
+* @returns The launched process and its three streams.
+* @throws If the runtime rejects the launch synchronously.
+*/
+function spawnCliProcess(command, args, options) {
+	if (node_process.default.platform === "win32") {
+		const native = spawnDenoProcess(command, args, options);
+		if (native !== void 0) return native;
+	}
+	return (0, node_child_process.spawn)(command, [...args], {
+		...options,
+		shell: false,
+		stdio: "pipe",
+		windowsHide: true
+	});
+}
+
+//#endregion
+//#region src/cli.ts
+/**
+* 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
+*/
+var CliInvocationError = class extends Error {
+	/** Whether launching, waiting, cancellation, I/O, or cleanup failed. */
+	reason;
+	/** Standard output collected before the invocation finished cleaning up. */
+	stdout;
+	/** Standard error collected before the invocation finished cleaning up. */
+	stderr;
+	/** Observed exit code, including during cleanup, or null. */
+	exitCode;
+	/** Observed terminating signal, including during cleanup, or null. */
+	signal;
+	/**
+	* 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, message, result, options) {
+		super(message, options);
+		this.name = "CliInvocationError";
+		this.reason = reason;
+		this.stdout = result.stdout;
+		this.stderr = result.stderr;
+		this.exitCode = result.exitCode;
+		this.signal = result.signal;
+	}
+};
+const emptyResult = {
+	stdout: "",
+	stderr: "",
+	exitCode: null,
+	signal: null
+};
+function filePath(value) {
+	if (value instanceof URL) return (0, node_url.fileURLToPath)(value);
+	if (typeof value !== "string") throw new TypeError("Expected a file path or URL.");
+	return value;
+}
+function strings(value) {
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new TypeError("Expected an array of strings.");
+	return [...value];
+}
+function validate(options) {
+	if (options == null || typeof options !== "object" || Array.isArray(options)) throw new TypeError("Expected process options.");
+	if (options.timeout !== void 0 && (!Number.isInteger(options.timeout) || options.timeout < 0 || options.timeout > 2147483647)) throw new RangeError("Timeout must be an integer between 0 and 2147483647.");
+	if (options.cleanup !== void 0 && options.cleanup !== "child" && options.cleanup !== "tree") throw new TypeError("Cleanup must be child or tree.");
+	if (options.cwd !== void 0) filePath(options.cwd);
+	if (options.env !== void 0 && (options.env === null || typeof options.env !== "object" || Array.isArray(options.env) || Object.values(options.env).some((v) => v !== void 0 && typeof v !== "string"))) throw new TypeError("Environment values must be strings or undefined.");
+	if (options.signal !== void 0 && (options.signal == null || typeof options.signal.aborted !== "boolean" || typeof options.signal.addEventListener !== "function" || typeof options.signal.removeEventListener !== "function")) throw new TypeError("Expected an AbortSignal.");
+}
+function environment(...layers) {
+	const result = Object.create(null);
+	const names = /* @__PURE__ */ new Map();
+	for (const layer of layers) {
+		if (layer === void 0) continue;
+		for (const [name, value] of Object.entries(layer)) {
+			const key = node_process.default.platform === "win32" ? name.toUpperCase() : name;
+			const previous = names.get(key);
+			if (previous !== void 0) delete result[previous];
+			names.set(key, name);
+			if (value !== void 0) result[name] = value;
+		}
+	}
+	return result;
+}
+/**
+* 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
+*/
+function createCliRunner(options) {
+	validate(options);
+	const hasCommand = options.command !== void 0;
+	if (hasCommand === (options.entrypoint !== void 0) || hasCommand && options.runtimeArgs !== void 0) throw new TypeError("Specify either an entrypoint or a command.");
+	const base = (0, node_path.resolve)(options.cwd === void 0 ? node_process.default.cwd() : filePath(options.cwd));
+	let fixed;
+	let entrypoint;
+	if (options.command !== void 0) {
+		fixed = strings(options.command);
+		if (fixed.length === 0 || fixed[0].length === 0) throw new TypeError("Command must contain a nonempty executable.");
+	} else entrypoint = (0, node_path.resolve)(base, filePath(options.entrypoint));
+	const runtimeArgs = strings(options.runtimeArgs ?? []);
+	const defaults = {
+		timeout: options.timeout ?? 5e3,
+		signal: options.signal,
+		cleanup: options.cleanup ?? "child",
+		env: options.env === void 0 ? void 0 : { ...options.env }
+	};
+	async function invoke(...input) {
+		let call;
+		if (input.length === 1 && typeof input[0] === "object") call = input[0];
+		else {
+			const args$1 = [];
+			for (const item of input) {
+				if (typeof item !== "string") throw new TypeError("Arguments must be strings.");
+				args$1.push(item);
+			}
+			call = { args: args$1 };
+		}
+		validate(call);
+		const args = strings(call.args ?? []);
+		if (call.stdin !== void 0 && typeof call.stdin !== "string") throw new TypeError("Stdin must be a string.");
+		const signal = call.signal ?? defaults.signal;
+		if (signal?.aborted) throw new CliInvocationError("aborted", "CLI invocation was aborted.", emptyResult, { cause: signal.reason });
+		try {
+			const command = fixed ?? [
+				node_process.default.execPath,
+				..."Deno" in globalThis ? ["run"] : [],
+				...runtimeArgs,
+				...entrypoint === void 0 ? [] : [entrypoint]
+			];
+			return await runProcess(command[0], [...command.slice(1), ...args], {
+				cwd: call.cwd === void 0 ? base : (0, node_path.resolve)(base, filePath(call.cwd)),
+				env: environment(node_process.default.env, defaults.env, call.env),
+				timeout: call.timeout ?? defaults.timeout,
+				cleanup: call.cleanup ?? defaults.cleanup,
+				signal,
+				stdin: call.stdin ?? ""
+			});
+		} catch (cause) {
+			if (cause instanceof CliInvocationError) throw cause;
+			throw new CliInvocationError("spawn", "Could not start the CLI.", emptyResult, { cause });
+		}
+	}
+	return Object.freeze({ invoke });
+}
+function errorCode(error) {
+	return error !== null && typeof error === "object" && "code" in error ? error.code : void 0;
+}
+function runProcess(command, args, options) {
+	return new Promise((resolveResult, reject) => {
+		let child;
+		let spawned = false;
+		let exited = false;
+		let closed = false;
+		let outEnd = false;
+		let errEnd = false;
+		let outClose = false;
+		let errClose = false;
+		let inClose = false;
+		let exitCode = null;
+		let signal = null;
+		const stdout = [];
+		const stderr = [];
+		let settled = false;
+		let failure;
+		const cleanupErrors = [];
+		let timer;
+		const waiters = /* @__PURE__ */ new Set();
+		const snapshot = () => ({
+			stdout: stdout.join(""),
+			stderr: stderr.join(""),
+			exitCode,
+			signal
+		});
+		const onAbort = () => fail("aborted", "CLI invocation was aborted.", options.signal?.reason);
+		const clearInvocation = () => {
+			clearTimeout(timer);
+			options.signal?.removeEventListener("abort", onAbort);
+		};
+		function release() {
+			clearInvocation();
+			child?.stdout.removeListener("data", onOut);
+			child?.stderr.removeListener("data", onErr);
+			if (closed) child?.removeListener("error", onError);
+			if (outClose) child?.stdout.removeListener("error", onIoError);
+			if (errClose) child?.stderr.removeListener("error", onIoError);
+			if (inClose) child?.stdin.removeListener("error", onInputError);
+		}
+		function update() {
+			for (const wake of [...waiters]) wake();
+			if (settled) {
+				release();
+				return;
+			}
+			if (!failure && exited && closed && outEnd && errEnd && outClose && errClose && inClose) {
+				settled = true;
+				release();
+				resolveResult(snapshot());
+			}
+		}
+		function waitFor(predicate, milliseconds) {
+			if (predicate()) return Promise.resolve(true);
+			return new Promise((done) => {
+				const finish = (value) => {
+					clearTimeout(timeout);
+					waiters.delete(wake);
+					done(value);
+				};
+				const wake = () => {
+					if (predicate()) finish(true);
+				};
+				const timeout = setTimeout(() => finish(false), Math.max(0, milliseconds));
+				waiters.add(wake);
+			});
+		}
+		function fail(reason, message, cause) {
+			if (failure || settled) return;
+			failure = {
+				reason,
+				message,
+				cause
+			};
+			clearInvocation();
+			queueMicrotask(() => {
+				cleanup();
+			});
+		}
+		function killChild(kind) {
+			if (!child?.pid || exited || closed) return;
+			try {
+				child.kill(kind);
+			} catch (error) {
+				cleanupErrors.push(error);
+			}
+		}
+		function groupSignal(kind) {
+			if (!child?.pid) return false;
+			try {
+				node_process.default.kill(-child.pid, kind);
+				return true;
+			} catch (error) {
+				if (errorCode(error) !== "ESRCH") cleanupErrors.push(error);
+				return false;
+			}
+		}
+		async function taskkill(deadline) {
+			let helper;
+			const root = node_process.default.env.SystemRoot ?? node_process.default.env.windir;
+			if (root === void 0 || !(0, node_path.isAbsolute)(root)) {
+				cleanupErrors.push(/* @__PURE__ */ new Error("Windows system directory is unavailable."));
+				killChild("SIGKILL");
+				return;
+			}
+			try {
+				helper = (0, node_child_process.spawn)((0, node_path.join)(root, "System32", "taskkill.exe"), [
+					"/PID",
+					String(child?.pid),
+					"/T",
+					"/F"
+				], {
+					shell: false,
+					windowsHide: true,
+					stdio: "pipe"
+				});
+			} catch (error) {
+				cleanupErrors.push(error);
+				killChild("SIGKILL");
+				return;
+			}
+			let helperClosed = false;
+			let helperError;
+			let helperCode = null;
+			let diagnostic = "";
+			helper.stdout.resume();
+			helper.stderr.setEncoding("utf8");
+			helper.stderr.on("data", (text) => {
+				diagnostic += text;
+			});
+			helper.stdin.on("error", () => {});
+			helper.stdout.on("error", (error) => {
+				helperError = error;
+			});
+			helper.stderr.on("error", (error) => {
+				helperError = error;
+			});
+			helper.on("error", (error) => {
+				helperError = error;
+				killChild("SIGKILL");
+			});
+			helper.on("close", (code) => {
+				helperClosed = true;
+				helperCode = code;
+				update();
+			});
+			helper.stdin.end();
+			if (!await waitFor(() => helperClosed, Math.min(1e3, deadline - Date.now()))) {
+				cleanupErrors.push(/* @__PURE__ */ new Error("Tree cleanup command timed out."));
+				try {
+					helper.kill("SIGKILL");
+				} catch (error) {
+					cleanupErrors.push(error);
+				}
+				killChild("SIGKILL");
+				helper.stdin.destroy();
+				helper.stdout.destroy();
+				helper.stderr.destroy();
+				if (!await waitFor(() => helperClosed, deadline - Date.now())) {
+					cleanupErrors.push(/* @__PURE__ */ new Error("Tree cleanup command did not close."));
+					helper.unref();
+				}
+			} else if (helperError !== void 0 || helperCode !== 0) {
+				cleanupErrors.push(helperError ?? /* @__PURE__ */ new Error(`Tree cleanup exited with code ${helperCode}: ${diagnostic}`));
+				killChild("SIGKILL");
+			}
+		}
+		async function cleanup() {
+			const deadline = Date.now() + 2e3;
+			try {
+				if (child !== void 0) {
+					child.stdin.destroy();
+					if (child.pid !== void 0) if (node_process.default.platform === "win32") if (options.cleanup === "tree") if (exited || closed) cleanupErrors.push(/* @__PURE__ */ new Error("Cannot trace a Windows process tree after its root exits."));
+					else await taskkill(deadline);
+					else killChild("SIGKILL");
+					else if (options.cleanup === "tree") {
+						const found = groupSignal("SIGTERM");
+						if (!found && !exited && !closed) cleanupErrors.push(/* @__PURE__ */ new Error("The child process group is unavailable."));
+						killChild("SIGTERM");
+						if (found && !await waitFor(() => (exited || closed) && !groupSignal(0), 1e3)) groupSignal("SIGKILL");
+						killChild("SIGKILL");
+					} else {
+						killChild("SIGTERM");
+						if (!await waitFor(() => exited || closed, 1e3)) killChild("SIGKILL");
+					}
+					if (!await waitFor(() => exited || closed, deadline - Date.now())) cleanupErrors.push(/* @__PURE__ */ new Error("The CLI process did not exit during cleanup."));
+					await waitFor(() => closed, Math.min(250, deadline - Date.now()));
+					child.stdout.destroy();
+					child.stderr.destroy();
+					if (!await waitFor(() => closed && outClose && errClose && inClose, deadline - Date.now())) {
+						cleanupErrors.push(/* @__PURE__ */ new Error("The CLI process streams did not close during cleanup."));
+						child.unref();
+					}
+				}
+			} catch (error) {
+				cleanupErrors.push(error);
+				killChild("SIGKILL");
+				child?.stdin.destroy();
+				child?.stdout.destroy();
+				child?.stderr.destroy();
+				child?.unref();
+			}
+			if (failure === void 0 || settled) return;
+			const result = snapshot();
+			const primary = new CliInvocationError(failure.reason, failure.message, result, { cause: failure.cause });
+			settled = true;
+			release();
+			reject(cleanupErrors.length === 0 ? primary : new CliInvocationError("cleanup", "CLI cleanup could not be completed.", result, { cause: new AggregateError([primary, ...cleanupErrors], "CLI invocation and cleanup failed.") }));
+		}
+		function onOut(text) {
+			stdout.push(text);
+		}
+		function onErr(text) {
+			stderr.push(text);
+		}
+		function onError(error) {
+			if (failure) cleanupErrors.push(error);
+			else fail(spawned ? "io" : "spawn", "Could not execute the CLI.", error);
+		}
+		function onIoError(error) {
+			fail("io", "Could not capture CLI output.", error);
+		}
+		function onInputError(error) {
+			const code = errorCode(error);
+			if (code !== "EPIPE" && code !== "ECONNRESET" && code !== "EOF") fail("io", "Could not write CLI input.", error);
+		}
+		function checkOutput() {
+			if (spawned && (outClose && !outEnd || errClose && !errEnd)) fail("io", "CLI output closed before it could be fully read.");
+			update();
+		}
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		if (options.signal?.aborted) {
+			onAbort();
+			return;
+		}
+		if (options.timeout > 0) timer = setTimeout(() => fail("timeout", "CLI invocation timed out."), options.timeout);
+		try {
+			child = spawnCliProcess(command, args, {
+				cwd: options.cwd,
+				env: options.env,
+				detached: node_process.default.platform !== "win32" && options.cleanup === "tree"
+			});
+			child.on("error", onError);
+			child.on("spawn", () => {
+				spawned = true;
+				checkOutput();
+			});
+			child.on("exit", (code, terminatingSignal) => {
+				exited = true;
+				exitCode = code;
+				signal = terminatingSignal;
+				update();
+			});
+			child.on("close", () => {
+				closed = true;
+				update();
+			});
+			child.stdout.setEncoding("utf8");
+			child.stderr.setEncoding("utf8");
+			child.stdout.on("data", onOut);
+			child.stderr.on("data", onErr);
+			child.stdout.on("error", onIoError);
+			child.stderr.on("error", onIoError);
+			child.stdin.on("error", onInputError);
+			child.stdout.on("end", () => {
+				outEnd = true;
+				update();
+			});
+			child.stderr.on("end", () => {
+				errEnd = true;
+				update();
+			});
+			child.stdout.on("close", () => {
+				outClose = true;
+				checkOutput();
+			});
+			child.stderr.on("close", () => {
+				errClose = true;
+				checkOutput();
+			});
+			child.stdin.on("close", () => {
+				inClose = true;
+				update();
+			});
+			child.stdin.end(options.stdin, "utf8");
+		} catch (cause) {
+			fail("spawn", "Could not start the CLI.", cause);
+		}
+	});
+}
+
+//#endregion
+exports.CliInvocationError = CliInvocationError;
+exports.createCliRunner = createCliRunner;