@oh-my-pi/pi-utils 16.5.0 → 16.5.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [16.5.2] - 2026-07-14
+
+### Fixed
+
+- Improved CLI argument and flag validation error output to display a concise error message and command usage instead of a minified code frame.
+- Corrected required variadic positionals to render as `MODELS...` instead of `[MODELS]` in usage help.
+
+## [16.5.1] - 2026-07-14
+
+### Added
+
+- Added terminal stderr guard utilities (suppressTerminalStderr and restoreTerminalStderr) to prevent macOS runtime diagnostics from corrupting TUI viewports while ensuring crash reports remain visible.
+
+### Fixed
+
+- Fixed an issue in Mermaid ASCII routing where unreachable edge attachment points caused unbounded pathfinder searches.
+
 ## [16.4.6] - 2026-07-12
 
 ### Added

package/dist/types/cli.d.ts

@@ -1,3 +1,13 @@
+/**
+ * A user-facing argument/flag validation failure. Thrown by {@link Command.parse}
+ * for missing/invalid positionals and flags. The top-level {@link run} handler
+ * prints its message plus the command usage line to stderr and exits 1, instead
+ * of letting it bubble to the process-level catch — which would dump a minified
+ * `dist/cli.js` code frame over a plain argument mistake (issue #5369).
+ */
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
 export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "string" | "boolean" | "integer"> {
     kind: K;
     description?: string;
@@ -91,6 +101,8 @@ export declare abstract class Command {
 }
 /** Render full root help: header, default command details, subcommand list. */
 export declare function renderRootHelp(config: CliConfig): void;
+/** Build the single USAGE line for a command (without the leading label). */
+export declare function commandUsageLine(bin: string, id: string, Cmd: CommandCtor): string;
 /** Render help for a single command. */
 export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void;
 /** A lazily-loaded command: canonical name, loader, and optional aliases. */

package/dist/types/index.d.ts

@@ -26,6 +26,7 @@ export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree.j
 export * from "./runtime-install.js";
 export * from "./sanitize-text.js";
 export * from "./snowflake.js";
+export * from "./stderr-guard.js";
 export * from "./stream.js";
 export * from "./tab-spacing.js";
 export * from "./temp.js";

package/dist/types/stderr-guard.d.ts

@@ -0,0 +1,22 @@
+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 declare function suppressTerminalStderr(options?: SuppressTerminalStderrOptions): boolean;
+/**
+ * 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 declare function restoreTerminalStderr(): void;
+/** Whether fd 2 is currently redirected away from the terminal. */
+export declare function isTerminalStderrSuppressed(): boolean;

package/dist/types/vendor/mermaid-ascii/ascii/pathfinder.d.ts

@@ -6,7 +6,7 @@ import type { GridCoord, AsciiNode } from './types.js';
 export declare function heuristic(a: GridCoord, b: GridCoord): number;
 /**
  * Find a path from `from` to `to` on the grid using A*.
- * Returns the path as an array of GridCoords, or null if no path exists.
+ * Returns the path as an array of GridCoords, or null if no bounded path exists.
  */
 export declare function getPath(grid: Map<string, AsciiNode>, from: GridCoord, to: GridCoord): GridCoord[] | null;
 /**

package/package.json

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

package/src/cli.ts

@@ -28,6 +28,20 @@ function startupMarker(text: string): void {
 	}
 }
 
+/**
+ * A user-facing argument/flag validation failure. Thrown by {@link Command.parse}
+ * for missing/invalid positionals and flags. The top-level {@link run} handler
+ * prints its message plus the command usage line to stderr and exits 1, instead
+ * of letting it bubble to the process-level catch — which would dump a minified
+ * `dist/cli.js` code frame over a plain argument mistake (issue #5369).
+ */
+export class CliUsageError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CliUsageError";
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Flag & Arg descriptors
 // ---------------------------------------------------------------------------
@@ -190,12 +204,18 @@ export abstract class Command {
 
 		// strict=false when command declares args (positionals must pass through)
 		// or when the command itself opts out
-		const { values: rawValues, positionals } = nodeParseArgs({
-			args: this.argv,
-			options,
-			allowPositionals: true,
-			strict,
-		});
+		const { values: rawValues, positionals } = (() => {
+			try {
+				return nodeParseArgs({
+					args: this.argv,
+					options,
+					allowPositionals: true,
+					strict,
+				});
+			} catch (error) {
+				throw new CliUsageError(error instanceof Error ? error.message : String(error));
+			}
+		})();
 
 		// Convert raw values to proper types and validate
 		const flags: Record<string, unknown> = {};
@@ -207,7 +227,7 @@ export abstract class Command {
 				} else {
 					const n = Number.parseInt(raw as string, 10);
 					if (Number.isNaN(n)) {
-						throw new Error(`Expected integer for --${name}, got "${raw}"`);
+						throw new CliUsageError(`Expected integer for --${name}, got "${raw}"`);
 					}
 					flags[name] = n;
 				}
@@ -220,14 +240,16 @@ export abstract class Command {
 				// Validate options constraint
 				if (val !== undefined && desc.options && !Array.isArray(val)) {
 					if (!desc.options.includes(val as string)) {
-						throw new Error(`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`);
+						throw new CliUsageError(
+							`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`,
+						);
 					}
 				}
 				flags[name] = val;
 			}
 			// Validate required
 			if (desc.required && flags[name] === undefined) {
-				throw new Error(`Missing required flag: --${name}`);
+				throw new CliUsageError(`Missing required flag: --${name}`);
 			}
 		}
 
@@ -246,13 +268,15 @@ export abstract class Command {
 			}
 			// Validate required
 			if (desc.required && args[argName] === undefined) {
-				throw new Error(`Missing required argument: ${argName}`);
+				throw new CliUsageError(`Missing required argument: ${argName}`);
 			}
 			// Validate options constraint
 			const argVal = args[argName];
 			if (argVal !== undefined && desc.options && typeof argVal === "string") {
 				if (!desc.options.includes(argVal)) {
-					throw new Error(`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`);
+					throw new CliUsageError(
+						`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`,
+					);
 				}
 			}
 		}
@@ -294,15 +318,34 @@ export function renderRootHelp(config: CliConfig): void {
 	process.stdout.write(lines.join("\n"));
 }
 
+/**
+ * Format a command's positional args for a USAGE line. Required args render
+ * bare (`MODELS`), optional args wrapped in brackets (`[MODELS]`), and
+ * `multiple` args get a trailing ellipsis (`MODELS...`) so a required
+ * variadic reads as `MODELS...`, not the misleading optional `[MODELS]`.
+ */
+function formatUsageArgs(Cmd: CommandCtor): string {
+	const entries = Object.entries(Cmd.args ?? {});
+	if (entries.length === 0) return "";
+	const parts = entries.map(([name, desc]) => {
+		const label = `${name.toUpperCase()}${desc.multiple ? "..." : ""}`;
+		return desc.required ? label : `[${label}]`;
+	});
+	return ` ${parts.join(" ")}`;
+}
+
+/** Build the single USAGE line for a command (without the leading label). */
+export function commandUsageLine(bin: string, id: string, Cmd: CommandCtor): string {
+	const hasFlags = Object.keys(Cmd.flags ?? {}).length > 0;
+	return `$ ${bin} ${id}${formatUsageArgs(Cmd)}${hasFlags ? " [FLAGS]" : ""}`;
+}
+
 /** Render help for a single command. */
 export function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void {
 	const lines: string[] = [];
 	if (Cmd.description) lines.push(`${Cmd.description}\n`);
 	lines.push("USAGE");
-	const argNames = Object.keys(Cmd.args ?? {});
-	const argStr = argNames.length > 0 ? ` ${argNames.map(n => `[${n.toUpperCase()}]`).join(" ")}` : "";
-	const hasFlags = Object.keys(Cmd.flags ?? {}).length > 0;
-	lines.push(`  $ ${bin} ${id}${argStr}${hasFlags ? " [FLAGS]" : ""}\n`);
+	lines.push(`  ${commandUsageLine(bin, id, Cmd)}\n`);
 	renderCommandBody(lines, Cmd);
 	process.stdout.write(lines.join("\n"));
 }
@@ -435,7 +478,22 @@ export async function run(opts: RunOptions): Promise<void> {
 	const Cmd = await loadEntry(entry);
 	const config: CliConfig = { bin, version, commands: new Map([[entry.name, Cmd]]) };
 	const instance = new Cmd(commandArgv, config);
-	await instance.run();
+	try {
+		await instance.run();
+	} catch (error) {
+		// A usage mistake (missing/invalid arg or flag) is not a crash: print the
+		// message and the command's usage line, then exit 1. Letting it reach the
+		// process-level catch would dump a minified `dist/cli.js` code frame over a
+		// plain argument error (issue #5369).
+		if (error instanceof CliUsageError) {
+			process.stderr.write(`error: ${error.message}\n\n`);
+			process.stderr.write(`USAGE\n  ${commandUsageLine(bin, entry.name, Cmd)}\n`);
+			process.stderr.write(`\nRun \`${bin} ${entry.name} --help\` for details.\n`);
+			process.exitCode = 1;
+			return;
+		}
+		throw error;
+	}
 }
 
 /** Load one command module, leaving streaming markers around the import. */

package/src/index.ts

@@ -26,6 +26,7 @@ export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
 export * from "./runtime-install";
 export * from "./sanitize-text";
 export * from "./snowflake";
+export * from "./stderr-guard";
 export * from "./stream";
 export * from "./tab-spacing";
 export * from "./temp";

package/src/postmortem.ts

@@ -8,6 +8,7 @@
 import inspector from "node:inspector";
 import { isMainThread } from "node:worker_threads";
 import { logger } from ".";
+import { restoreTerminalStderr } from "./stderr-guard";
 
 // Cleanup reasons, in order of priority/meaning.
 export enum Reason {
@@ -166,6 +167,11 @@ if (isMainThread) {
 				logger.warn("Ignoring expected cleanup exception", { err });
 				return;
 			}
+			// fd 2 may be redirected to the log while a TUI owns the terminal
+			// (stderr-guard); re-point it at the real terminal so the fatal
+			// report is visible. Terminal modes are restored moments later by
+			// the terminal-restore cleanup callback inside runCleanup().
+			restoreTerminalStderr();
 			process.stderr.write(formatFatalError("Uncaught Exception", err));
 			logger.error("Uncaught exception", { err });
 			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
@@ -199,6 +205,8 @@ if (isMainThread) {
 					});
 				}
 			}
+			// See uncaughtException above: surface the report on the real stderr.
+			restoreTerminalStderr();
 			process.stderr.write(formatFatalError("Unhandled Rejection", err));
 			logger.error("Unhandled rejection", { err });
 			await runCleanup(Reason.UNHANDLED_REJECTION);

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;
+}

package/src/vendor/mermaid-ascii/ascii/pathfinder.ts

@@ -108,21 +108,75 @@ const MOVE_DIRS: GridCoord[] = [
   { x: 0, y: -1 },
 ]
 
-/** Check if a grid cell is unoccupied and has non-negative coordinates. */
-function isFreeInGrid(grid: Map<string, AsciiNode>, c: GridCoord): boolean {
-  if (c.x < 0 || c.y < 0) return false
+interface SearchBounds {
+  minX: number
+  maxX: number
+  minY: number
+  maxY: number
+  expansionLimit: number
+}
+
+const MIN_ROUTING_MARGIN = 8
+const MIN_EXPANSION_BUDGET = 256
+const MAX_EXPANSION_BUDGET = 50_000
+
+function searchBoundsFor(grid: Map<string, AsciiNode>, from: GridCoord, to: GridCoord): SearchBounds {
+  let minX = Math.min(from.x, to.x)
+  let maxX = Math.max(from.x, to.x)
+  let minY = Math.min(from.y, to.y)
+  let maxY = Math.max(from.y, to.y)
+
+  for (const key of grid.keys()) {
+    const comma = key.indexOf(',')
+    if (comma === -1) continue
+
+    const x = Number(key.slice(0, comma))
+    const y = Number(key.slice(comma + 1))
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue
+
+    minX = Math.min(minX, x)
+    maxX = Math.max(maxX, x)
+    minY = Math.min(minY, y)
+    maxY = Math.max(maxY, y)
+  }
+
+  const width = maxX - minX + 1
+  const height = maxY - minY + 1
+  const margin = Math.max(MIN_ROUTING_MARGIN, Math.ceil(Math.max(width, height) / 2))
+  const boundedMinX = Math.max(0, minX - margin)
+  const boundedMaxX = maxX + margin
+  const boundedMinY = Math.max(0, minY - margin)
+  const boundedMaxY = maxY + margin
+  const area = (boundedMaxX - boundedMinX + 1) * (boundedMaxY - boundedMinY + 1)
+
+  return {
+    minX: boundedMinX,
+    maxX: boundedMaxX,
+    minY: boundedMinY,
+    maxY: boundedMaxY,
+    expansionLimit: Math.min(MAX_EXPANSION_BUDGET, Math.max(MIN_EXPANSION_BUDGET, area * 4)),
+  }
+}
+
+/** Check if a grid cell is unoccupied and inside the bounded routing area. */
+function isFreeInGrid(grid: Map<string, AsciiNode>, c: GridCoord, bounds: SearchBounds): boolean {
+  if (c.x < bounds.minX || c.x > bounds.maxX || c.y < bounds.minY || c.y > bounds.maxY) {
+    return false
+  }
+
   return !grid.has(gridKey(c))
 }
 
 /**
  * Find a path from `from` to `to` on the grid using A*.
- * Returns the path as an array of GridCoords, or null if no path exists.
+ * Returns the path as an array of GridCoords, or null if no bounded path exists.
  */
 export function getPath(
   grid: Map<string, AsciiNode>,
   from: GridCoord,
   to: GridCoord,
 ): GridCoord[] | null {
+  const bounds = searchBoundsFor(grid, from, to)
   const pq = new MinHeap()
   pq.push({ coord: from, priority: 0 })
 
@@ -132,7 +186,13 @@ export function getPath(
   const cameFrom = new Map<string, GridCoord | null>()
   cameFrom.set(gridKey(from), null)
 
+  let expansions = 0
+
   while (pq.length > 0) {
+    if (expansions++ >= bounds.expansionLimit) {
+      return null
+    }
+
     const current = pq.pop()!.coord
 
     if (gridCoordEquals(current, to)) {
@@ -150,9 +210,11 @@ export function getPath(
 
     for (const dir of MOVE_DIRS) {
       const next: GridCoord = { x: current.x + dir.x, y: current.y + dir.y }
+      const insideBounds = next.x >= bounds.minX && next.x <= bounds.maxX
+        && next.y >= bounds.minY && next.y <= bounds.maxY
 
       // Allow moving to the destination even if it's occupied (it's a node boundary)
-      if (!isFreeInGrid(grid, next) && !gridCoordEquals(next, to)) {
+      if (!insideBounds || (!isFreeInGrid(grid, next, bounds) && !gridCoordEquals(next, to))) {
         continue
       }