@oh-my-pi/pi-utils 6.8.0 → 6.8.2

package/package.json

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

package/src/abortable.ts

@@ -5,9 +5,8 @@ export class AbortError extends Error {
 		assert(signal.aborted, "Abort signal must be aborted");
 
 		const message = signal.reason instanceof Error ? signal.reason.message : "Cancelled";
-		super(`Aborted: ${message}`, { cause: message });
+		super(`Aborted: ${message}`, { cause: signal.reason });
 		this.name = "AbortError";
-		this.cause = signal.reason;
 	}
 }
 
@@ -42,9 +41,11 @@ export function createAbortablePromise<T>(signal?: AbortSignal): {
 		reject(new AbortError(signal));
 	};
 	signal.addEventListener("abort", abortHandler, { once: true });
-	promise.finally(() => {
-		signal.removeEventListener("abort", abortHandler);
-	});
+	promise
+		.finally(() => {
+			signal.removeEventListener("abort", abortHandler);
+		})
+		.catch(() => {});
 	return { promise, resolve, reject };
 }
 
@@ -63,7 +64,20 @@ export function untilAborted<T>(signal: AbortSignal | undefined | null, pr: () =
 		return Promise.reject(new AbortError(signal));
 	}
 	const { promise, resolve, reject } = createAbortablePromise<T>(signal);
-	pr().then(resolve, reject);
+	let settled = false;
+	const wrappedResolve = (value: T | PromiseLike<T>) => {
+		if (!settled) {
+			settled = true;
+			resolve(value);
+		}
+	};
+	const wrappedReject = (reason?: unknown) => {
+		if (!settled) {
+			settled = true;
+			reject(reason);
+		}
+	};
+	pr().then(wrappedResolve, wrappedReject);
 	return promise;
 }
 

package/src/postmortem.ts

@@ -6,6 +6,7 @@
  * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
  */
 
+import { isMainThread } from "node:worker_threads";
 import { logger } from ".";
 
 // Cleanup reasons, in order of priority/meaning.
@@ -45,7 +46,8 @@ function runCleanup(reason: Reason): Promise<void> {
 
 	// Call .cleanup() for each callback that is still "armed".
 	// Use Promise.try to handle sync/async, but only those armed.
-	const promises = callbackList.reverse().map((callback) => {
+	// Create a copy to avoid mutating the original array with reverse()
+	const promises = [...callbackList].reverse().map((callback) => {
 		return Promise.try(() => callback(reason));
 	});
 
@@ -61,33 +63,45 @@ function runCleanup(reason: Reason): Promise<void> {
 }
 
 // Register signal and error event handlers to trigger cleanup before exit.
-process
-	.on("SIGINT", async () => {
-		await runCleanup(Reason.SIGINT);
-		process.exit(130); // 128 + SIGINT (2)
-	})
-	.on("uncaughtException", async (err) => {
-		logger.error("Uncaught exception", { err, stack: err.stack });
-		await runCleanup(Reason.UNCAUGHT_EXCEPTION);
-		process.exit(1);
-	})
-	.on("unhandledRejection", async (reason) => {
-		const err = reason instanceof Error ? reason : new Error(String(reason));
-		logger.error("Unhandled rejection", { err, stack: err.stack });
-		await runCleanup(Reason.UNHANDLED_REJECTION);
-		process.exit(1);
-	})
-	.on("exit", async () => {
-		void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
-	})
-	.on("SIGTERM", async () => {
-		await runCleanup(Reason.SIGTERM);
-		process.exit(143); // 128 + SIGTERM (15)
-	})
-	.on("SIGHUP", async () => {
-		await runCleanup(Reason.SIGHUP);
-		process.exit(129); // 128 + SIGHUP (1)
+// Main thread: full signal handling (SIGINT, SIGTERM, SIGHUP) + exceptions + exit
+// Worker thread: exit only (workers use self.addEventListener for exceptions)
+if (isMainThread) {
+	process
+		.on("SIGINT", async () => {
+			await runCleanup(Reason.SIGINT);
+			process.exit(130); // 128 + SIGINT (2)
+		})
+		.on("uncaughtException", async (err) => {
+			logger.error("Uncaught exception", { err, stack: err.stack });
+			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
+			process.exit(1);
+		})
+		.on("unhandledRejection", async (reason) => {
+			const err = reason instanceof Error ? reason : new Error(String(reason));
+			logger.error("Unhandled rejection", { err, stack: err.stack });
+			await runCleanup(Reason.UNHANDLED_REJECTION);
+			process.exit(1);
+		})
+		.on("exit", async () => {
+			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
+		})
+		.on("SIGTERM", async () => {
+			await runCleanup(Reason.SIGTERM);
+			process.exit(143); // 128 + SIGTERM (15)
+		})
+		.on("SIGHUP", async () => {
+			await runCleanup(Reason.SIGHUP);
+			process.exit(129); // 128 + SIGHUP (1)
+		});
+} else {
+	// Worker thread: only register exit handler for cleanup.
+	// DO NOT register uncaughtException/unhandledRejection handlers here -
+	// they would swallow errors before the worker's own handlers (self.addEventListener)
+	// can report failures back to the parent thread.
+	process.on("exit", () => {
+		void runCleanup(Reason.EXIT);
 	});
+}
 
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
@@ -134,10 +148,26 @@ export function register(id: string, callback: (reason: Reason) => void | Promis
 }
 
 /**
- * Runs all cleanup callbacks and exits the process.
+ * Runs all cleanup callbacks without exiting.
+ * Use this in workers or when you need to clean up but continue execution.
+ */
+export function cleanup(): Promise<void> {
+	return runCleanup(Reason.MANUAL);
+}
+
+/**
+ * Runs all cleanup callbacks and exits.
+ *
+ * In main thread: waits for stdout drain, then calls process.exit().
+ * In workers: runs cleanup only (process.exit would kill entire process).
  */
 export async function quit(code: number = 0): Promise<void> {
 	await runCleanup(Reason.MANUAL);
+
+	if (!isMainThread) {
+		return; // Workers: cleanup done, let worker exit naturally
+	}
+
 	if (process.stdout.writableLength > 0) {
 		const { promise, resolve } = Promise.withResolvers<void>();
 		process.stdout.once("drain", resolve);

package/src/ptree.ts

@@ -16,6 +16,59 @@ const isWindows = process.platform === "win32";
 // Set of live children for managed termination/cleanup on shutdown.
 const managedChildren = new Set<PipedSubprocess>();
 
+class AsyncQueue<T> {
+	#items: T[] = [];
+	#resolvers: Array<(result: IteratorResult<T>) => void> = [];
+	#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);
+	}
+
+	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 });
+			}
+		}
+	}
+
+	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);
+		});
+	}
+}
+
+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;
+}
+
 /**
  * Kill a child process and its descendents.
  * - Windows: uses taskkill for tree and forceful kill (/T /F)
@@ -71,8 +124,8 @@ function registerManaged(child: PipedSubprocess): void {
 	});
 }
 
-// A Bun subprocess with stdin=Writable, stdout/stderr=pipe (for tracking/cleanup).
-type PipedSubprocess = Subprocess<"pipe" | null, "pipe", "pipe">;
+// A Bun subprocess with stdin=Writable/ignore, stdout/stderr=pipe (for tracking/cleanup).
+type PipedSubprocess = Subprocess<"pipe" | "ignore" | null, "pipe", "pipe">;
 
 /**
  * ChildProcess wraps a managed subprocess, capturing output, errors, and providing
@@ -82,8 +135,11 @@ export class ChildProcess {
 	#proc: PipedSubprocess;
 	#detached = false;
 	#nothrow = false;
-	#stderrTee: ReadableStream<Uint8Array<ArrayBuffer>>;
 	#stderrBuffer = "";
+	#stdoutQueue = new AsyncQueue<Uint8Array>();
+	#stderrQueue = new AsyncQueue<Uint8Array>();
+	#stdoutStream?: ReadableStream<Uint8Array>;
+	#stderrStream?: ReadableStream<Uint8Array>;
 	#exitReason?: Exception;
 	#exitReasonPending?: Exception;
 	#exited: Promise<void>;
@@ -92,23 +148,75 @@ export class ChildProcess {
 	constructor(proc: PipedSubprocess) {
 		registerManaged(proc);
 
-		const [left, right] = proc.stderr.tee();
-		this.#stderrTee = right;
+		const exitSettled = proc.exited.then(
+			() => {},
+			() => {},
+		);
+
+		// 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();
+			}
+		})().catch(() => {
+			this.#stdoutQueue.close();
+		});
 
 		// Capture stderr at all times, with a capped buffer for errors.
 		const decoder = new TextDecoder();
 		void (async () => {
-			for await (const chunk of left) {
-				this.#stderrBuffer += decoder.decode(chunk, { stream: true });
+			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);
+					}
+				}
+			} catch {
+				// ignore
+			} finally {
+				this.#stderrBuffer += decoder.decode();
 				if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
 					this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
 				}
+				try {
+					await reader.cancel();
+				} catch {}
+				try {
+					reader.releaseLock();
+				} catch {}
+				this.#stderrQueue.close();
 			}
-			this.#stderrBuffer += decoder.decode();
-			if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
-				this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
-			}
-		})().catch(() => {});
+		})().catch(() => {
+			this.#stderrQueue.close();
+		});
 
 		const { promise, resolve } = Promise.withResolvers<Exception | undefined>();
 
@@ -152,11 +260,17 @@ export class ChildProcess {
 	get stdin(): FileSink | undefined {
 		return this.#proc.stdin;
 	}
-	get stdout(): ReadableStream<Uint8Array<ArrayBuffer>> {
-		return this.#proc.stdout;
+	get stdout(): ReadableStream<Uint8Array> {
+		if (!this.#stdoutStream) {
+			this.#stdoutStream = createProcessStream(this.#stdoutQueue);
+		}
+		return this.#stdoutStream;
 	}
-	get stderr(): ReadableStream<Uint8Array<ArrayBuffer>> {
-		return this.#stderrTee;
+	get stderr(): ReadableStream<Uint8Array> {
+		if (!this.#stderrStream) {
+			this.#stderrStream = createProcessStream(this.#stderrQueue);
+		}
+		return this.#stderrStream;
 	}
 
 	/**
@@ -201,7 +315,14 @@ export class ChildProcess {
 	async killAndWait(): Promise<void> {
 		// Try killing with SIGTERM, then SIGKILL if it doesn't exit within 1 second
 		this.kill("SIGTERM");
-		await Promise.race([this.exited, Bun.sleep(1000).then(() => this.kill("SIGKILL"))]);
+		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 utilities (aliases for easy chaining)
@@ -220,7 +341,7 @@ export class ChildProcess {
 	async blob() {
 		const { promise, resolve, reject } = Promise.withResolvers<Blob>();
 
-		const blob = this.#proc.stdout.blob();
+		const blob = this.stdout.blob();
 		if (!this.#nothrow) {
 			this.#exited.catch((ex: Exception) => {
 				reject(ex);
@@ -329,14 +450,17 @@ export class AbortError extends Exception {
  */
 export class TimeoutError extends AbortError {
 	constructor(timeout: number, stderr: string) {
-		super(new Error(`Process timed out after ${timeout}ms`), stderr);
+		super(new Error(`Timed out after ${Math.round(timeout / 1000)}s`), stderr);
 	}
 }
 
 /**
  * Options for cspawn (child spawn). Always pipes stdout/stderr, allows signal.
  */
-type ChildSpawnOptions = Omit<Spawn.SpawnOptions<"pipe" | null, "pipe", "pipe">, "stdout" | "stderr"> & {
+type ChildSpawnOptions = Omit<
+	Spawn.SpawnOptions<"pipe" | "ignore" | Buffer | null, "pipe", "pipe">,
+	"stdout" | "stderr"
+> & {
 	signal?: AbortSignal;
 };
 
@@ -348,6 +472,7 @@ type ChildSpawnOptions = Omit<Spawn.SpawnOptions<"pipe" | null, "pipe", "pipe">,
 export function cspawn(cmd: string[], options?: ChildSpawnOptions): ChildProcess {
 	const { timeout, ...rest } = options ?? {};
 	const child = spawn(cmd, {
+		stdin: "ignore",
 		...rest,
 		stdout: "pipe",
 		stderr: "pipe",