@gajae-code/utils 0.10.0 → 0.10.1

package/dist/types/broken-pipe.d.ts

@@ -0,0 +1,27 @@
+/**
+ * True when an error from a writer that owns its sink reports that the peer
+ * closed that sink. This intentionally accepts structural error objects rather
+ * than requiring an `Error` instance.
+ */
+export declare function isKnownSinkPeerClosedError(error: unknown): boolean;
+/**
+ * Backward-compatible local-sink classifier for output writers. Callers must
+ * use it only when they own the sink that produced the error.
+ */
+export declare function isBrokenPipeError(error: unknown): boolean;
+/**
+ * A classifier for process-level stdout `EPIPE` errors. Its direct-write
+ * evidence is private to each factory instance, so only the owner that
+ * intercepted `process.stdout.write` can mark an error for this classifier.
+ */
+export interface ProcessStdoutEpipeClassifier {
+    markDirectProcessStdoutWriteError(error: unknown): void;
+    isAttributableProcessStdoutEpipe(error: unknown): boolean;
+}
+export declare function createProcessStdoutEpipeClassifier(): ProcessStdoutEpipeClassifier;
+/**
+ * Exit code for a producer terminated because its output pipe broke:
+ * 128 + SIGPIPE (13), matching what shells report for SIGPIPE-killed tools
+ * in `foo | head`-style pipelines.
+ */
+export declare const BROKEN_PIPE_EXIT_CODE = 141;

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export { createAbortableStream, once, untilAborted } from "./abortable";
 export * from "./async";
+export * from "./broken-pipe";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.10.0",
+	"version": "0.10.1",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.10.0",
+		"@gajae-code/natives": "0.10.1",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/broken-pipe.ts

@@ -0,0 +1,132 @@
+/**
+ * Broken-pipe classification for writers that own a local output sink and for
+ * the process-wide postmortem fallback.
+ *
+ * A local writer may classify its own sink closure from the error code. The
+ * process-wide fallback is deliberately stricter: an `EPIPE` must be
+ * attributable to process stdout before it receives SIGPIPE-style shutdown.
+ */
+import * as fs from "node:fs";
+
+const KNOWN_SINK_PEER_CLOSED_CODES = new Set(["EPIPE", "ERR_STREAM_DESTROYED"]);
+
+type ErrorProperty = "code" | "fd" | "syscall";
+
+interface ErrorPropertyRead {
+	available: boolean;
+	value: unknown;
+}
+
+function isObjectLike(value: unknown): value is object {
+	return value !== null && (typeof value === "object" || typeof value === "function");
+}
+
+function readErrorProperty(error: object, property: ErrorProperty): ErrorPropertyRead {
+	try {
+		return { available: true, value: Reflect.get(error, property) };
+	} catch {
+		return { available: false, value: undefined };
+	}
+}
+
+function isUsableFileDescriptor(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+interface FileIdentity {
+	dev: number | bigint;
+	ino: number | bigint;
+}
+
+function fileIdentity(fd: number): FileIdentity | undefined {
+	try {
+		const stat = fs.fstatSync(fd);
+		return { dev: stat.dev, ino: stat.ino };
+	} catch {
+		return undefined;
+	}
+}
+
+function sameFileIdentity(left: FileIdentity, right: FileIdentity): boolean {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+
+/**
+ * True when an error from a writer that owns its sink reports that the peer
+ * closed that sink. This intentionally accepts structural error objects rather
+ * than requiring an `Error` instance.
+ */
+export function isKnownSinkPeerClosedError(error: unknown): boolean {
+	if (!isObjectLike(error)) return false;
+	const code = readErrorProperty(error, "code");
+	return code.available && typeof code.value === "string" && KNOWN_SINK_PEER_CLOSED_CODES.has(code.value);
+}
+
+/**
+ * Backward-compatible local-sink classifier for output writers. Callers must
+ * use it only when they own the sink that produced the error.
+ */
+export function isBrokenPipeError(error: unknown): boolean {
+	return isKnownSinkPeerClosedError(error);
+}
+
+/**
+ * A classifier for process-level stdout `EPIPE` errors. Its direct-write
+ * evidence is private to each factory instance, so only the owner that
+ * intercepted `process.stdout.write` can mark an error for this classifier.
+ */
+export interface ProcessStdoutEpipeClassifier {
+	markDirectProcessStdoutWriteError(error: unknown): void;
+	isAttributableProcessStdoutEpipe(error: unknown): boolean;
+}
+
+export function createProcessStdoutEpipeClassifier(): ProcessStdoutEpipeClassifier {
+	const directProcessStdoutWriteErrors = new WeakSet<object>();
+	const initialStdoutIdentity = isUsableFileDescriptor(process.stdout.fd)
+		? fileIdentity(process.stdout.fd)
+		: undefined;
+
+	const hasCurrentStdoutIdentity = (fd: number): boolean => {
+		if (!initialStdoutIdentity) return false;
+		let stdoutFd: number;
+		try {
+			stdoutFd = process.stdout.fd;
+		} catch {
+			return false;
+		}
+		if (!isUsableFileDescriptor(stdoutFd)) return false;
+		const currentStdoutIdentity = fileIdentity(stdoutFd);
+		const errorFdIdentity = fileIdentity(fd);
+		if (!currentStdoutIdentity || !errorFdIdentity) return false;
+		if (!sameFileIdentity(currentStdoutIdentity, initialStdoutIdentity)) return false;
+		return fd === stdoutFd || sameFileIdentity(errorFdIdentity, currentStdoutIdentity);
+	};
+
+	return {
+		markDirectProcessStdoutWriteError(error: unknown): void {
+			if (isObjectLike(error)) directProcessStdoutWriteErrors.add(error);
+		},
+		isAttributableProcessStdoutEpipe(error: unknown): boolean {
+			if (!isObjectLike(error)) return false;
+
+			const code = readErrorProperty(error, "code");
+			if (!code.available || code.value !== "EPIPE") return false;
+
+			if (directProcessStdoutWriteErrors.has(error)) return true;
+
+			const syscall = readErrorProperty(error, "syscall");
+			if (!syscall.available || syscall.value !== "write") return false;
+
+			const fd = readErrorProperty(error, "fd");
+			if (!fd.available || !isUsableFileDescriptor(fd.value)) return false;
+
+			return hasCurrentStdoutIdentity(fd.value);
+		},
+	};
+}
+
+/**
+ * Exit code for a producer terminated because its output pipe broke:
+ * 128 + SIGPIPE (13), matching what shells report for SIGPIPE-killed tools
+ * in `foo | head`-style pipelines.
+ */
+export const BROKEN_PIPE_EXIT_CODE = 141;

package/src/index.ts

@@ -1,5 +1,6 @@
 export { createAbortableStream, once, untilAborted } from "./abortable";
 export * from "./async";
+export * from "./broken-pipe";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";

package/src/postmortem.ts

@@ -7,6 +7,7 @@
  */
 import inspector from "node:inspector";
 import { isMainThread } from "node:worker_threads";
+import { BROKEN_PIPE_EXIT_CODE, createProcessStdoutEpipeClassifier } from "./broken-pipe";
 import * as logger from "./logger";
 import { safeStderrWrite } from "./safe-stderr";
 
@@ -22,10 +23,24 @@ export enum Reason {
 	MANUAL = "manual", // Manual cleanup (not triggered by process)
 }
 
+interface CleanupOptions {
+	quiet?: boolean;
+}
+
+type StdoutWriteCallback = (error?: Error | null) => void;
+
 // 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";
+let cleanupPromise: Promise<void> | undefined;
+let quietShutdownStarted = false;
+let ordinaryFatalStarted = false;
+const stdoutEpipeClassifier = createProcessStdoutEpipeClassifier();
+
+function shouldSuppressCleanupLogging(quiet: boolean): boolean {
+	return quiet || quietShutdownStarted;
+}
 
 /**
  * Internal: runs all registered cleanup callbacks for the given reason.
@@ -33,36 +48,87 @@ let cleanupStage: "idle" | "running" | "complete" = "idle";
  *
  * Returns a Promise that settles after all cleanups complete or error out.
  */
-function runCleanup(reason: Reason): Promise<void> {
+function runCleanup(reason: Reason, options: CleanupOptions = {}): Promise<void> {
+	const quiet = options.quiet === true;
 	switch (cleanupStage) {
 		case "idle":
 			cleanupStage = "running";
 			break;
 		case "running":
-			if (reason === Reason.EXIT) {
-				return Promise.resolve();
+			if (reason !== Reason.EXIT && !shouldSuppressCleanupLogging(quiet)) {
+				logger.error("Cleanup invoked recursively", { stack: new Error().stack });
 			}
-			logger.error("Cleanup invoked recursively", { stack: new Error().stack });
 			return Promise.resolve();
 		case "complete":
 			return Promise.resolve();
 	}
 
+	const { promise, resolve } = Promise.withResolvers<void>();
+	cleanupPromise = promise;
+
 	// Call .cleanup() for each callback that is still "armed".
-	// Use Promise.try to handle sync/async, but only those armed.
+	// Assign the shared completion promise first so synchronous re-entry joins it.
 	const promises = callbackList.toReversed().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 });
+	void Promise.allSettled(promises).then(results => {
+		try {
+			if (!shouldSuppressCleanupLogging(quiet)) {
+				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 });
+					}
+				}
 			}
+		} finally {
+			cleanupStage = "complete";
+			resolve();
 		}
-		cleanupStage = "complete";
 	});
+	return promise;
+}
+
+async function runCleanupAndWait(reason: Reason, options: CleanupOptions = {}): Promise<void> {
+	void runCleanup(reason, options);
+	await (cleanupPromise ?? Promise.resolve());
+}
+
+function installProcessStdoutWriteClassifier(): void {
+	const originalWrite = process.stdout.write.bind(process.stdout);
+	const markCallback = (callback: StdoutWriteCallback): StdoutWriteCallback => {
+		return error => {
+			stdoutEpipeClassifier.markDirectProcessStdoutWriteError(error);
+			callback(error);
+		};
+	};
+
+	const markedWrite = (
+		chunk: string | Uint8Array,
+		encoding?: BufferEncoding | StdoutWriteCallback,
+		callback?: StdoutWriteCallback,
+	): boolean => {
+		try {
+			if (typeof encoding === "function") return originalWrite(chunk, markCallback(encoding));
+			if (callback) {
+				return typeof chunk === "string"
+					? originalWrite(chunk, encoding, markCallback(callback))
+					: originalWrite(chunk, markCallback(callback));
+			}
+			if (encoding === undefined) return originalWrite(chunk);
+			return typeof chunk === "string" ? originalWrite(chunk, encoding) : originalWrite(chunk);
+		} catch (error) {
+			stdoutEpipeClassifier.markDirectProcessStdoutWriteError(error);
+			throw error;
+		}
+	};
+
+	process.stdout.write = markedWrite as typeof process.stdout.write;
+}
+
+function errorForDiagnostic(reason: unknown): Error {
+	return reason instanceof Error ? reason : new Error(String(reason));
 }
 
 // Register signal and error event handlers to trigger cleanup before exit.
@@ -79,10 +145,43 @@ function formatFatalError(label: string, err: Error): string {
 	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
 }
 
+async function exitQuietlyForAttributableStdoutEpipe(reason: Reason): Promise<void> {
+	if (ordinaryFatalStarted || quietShutdownStarted) return;
+	quietShutdownStarted = true;
+	// Set the observable status before cleanup can await or trigger another error.
+	process.exitCode = BROKEN_PIPE_EXIT_CODE;
+	await runCleanupAndWait(reason, { quiet: true });
+	// An ordinary fatal that arrived during quiet cleanup takes precedence.
+	if (process.exitCode === BROKEN_PIPE_EXIT_CODE) process.exit(BROKEN_PIPE_EXIT_CODE);
+}
+
+async function handleFatalError(label: string, reason: unknown, cleanupReason: Reason): Promise<void> {
+	if (stdoutEpipeClassifier.isAttributableProcessStdoutEpipe(reason)) {
+		await exitQuietlyForAttributableStdoutEpipe(cleanupReason);
+		return;
+	}
+
+	// A distinct ordinary fatal must retain its normal diagnostic and status-1
+	// contract, including when it arrives while quiet cleanup is still pending.
+	ordinaryFatalStarted = true;
+	process.exitCode = 1;
+	const err = errorForDiagnostic(reason);
+	safeStderrWrite(formatFatalError(label, err));
+	if (!quietShutdownStarted) {
+		logger.error(label === "Uncaught Exception" ? "Uncaught exception" : "Unhandled rejection", {
+			err,
+			stack: err.stack,
+		});
+	}
+	await runCleanupAndWait(cleanupReason);
+	process.exit(1);
+}
+
 if (isMainThread) {
+	installProcessStdoutWriteClassifier();
 	process
 		.on("SIGINT", async () => {
-			await runCleanup(Reason.SIGINT);
+			await runCleanupAndWait(Reason.SIGINT);
 			process.exit(130); // 128 + SIGINT (2)
 		})
 		.on("SIGUSR1", () => {
@@ -92,28 +191,21 @@ if (isMainThread) {
 			const url = inspector.url();
 			safeStderrWrite(`Inspector opened: ${url}\n`);
 		})
-		.on("uncaughtException", async err => {
-			safeStderrWrite(formatFatalError("Uncaught Exception", err));
-			logger.error("Uncaught exception", { err, stack: err.stack });
-			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
-			process.exit(1);
+		.on("uncaughtException", async error => {
+			await handleFatalError("Uncaught Exception", error, Reason.UNCAUGHT_EXCEPTION);
 		})
 		.on("unhandledRejection", async reason => {
-			const err = reason instanceof Error ? reason : new Error(String(reason));
-			safeStderrWrite(formatFatalError("Unhandled Rejection", err));
-			logger.error("Unhandled rejection", { err, stack: err.stack });
-			await runCleanup(Reason.UNHANDLED_REJECTION);
-			process.exit(1);
+			await handleFatalError("Unhandled Rejection", reason, Reason.UNHANDLED_REJECTION);
 		})
 		.on("exit", async () => {
 			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
 		})
 		.on("SIGTERM", async () => {
-			await runCleanup(Reason.SIGTERM);
+			await runCleanupAndWait(Reason.SIGTERM);
 			process.exit(143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
-			await runCleanup(Reason.SIGHUP);
+			await runCleanupAndWait(Reason.SIGHUP);
 			process.exit(129); // 128 + SIGHUP (1)
 		});
 } else {
@@ -139,8 +231,9 @@ export function register(id: string, callback: (reason: Reason) => void | Promis
 		done = true;
 		try {
 			return callback(reason);
-		} catch (e) {
-			const err = e instanceof Error ? e : new Error(String(e));
+		} catch (error) {
+			if (quietShutdownStarted) return;
+			const err = error instanceof Error ? error : new Error(String(error));
 			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 		}
 	};
@@ -154,12 +247,20 @@ export function register(id: string, callback: (reason: Reason) => void | Promis
 	};
 
 	if (cleanupStage !== "idle") {
+		if (quietShutdownStarted) {
+			queueMicrotask(() => {
+				void Promise.try(() => exec(Reason.MANUAL)).catch(() => {});
+			});
+			return () => {
+				done = true;
+			};
+		}
 		// 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));
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
 			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 		}
 		return () => {};
@@ -185,16 +286,28 @@ export function cleanup(): Promise<void> {
  * In workers: runs cleanup only (process.exit would kill entire process).
  */
 export async function quit(code: number = 0): Promise<void> {
-	await runCleanup(Reason.MANUAL);
+	const cleanupWasRunning = cleanupStage === "running";
+	void runCleanup(Reason.MANUAL);
+	const completion = cleanupPromise ?? Promise.resolve();
 
 	if (!isMainThread) {
-		return; // Workers: cleanup done, let worker exit naturally
+		if (!cleanupWasRunning) await completion;
+		return;
 	}
 
-	if (process.stdout.writableLength > 0) {
-		const { promise, resolve } = Promise.withResolvers<void>();
-		process.stdout.once("drain", resolve);
-		await Promise.race([promise, Bun.sleep(5000)]);
+	const exitAfterCleanup = async (): Promise<void> => {
+		await completion;
+		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);
+	};
+
+	if (cleanupWasRunning) {
+		void exitAfterCleanup();
+		return;
 	}
-	process.exit(code);
+	await exitAfterCleanup();
 }