@oh-my-pi/pi-utils 8.12.2 → 8.12.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "8.12.2",
+	"version": "8.12.4",
 	"description": "Shared utilities for pi packages",
 	"type": "module",
 	"main": "./src/index.ts",

package/src/index.ts

@@ -5,6 +5,6 @@ export * from "./glob";
 export * as logger from "./logger";
 export * as postmortem from "./postmortem";
 export * as ptree from "./ptree";
-export { AbortError, ChildProcess, cspawn, Exception, NonZeroExitError } from "./ptree";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
 export * from "./stream";
 export * from "./temp";

package/src/ptree.ts

@@ -1,455 +1,442 @@
 /**
  * Process tree management utilities for Bun subprocesses.
  *
- * Provides:
- * - Managed tracking of child subprocesses for cleanup on exit/signals.
- * - Windows and Unix support for proper tree killing.
- * - ChildProcess wrapper for capturing output, errors, and kill/detach.
+ * Exposes the same public interface as the original implementation, but with
+ * much less code:
+ * - Track managed child processes for cleanup on shutdown (postmortem).
+ * - Drain stdout/stderr to avoid subprocess pipe deadlocks.
+ * - Cross-platform tree kill for process groups (Windows taskkill, Unix -pid).
+ * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
  */
-import { type FileSink, type Spawn, type Subprocess, spawn, spawnSync } from "bun";
+import { $, type FileSink, type Spawn, type Subprocess } from "bun";
 import { postmortem } from ".";
 
-// Platform detection: process tree kill behavior differs.
 const isWindows = process.platform === "win32";
+const managedChildren = new Set<ChildProcess>();
 
-// Set of live children for managed termination/cleanup on shutdown.
-const managedChildren = new Set<PipedSubprocess>();
+/** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
+type PipedSubprocess = Subprocess<"pipe" | "ignore" | null, "pipe", "pipe">;
 
-class AsyncQueue<T> {
-	#items: T[] = [];
-	#resolvers: Array<(result: IteratorResult<T>) => void> = [];
-	#closed = false;
+/** Minimal push-based ReadableStream that buffers unboundedly (like the old queue). */
+function pushStream<T>() {
+	let controller!: ReadableStreamDefaultController<T>;
+	let closed = false;
 
-	push(item: T): void {
-		if (this.#closed) return;
-		const resolver = this.#resolvers.shift();
-		if (resolver) {
-			resolver({ value: item, done: false });
-			return;
-		}
-		this.#items.push(item);
-	}
+	const stream = new ReadableStream<T>({
+		start(c) {
+			controller = c;
+		},
+		cancel() {
+			closed = true; // consumer no longer cares; keep draining but drop
+		},
+	});
 
-	close(): void {
-		if (this.#closed) return;
-		this.#closed = true;
-		while (this.#resolvers.length > 0) {
-			const resolver = this.#resolvers.shift();
-			if (resolver) {
-				resolver({ value: undefined, done: true });
+	return {
+		stream,
+		push(value: T) {
+			if (closed) return;
+			try {
+				controller.enqueue(value);
+			} catch {
+				closed = true;
 			}
-		}
-	}
+		},
+		close() {
+			if (closed) return;
+			closed = true;
+			try {
+				controller.close();
+			} catch {}
+		},
+	};
+}
 
-	async next(): Promise<IteratorResult<T>> {
-		if (this.#items.length > 0) {
-			return { value: this.#items.shift() as T, done: false };
-		}
-		if (this.#closed) {
-			return { value: undefined, done: true };
-		}
-		return await new Promise<IteratorResult<T>>(resolve => {
-			this.#resolvers.push(resolve);
-		});
-	}
+const DONE = { done: true, value: undefined } as const;
+
+function abortRead(signal: AbortSignal) {
+	if (signal.aborted) return Promise.resolve(DONE);
+	const { promise, resolve } = Promise.withResolvers<typeof DONE>();
+	signal.addEventListener("abort", () => resolve(DONE), { once: true });
+	return promise;
 }
 
-function createProcessStream(queue: AsyncQueue<Uint8Array>): ReadableStream<Uint8Array> {
-	const stream = new ReadableStream<Uint8Array>({
-		pull: async controller => {
-			const result = await queue.next();
-			if (result.done) {
-				controller.close();
-				return;
-			}
-			controller.enqueue(result.value);
-		},
-	});
-	return stream;
+/** Drain a ReadableStream into a pushStream, optionally tapping each chunk. */
+async function pump(
+	src: ReadableStream<Uint8Array>,
+	dst: ReturnType<typeof pushStream<Uint8Array>>,
+	opts?: { signal?: AbortSignal; onChunk?: (chunk: Uint8Array) => void; onFinally?: () => void },
+) {
+	const reader = src.getReader();
+	const stop = opts?.signal ? abortRead(opts.signal) : null;
+
+	try {
+		while (true) {
+			const r = stop ? await Promise.race([reader.read(), stop]) : await reader.read();
+			if (r.done) break;
+			if (!r.value) continue;
+			opts?.onChunk?.(r.value);
+			dst.push(r.value);
+		}
+	} catch {
+		// ignore; this module is "best effort" for streaming/cleanup
+	} finally {
+		try {
+			await reader.cancel();
+		} catch {}
+		try {
+			reader.releaseLock();
+		} catch {}
+		dst.close();
+		opts?.onFinally?.();
+	}
 }
 
 /**
  * Kill a child process and its descendents.
- * - Windows: uses taskkill for tree and forceful kill (/T /F)
- * - Unix: negative PID sends signal to process group (tree kill)
+ * - Windows: taskkill /T, add /F on SIGKILL
+ * - Unix: negative PID signals the process group
  */
-function killChild(child: PipedSubprocess, signal: NodeJS.Signals = "SIGTERM"): void {
+async function killChild(child: ChildProcess) {
 	const pid = child.pid;
-	if (!pid) return;
+	if (!pid || child.killed) return;
 
+	const exited = child.proc.exited.then(
+		() => true,
+		() => true,
+	);
+	const waitForExit = (timeout = 1000) => Promise.race([Bun.sleep(timeout).then(() => false), exited]);
+
+	// Give it a moment to exit gracefully first.
 	try {
-		if (isWindows) {
-			// /T (tree), /F (force): ensure entire tree is killed.
-			spawnSync(["taskkill", ...(signal === "SIGKILL" ? ["/F"] : []), "/T", "/PID", pid.toString()], {
-				stdout: "ignore",
-				stderr: "ignore",
-				timeout: 1000,
-			});
-		} else {
-			// Send signal to process group (negative PID).
-			process.kill(-pid, signal);
-		}
+		child.proc.kill();
+	} catch {}
+	if (await waitForExit(1000)) return true;
+
+	if (child.isProcessGroup) {
+		try {
+			if (isWindows) {
+				await $`taskkill /F /T /PID ${pid}`.quiet().nothrow();
+			} else {
+				process.kill(-pid);
+			}
+		} catch {}
+	}
+	try {
+		child.proc.kill("SIGKILL");
+	} catch {}
 
-		// If killed, remove from managed set and clean up.
-		if (child.killed) {
-			managedChildren.delete(child);
-			child.unref();
-		}
-	} catch {
-		// Ignore: process may already be dead.
+	return await waitForExit(1000);
+}
+
+postmortem.register("managed-children", async () => {
+	const children = Array.from(managedChildren);
+	managedChildren.clear();
+	await Promise.all(children.map(killChild));
+});
+
+/**
+ * Options for waiting for process exit and capturing output.
+ */
+export interface WaitOptions {
+	allowNonZero?: boolean;
+	allowAbort?: boolean;
+	stderr?: "full" | "buffer";
+}
+
+/**
+ * Result from wait and captureText.
+ */
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number | null;
+	ok: boolean;
+	exitError?: Exception;
+}
+
+/**
+ * Base for all exceptions representing child process nonzero exit, killed, or cancellation.
+ */
+export abstract class Exception extends Error {
+	constructor(
+		message: string,
+		public readonly exitCode: number,
+		public readonly stderr: string,
+	) {
+		super(message);
+		this.name = this.constructor.name;
 	}
+	abstract get aborted(): boolean;
 }
 
-postmortem.register("managed-children", () => {
-	for (const child of [...managedChildren]) {
-		killChild(child, "SIGKILL");
-		managedChildren.delete(child);
+/**
+ * Exception for nonzero exit codes (not cancellation).
+ */
+export class NonZeroExitError extends Exception {
+	static readonly MAX_TRACE = 32 * 1024;
+
+	constructor(
+		public readonly exitCode: number,
+		public readonly stderr: string,
+	) {
+		super(`Process exited with code ${exitCode}:\n${stderr}`, exitCode, stderr);
 	}
-});
+	get aborted(): boolean {
+		return false;
+	}
+}
 
 /**
- * Register a subprocess for managed cleanup.
- * Will attach to exit Promise so removal happens even if child exits "naturally".
+ * Exception for explicit process abortion (via signal).
  */
-function registerManaged(child: PipedSubprocess): void {
-	if (child.exitCode !== null) return;
-	if (managedChildren.has(child)) return;
-	child.ref();
-	managedChildren.add(child);
-
-	child.exited.then(() => {
-		managedChildren.delete(child);
-		child.unref();
-	});
+export class AbortError extends Exception {
+	constructor(
+		public readonly reason: unknown,
+		stderr: string,
+	) {
+		const reasonString = reason instanceof Error ? reason.message : String(reason ?? "aborted");
+		super(`Operation cancelled: ${reasonString}`, -1, stderr);
+	}
+	get aborted(): boolean {
+		return true;
+	}
 }
 
-// A Bun subprocess with stdin=Writable/ignore, stdout/stderr=pipe (for tracking/cleanup).
-type PipedSubprocess = Subprocess<"pipe" | "ignore" | null, "pipe", "pipe">;
+/**
+ * Exception for process timeout.
+ */
+export class TimeoutError extends AbortError {
+	constructor(timeout: number, stderr: string) {
+		super(new Error(`Timed out after ${Math.round(timeout / 1000)}s`), stderr);
+	}
+}
 
 /**
- * ChildProcess wraps a managed subprocess, capturing output, errors, and providing
+ * ChildProcess wraps a managed subprocess, capturing stderr tail, providing
  * cross-platform kill/detach logic plus AbortSignal integration.
  */
 export class ChildProcess {
-	#proc: PipedSubprocess;
-	#detached = false;
 	#nothrow = false;
+
 	#stderrBuffer = "";
-	#stdoutQueue = new AsyncQueue<Uint8Array>();
-	#stderrQueue = new AsyncQueue<Uint8Array>();
-	#stdoutStream?: ReadableStream<Uint8Array>;
-	#stderrStream?: ReadableStream<Uint8Array>;
 	#exitReason?: Exception;
 	#exitReasonPending?: Exception;
+
+	#stop = new AbortController();
+
+	#stdoutOut = pushStream<Uint8Array>();
+	#stderrOut = pushStream<Uint8Array>();
+
+	#stderrDone: Promise<void>;
 	#exited: Promise<number>;
-	#resolveExited: (ex?: PromiseLike<Exception> | Exception) => void;
 
-	constructor(proc: PipedSubprocess) {
-		registerManaged(proc);
+	constructor(
+		public readonly proc: PipedSubprocess,
+		public readonly isProcessGroup: boolean,
+	) {
+		const { promise: stderrDone, resolve: resolveStderrDone } = Promise.withResolvers<void>();
+		this.#stderrDone = stderrDone;
 
-		const exitSettled = proc.exited.then(
-			() => {},
-			() => {},
-		);
+		// Drain stdout always -> expose our buffered stream to the user.
+		void pump(proc.stdout, this.#stdoutOut, { signal: this.#stop.signal }).catch(() => this.#stdoutOut.close());
 
-		// Capture stdout at all times. Close the passthrough when the process exits.
-		void (async () => {
-			const reader = proc.stdout.getReader();
-			try {
-				while (true) {
-					const result = await Promise.race([
-						reader.read(),
-						exitSettled.then(() => ({ done: true, value: undefined as Uint8Array | undefined })),
-					]);
-					if (result.done) break;
-					if (!result.value) continue;
-					this.#stdoutQueue.push(result.value);
-				}
-			} catch {
-				// ignore
-			} finally {
-				try {
-					await reader.cancel();
-				} catch {}
-				try {
-					reader.releaseLock();
-				} catch {}
-				this.#stdoutQueue.close();
+		// Drain stderr always -> expose stream + keep a bounded tail buffer.
+		const decoder = new TextDecoder();
+		const trim = () => {
+			if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
+				this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
 			}
-		})().catch(() => {
-			this.#stdoutQueue.close();
+		};
+		void pump(proc.stderr, this.#stderrOut, {
+			signal: this.#stop.signal,
+			onChunk: chunk => {
+				this.#stderrBuffer += decoder.decode(chunk, { stream: true });
+				trim();
+			},
+			onFinally: () => {
+				this.#stderrBuffer += decoder.decode();
+				trim();
+				resolveStderrDone();
+			},
+		}).catch(() => {
+			try {
+				this.#stderrBuffer += decoder.decode();
+				trim();
+			} catch {}
+			this.#stderrOut.close();
+			resolveStderrDone();
 		});
 
-		// Capture stderr at all times, with a capped buffer for errors.
-		const decoder = new TextDecoder();
-		void (async () => {
-			const reader = proc.stderr.getReader();
-			try {
-				while (true) {
-					const result = await Promise.race([
-						reader.read(),
-						exitSettled.then(() => ({ done: true, value: undefined as Uint8Array | undefined })),
-					]);
-					if (result.done) break;
-					if (!result.value) continue;
-					this.#stderrQueue.push(result.value);
-					this.#stderrBuffer += decoder.decode(result.value, { stream: true });
-					if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
-						this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
-					}
+		const { promise, resolve, reject } = Promise.withResolvers<number>();
+		this.#exited = promise;
+
+		if (this.proc.exitCode === null) managedChildren.add(this);
+
+		// Normalize Bun's exited promise into our "exitReason / exitedCleanly" model.
+		proc.exited
+			.catch(() => null)
+			.then(async exitCode => {
+				if (this.#exitReasonPending) {
+					this.#exitReason = this.#exitReasonPending;
+					reject(this.#exitReasonPending);
+					return;
 				}
-			} catch {
-				// ignore
-			} finally {
-				this.#stderrBuffer += decoder.decode();
-				if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
-					this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
+
+				if (exitCode === 0) {
+					resolve(0);
+					return;
 				}
-				try {
-					await reader.cancel();
-				} catch {}
-				try {
-					reader.releaseLock();
-				} catch {}
-				this.#stderrQueue.close();
-			}
-		})().catch(() => {
-			this.#stderrQueue.close();
-		});
 
-		const { promise, resolve } = Promise.withResolvers<Exception | undefined>();
+				await this.#stderrDone;
 
-		this.#exited = promise.then((ex?: Exception) => {
-			if (!ex) return proc.exitCode ?? -1337; // success, no exception
-			if (proc.killed && this.#exitReasonPending) {
-				ex = this.#exitReasonPending; // propagate reason if killed
-			}
-			this.#exitReason = ex;
-			return Promise.reject(ex);
-		});
-		this.#resolveExited = resolve;
+				if (exitCode !== null) {
+					this.#exitReason = new NonZeroExitError(exitCode, this.#stderrBuffer);
+					resolve(exitCode);
+					return;
+				}
 
-		// On exit, resolve with a ChildError if nonzero code.
-		proc.exited.then(exitCode => {
-			if (exitCode !== 0) {
-				resolve(new NonZeroExitError(exitCode, this.#stderrBuffer));
-			} else {
-				resolve(undefined);
-			}
-		});
+				const ex = this.proc.killed
+					? new AbortError(new Error("process killed"), this.#stderrBuffer)
+					: new NonZeroExitError(-1, this.#stderrBuffer);
 
-		this.#proc = proc;
+				this.#exitReason = ex;
+				reject(ex);
+			})
+			.finally(() => {
+				managedChildren.delete(this);
+			});
 	}
 
 	get pid(): number | undefined {
-		return this.#proc.pid;
+		return this.proc.pid;
 	}
 	get exited(): Promise<number> {
 		return this.#exited;
 	}
+	get exitedCleanly(): Promise<number> {
+		if (this.#nothrow) return this.exited;
+		return this.exited.then(code => {
+			if (code !== 0) throw new NonZeroExitError(code, this.#stderrBuffer);
+			return code;
+		});
+	}
 	get exitCode(): number | null {
-		return this.#proc.exitCode;
+		return this.proc.exitCode;
 	}
 	get exitReason(): Exception | undefined {
 		return this.#exitReason;
 	}
 	get killed(): boolean {
-		return this.#proc.killed;
+		return this.proc.killed;
 	}
 	get stdin(): FileSink | undefined {
-		return this.#proc.stdin;
+		return this.proc.stdin;
 	}
 	get stdout(): ReadableStream<Uint8Array> {
-		if (!this.#stdoutStream) {
-			this.#stdoutStream = createProcessStream(this.#stdoutQueue);
-		}
-		return this.#stdoutStream;
+		return this.#stdoutOut.stream;
 	}
 	get stderr(): ReadableStream<Uint8Array> {
-		if (!this.#stderrStream) {
-			this.#stderrStream = createProcessStream(this.#stderrQueue);
-		}
-		return this.#stderrStream;
+		return this.#stderrOut.stream;
 	}
 
-	/**
-	 * Peek at the stderr buffer.
-	 * @returns The stderr buffer.
-	 */
 	peekStderr(): string {
 		return this.#stderrBuffer;
 	}
 
-	/**
-	 * Detach this process from management (no cleanup on shutdown).
-	 */
-	detach(): void {
-		if (this.#detached || this.#proc.killed) return;
-		this.#detached = true;
-		if (managedChildren.delete(this.#proc)) {
-			this.#proc.unref();
-		}
-	}
-
-	/**
-	 * Prevents thrown ChildError on nonzero exit code, for optional error handling.
-	 */
 	nothrow(): this {
 		this.#nothrow = true;
 		return this;
 	}
 
-	/**
-	 * Kill the process tree.
-	 * Optionally set an exit reason (for better error propagation on cancellation).
-	 */
-	kill(signal: NodeJS.Signals = "SIGTERM", reason?: Exception) {
-		if (this.#proc.killed) return;
-		if (reason) {
-			this.#exitReasonPending = reason;
-		}
-		killChild(this.#proc, signal);
+	kill(reason?: Exception) {
+		if (reason && !this.#exitReasonPending) this.#exitReasonPending = reason;
+		this.#stop.abort();
+		if (this.proc.killed) return;
+		void killChild(this);
 	}
 
-	async killAndWait(): Promise<void> {
-		// Try killing with SIGTERM, then SIGKILL if it doesn't exit within 1 second
-		this.kill("SIGTERM");
-		const exitedOrTimeout = await Promise.race([
-			this.exited.then(() => "exited" as const),
-			Bun.sleep(1000).then(() => "timeout" as const),
-		]);
-		if (exitedOrTimeout === "timeout") {
-			this.kill("SIGKILL");
-			await this.exited.catch(() => {});
-		}
+	// Output helpers
+	async blob(): Promise<Blob> {
+		const blobPromise = new Response(this.stdout).blob();
+		if (this.#nothrow) return await blobPromise;
+		const [blob] = await Promise.all([blobPromise, this.exitedCleanly]);
+		return blob;
 	}
-
-	// Output utilities (aliases for easy chaining)
 	async text(): Promise<string> {
 		return (await this.blob()).text();
 	}
 	async json(): Promise<unknown> {
-		return (await this.blob()).json();
+		return await new Response(await this.blob()).json();
 	}
 	async arrayBuffer(): Promise<ArrayBuffer> {
 		return (await this.blob()).arrayBuffer();
 	}
-	async bytes() {
-		return (await this.blob()).bytes();
+	async bytes(): Promise<Uint8Array> {
+		return new Uint8Array(await this.arrayBuffer());
 	}
-	async blob() {
-		const { promise, resolve, reject } = Promise.withResolvers<Blob>();
 
-		const blob = this.stdout.blob();
-		if (!this.#nothrow) {
-			this.#exited.catch((ex: Exception) => {
-				reject(ex);
-			});
+	async wait(options?: WaitOptions): Promise<ExecResult> {
+		const { allowNonZero = false, allowAbort = false, stderr: stderrMode = "buffer" } = options ?? {};
+
+		const stdoutPromise = new Response(this.stdout).text();
+		const stderrPromise =
+			stderrMode === "full"
+				? new Response(this.stderr).text()
+				: (async () => {
+						await Promise.allSettled([stdoutPromise, this.exited, this.#stderrDone]);
+						return this.peekStderr();
+					})();
+
+		const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+
+		let exitError: Exception | undefined;
+		try {
+			await this.exited;
+		} catch (err) {
+			if (err instanceof Exception) exitError = err;
+			else throw err;
 		}
-		blob.then(resolve, reject);
-		return promise;
-	}
 
-	/**
-	 * Attach an AbortSignal to this process. Will kill tree with SIGKILL if aborted.
-	 */
-	attachSignal(signal: AbortSignal): void {
-		const onAbort = () => {
-			const cause = new AbortError(signal.reason, "<cancelled>");
-			this.kill("SIGKILL", cause);
-			if (this.#proc.killed) {
-				queueMicrotask(() => {
-					try {
-						this.#resolveExited(cause);
-					} catch {
-						// Ignore
-					}
-				});
+		const exitCode = this.exitCode ?? (exitError && !exitError.aborted ? exitError.exitCode : null);
+		const ok = exitCode === 0;
+
+		if (exitError) {
+			if ((exitError.aborted && !allowAbort) || (!exitError.aborted && !allowNonZero)) {
+				throw exitError;
 			}
-		};
-		if (signal.aborted) {
-			return void onAbort();
 		}
+
+		return { stdout, stderr, exitCode, ok, exitError };
+	}
+
+	attachSignal(signal: AbortSignal): void {
+		const onAbort = () => this.kill(new AbortError(signal.reason, "<cancelled>"));
+		if (signal.aborted) return void onAbort();
+
 		signal.addEventListener("abort", onAbort, { once: true });
-		// Use .finally().catch() to avoid unhandled rejection when #exited rejects
 		this.#exited
+			.catch(() => {})
 			.finally(() => {
 				signal.removeEventListener("abort", onAbort);
-			})
-			.catch(() => {});
+			});
 	}
 
-	/**
-	 * Attach a timeout to this process. Will kill the process with SIGKILL if the timeout is reached.
-	 */
 	attachTimeout(timeout: number): void {
-		if (timeout <= 0) return;
-		const timeoutId = setTimeout(() => {
-			this.kill("SIGKILL", new TimeoutError(timeout, this.#stderrBuffer));
-		}, timeout);
-		// Use .finally().catch() to avoid unhandled rejection when #exited rejects
-		this.#exited
-			.finally(() => {
-				clearTimeout(timeoutId);
-			})
-			.catch(() => {});
-	}
-}
-
-/**
- * Base for all exceptions representing child process nonzero exit, killed, or cancellation.
- */
-export abstract class Exception extends Error {
-	constructor(
-		message: string,
-		public readonly exitCode: number,
-		public readonly stderr: string,
-	) {
-		super(message);
-		this.name = this.constructor.name;
-	}
-	abstract get aborted(): boolean;
-}
-
-/**
- * Exception for nonzero exit codes (not cancellation).
- */
-export class NonZeroExitError extends Exception {
-	static readonly MAX_TRACE = 32 * 1024;
-
-	constructor(
-		public readonly exitCode: number,
-		public readonly stderr: string,
-	) {
-		super(`Process exited with code ${exitCode}:\n${stderr}`, exitCode, stderr);
-	}
-	get aborted(): boolean {
-		return false;
-	}
-}
-
-/**
- * Exception for explicit process abortion (via signal).
- */
-export class AbortError extends Exception {
-	constructor(
-		public readonly reason: unknown,
-		stderr: string,
-	) {
-		const reasonString = reason instanceof Error ? reason.message : String(reason ?? "aborted");
-		super(`Operation cancelled: ${reasonString}`, -1, stderr);
-	}
-	get aborted(): boolean {
-		return true;
+		if (timeout <= 0 || this.proc.killed) return;
+		void (async () => {
+			const timedOut = await Promise.race([
+				Bun.sleep(timeout).then(() => true),
+				this.proc.exited.then(
+					() => false,
+					() => false,
+				),
+			]);
+			if (timedOut) this.kill(new TimeoutError(timeout, this.#stderrBuffer));
+		})();
 	}
-}
 
-/**
- * Exception for process timeout.
- */
-export class TimeoutError extends AbortError {
-	constructor(timeout: number, stderr: string) {
-		super(new Error(`Timed out after ${Math.round(timeout / 1000)}s`), stderr);
+	[Symbol.dispose](): void {
+		this.kill(new AbortError("process disposed", this.#stderrBuffer));
 	}
 }
 
@@ -457,33 +444,42 @@ export class TimeoutError extends AbortError {
  * Options for cspawn (child spawn). Always pipes stdout/stderr, allows signal.
  */
 type ChildSpawnOptions = Omit<
-	Spawn.SpawnOptions<"pipe" | "ignore" | Buffer | null, "pipe", "pipe">,
+	Spawn.SpawnOptions<"pipe" | "ignore" | Buffer | Uint8Array | null, "pipe", "pipe">,
 	"stdout" | "stderr"
-> & {
-	signal?: AbortSignal;
-};
+> & { signal?: AbortSignal; detached?: boolean };
 
 /**
- * Spawn a subprocess as a managed child process.
- * - Always pipes stdout/stderr, launches in new session/process group (detached).
- * - Optional AbortSignal integrates with kill-on-abort.
+ * Spawn a child process.
+ * @param cmd - The command to spawn.
+ * @param options - The options for the spawn.
+ * @returns A ChildProcess instance.
  */
-export function cspawn(cmd: string[], options?: ChildSpawnOptions): ChildProcess {
-	const { timeout, ...rest } = options ?? {};
-	const child = spawn(cmd, {
+export function spawn(cmd: string[], options?: ChildSpawnOptions): ChildProcess {
+	const { detached = false, timeout, signal, ...rest } = options ?? {};
+	const child = Bun.spawn(cmd, {
 		stdin: "ignore",
-		...rest,
 		stdout: "pipe",
 		stderr: "pipe",
-		// Windows: new console/pgroup; Unix: setsid for process group.
-		detached: true,
+		detached,
+		...rest,
 	});
-	const cproc = new ChildProcess(child);
-	if (options?.signal) {
-		cproc.attachSignal(options.signal);
-	}
-	if (timeout && timeout > 0) {
-		cproc.attachTimeout(timeout);
-	}
+	const cproc = new ChildProcess(child, detached);
+	if (signal) cproc.attachSignal(signal);
+	if (timeout && timeout > 0) cproc.attachTimeout(timeout);
 	return cproc;
 }
+
+/**
+ * Options for execText.
+ */
+export interface ExecOptions extends Omit<ChildSpawnOptions, "stdin">, WaitOptions {
+	input?: string | Buffer | Uint8Array;
+}
+
+export async function exec(cmd: string[], options?: ExecOptions): Promise<ExecResult> {
+	const { input, stderr, allowAbort, allowNonZero, ...spawnOptions } = options ?? {};
+	const stdin = typeof input === "string" ? Buffer.from(input) : input;
+	const resolvedOptions: ChildSpawnOptions = stdin === undefined ? { ...spawnOptions } : { ...spawnOptions, stdin };
+	using child = spawn(cmd, resolvedOptions);
+	return await child.wait({ stderr, allowAbort, allowNonZero });
+}