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

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/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.3",
 	"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.3",
 		"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/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/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, "");
+}