@prometheus-ai/utils 0.5.0

package/src/peek-file.ts

@@ -0,0 +1,188 @@
+/**
+ * Read the first `maxBytes` of a file (offset 0) and pass that slice to `op`.
+ *
+ * Buffers are reused to avoid allocating on every peek: sync uses one growable
+ * `Uint8Array`; async uses a small fixed pool of `Buffer`s with a bounded wait
+ * queue, falling back to a fresh allocation when the pool and queue are saturated
+ * or when `maxBytes` exceeds the pool slot size.
+ */
+import * as fs from "node:fs";
+
+/** Async pool slot size; larger peeks allocate ad hoc. */
+const POOLED_BUFFER_SIZE = 512;
+const ASYNC_POOL_SIZE = 10;
+/** Cap waiter queue so heavy concurrency does not queue unbounded; overflow uses alloc. */
+const MAX_ASYNC_WAITERS = 4;
+const INITIAL_SYNC_BUFFER_SIZE = 1024;
+const EMPTY_BUFFER = Buffer.alloc(0);
+
+const asyncPool = Array.from({ length: ASYNC_POOL_SIZE }, () => Buffer.allocUnsafe(POOLED_BUFFER_SIZE));
+const availableAsyncPoolIndexes = Array.from({ length: ASYNC_POOL_SIZE }, (_, index) => index);
+const asyncPoolWaiters: Array<(index: number) => void> = [];
+let syncPool = new Uint8Array(INITIAL_SYNC_BUFFER_SIZE);
+
+/** Returns a pool slot index, or `-1` when the caller should use a standalone buffer. */
+function acquireAsyncPoolIndex(): Promise<number> | number {
+	const index = availableAsyncPoolIndexes.pop();
+	if (index !== undefined) {
+		return index;
+	}
+	if (asyncPoolWaiters.length >= MAX_ASYNC_WAITERS) {
+		return -1;
+	}
+	const { promise, resolve } = Promise.withResolvers<number>();
+	asyncPoolWaiters.push(resolve);
+	return promise;
+}
+
+function releaseAsyncPoolIndex(index: number): void {
+	if (index < 0) {
+		return;
+	}
+	const waiter = asyncPoolWaiters.shift();
+	if (waiter) {
+		waiter(index);
+		return;
+	}
+	availableAsyncPoolIndexes.push(index);
+}
+
+async function withAsyncPoolBuffer<T>(maxBytes: number, op: (buffer: Buffer) => Promise<T>): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > POOLED_BUFFER_SIZE) {
+		return op(Buffer.allocUnsafe(maxBytes));
+	}
+
+	const poolIndex = await acquireAsyncPoolIndex();
+	const buffer = poolIndex >= 0 ? asyncPool[poolIndex] : Buffer.allocUnsafe(maxBytes);
+	try {
+		return await op(buffer.subarray(0, maxBytes));
+	} finally {
+		releaseAsyncPoolIndex(poolIndex);
+	}
+}
+
+function withSyncPoolBuffer<T>(maxBytes: number, op: (buffer: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > syncPool.byteLength) {
+		syncPool = new Uint8Array(maxBytes + (maxBytes >> 1));
+	}
+	return op(syncPool.subarray(0, maxBytes));
+}
+
+/**
+ * Synchronously reads up to `maxBytes` from the start of `filePath` and returns `op(header)`.
+ * If the file is shorter, `header` is only the bytes actually read.
+ */
+export function peekFileSync<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = fs.openSync(filePath, "r");
+	try {
+		return withSyncPoolBuffer(maxBytes, buffer => {
+			const bytesRead = fs.readSync(fileHandle, buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		fs.closeSync(fileHandle);
+	}
+}
+
+/**
+ * Like {@link peekFileSync} but uses async I/O.
+ */
+export async function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		return await withAsyncPoolBuffer(maxBytes, async buffer => {
+			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		await fileHandle.close();
+	}
+}
+
+/**
+ * Read up to the last `maxBytes` of `filePath` and pass that slice to `op`.
+ *
+ * The tail mirror of {@link peekFile}: same pooled-buffer strategy (no per-call
+ * allocation for small reads), but the read is positioned at `size - len` so the
+ * window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
+ * returned. A multi-byte codepoint straddling the leading cut decodes to a
+ * replacement char — callers that parse line-oriented tails drop the partial
+ * leading line anyway.
+ */
+export async function peekFileTail<T>(filePath: string, maxBytes: number, op: (tail: Uint8Array) => T): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		const { size } = await fileHandle.stat();
+		const len = Math.min(maxBytes, size);
+		if (len <= 0) {
+			return op(EMPTY_BUFFER);
+		}
+		return await withAsyncPoolBuffer(len, async buffer => {
+			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, size - len);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		await fileHandle.close();
+	}
+}
+
+/**
+ * Read up to the first `prefixBytes` and last `suffixBytes` of `filePath`, then
+ * pass both slices to `op`.
+ *
+ * Uses a single open/stat sequence. When the whole file fits in the head window,
+ * the tail is sliced from the already-read head bytes instead of issuing a
+ * second read.
+ */
+export async function peekFileEnds<T>(
+	filePath: string,
+	prefixBytes: number,
+	suffixBytes: number,
+	op: (head: Uint8Array, tail: Uint8Array) => T,
+): Promise<T> {
+	if (prefixBytes <= 0 && suffixBytes <= 0) {
+		return op(EMPTY_BUFFER, EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		const { size } = await fileHandle.stat();
+		const headLen = prefixBytes > 0 ? Math.min(prefixBytes, size) : 0;
+		const tailLen = suffixBytes > 0 ? Math.min(suffixBytes, size) : 0;
+
+		const head = headLen > 0 ? Buffer.allocUnsafe(headLen) : EMPTY_BUFFER;
+		const headBytesRead = headLen > 0 ? (await fileHandle.read(head, 0, head.byteLength, 0)).bytesRead : 0;
+		const headSlice = head.subarray(0, headBytesRead);
+
+		if (tailLen <= 0) {
+			return op(headSlice, EMPTY_BUFFER);
+		}
+		if (size <= headLen) {
+			return op(headSlice, headSlice.subarray(Math.max(0, headBytesRead - tailLen)));
+		}
+
+		const tail = Buffer.allocUnsafe(tailLen);
+		const { bytesRead: tailBytesRead } = await fileHandle.read(tail, 0, tail.byteLength, size - tailLen);
+		return op(headSlice, tail.subarray(0, tailBytesRead));
+	} finally {
+		await fileHandle.close();
+	}
+}

package/src/postmortem.ts

@@ -0,0 +1,196 @@
+/**
+ * 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 inspector from "node:inspector";
+import { isMainThread } from "node:worker_threads";
+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.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 });
+			}
+		}
+		cleanupStage = "complete";
+	});
+}
+
+// Register signal and error event handlers to trigger cleanup before exit.
+// Main thread: full signal handling (SIGINT, SIGTERM, SIGHUP) + exceptions + exit
+// Worker thread: exit only (workers use self.addEventListener for exceptions)
+let inspectorOpened = false;
+
+function formatFatalError(label: string, err: Error): string {
+	const name = err.name || "Error";
+	const message = err.message || "(no message)";
+	const stack = err.stack || "";
+	const stackLines = stack.split("\n").slice(1);
+	const formattedStack = stackLines.length > 0 ? `\n${stackLines.join("\n")}` : "";
+	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
+}
+
+if (isMainThread) {
+	process
+		.on("SIGINT", async () => {
+			await runCleanup(Reason.SIGINT);
+			process.exit(130); // 128 + SIGINT (2)
+		})
+		.on("SIGUSR1", () => {
+			if (inspectorOpened) return;
+			inspectorOpened = true;
+			inspector.open(undefined, undefined, false);
+			const url = inspector.url();
+			process.stderr.write(`Inspector opened: ${url}\n`);
+		})
+		.on("uncaughtException", async err => {
+			process.stderr.write(formatFatalError("Uncaught Exception", err));
+			logger.error("Uncaught exception", { err });
+			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
+			process.exit(1);
+		})
+		.on("unhandledRejection", async reason => {
+			const err = reason instanceof Error ? reason : new Error(String(reason));
+			process.stderr.write(formatFatalError("Unhandled Rejection", err));
+			logger.error("Unhandled rejection", { err });
+			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.
+ *
+ * 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 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);
+		await Promise.race([promise, Bun.sleep(5000)]);
+	}
+	process.exit(code);
+}

package/src/procmgr.ts

@@ -0,0 +1,195 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Process, ProcessStatus } from "@prometheus-ai/natives";
+import type { Subprocess } from "bun";
+import { $env, filterProcessEnv } from "./env";
+import { $which } from "./which";
+
+export interface ShellConfig {
+	shell: string;
+	args: string[];
+	env: Record<string, string>;
+	prefix: string | undefined;
+}
+let cachedShellConfig: ShellConfig | null = null;
+
+/**
+ * Check if a shell binary is executable.
+ */
+function isExecutable(path: string): boolean {
+	try {
+		fs.accessSync(path, fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Build the spawn environment (cached).
+ */
+function buildSpawnEnv(shell: string): Record<string, string> {
+	const noCI = $env.PROMETHEUS_BASH_NO_CI || $env.CLAUDE_BASH_NO_CI;
+	return {
+		...filterProcessEnv(Bun.env),
+		SHELL: shell,
+		GIT_EDITOR: "true",
+		GPG_TTY: "not a tty",
+		PROMETHEUS_CODE: "1",
+		CLAUDECODE: "1",
+		...(noCI ? {} : { CI: "true" }),
+	} as Record<string, string>;
+}
+
+/**
+ * Get shell args, optionally including login shell flag.
+ * Supports PROMETHEUS_BASH_NO_LOGIN and CLAUDE_BASH_NO_LOGIN to skip -l.
+ */
+function getShellArgs(): string[] {
+	const noLogin = $env.PROMETHEUS_BASH_NO_LOGIN || $env.CLAUDE_BASH_NO_LOGIN;
+	return noLogin ? ["-c"] : ["-l", "-c"];
+}
+
+/**
+ * Get shell prefix for wrapping commands (profilers, strace, etc.).
+ */
+function getShellPrefix(): string | undefined {
+	return $env.PROMETHEUS_SHELL_PREFIX || $env.CLAUDE_CODE_SHELL_PREFIX;
+}
+
+/**
+ * Build full shell config from a shell path.
+ */
+function buildConfig(shell: string): ShellConfig {
+	return {
+		shell,
+		args: getShellArgs(),
+		env: buildSpawnEnv(shell),
+		prefix: getShellPrefix(),
+	};
+}
+
+/**
+ * Resolve a basic shell (bash or sh) as fallback.
+ */
+export function resolveBasicShell(): string | undefined {
+	for (const name of ["bash", "bash.exe", "sh", "sh.exe"]) {
+		const resolved = $which(name);
+		if (resolved) return resolved;
+	}
+
+	if (process.platform !== "win32") {
+		const searchPaths = ["/bin", "/usr/bin", "/usr/local/bin", "/opt/homebrew/bin"];
+		const candidates = ["bash", "sh"];
+
+		for (const name of candidates) {
+			for (const dir of searchPaths) {
+				const fullPath = path.join(dir, name);
+				if (fs.existsSync(fullPath)) return fullPath;
+			}
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Get shell configuration based on platform.
+ * Resolution order:
+ * 1. User-specified shellPath in settings.json
+ * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 3. On Unix: $SHELL if bash/zsh, then fallback paths
+ * 4. Fallback: sh
+ */
+export function getShellConfig(customShellPath?: string): ShellConfig {
+	if (cachedShellConfig) {
+		return cachedShellConfig;
+	}
+
+	// 1. Check user-specified shell path
+	if (customShellPath) {
+		if (fs.existsSync(customShellPath)) {
+			cachedShellConfig = buildConfig(customShellPath);
+			return cachedShellConfig;
+		}
+		throw new Error(
+			`Custom shell path not found: ${customShellPath}\nPlease update shellPath in ~/.prometheus/agent/settings.json`,
+		);
+	}
+
+	if (process.platform === "win32") {
+		// 2. Try Git Bash in known locations
+		const paths: string[] = [];
+		const programFiles = Bun.env.ProgramFiles;
+		if (programFiles) {
+			paths.push(`${programFiles}\\Git\\bin\\bash.exe`);
+		}
+		const programFilesX86 = Bun.env["ProgramFiles(x86)"];
+		if (programFilesX86) {
+			paths.push(`${programFilesX86}\\Git\\bin\\bash.exe`);
+		}
+
+		for (const path of paths) {
+			if (fs.existsSync(path)) {
+				cachedShellConfig = buildConfig(path);
+				return cachedShellConfig;
+			}
+		}
+
+		// 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)
+		const bashOnPath = $which("bash.exe");
+		if (bashOnPath) {
+			cachedShellConfig = buildConfig(bashOnPath);
+			return cachedShellConfig;
+		}
+
+		throw new Error(
+			`No bash shell found. Options:\n` +
+				`  1. Install Git for Windows: https://git-scm.com/download/win\n` +
+				`  2. Add your bash to PATH (Cygwin, MSYS2, etc.)\n` +
+				`  3. Set shellPath in ~/.prometheus/agent/settings.json\n\n` +
+				`Searched Git Bash in:\n${paths.map(p => `  ${p}`).join("\n")}`,
+		);
+	}
+
+	// Unix: prefer user's shell from $SHELL if it's bash/zsh and executable
+	const userShell = Bun.env.SHELL;
+	const isValidShell = userShell && (userShell.includes("bash") || userShell.includes("zsh"));
+	if (isValidShell && isExecutable(userShell)) {
+		cachedShellConfig = buildConfig(userShell);
+		return cachedShellConfig;
+	}
+
+	// 4. Fallback: use basic shell
+	const basicShell = resolveBasicShell();
+	if (basicShell) {
+		cachedShellConfig = buildConfig(basicShell);
+		return cachedShellConfig;
+	}
+	cachedShellConfig = buildConfig("sh");
+	return cachedShellConfig;
+}
+
+/**
+ * Check if a process is running.
+ */
+export function isPidRunning(pid: number | Subprocess): boolean {
+	if (typeof pid !== "number") {
+		if (pid.killed) return false;
+		if (pid.exitCode !== null) return false;
+		return true;
+	}
+
+	return Process.fromPid(pid)?.status() === ProcessStatus.Running;
+}
+
+export async function onProcessExit(proc: Subprocess | number, abortSignal?: AbortSignal): Promise<boolean> {
+	if (typeof proc !== "number") {
+		return proc.exited.then(
+			() => true,
+			() => true,
+		);
+	}
+
+	return (await Process.fromPid(proc)?.waitForExit({ signal: abortSignal })) ?? true;
+}