@oh-my-pi/pi-utils 6.8.0

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@oh-my-pi/pi-utils",
+	"version": "6.8.0",
+	"description": "Shared utilities for pi packages",
+	"type": "module",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"check": "tsgo --noEmit",
+		"build": "tsgo -p tsconfig.build.json",
+		"test": "vitest --run"
+	},
+	"author": "Can Bölük",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/can1357/oh-my-pi.git",
+		"directory": "packages/pi-utils"
+	},
+	"dependencies": {
+		"winston": "^3.17.0",
+		"winston-daily-rotate-file": "^5.0.0",
+		"strip-ansi": "^7.1.2"
+	},
+	"devDependencies": {
+		"@types/node": "^24.3.0"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	}
+}

package/src/abortable.ts

@@ -0,0 +1,86 @@
+import assert from "node:assert/strict";
+
+export class AbortError extends Error {
+	constructor(signal: AbortSignal) {
+		assert(signal.aborted, "Abort signal must be aborted");
+
+		const message = signal.reason instanceof Error ? signal.reason.message : "Cancelled";
+		super(`Aborted: ${message}`, { cause: message });
+		this.name = "AbortError";
+		this.cause = signal.reason;
+	}
+}
+
+/**
+ * Sleep for a given number of milliseconds, respecting abort signal.
+ */
+export async function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return untilAborted(signal, () => Bun.sleep(ms));
+}
+
+/**
+ * Creates a deferred { promise, resolve, reject } triple which automatically rejects
+ * with { name: "AbortError" } if the given abort signal fires before resolve/reject.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @returns A deferred { promise, resolve, reject } triple
+ */
+export function createAbortablePromise<T>(signal?: AbortSignal): {
+	promise: Promise<T>;
+	resolve: (value: T | PromiseLike<T>) => void;
+	reject: (reason?: unknown) => void;
+} {
+	if (!signal) {
+		return Promise.withResolvers<T>();
+	} else if (signal.aborted) {
+		return { promise: Promise.reject(new AbortError(signal)), resolve: () => {}, reject: () => {} };
+	}
+
+	const { promise, resolve, reject } = Promise.withResolvers<T>();
+
+	const abortHandler = () => {
+		reject(new AbortError(signal));
+	};
+	signal.addEventListener("abort", abortHandler, { once: true });
+	promise.finally(() => {
+		signal.removeEventListener("abort", abortHandler);
+	});
+	return { promise, resolve, reject };
+}
+
+/**
+ * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
+ * execution, the promise is rejected with a standard error.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @param pr - Function returning a promise to run
+ * @returns Promise resolving as `pr` would, or rejecting on abort
+ */
+export function untilAborted<T>(signal: AbortSignal | undefined | null, pr: () => Promise<T>): Promise<T> {
+	if (!signal) {
+		return pr();
+	} else if (signal.aborted) {
+		return Promise.reject(new AbortError(signal));
+	}
+	const { promise, resolve, reject } = createAbortablePromise<T>(signal);
+	pr().then(resolve, reject);
+	return promise;
+}
+
+/**
+ * Memoizes a function with no arguments, calling it once and caching the result.
+ *
+ * @param fn - Function to be called once
+ * @returns A function that returns the cached result of `fn`
+ */
+export function once<T>(fn: () => T): () => T {
+	let store = undefined as { value: T } | undefined;
+	return () => {
+		if (store) {
+			return store.value;
+		}
+		const value = fn();
+		store = { value };
+		return value;
+	};
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./abortable";
+export * as logger from "./logger";
+export * as postmortem from "./postmortem";
+export * as ptree from "./ptree";
+export { AbortError, ChildProcess, cspawn, Exception, NonZeroExitError } from "./ptree";
+export * from "./stream";
+export * from "./temp";

package/src/logger.ts

@@ -0,0 +1,111 @@
+/**
+ * Centralized file logger for omp.
+ *
+ * Logs to ~/.omp/logs/ with size-based rotation, supporting concurrent omp instances.
+ * Each log entry includes process.pid for traceability.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import winston from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+
+/** Get the logs directory (~/.omp/logs/) */
+function getLogsDir(): string {
+	return join(homedir(), ".omp", "logs");
+}
+
+/** Ensure logs directory exists */
+function ensureLogsDir(): string {
+	const logsDir = getLogsDir();
+	if (!existsSync(logsDir)) {
+		mkdirSync(logsDir, { recursive: true });
+	}
+	return logsDir;
+}
+
+/** Custom format that includes pid and flattens metadata */
+const logFormat = winston.format.combine(
+	winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+	winston.format.printf(({ timestamp, level, message, ...meta }) => {
+		const entry: Record<string, unknown> = {
+			timestamp,
+			level,
+			pid: process.pid,
+			message,
+		};
+		// Flatten metadata into entry
+		for (const [key, value] of Object.entries(meta)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") {
+				entry[key] = value;
+			}
+		}
+		return JSON.stringify(entry);
+	}),
+);
+
+/** Size-based rotating file transport */
+const fileTransport = new DailyRotateFile({
+	dirname: ensureLogsDir(),
+	filename: "omp.%DATE%.log",
+	datePattern: "YYYY-MM-DD",
+	maxSize: "10m",
+	maxFiles: 5,
+	zippedArchive: true,
+});
+
+/** The winston logger instance */
+const winstonLogger = winston.createLogger({
+	level: "debug",
+	format: logFormat,
+	transports: [fileTransport],
+	// Don't exit on error - logging failures shouldn't crash the app
+	exitOnError: false,
+});
+
+/** Logger type exposed to plugins and internal code */
+export interface Logger {
+	error(message: string, context?: Record<string, unknown>): void;
+	warn(message: string, context?: Record<string, unknown>): void;
+	debug(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Centralized logger for omp.
+ *
+ * Logs to ~/.omp/logs/omp.YYYY-MM-DD.log with size-based rotation.
+ * Safe for concurrent access from multiple omp instances.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from "@oh-my-pi/pi-utils";
+ *
+ * logger.error("MCP request failed", { url, method });
+ * logger.warn("Theme file invalid, using fallback", { path });
+ * logger.debug("LSP fallback triggered", { reason });
+ * ```
+ */
+export function error(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.error(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+export function warn(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.warn(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+export function debug(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.debug(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}

package/src/postmortem.ts

@@ -0,0 +1,147 @@
+/**
+ * Cleanup and postmortem handler utilities.
+ *
+ * This module provides a system for registering and running cleanup callbacks
+ * in response to process exit, signals, or fatal exceptions. It is intended to
+ * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
+ */
+
+import { logger } from ".";
+
+// Cleanup reasons, in order of priority/meaning.
+export enum Reason {
+	PRE_EXIT = "pre_exit", // Pre-exit phase (not used by default)
+	EXIT = "exit", // Normal process exit
+	SIGINT = "sigint", // Ctrl-C or SIGINT
+	SIGTERM = "sigterm", // SIGTERM
+	SIGHUP = "sighup", // SIGHUP
+	UNCAUGHT_EXCEPTION = "uncaught_exception", // Fatal exception
+	UNHANDLED_REJECTION = "unhandled_rejection", // Unhandled promise rejection
+	MANUAL = "manual", // Manual cleanup (not triggered by process)
+}
+
+// Internal list of active cleanup callbacks (in registration order)
+const callbackList: ((reason: Reason) => Promise<void> | void)[] = [];
+// Tracks cleanup run state (to prevent recursion/reentry issues)
+let cleanupStage: "idle" | "running" | "complete" = "idle";
+
+/**
+ * Internal: runs all registered cleanup callbacks for the given reason.
+ * Ensures each callback is invoked at most once. Handles errors and prevents reentrancy.
+ *
+ * Returns a Promise that settles after all cleanups complete or error out.
+ */
+function runCleanup(reason: Reason): Promise<void> {
+	switch (cleanupStage) {
+		case "idle":
+			cleanupStage = "running";
+			break;
+		case "running":
+			logger.error("Cleanup invoked recursively", { stack: new Error().stack });
+			return Promise.resolve();
+		case "complete":
+			return Promise.resolve();
+	}
+
+	// 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) => {
+		return Promise.try(() => callback(reason));
+	});
+
+	return Promise.allSettled(promises).then((results) => {
+		for (const result of results) {
+			if (result.status === "rejected") {
+				const err = result.reason instanceof Error ? result.reason : new Error(String(result.reason));
+				logger.error("Cleanup callback failed", { err, stack: err.stack });
+			}
+		}
+		cleanupStage = "complete";
+	});
+}
+
+// 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)
+	});
+
+/**
+ * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ *
+ * Returns a Callback instance that can be used to cancel (unregister) or manually clean up.
+ * If register is called after cleanup already began, invokes callback on a microtask.
+ */
+export function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void {
+	let done = false;
+	const exec = (reason: Reason) => {
+		if (done) return;
+		done = true;
+		try {
+			return callback(reason);
+		} catch (e) {
+			const err = e instanceof Error ? e : new Error(String(e));
+			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
+		}
+	};
+
+	const cancel = () => {
+		const index = callbackList.indexOf(exec);
+		if (index >= 0) {
+			callbackList.splice(index, 1);
+		}
+		done = true;
+	};
+
+	if (cleanupStage !== "idle") {
+		// If cleanup is already running/completed, warn and run on microtask.
+		logger.warn("Cleanup invoked recursively", { id });
+		try {
+			callback(Reason.MANUAL);
+		} catch (e) {
+			const err = e instanceof Error ? e : new Error(String(e));
+			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
+		}
+		return () => {};
+	}
+
+	// Register callback as "armed" (active).
+	callbackList.push(exec);
+	return cancel;
+}
+
+/**
+ * Runs all cleanup callbacks and exits the process.
+ */
+export async function quit(code: number = 0): Promise<void> {
+	await runCleanup(Reason.MANUAL);
+	if (process.stdout.writableLength > 0) {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		process.stdout.once("drain", resolve);
+		await Promise.race([promise, Bun.sleep(5000)]);
+	}
+	process.exit(code);
+}

package/src/ptree.ts

@@ -0,0 +1,365 @@
+/**
+ * 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.
+ */
+
+import { type FileSink, type Spawn, type Subprocess, spawn, spawnSync } from "bun";
+import { postmortem } from ".";
+
+// Platform detection: process tree kill behavior differs.
+const isWindows = process.platform === "win32";
+
+// Set of live children for managed termination/cleanup on shutdown.
+const managedChildren = new Set<PipedSubprocess>();
+
+/**
+ * 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)
+ */
+function killChild(child: PipedSubprocess, signal: NodeJS.Signals = "SIGTERM"): void {
+	const pid = child.pid;
+	if (!pid) return;
+
+	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);
+		}
+
+		// If killed, remove from managed set and clean up.
+		if (child.killed) {
+			managedChildren.delete(child);
+			child.unref();
+		}
+	} catch {
+		// Ignore: process may already be dead.
+	}
+}
+
+postmortem.register("managed-children", () => {
+	for (const child of [...managedChildren]) {
+		killChild(child, "SIGKILL");
+		managedChildren.delete(child);
+	}
+});
+
+/**
+ * Register a subprocess for managed cleanup.
+ * Will attach to exit Promise so removal happens even if child exits "naturally".
+ */
+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();
+	});
+}
+
+// A Bun subprocess with stdin=Writable, stdout/stderr=pipe (for tracking/cleanup).
+type PipedSubprocess = Subprocess<"pipe" | null, "pipe", "pipe">;
+
+/**
+ * ChildProcess wraps a managed subprocess, capturing output, errors, and providing
+ * cross-platform kill/detach logic plus AbortSignal integration.
+ */
+export class ChildProcess {
+	#proc: PipedSubprocess;
+	#detached = false;
+	#nothrow = false;
+	#stderrTee: ReadableStream<Uint8Array<ArrayBuffer>>;
+	#stderrBuffer = "";
+	#exitReason?: Exception;
+	#exitReasonPending?: Exception;
+	#exited: Promise<void>;
+	#resolveExited: (ex?: PromiseLike<Exception> | Exception) => void;
+
+	constructor(proc: PipedSubprocess) {
+		registerManaged(proc);
+
+		const [left, right] = proc.stderr.tee();
+		this.#stderrTee = right;
+
+		// 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 });
+				if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
+					this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
+				}
+			}
+			this.#stderrBuffer += decoder.decode();
+			if (this.#stderrBuffer.length > NonZeroExitError.MAX_TRACE) {
+				this.#stderrBuffer = this.#stderrBuffer.slice(-NonZeroExitError.MAX_TRACE);
+			}
+		})().catch(() => {});
+
+		const { promise, resolve } = Promise.withResolvers<Exception | undefined>();
+
+		this.#exited = promise.then((ex?: Exception) => {
+			if (!ex) return; // 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;
+
+		// 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);
+			}
+		});
+
+		this.#proc = proc;
+	}
+
+	get pid(): number | undefined {
+		return this.#proc.pid;
+	}
+	get exited(): Promise<void> {
+		return this.#exited;
+	}
+	get exitCode(): number | null {
+		return this.#proc.exitCode;
+	}
+	get exitReason(): Exception | undefined {
+		return this.#exitReason;
+	}
+	get killed(): boolean {
+		return this.#proc.killed;
+	}
+	get stdin(): FileSink | undefined {
+		return this.#proc.stdin;
+	}
+	get stdout(): ReadableStream<Uint8Array<ArrayBuffer>> {
+		return this.#proc.stdout;
+	}
+	get stderr(): ReadableStream<Uint8Array<ArrayBuffer>> {
+		return this.#stderrTee;
+	}
+
+	/**
+	 * 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);
+	}
+
+	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"))]);
+	}
+
+	// Output utilities (aliases for easy chaining)
+	async text(): Promise<string> {
+		return (await this.blob()).text();
+	}
+	async json(): Promise<unknown> {
+		return (await this.blob()).json();
+	}
+	async arrayBuffer(): Promise<ArrayBuffer> {
+		return (await this.blob()).arrayBuffer();
+	}
+	async bytes() {
+		return (await this.blob()).bytes();
+	}
+	async blob() {
+		const { promise, resolve, reject } = Promise.withResolvers<Blob>();
+
+		const blob = this.#proc.stdout.blob();
+		if (!this.#nothrow) {
+			this.#exited.catch((ex: Exception) => {
+				reject(ex);
+			});
+		}
+		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
+					}
+				});
+			}
+		};
+		if (signal.aborted) {
+			return void onAbort();
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		// Use .finally().catch() to avoid unhandled rejection when #exited rejects
+		this.#exited
+			.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;
+	}
+}
+
+/**
+ * Exception for process timeout.
+ */
+export class TimeoutError extends AbortError {
+	constructor(timeout: number, stderr: string) {
+		super(new Error(`Process timed out after ${timeout}ms`), stderr);
+	}
+}
+
+/**
+ * Options for cspawn (child spawn). Always pipes stdout/stderr, allows signal.
+ */
+type ChildSpawnOptions = Omit<Spawn.SpawnOptions<"pipe" | null, "pipe", "pipe">, "stdout" | "stderr"> & {
+	signal?: AbortSignal;
+};
+
+/**
+ * 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.
+ */
+export function cspawn(cmd: string[], options?: ChildSpawnOptions): ChildProcess {
+	const { timeout, ...rest } = options ?? {};
+	const child = spawn(cmd, {
+		...rest,
+		stdout: "pipe",
+		stderr: "pipe",
+		// Windows: new console/pgroup; Unix: setsid for process group.
+		detached: true,
+	});
+	const cproc = new ChildProcess(child);
+	if (options?.signal) {
+		cproc.attachSignal(options.signal);
+	}
+	if (timeout && timeout > 0) {
+		cproc.attachTimeout(timeout);
+	}
+	return cproc;
+}

package/src/stream.ts

@@ -0,0 +1,241 @@
+import { TextDecoderStream } from "node:stream/web";
+import stripAnsi from "strip-ansi";
+
+/**
+ * Sanitize binary output for display/storage.
+ * Removes characters that crash string-width or cause display issues:
+ * - Control characters (except tab, newline, carriage return)
+ * - Lone surrogates
+ * - Unicode Format characters (crash string-width due to a bug)
+ * - Characters with undefined code points
+ */
+export function sanitizeBinaryOutput(str: string): string {
+	// Use Array.from to properly iterate over code points (not code units)
+	// This handles surrogate pairs correctly and catches edge cases where
+	// codePointAt() might return undefined
+	return Array.from(str)
+		.filter((char) => {
+			// Filter out characters that cause string-width to crash
+			// This includes:
+			// - Unicode format characters
+			// - Lone surrogates (already filtered by Array.from)
+			// - Control chars except \t \n \r
+			// - Characters with undefined code points
+
+			const code = char.codePointAt(0);
+
+			// Skip if code point is undefined (edge case with invalid strings)
+			if (code === undefined) return false;
+
+			// Allow tab, newline, carriage return
+			if (code === 0x09 || code === 0x0a || code === 0x0d) return true;
+
+			// Filter out control characters (0x00-0x1F, except 0x09, 0x0a, 0x0x0d)
+			if (code <= 0x1f) return false;
+
+			// Filter out Unicode format characters
+			if (code >= 0xfff9 && code <= 0xfffb) return false;
+
+			return true;
+		})
+		.join("");
+}
+
+/**
+ * Sanitize text output: strip ANSI codes, remove binary garbage, normalize line endings.
+ */
+export function sanitizeText(text: string): string {
+	return sanitizeBinaryOutput(stripAnsi(text)).replace(/\r/g, "");
+}
+
+/**
+ * Create a transform stream that splits lines.
+ */
+export function createSplitterStream(delimiter: string): TransformStream<string, string> {
+	let buf = "";
+	return new TransformStream<string, string>({
+		transform(chunk, controller) {
+			buf = buf ? `${buf}${chunk}` : chunk;
+
+			while (true) {
+				const nl = buf.indexOf(delimiter);
+				if (nl === -1) break;
+				controller.enqueue(buf.slice(0, nl));
+				buf = buf.slice(nl + delimiter.length);
+			}
+		},
+		flush(controller) {
+			if (buf) {
+				controller.enqueue(buf);
+			}
+		},
+	});
+}
+
+/**
+ * Create a transform stream that sanitizes text.
+ */
+export function createSanitizerStream(): TransformStream<string, string> {
+	return new TransformStream<string, string>({
+		transform(chunk, controller) {
+			controller.enqueue(sanitizeText(chunk));
+		},
+	});
+}
+
+/**
+ * Create a transform stream that decodes text.
+ */
+export function createTextDecoderStream(): TransformStream<Uint8Array, string> {
+	return new TextDecoderStream("utf-8", { ignoreBOM: true });
+}
+
+/**
+ * Read stream line-by-line
+ *
+ * @param delimiter Line delimiter (default: "\n")
+ */
+export function readLines(stream: ReadableStream<Uint8Array>, delimiter = "\n"): AsyncIterable<string> {
+	return stream.pipeThrough(createTextDecoderStream()).pipeThrough(createSplitterStream(delimiter));
+}
+
+// =============================================================================
+// SSE (Server-Sent Events)
+// =============================================================================
+
+/**
+ * Parsed SSE event.
+ */
+export interface SseEvent {
+	/** Event type (from `event:` field, default: "message") */
+	event: string;
+	/** Event data (from `data:` field(s), joined with newlines) */
+	data: string;
+	/** Event ID (from `id:` field) */
+	id?: string;
+	/** Retry interval in ms (from `retry:` field) */
+	retry?: number;
+}
+
+/**
+ * Parse a single SSE event block (lines between blank lines).
+ * Returns null if the block contains no data.
+ */
+export function parseSseEvent(block: string): SseEvent | null {
+	const lines = block.split("\n");
+	let event = "message";
+	const dataLines: string[] = [];
+	let id: string | undefined;
+	let retry: number | undefined;
+
+	for (const line of lines) {
+		// Comments start with ':'
+		if (line.startsWith(":")) continue;
+
+		const colonIdx = line.indexOf(":");
+		if (colonIdx === -1) continue;
+
+		const field = line.slice(0, colonIdx);
+		// Value starts after colon, with optional leading space trimmed
+		let value = line.slice(colonIdx + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+
+		switch (field) {
+			case "event":
+				event = value;
+				break;
+			case "data":
+				dataLines.push(value);
+				break;
+			case "id":
+				id = value;
+				break;
+			case "retry": {
+				const n = parseInt(value, 10);
+				if (!Number.isNaN(n)) retry = n;
+				break;
+			}
+		}
+	}
+
+	if (dataLines.length === 0) return null;
+
+	return {
+		event,
+		data: dataLines.join("\n"),
+		id,
+		retry,
+	};
+}
+
+/**
+ * Read SSE events from a stream.
+ *
+ * Handles the SSE wire format:
+ * - Events separated by blank lines
+ * - Fields: event, data, id, retry
+ * - Comments (lines starting with :) are ignored
+ * - Multiple data: lines are joined with newlines
+ *
+ * @example
+ * ```ts
+ * for await (const event of readSseEvents(response.body)) {
+ *   if (event.data === "[DONE]") break;
+ *   const payload = JSON.parse(event.data);
+ *   console.log(event.event, payload);
+ * }
+ * ```
+ */
+export async function* readSseEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent, void, undefined> {
+	const blockLines: string[] = [];
+
+	for await (const rawLine of readLines(stream)) {
+		const line = rawLine.replace(/\r$/, "");
+		if (line === "") {
+			if (blockLines.length > 0) {
+				const event = parseSseEvent(blockLines.join("\n"));
+				if (event) yield event;
+				blockLines.length = 0;
+			}
+			continue;
+		}
+
+		blockLines.push(line);
+	}
+
+	if (blockLines.length > 0) {
+		const event = parseSseEvent(blockLines.join("\n"));
+		if (event) yield event;
+	}
+}
+
+/**
+ * Read SSE data payloads from a stream, parsing JSON automatically.
+ *
+ * Convenience wrapper over readSseEvents that:
+ * - Skips [DONE] markers
+ * - Parses JSON data
+ * - Optionally filters by event type
+ *
+ * @example
+ * ```ts
+ * for await (const data of readSseData<ChatChunk>(response.body)) {
+ *   console.log(data.choices[0].delta);
+ * }
+ * ```
+ */
+export async function* readSseData<T = unknown>(
+	stream: ReadableStream<Uint8Array>,
+	eventType?: string,
+): AsyncGenerator<T, void, undefined> {
+	for await (const event of readSseEvents(stream)) {
+		if (eventType && event.event !== eventType) continue;
+		if (event.data === "[DONE]") continue;
+
+		try {
+			yield JSON.parse(event.data) as T;
+		} catch {
+			// Skip malformed JSON
+		}
+	}
+}

package/src/temp.ts

@@ -0,0 +1,73 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, sep } from "node:path";
+
+export interface AsyncTempDir {
+	path: string;
+	remove(): Promise<void>;
+	toString(): string;
+	[Symbol.asyncDispose](): Promise<void>;
+}
+
+export interface SyncTempDir {
+	path: string;
+	remove(): void;
+	toString(): string;
+	[Symbol.dispose](): void;
+}
+
+const kTempDir = tmpdir();
+
+function normalizePrefix(prefix?: string): string {
+	if (!prefix) {
+		return `${kTempDir}${sep}pi-temp-`;
+	} else if (prefix.startsWith("@")) {
+		return join(kTempDir, prefix.slice(1));
+	}
+	return prefix;
+}
+
+export async function createTempDir(prefix?: string): Promise<AsyncTempDir> {
+	const path = await mkdtemp(normalizePrefix(prefix));
+
+	let promise: Promise<void> | null = null;
+	const remove = () => {
+		if (promise) {
+			return promise;
+		}
+		promise = rm(path, { recursive: true, force: true }).catch(() => {});
+		return promise;
+	};
+
+	return {
+		path: path!,
+		remove,
+		toString: () => path,
+		[Symbol.asyncDispose]: remove,
+	};
+}
+
+export function createTempDirSync(prefix?: string): SyncTempDir {
+	const path = mkdtempSync(normalizePrefix(prefix));
+
+	let done = false;
+	const remove = () => {
+		if (done) {
+			return;
+		}
+		done = true;
+		try {
+			rmSync(path, { recursive: true, force: true });
+		} catch {
+			// Ignore cleanup errors
+		}
+	};
+
+	return {
+		path,
+		toString: () => path,
+		remove,
+		[Symbol.dispose]: remove,
+	};
+}