@sayknow-cli/utils 0.3.12 → 0.3.15

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/cli.d.ts

@@ -31,10 +31,10 @@ interface ArgInput {
 /** Builders that match the `Flags.*()` / `Args.*()` API from oclif. */
 export declare const Flags: {
     string<T extends FlagInput>(opts?: T): FlagDescriptor<"string"> & T;
-    boolean<T_1 extends FlagInput>(opts?: T_1): FlagDescriptor<"boolean"> & T_1;
-    integer<T_2 extends FlagInput & {
+    boolean<T extends FlagInput>(opts?: T): FlagDescriptor<"boolean"> & T;
+    integer<T extends FlagInput & {
         default?: number;
-    }>(opts?: T_2): FlagDescriptor<"integer"> & T_2;
+    }>(opts?: T): FlagDescriptor<"integer"> & T;
 };
 export declare const Args: {
     string<T extends ArgInput>(opts?: T): ArgDescriptor & T;

package/dist/types/frontmatter.d.ts

@@ -1,6 +1,6 @@
 export declare class FrontmatterError extends Error {
-    readonly source?: unknown;
-    constructor(error: Error, source?: unknown);
+    readonly source?: unknown | undefined;
+    constructor(error: Error, source?: unknown | undefined);
     toString(): string;
 }
 export interface FrontmatterOptions {

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/dist/types/which.d.ts

@@ -26,7 +26,8 @@ export interface WhichOptions extends Bun.WhichOptions {
      */
     cache?: WhichCachePolicy;
 }
-export declare const whichFresh: typeof Bun.which;
+declare function darwinWhich(command: string, _options?: Bun.WhichOptions): string | null;
+export declare const whichFresh: typeof darwinWhich;
 /**
  * Locate binary on PATH (with flexible caching).
  *
@@ -35,3 +36,4 @@ export declare const whichFresh: typeof Bun.which;
  * @returns Filesystem path if found, else null
  */
 export declare function $which(command: string, options?: WhichOptions): string | null;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/utils",
-	"version": "0.3.12",
+	"version": "0.3.15",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -24,14 +24,14 @@
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test",
 		"fix": "biome check --write --unsafe .",
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.12",
+		"@sayknow-cli/natives": "0.3.15",
 		"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.
@@ -80,15 +146,10 @@ function formatFatalError(label: string, err: Error): string {
 }
 
 /**
- * True for terminal/pipe write failures (EIO, EPIPE, EBADF, …) on the write side.
- *
- * Bun flushes TTY writes asynchronously, so when the controlling terminal hangs up
- * (terminal closed, external volume stalled, SSH dropped) a restore write issued during
- * shutdown can surface as an uncaughtException on a later tick — after cleanup has already
- * begun. Treating that as fatal logs a scary stack and exits nonzero, which a hosting
- * terminal renders as a crash/restart loop. When it happens mid-shutdown it is a benign
- * artifact, not a real fault. We only match write-side syscalls so genuine bugs (a read
- * EIO, a logic error that happens to carry one of these codes) are never masked.
+ * True for terminal/pipe/disk write failures (EIO, EPIPE, EBADF, …) on the write side.
+ * Covers external-volume stalls and terminal hangups that surface as a late uncaught
+ * exception mid-shutdown — a benign artifact upstream's stdout-EPIPE classifier misses.
+ * Only write-side syscalls match so genuine read/logic bugs are never masked.
  */
 function isBenignIoWriteError(err: unknown): boolean {
 	if (!err || typeof err !== "object") return false;
@@ -103,11 +164,50 @@ function isBenignIoWriteError(err: unknown): boolean {
 	return isIoCode && (syscall === undefined || syscall === "write" || syscall === "writev");
 }
 
+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 (cleanupStage !== "idle" && isBenignIoWriteError(reason)) {
+		logger.debug("Ignoring benign terminal I/O write error during shutdown", {
+			code: (reason as { code?: unknown }).code,
+			syscall: (reason as { syscall?: unknown }).syscall,
+		});
+		return;
+	}
+	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 () => {
-			logger.debug("Shutting down on SIGINT");
-			await runCleanup(Reason.SIGINT);
+			await runCleanupAndWait(Reason.SIGINT);
 			process.exit(130); // 128 + SIGINT (2)
 		})
 		.on("SIGUSR1", () => {
@@ -117,43 +217,21 @@ if (isMainThread) {
 			const url = inspector.url();
 			safeStderrWrite(`Inspector opened: ${url}\n`);
 		})
-		.on("uncaughtException", async err => {
-			// A terminal/stdout write can fail asynchronously (EIO/EPIPE) while we are
-			// already tearing down — e.g. the controlling terminal hung up, or the volume
-			// the runtime lives on stalled. Bun surfaces that on a later tick, after cleanup
-			// has begun. Treat it as a benign shutdown artifact: log at debug and let the
-			// in-progress shutdown own the exit, instead of logging a fatal error and exiting
-			// nonzero (which a hosting terminal renders as a crash/restart loop).
-			if (cleanupStage !== "idle" && isBenignIoWriteError(err)) {
-				logger.debug("Ignoring benign terminal I/O write error during shutdown", {
-					code: (err as { code?: unknown }).code,
-					syscall: (err as { syscall?: unknown }).syscall,
-				});
-				return;
-			}
-			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 () => {
-			logger.warn("Shutting down on SIGTERM (terminated by another process)");
-			await runCleanup(Reason.SIGTERM);
+			await runCleanupAndWait(Reason.SIGTERM);
 			process.exit(143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
-			logger.warn("Shutting down on SIGHUP (controlling terminal hung up / disconnected)");
-			await runCleanup(Reason.SIGHUP);
+			await runCleanupAndWait(Reason.SIGHUP);
 			process.exit(129); // 128 + SIGHUP (1)
 		});
 } else {
@@ -179,8 +257,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 });
 		}
 	};
@@ -194,12 +273,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 () => {};
@@ -225,16 +312,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();
 }