@oh-my-pi/pi-utils 17.1.8 → 17.2.0

package/dist/types/postmortem.d.ts

@@ -64,10 +64,15 @@ export declare function register(id: string, callback: (reason: Reason) => void
  * Use this in workers or when you need to clean up but continue execution.
  */
 export declare function cleanup(): Promise<void>;
+/** Controls how manual process shutdown handles terminal output. */
+export interface QuitOptions {
+    /** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
+    drainStdout?: boolean;
+}
 /**
  * Runs all cleanup callbacks and exits through the current `process.exit`.
  *
- * In main thread: waits for stdout drain, then calls `process.exit()`.
+ * In main thread: waits for stdout drain unless disabled, then calls `process.exit()`.
  * In workers: runs cleanup only (process.exit would kill entire process).
  */
-export declare function quit(code?: number): Promise<void>;
+export declare function quit(code?: number, options?: QuitOptions): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "17.1.8",
+	"version": "17.2.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,10 +31,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.1.8",
+		"@oh-my-pi/pi-natives": "17.2.0",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
-		"winston-daily-rotate-file": "^5.0.0"
+		"winston-daily-rotate-file": "5.0.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/logger.ts

@@ -1,3 +1,5 @@
+/// <reference path="./winston-daily-rotate-file.d.ts" />
+
 /**
  * Centralized logger for omp.
  *
@@ -11,10 +13,13 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { isPromise } from "node:util/types";
-import winston from "winston";
-import DailyRotateFile from "winston-daily-rotate-file";
+import type DailyRotateFile from "winston-daily-rotate-file";
+// Import the implementation directly because the package index imports and mutates
+// Winston. The exact workspace catalog pin protects this internal entrypoint.
+import DailyRotateFileImplementation from "winston-daily-rotate-file/daily-rotate-file.js";
 import { getLogsDir } from "./dirs";
 import { drainModuleLoadEvents } from "./timing-buffer";
 /** Severity names accepted by the centralized logger. */
@@ -143,36 +148,68 @@ function jsonReplacer(_key: string, value: unknown): unknown {
 	return value;
 }
 
-/** Custom format that includes pid and flattens metadata; built on first use. */
-let logFormat: winston.Logform.Format | undefined;
-
-function getLogFormat(): winston.Logform.Format {
-	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, jsonReplacer);
-		}),
+interface NormalizedLogInfo extends Record<string, unknown> {
+	level: LogLevel;
+	message: unknown;
+}
+
+function padTimestampPart(value: number, width = 2): string {
+	return String(value).padStart(width, "0");
+}
+
+function formatLocalTimestamp(date: Date): string {
+	const offsetMinutes = -date.getTimezoneOffset();
+	const absoluteOffset = Math.abs(offsetMinutes);
+	const offsetSign = offsetMinutes >= 0 ? "+" : "-";
+	return (
+		`${padTimestampPart(date.getFullYear(), 4)}-${padTimestampPart(date.getMonth() + 1)}-${padTimestampPart(date.getDate())}` +
+		`T${padTimestampPart(date.getHours())}:${padTimestampPart(date.getMinutes())}:${padTimestampPart(date.getSeconds())}` +
+		`.${padTimestampPart(date.getMilliseconds(), 3)}${offsetSign}${padTimestampPart(Math.floor(absoluteOffset / 60))}` +
+		`:${padTimestampPart(absoluteOffset % 60)}`
 	);
-	return logFormat;
 }
 
+const FORMAT_TOKEN_PATTERN = /%[scdjifoO%]/;
+
+function normalizeLogInfo(
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+): NormalizedLogInfo {
+	const metadata =
+		!FORMAT_TOKEN_PATTERN.test(message) && context !== null && typeof context === "object" ? context : undefined;
+	const info = Object.assign({}, metadata, { level, message }) as NormalizedLogInfo;
+	if (metadata?.message) info.message = `${message} ${metadata.message}`;
+	if (metadata?.stack) info.stack = metadata.stack;
+	if (metadata?.cause) info.cause = metadata.cause;
+	return info;
+}
+
+function formatLogInfo(info: NormalizedLogInfo): string {
+	const timestamp = formatLocalTimestamp(new Date());
+	info.timestamp = timestamp;
+	const entry: Record<string, unknown> = {
+		timestamp,
+		level: info.level,
+		pid: process.pid,
+		message: info.message,
+	};
+	for (const [key, value] of Object.entries(info)) {
+		if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = value;
+	}
+	return JSON.stringify(entry, jsonReplacer) as string;
+}
+
+type FileTransport = DailyRotateFile & {
+	log(info: Record<symbol, string>, callback: () => void): void;
+	close(): void;
+};
+
 /** Build a rotating file transport with process-local rotation and shared retention. */
-function makeFileTransport(dir?: string): winston.transport {
+function makeFileTransport(dir?: string): FileTransport {
 	const logsDir = ensureDir(dir ?? getLogsDir());
 	pruneStaleProcessLogs(logsDir);
-	return new DailyRotateFile({
+	return new DailyRotateFileImplementation({
 		dirname: logsDir,
 		filename: `omp.%DATE%.${process.pid}.log`,
 		datePattern: "YYYY-MM-DD",
@@ -180,45 +217,48 @@ function makeFileTransport(dir?: string): winston.transport {
 		maxFiles: 5,
 		zippedArchive: false,
 		auditFile: path.join(logsDir, `.omp.${process.pid}-audit.json`),
-	});
-}
-
-function makeConsoleTransport(): winston.transport {
-	return new winston.transports.Console({ format: getLogFormat() });
+	}) as FileTransport;
 }
 
 /**
- * Desired transport configuration, applied when the winston logger is built.
+ * Desired transport configuration, applied when local logging is initialized.
  * Default: file ON (TUI-safe), console OFF.
  */
 let transportOpts: { console?: boolean; file?: boolean | string } = { file: true };
 
-/** The winston logger instance, created lazily on first log emission. */
-let winstonLogger: winston.Logger | undefined;
+interface LocalTransports {
+	readonly file: FileTransport | undefined;
+	readonly console: boolean;
+}
+
+/** Local transports, constructed lazily on first log emission. */
+let activeTransports: LocalTransports | undefined;
+
+const TRANSPORT_MESSAGE = Symbol.for("message");
+const onTransportLogged = (): void => {};
 
-function buildTransports(opts: { console?: boolean; file?: boolean | string }): winston.transport[] {
-	const transports: winston.transport[] = [];
-	if (opts.file) transports.push(makeFileTransport(typeof opts.file === "string" ? opts.file : undefined));
-	if (opts.console) transports.push(makeConsoleTransport());
-	return transports;
+function buildTransports(opts: { console?: boolean; file?: boolean | string }): LocalTransports {
+	return {
+		file: opts.file ? makeFileTransport(typeof opts.file === "string" ? opts.file : undefined) : undefined,
+		console: opts.console === true,
+	};
 }
 
-function getWinstonLogger(): winston.Logger {
-	if (!winstonLogger) {
-		const transports = buildTransports(transportOpts);
-		winstonLogger = winston.createLogger({
-			level: "debug",
-			format: getLogFormat(),
-			transports,
-			// A transport-less winston logger console.warns "Attempt to write logs
-			// with no transports" on every emit; mark it silent instead so disabling
-			// all transports is a clean no-op.
-			silent: transports.length === 0,
-			// Don't exit on error - logging failures shouldn't crash the app
-			exitOnError: false,
-		});
-	}
-	return winstonLogger;
+function getLocalTransports(): LocalTransports {
+	activeTransports ??= buildTransports(transportOpts);
+	return activeTransports;
+}
+
+function emitLocally(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
+	const transports = getLocalTransports();
+	const info = normalizeLogInfo(level, message, context);
+	if (!transports.file && !transports.console) return;
+
+	// Winston applied the shared format before dispatch, then the same format a
+	// second time inside Console. Keep those evaluation and timestamp semantics.
+	const line = formatLogInfo(info);
+	if (transports.file) transports.file.log({ [TRANSPORT_MESSAGE]: line }, onTransportLogged);
+	if (transports.console) process.stdout.write(`${formatLogInfo(info)}${os.EOL}`);
 }
 
 /**
@@ -228,12 +268,11 @@ function getWinstonLogger(): winston.Logger {
  */
 export function setTransports(opts: { console?: boolean; file?: boolean | string }): void {
 	transportOpts = opts;
-	if (!winstonLogger) return; // applied lazily when the logger is first built
-	winstonLogger.clear();
-	const transports = buildTransports(opts);
-	for (const transport of transports) winstonLogger.add(transport);
-	// Keep the logger silent when nothing is attached so winston doesn't warn on emit.
-	winstonLogger.silent = transports.length === 0;
+	if (!activeTransports) return; // applied lazily when local logging is first initialized
+	const previousTransports = activeTransports;
+	activeTransports = { file: undefined, console: false };
+	previousTransports.file?.close();
+	activeTransports = buildTransports(opts);
 }
 
 /**
@@ -243,7 +282,7 @@ export function setTransports(opts: { console?: boolean; file?: boolean | string
  */
 export function error(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().error(message, context);
+		emitLocally("error", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}
@@ -257,7 +296,7 @@ export function error(message: string, context?: Record<string, unknown>): void
  */
 export function warn(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().warn(message, context);
+		emitLocally("warn", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}
@@ -271,7 +310,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
  */
 export function info(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().info(message, context);
+		emitLocally("info", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}
@@ -285,7 +324,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
  */
 export function debug(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().debug(message, context);
+		emitLocally("debug", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}

package/src/postmortem.ts

@@ -319,14 +319,20 @@ export function cleanup(): Promise<void> {
 	return runCleanup(Reason.MANUAL);
 }
 
-async function runQuit(code: number, exitMode: "guarded" | "native"): Promise<void> {
+/** Controls how manual process shutdown handles terminal output. */
+export interface QuitOptions {
+	/** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
+	drainStdout?: boolean;
+}
+
+async function runQuit(code: number, exitMode: "guarded" | "native", options: QuitOptions = {}): Promise<void> {
 	await runCleanup(Reason.MANUAL);
 
 	if (!isMainThread) {
 		return; // Workers: cleanup done, let worker exit naturally
 	}
 
-	if (process.stdout.writableLength > 0) {
+	if (options.drainStdout !== false && process.stdout.writableLength > 0) {
 		const { promise, resolve } = Promise.withResolvers<void>();
 		process.stdout.once("drain", resolve);
 		await Promise.race([promise, Bun.sleep(5000)]);
@@ -343,9 +349,9 @@ async function runQuit(code: number, exitMode: "guarded" | "native"): Promise<vo
 /**
  * Runs all cleanup callbacks and exits through the current `process.exit`.
  *
- * In main thread: waits for stdout drain, then calls `process.exit()`.
+ * In main thread: waits for stdout drain unless disabled, then calls `process.exit()`.
  * In workers: runs cleanup only (process.exit would kill entire process).
  */
-export function quit(code: number = 0): Promise<void> {
-	return runQuit(code, "guarded");
+export function quit(code: number = 0, options: QuitOptions = {}): Promise<void> {
+	return runQuit(code, "guarded", options);
 }

package/src/winston-daily-rotate-file.d.ts

@@ -0,0 +1,6 @@
+declare module "winston-daily-rotate-file/daily-rotate-file.js" {
+	import type DailyRotateFile from "winston-daily-rotate-file";
+
+	const DailyRotateFileImplementation: typeof DailyRotateFile;
+	export default DailyRotateFileImplementation;
+}