@linxiraos/pi-utils 1.0.0

package/src/snowflake.ts

@@ -0,0 +1,121 @@
+function randu32() {
+	return crypto.getRandomValues(new Uint32Array(1))[0];
+}
+
+const EPOCH = 1420070400000;
+const MAX_SEQ = 0x3fffff;
+
+// Snowflake as a hex string (16 chars, zero-padded).
+//
+// Since this is not distributed (no machine ID needed), we use an extended
+// 22-bit sequence instead of the standard 10-bit machine ID + 12-bit sequence.
+//
+type Snowflake = string & { readonly __brand: unique symbol };
+
+namespace Snowflake {
+	// Hex string validation pattern (16 lowercase hex chars).
+	//
+	export const PATTERN = /^[0-9a-f]{16}$/;
+
+	// Epoch timestamp.
+	//
+	export const EPOCH_TIMESTAMP = EPOCH;
+
+	// Maximum sequence number.
+	//
+	export const MAX_SEQUENCE = MAX_SEQ;
+
+	// Formats a sequence and timestamp into a snowflake hex string.
+	//
+	// dt fits well within BigInt range: (dt << 22) | seq stays under 2^64 for
+	// any dt < 2^42 (~year 2154), so a single 64-bit format is exact — and
+	// measures ~1.7x faster than stitching four 16-bit hex segments.
+	//
+	export function formatParts(dt: number, seq: number): Snowflake {
+		return ((BigInt(dt) << 22n) | BigInt(seq)).toString(16).padStart(16, "0") as Snowflake;
+	}
+
+	// Snowflake generator type.
+	//
+	export class Source {
+		#seq = 0;
+		constructor(sequence: number = randu32() & MAX_SEQ) {
+			this.#seq = sequence & MAX_SEQ;
+		}
+
+		// Sequence number.
+		//
+		get sequence() {
+			return this.#seq & MAX_SEQ;
+		}
+		set sequence(v: number) {
+			this.#seq = v & MAX_SEQ;
+		}
+		reset() {
+			this.#seq = 0;
+		}
+
+		// Generates the next value as a hex string.
+		//
+		generate(timestamp: number): Snowflake {
+			const seq = (this.#seq + 1) & MAX_SEQ;
+			const dt = timestamp - EPOCH;
+			this.#seq = seq;
+			return formatParts(dt, seq);
+		}
+	}
+
+	// Gets the next snowflake given the timestamp.
+	//
+	let defaultSource: Source | undefined;
+	export function next(timestamp = Date.now()): Snowflake {
+		defaultSource ??= new Source();
+		return defaultSource.generate(timestamp);
+	}
+
+	// Validates a snowflake hex string.
+	//
+	export function valid(value: string): value is Snowflake {
+		return value.length === 16 && PATTERN.test(value);
+	}
+
+	// Returns the upper/lower boundaries for the given timestamp.
+	//
+	export function lowerbound(timelike: Date | number | Snowflake): Snowflake {
+		switch (typeof timelike) {
+			case "object": // Date
+				return formatParts(timelike.getTime() - EPOCH, 0);
+			case "number":
+				return formatParts(timelike - EPOCH, 0);
+			case "string": // Snowflake hex string
+				return timelike;
+		}
+	}
+	export function upperbound(timelike: Date | number | Snowflake): Snowflake {
+		switch (typeof timelike) {
+			case "object": // Date
+				return formatParts(timelike.getTime() - EPOCH, MAX_SEQ);
+			case "number":
+				return formatParts(timelike - EPOCH, MAX_SEQ);
+			case "string": // Snowflake hex string
+				return timelike;
+		}
+	}
+
+	// Returns the individual bits given the snowflake.
+	//
+	export function getSequence(value: Snowflake) {
+		return Number.parseInt(value.substring(8, 16), 16) & MAX_SEQ;
+	}
+	export function getTimestamp(value: Snowflake) {
+		const hi = Number.parseInt(value.substring(0, 8), 16);
+		const lo = Number.parseInt(value.substring(8, 16), 16);
+		// (hi:lo) >> 22 == hi * 2^10 + (lo >>> 22); at most ~2^42, exact in a double.
+		return hi * 1024 + (lo >>> 22) + EPOCH;
+	}
+	export function getDate(value: Snowflake) {
+		return new Date(getTimestamp(value));
+	}
+}
+
+export { Snowflake };

package/src/stderr-guard.ts

@@ -0,0 +1,155 @@
+/**
+ * Terminal stderr guard: keeps unmanaged fd-2 writes off the terminal while a
+ * TUI owns the viewport.
+ *
+ * On macOS, runtime diagnostics are written by the platform directly to file
+ * descriptor 2 at arbitrary times — e.g. libmalloc's "MallocStackLogging:
+ * can't turn off malloc stack logging because it was not enabled" when the OS
+ * broadcasts a memory-diagnostic event to long-lived processes. Those bytes
+ * bypass the renderer and paint straight into the viewport. Stripping the
+ * MallocStackLogging* env vars (cli.ts) only protects child processes; it
+ * cannot stop libmalloc inside THIS process from logging.
+ *
+ * Fix (mirrors openai/codex#24459): while the TUI owns the terminal, dup fd 2
+ * aside and dup2 a redirect target over it; restore the saved fd whenever
+ * terminal ownership is released (external editor, Ctrl+Z suspend, shutdown,
+ * crash restore). Unlike codex we redirect to the omp log file — not
+ * /dev/null — so the diagnostics stay greppable and Bun native-crash reports
+ * (which abort before any JS cleanup can restore fd 2) are preserved.
+ *
+ * Only dup/dup2 go through bun:ffi. fcntl is deliberately avoided: it is
+ * variadic, and the arm64-darwin ABI passes variadic arguments on the stack,
+ * so a fixed-arity FFI signature would read garbage for the third argument.
+ */
+import { dlopen, FFIType } from "bun:ffi";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getLogPath } from "./dirs";
+
+const STDOUT_FILENO = 1;
+const STDERR_FILENO = 2;
+
+interface LibcFdOps {
+	dup(fd: number): number;
+	dup2(oldFd: number, newFd: number): number;
+}
+
+let libcFdOpsCache: LibcFdOps | null | undefined;
+
+function libcFdOps(): LibcFdOps | null {
+	if (libcFdOpsCache !== undefined) return libcFdOpsCache;
+	libcFdOpsCache = null;
+	if (process.platform === "win32") return null;
+	// Darwin: dyld resolves libSystem from the shared cache. Linux: glibc
+	// first, then the generic soname for musl-style layouts.
+	const candidates =
+		process.platform === "darwin" ? ["libSystem.B.dylib", "/usr/lib/libSystem.B.dylib"] : ["libc.so.6", "libc.so"];
+	for (const candidate of candidates) {
+		try {
+			const libc = dlopen(candidate, {
+				dup: { args: [FFIType.i32], returns: FFIType.i32 },
+				dup2: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+			});
+			libcFdOpsCache = libc.symbols;
+			return libcFdOpsCache;
+		} catch {
+			// Try the next candidate; the guard stays inert if none load.
+		}
+	}
+	return libcFdOpsCache;
+}
+
+/**
+ * True when fd 2 writes would land on the same terminal the TUI paints to:
+ * both stdout and stderr are ttys backed by the same device file. A stderr
+ * the user already redirected (`2>file`, `2>/dev/null`, a different tty) must
+ * keep flowing untouched.
+ */
+function stderrSharesStdoutTerminal(): boolean {
+	if (!process.stdout.isTTY || !process.stderr.isTTY) return false;
+	try {
+		const stdoutStat = fs.fstatSync(STDOUT_FILENO);
+		const stderrStat = fs.fstatSync(STDERR_FILENO);
+		return stdoutStat.dev === stderrStat.dev && stdoutStat.ino === stderrStat.ino;
+	} catch {
+		return false;
+	}
+}
+
+/** Saved dup of the real stderr while suppression is active, else null. */
+let savedStderrFd: number | null = null;
+
+export interface SuppressTerminalStderrOptions {
+	/** Redirect target path; defaults to today's omp log file, then /dev/null. */
+	redirectPath?: string;
+	/** Bypass the macOS + same-terminal gate. Tests only. */
+	force?: boolean;
+}
+
+/**
+ * Redirect fd 2 away from the terminal while the TUI owns the viewport.
+ * Returns true when suppression is (already) active. No-op — returning
+ * false — off macOS, when stderr does not target the stdout terminal, or
+ * when the libc fd ops are unavailable.
+ */
+export function suppressTerminalStderr(options?: SuppressTerminalStderrOptions): boolean {
+	if (savedStderrFd !== null) return true;
+	if (!options?.force && (process.platform !== "darwin" || !stderrSharesStdoutTerminal())) {
+		return false;
+	}
+	const libc = libcFdOps();
+	if (!libc) return false;
+
+	let redirectFd: number;
+	try {
+		const redirectPath = options?.redirectPath ?? getLogPath();
+		// getLogsDir() only computes the path; the logger creates it lazily, so
+		// on a fresh profile ~/.omp/logs may not exist yet. Create it here so
+		// diagnostics land in the log instead of falling through to /dev/null.
+		fs.mkdirSync(path.dirname(redirectPath), { recursive: true });
+		redirectFd = fs.openSync(redirectPath, "a");
+	} catch {
+		try {
+			redirectFd = fs.openSync("/dev/null", "w");
+		} catch {
+			return false;
+		}
+	}
+
+	const saved = libc.dup(STDERR_FILENO);
+	if (saved === -1) {
+		fs.closeSync(redirectFd);
+		return false;
+	}
+	if (libc.dup2(redirectFd, STDERR_FILENO) === -1) {
+		fs.closeSync(redirectFd);
+		fs.closeSync(saved);
+		return false;
+	}
+	fs.closeSync(redirectFd);
+	savedStderrFd = saved;
+	return true;
+}
+
+/**
+ * Re-point fd 2 at the saved terminal stderr. Safe to call unconditionally:
+ * no-op when suppression is not active. Called at every terminal-ownership
+ * release and by the postmortem fatal handlers before they print, so crash
+ * reports reach the real terminal.
+ */
+export function restoreTerminalStderr(): void {
+	if (savedStderrFd === null) return;
+	const saved = savedStderrFd;
+	savedStderrFd = null;
+	libcFdOps()?.dup2(saved, STDERR_FILENO);
+	try {
+		fs.closeSync(saved);
+	} catch {
+		// The dup'ed fd is process-owned; a close failure leaves nothing to recover.
+	}
+}
+
+/** Whether fd 2 is currently redirected away from the terminal. */
+export function isTerminalStderrSuppressed(): boolean {
+	return savedStderrFd !== null;
+}