@oh-my-pi/pi-utils 15.1.2 → 15.1.4

package/dist/types/dirs.d.ts

@@ -137,3 +137,15 @@ export declare function getProjectPluginOverridesPath(cwd?: string): string;
 export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
 /** Get the SSH config file path. */
 export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
+/**
+ * Persistent per-install UUID stored at `~/.omp/install-id`.
+ *
+ * Generated lazily on first call and persisted with `O_CREAT|O_EXCL` so
+ * concurrent first-call races don't clobber each other (loser re-reads the
+ * winner's id). Survives independently of agent state: deleting
+ * `~/.omp/agent/` does not regenerate it. Server-side dedup for grievance
+ * pushes (and similar telemetry) keys on this id.
+ */
+export declare function getInstallId(): string;
+/** Test-only: clear cached install id. Never call from production code. */
+export declare function __resetInstallIdCacheForTests(): void;

package/dist/types/env.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export declare function isValidEnvName(name: string): boolean;
+/**
+ * The only names that are genuinely unsafe to forward to a native `execve`
+ * spawn: empty, containing `=` (would corrupt the `KEY=VALUE` framing) or
+ * NUL (terminates the C string mid-entry). Windows ships standard variables
+ * whose names contain parentheses (e.g. `ProgramFiles(x86)`, `CommonProgramFiles(x86)`)
+ * — those MUST survive the scrub so downstream resolvers (Git Bash discovery
+ * in `procmgr.ts`, etc.) can still read them.
+ */
+export declare function isSafeEnvName(name: string): boolean;
+export declare function isSafeEnvValue(value: string): boolean;
+export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+export declare function parseEnvFile(filePath: string): Record<string, string>;
 /**
  * Intentional re-export of Bun.env.
  *

package/dist/types/fetch-retry.d.ts

@@ -58,7 +58,7 @@ export declare function fetchWithRetry(url: string | URL | ((attempt: number) =>
  * Inspect an arbitrary error value (or its `cause` chain, up to depth 2) for an
  * HTTP status code. Reads `status`, `statusCode`, and `response.status` fields,
  * coerces string values, and falls back to scanning the error message for
- * common patterns like `error (429)` or `HTTP 503`.
+ * common patterns like `Error: 401`, `error (429)`, or `HTTP 503`.
  */
 export declare function extractHttpStatusFromError(error: unknown): number | undefined;
 /**

package/dist/types/index.d.ts

@@ -19,6 +19,7 @@ export * as procmgr from "./procmgr";
 export * as prompt from "./prompt";
 export * as ptree from "./ptree";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./sanitize-text";
 export * from "./snowflake";
 export * from "./stream";
 export * from "./tab-spacing";

package/dist/types/logger.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Replace the active log transports. Pass `console: true, file: false` for
+ * long-running services (the auth broker, etc.) that want their structured
+ * logs piped into a process supervisor instead of the rotating file.
+ */
+export declare function setTransports(opts: {
+    console?: boolean;
+    file?: boolean | string;
+}): void;
 /**
  * Log an error message.
  * @param message - The message to log.
@@ -10,6 +19,12 @@ export declare function error(message: string, context?: Record<string, unknown>
  * @param context - The context to log.
  */
 export declare function warn(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log an informational message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function info(message: string, context?: Record<string, unknown>): void;
 /**
  * Log a debug message.
  * @param message - The message to log.

package/dist/types/sanitize-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Strip ANSI escape sequences, remove control characters / lone surrogates,
+ * and normalize line endings.
+ *
+ * Bun-native implementation of the former native `sanitizeText` (see
+ * `crates/pi-natives/src/text.rs::sanitize_text`). JavaScript strings are
+ * already UTF-16 code-unit arrays. `toWellFormed()` handles the uncommon
+ * malformed path; when it changes the input, replacement characters are
+ * dropped and the normalized result goes through the well-formed sanitizer.
+ *
+ * Fast path: well-formed input with no controls or ANSI returns the original
+ * string after the control probe.
+ */
+export declare function sanitizeText(text: string): string;

package/package.json

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

package/src/dirs.ts

@@ -477,3 +477,76 @@ export function getSSHConfigPath(scope: "user" | "project", cwd: string = getPro
 	}
 	return path.join(getProjectAgentDir(cwd), "ssh.json");
 }
+
+// =============================================================================
+// Install identity
+// =============================================================================
+
+let cachedInstallId: string | null = null;
+
+const INSTALL_ID_FILE = "install-id";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Persistent per-install UUID stored at `~/.omp/install-id`.
+ *
+ * Generated lazily on first call and persisted with `O_CREAT|O_EXCL` so
+ * concurrent first-call races don't clobber each other (loser re-reads the
+ * winner's id). Survives independently of agent state: deleting
+ * `~/.omp/agent/` does not regenerate it. Server-side dedup for grievance
+ * pushes (and similar telemetry) keys on this id.
+ */
+export function getInstallId(): string {
+	if (cachedInstallId) return cachedInstallId;
+	const filePath = path.join(getConfigRootDir(), INSTALL_ID_FILE);
+
+	let observedInvalid = false;
+	try {
+		const existing = fs.readFileSync(filePath, "utf8").trim();
+		if (UUID_RE.test(existing)) {
+			cachedInstallId = existing;
+			return existing;
+		}
+		// File present but unparseable — fall through and overwrite below.
+		observedInvalid = existing.length > 0;
+	} catch {}
+
+	const next = crypto.randomUUID();
+	try {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		// If we already saw garbage in the file, unlink first so O_EXCL doesn't
+		// trip on it. Ignored if the unlink races against another writer.
+		if (observedInvalid) {
+			try {
+				fs.unlinkSync(filePath);
+			} catch {}
+		}
+		const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+		try {
+			fs.writeSync(fd, `${next}\n`);
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch (err) {
+		// Lost the create race — re-read whatever the winner wrote.
+		if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+			try {
+				const existing = fs.readFileSync(filePath, "utf8").trim();
+				if (UUID_RE.test(existing)) {
+					cachedInstallId = existing;
+					return existing;
+				}
+			} catch {}
+		}
+		// Any other failure: keep the generated id in-memory so the rest of
+		// this process has a stable value; future processes will retry.
+	}
+
+	cachedInstallId = next;
+	return next;
+}
+
+/** Test-only: clear cached install id. Never call from production code. */
+export function __resetInstallIdCacheForTests(): void {
+	cachedInstallId = null;
+}

package/src/env.ts

@@ -3,13 +3,50 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { getAgentDir, getConfigRootDir } from "./dirs";
 
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export function isValidEnvName(name: string): boolean {
+	return ENV_NAME_RE.test(name);
+}
+
+/**
+ * The only names that are genuinely unsafe to forward to a native `execve`
+ * spawn: empty, containing `=` (would corrupt the `KEY=VALUE` framing) or
+ * NUL (terminates the C string mid-entry). Windows ships standard variables
+ * whose names contain parentheses (e.g. `ProgramFiles(x86)`, `CommonProgramFiles(x86)`)
+ * — those MUST survive the scrub so downstream resolvers (Git Bash discovery
+ * in `procmgr.ts`, etc.) can still read them.
+ */
+export function isSafeEnvName(name: string): boolean {
+	return name.length > 0 && !name.includes("=") && !name.includes("\0");
+}
+
+export function isSafeEnvValue(value: string): boolean {
+	return !value.includes("\0");
+}
+
+export function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const key in env) {
+		const value = env[key];
+		if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) continue;
+		result[key] = value;
+	}
+	return result;
+}
+
 /**
  * Parses a .env file synchronously and extracts key-value string pairs.
  * Ignores lines that are empty or start with '#'. Trims whitespace.
  * Allows values to be quoted with single or double quotes.
  * Returns an object of key-value pairs.
  */
-function parseEnvFile(filePath: string): Record<string, string> {
+export function parseEnvFile(filePath: string): Record<string, string> {
 	const result: Record<string, string> = {};
 	try {
 		const content = fs.readFileSync(filePath, "utf-8");
@@ -22,12 +59,15 @@ function parseEnvFile(filePath: string): Record<string, string> {
 			if (eqIndex === -1) continue;
 
 			const key = trimmed.slice(0, eqIndex).trim();
+			if (!isValidEnvName(key)) continue;
+
 			let value = trimmed.slice(eqIndex + 1).trim();
 
 			// Remove surrounding quotes (" or ')
 			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
 				value = value.slice(1, -1);
 			}
+			if (!isSafeEnvValue(value)) continue;
 
 			result[key] = value;
 		}
@@ -51,10 +91,17 @@ const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
 const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
 const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
 
+for (const key of Object.keys(Bun.env)) {
+	const value = Bun.env[key];
+	if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) {
+		delete Bun.env[key];
+	}
+}
+
 for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
-	for (const [key, value] of Object.entries(file)) {
+	for (const key in file) {
 		if (!Bun.env[key]) {
-			Bun.env[key] = value;
+			Bun.env[key] = file[key];
 		}
 	}
 }

package/src/fetch-retry.ts

@@ -198,7 +198,7 @@ function resolveDefaultDelay(
  * Inspect an arbitrary error value (or its `cause` chain, up to depth 2) for an
  * HTTP status code. Reads `status`, `statusCode`, and `response.status` fields,
  * coerces string values, and falls back to scanning the error message for
- * common patterns like `error (429)` or `HTTP 503`.
+ * common patterns like `Error: 401`, `error (429)`, or `HTTP 503`.
  */
 export function extractHttpStatusFromError(error: unknown): number | undefined {
 	return extractHttpStatusFromErrorInternal(error, 0);
@@ -236,6 +236,7 @@ function extractHttpStatusFromErrorInternal(error: unknown, depth: number): numb
 }
 
 const STATUS_MESSAGE_PATTERNS = [
+	/\berror\s*[:=]\s*(\d{3})\b/i,
 	/error\s*\((\d{3})\)/i,
 	/status\s*[:=]?\s*(\d{3})/i,
 	/\bhttp\s*(\d{3})\b/i,

package/src/index.ts

@@ -19,6 +19,7 @@ export * as procmgr from "./procmgr";
 export * as prompt from "./prompt";
 export * as ptree from "./ptree";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./sanitize-text";
 export * from "./snowflake";
 export * from "./stream";
 export * from "./tab-spacing";

package/src/logger.ts

@@ -1,8 +1,13 @@
 /**
- * Centralized file logger for omp.
+ * Centralized logger for omp.
  *
- * Logs to ~/.omp/logs/ with size-based rotation, supporting concurrent omp instances.
- * Each log entry includes process.pid for traceability.
+ * Default: rotating `~/.omp/logs/omp.<DATE>.log`, no console output (writing
+ * to stdout/stderr would corrupt the TUI). Long-running headless services
+ * (the auth broker, etc.) call {@link setTransports} to swap in a console
+ * transport so a process supervisor (pm2, journald, k8s) captures the logs.
+ *
+ * Each entry includes `process.pid` so concurrent omp instances stay
+ * traceable.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
@@ -10,13 +15,12 @@ import winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
 import { getLogsDir } from "./dirs";
 
-/** Ensure logs directory exists */
-function ensureLogsDir(): string {
-	const logsDir = getLogsDir();
-	if (!fs.existsSync(logsDir)) {
-		fs.mkdirSync(logsDir, { recursive: true });
+/** Ensure a logs directory exists; return the resolved path. */
+function ensureDir(dir: string): string {
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
 	}
-	return logsDir;
+	return dir;
 }
 
 /** Custom format that includes pid and flattens metadata */
@@ -39,25 +43,44 @@ const logFormat = winston.format.combine(
 	}),
 );
 
-/** Size-based rotating file transport */
-const fileTransport = new DailyRotateFile({
-	dirname: ensureLogsDir(),
-	filename: "omp.%DATE%.log",
-	datePattern: "YYYY-MM-DD",
-	maxSize: "10m",
-	maxFiles: 5,
-	zippedArchive: true,
-});
+/** Build a rotating file transport, materializing the target directory lazily. */
+function makeFileTransport(dir?: string): winston.transport {
+	return new DailyRotateFile({
+		dirname: ensureDir(dir ?? getLogsDir()),
+		filename: "omp.%DATE%.log",
+		datePattern: "YYYY-MM-DD",
+		maxSize: "10m",
+		maxFiles: 5,
+		zippedArchive: true,
+	});
+}
+
+function makeConsoleTransport(): winston.transport {
+	return new winston.transports.Console({ format: logFormat });
+}
 
-/** The winston logger instance */
+/** The winston logger instance. Default: file ON (TUI-safe), console OFF. */
 const winstonLogger = winston.createLogger({
 	level: "debug",
 	format: logFormat,
-	transports: [fileTransport],
+	transports: [makeFileTransport()],
 	// Don't exit on error - logging failures shouldn't crash the app
 	exitOnError: false,
 });
 
+/**
+ * Replace the active log transports. Pass `console: true, file: false` for
+ * long-running services (the auth broker, etc.) that want their structured
+ * logs piped into a process supervisor instead of the rotating file.
+ */
+export function setTransports(opts: { console?: boolean; file?: boolean | string }): void {
+	winstonLogger.clear();
+	if (opts.file) {
+		winstonLogger.add(makeFileTransport(typeof opts.file === "string" ? opts.file : undefined));
+	}
+	if (opts.console) winstonLogger.add(makeConsoleTransport());
+}
+
 /**
  * Log an error message.
  * @param message - The message to log.
@@ -84,6 +107,19 @@ export function warn(message: string, context?: Record<string, unknown>): void {
 	}
 }
 
+/**
+ * Log an informational message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function info(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.info(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
 /**
  * Log a debug message.
  * @param message - The message to log.

package/src/procmgr.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Process, ProcessStatus } from "@oh-my-pi/pi-natives";
 import type { Subprocess } from "bun";
-import { $env } from "./env";
+import { $env, filterProcessEnv } from "./env";
 import { $which } from "./which";
 
 export interface ShellConfig {
@@ -45,7 +45,7 @@ function isExecutable(path: string): boolean {
 function buildSpawnEnv(shell: string): Record<string, string> {
 	const noCI = $env.PI_BASH_NO_CI || $env.CLAUDE_BASH_NO_CI;
 	return {
-		...Bun.env,
+		...filterProcessEnv(Bun.env),
 		SHELL: shell,
 		GIT_EDITOR: "true",
 		GPG_TTY: "not a tty",

package/src/sanitize-text.ts

@@ -0,0 +1,38 @@
+/**
+ * Strip ANSI escape sequences, remove control characters / lone surrogates,
+ * and normalize line endings.
+ *
+ * Bun-native implementation of the former native `sanitizeText` (see
+ * `crates/pi-natives/src/text.rs::sanitize_text`). JavaScript strings are
+ * already UTF-16 code-unit arrays. `toWellFormed()` handles the uncommon
+ * malformed path; when it changes the input, replacement characters are
+ * dropped and the normalized result goes through the well-formed sanitizer.
+ *
+ * Fast path: well-formed input with no controls or ANSI returns the original
+ * string after the control probe.
+ */
+
+const ESC_CHAR = "\x1b";
+
+// Well-formed strings only need control/ANSI detection: C0 (excl. \t \n),
+// CR, DEL, and C1. ESC (0x1B) is in \x0B-\x1F.
+const CONTROL_RE = /[\x00-\x08\x0B-\x1F\x7F-\x9F]/g;
+
+const REPLACEMENT_CHAR = "\ufffd";
+
+export function sanitizeText(text: string): string {
+	const wellFormed = text.toWellFormed();
+	if (wellFormed !== text) {
+		return sanitizeWellFormedText(wellFormed.replaceAll(REPLACEMENT_CHAR, ""));
+	}
+	return sanitizeWellFormedText(text);
+}
+
+function sanitizeWellFormedText(text: string): string {
+	CONTROL_RE.lastIndex = 0;
+	if (CONTROL_RE.exec(text) === null) return text;
+
+	const stripped = text.indexOf(ESC_CHAR) === -1 ? text : Bun.stripANSI(text);
+	CONTROL_RE.lastIndex = 0;
+	return stripped.replace(CONTROL_RE, "");
+}