@oh-my-pi/pi-utils 18.2.4 → 18.2.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [18.2.5] - 2026-09-17
+
+### Added
+
+- Added utilities for reading dotenv-sourced environment values, customizing filtered child-shell environment values, converting color palettes to RGB, cleaning trailing spaces from YAML block headers, and counting newlines in text.
+
+### Fixed
+
+- Improved rotating file logging performance by reusing an append file descriptor for each active log file.
+- Improved JSON serialization performance by avoiding unnecessary bigint handling when serializing values without bigints.
+- Fixed `$which` cache collisions for lookups using different PATH or working-directory options.
+- SSE token reads now expose raw wire-line data only when explicitly requested; the default token path no longer includes per-line raw slices.
+
 ## [18.2.3] - 2026-09-17
 
 ### Fixed

package/dist/types/color.d.ts

@@ -82,6 +82,8 @@ export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;
  * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
  */
 export declare function hslToHex(h: number, s: number, l: number): string;
+/** Parse a 256-color palette index (0–255) to RGB (0..255). */
+export declare function paletteToRgb(index: number): RGB | undefined;
 export interface OKLCH {
     /** Perceptual lightness (0-1) */
     l: number;

package/dist/types/env.d.ts

@@ -36,6 +36,8 @@ export declare function filterProcessEnv(env: Record<string, string | undefined>
 export declare function stripGitRepoLocationEnv(env: Record<string, string>, platform?: NodeJS.Platform): void;
 /** Filters process env for child shells without launch-cwd dotenv values. */
 export declare function filterChildShellEnv(env: Record<string, string | undefined>, cwd?: string): Record<string, string>;
+/** Return every value defined by `cwd`'s dotenv files, plus environment values that came from them. */
+export declare function getDotenvEnvValues(cwd?: string, env?: Record<string, string | undefined>): string[];
 /**
  * Parses a complete .env file with the runtime's dotenv grammar, then retains
  * only shell-identifier names and spawn-safe values before mirroring valid

package/dist/types/format.d.ts

@@ -14,6 +14,13 @@ export declare function formatNumber(n: number): string;
  * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
  */
 export declare function formatBytes(bytes: number): string;
+/**
+ * Count `\n` code units via native `indexOf` — no split array, roughly an
+ * order of magnitude cheaper than a per-code-unit loop on multi-MiB text.
+ * Line-count semantics are the caller's (empty text is 0 or 1 lines
+ * depending on the contract).
+ */
+export declare function countNewlines(text: string): number;
 /**
  * Truncate a string to maxLen characters, appending an ellipsis if truncated.
  * For display-width-aware truncation (terminals), use truncateToWidth from @oh-my-pi/pi-tui.

package/dist/types/index.d.ts

@@ -40,4 +40,5 @@ export * from "./tls-fetch.js";
 export * from "./type-guards.js";
 export * from "./version.js";
 export * from "./which.js";
+export * from "./yaml-config.js";
 export declare function structuredCloneJSON<T>(value: T): T;

package/dist/types/stream.d.ts

@@ -91,6 +91,15 @@ export declare function readSseJsonOrText<T>(stream: ReadableStream<Uint8Array>,
 export interface ServerSentEvent {
     event: string | null;
     data: string;
+    /**
+     * Decoded wire lines for this event (`event:`/`data:`/etc.), for the
+     * diagnostic pipeline. Populated only when the reader opts in via
+     * {@link ReadSseEventsOptions.captureRaw} (or attaches an `onSseEvent`
+     * observer to the JSON readers, which opt in automatically); otherwise
+     * `[]`. Direct `readSseEvents` callers that need wire text must pass
+     * `{ captureRaw: true }` — the field is allocation-free by default so
+     * the token path pays no per-frame array/slice cost.
+     */
     raw: string[];
     id?: string;
     retry?: number;
@@ -114,7 +123,16 @@ export interface ServerSentEvent {
  * }
  * ```
  */
-export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ServerSentEvent>;
+export interface ReadSseEventsOptions {
+    /**
+     * Capture per-line wire text into `event.raw` for the diagnostic
+     * pipeline (`onSseEvent` observers, raw-SSE viewer). Off by default:
+     * every frame otherwise pays an array allocation plus one string slice
+     * per line on the token path.
+     */
+    captureRaw?: boolean;
+}
+export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, options?: ReadSseEventsOptions): AsyncGenerator<ServerSentEvent>;
 /**
  * Parse a complete JSONL string, skipping malformed lines instead of throwing.
  *

package/dist/types/which.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cache policy for which lookups.
  */
-export declare const enum WhichCachePolicy {
+export declare enum WhichCachePolicy {
     /**
      * Use cached result if available.
      */
@@ -22,7 +22,7 @@ export declare const enum WhichCachePolicy {
 export interface WhichOptions extends Bun.WhichOptions {
     /**
      * Cache policy for the lookup.
-     * Defaults to `WhichCachePolicy.Fresh`.
+     * Defaults to `WhichCachePolicy.Cached`.
      */
     cache?: WhichCachePolicy;
     /**

package/dist/types/yaml-config.d.ts

@@ -0,0 +1,2 @@
+/** Serialize config YAML without Bun's trailing space on block mapping headers. */
+export declare function stringifyYamlConfig(value: unknown): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.2.4",
+	"version": "18.2.5",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -54,7 +54,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.2.4"
+		"@oh-my-pi/pi-natives": "18.2.5"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/color.ts

@@ -239,7 +239,7 @@ const ANSI_16: readonly (readonly [number, number, number])[] = [
 const CUBE_STEPS = [0, 95, 135, 175, 215, 255] as const;
 
 /** Parse a 256-color palette index (0–255) to RGB (0..255). */
-function paletteToRgb(index: number): RGB | undefined {
+export function paletteToRgb(index: number): RGB | undefined {
 	if (!Number.isInteger(index) || index < 0 || index > 255) return undefined;
 	if (index < 16) {
 		const rgb = ANSI_16[index];

package/src/env.ts

@@ -150,10 +150,10 @@ function expandDotenvValues(values: Record<string, string>, env: Record<string,
 	return expanded;
 }
 
-/** Filters process env for child shells without launch-cwd dotenv values. */
-export function filterChildShellEnv(
+function filterChildShellEnvInternal(
 	env: Record<string, string | undefined>,
-	cwd: string = getProjectDir(),
+	cwd: string,
+	onDotenvValue?: (value: string) => void,
 ): Record<string, string> {
 	const runtimeLaunchEnvValues = env === Bun.env || env === process.env ? launchEnvValues : undefined;
 	const result = filterProcessEnv(env);
@@ -190,6 +190,12 @@ export function filterChildShellEnv(
 		}
 	}
 	const allLaunchEnv = fallbackLaunchEnv ? { ...launchEnv, ...fallbackLaunchEnv } : launchEnv;
+	if (onDotenvValue) {
+		// Every value the project's dotenv files define is dotenv-sourced, whether
+		// or not this process loaded it (a `--cwd` launch never did).
+		for (const key in allLaunchEnv) onDotenvValue(allLaunchEnv[key]!);
+		for (const key in expandedLaunchEnv) onDotenvValue(expandedLaunchEnv[key]!);
+	}
 	for (const key in allLaunchEnv) {
 		const launchValue = runtimeLaunchEnvValues?.get(key);
 		if (launchValue !== undefined) {
@@ -211,6 +217,8 @@ export function filterChildShellEnv(
 			// Strong provenance: the launch environment is known and this name is
 			// absent from it, or OMP itself injected the value — either way it came
 			// from a project dotenv file, not the parent shell.
+			const value = result[key];
+			if (value !== undefined) onDotenvValue?.(value);
 			delete result[key];
 		} else if (
 			result[key] === launchEnv[key] ||
@@ -220,6 +228,8 @@ export function filterChildShellEnv(
 		) {
 			// No launch-env snapshot (dotenv autoloaded without procfs): best-effort
 			// value match against the Bun-parsed dotenv.
+			const value = result[key];
+			if (value !== undefined) onDotenvValue?.(value);
 			delete result[key];
 		}
 	}
@@ -229,6 +239,24 @@ export function filterChildShellEnv(
 	return result;
 }
 
+/** Filters process env for child shells without launch-cwd dotenv values. */
+export function filterChildShellEnv(
+	env: Record<string, string | undefined>,
+	cwd: string = getProjectDir(),
+): Record<string, string> {
+	return filterChildShellEnvInternal(env, cwd);
+}
+
+/** Return every value defined by `cwd`'s dotenv files, plus environment values that came from them. */
+export function getDotenvEnvValues(
+	cwd: string = getProjectDir(),
+	env: Record<string, string | undefined> = process.env,
+): string[] {
+	const values = new Set<string>();
+	filterChildShellEnvInternal(env, cwd, value => values.add(value));
+	return [...values];
+}
+
 /**
  * Parses a complete .env file with the runtime's dotenv grammar, then retains
  * only shell-identifier names and spawn-safe values before mirroring valid

package/src/format.ts

@@ -58,6 +58,22 @@ export function formatBytes(bytes: number): string {
 	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
 }
 
+/**
+ * Count `\n` code units via native `indexOf` — no split array, roughly an
+ * order of magnitude cheaper than a per-code-unit loop on multi-MiB text.
+ * Line-count semantics are the caller's (empty text is 0 or 1 lines
+ * depending on the contract).
+ */
+export function countNewlines(text: string): number {
+	let count = 0;
+	let pos = text.indexOf("\n");
+	while (pos !== -1) {
+		count++;
+		pos = text.indexOf("\n", pos + 1);
+	}
+	return count;
+}
+
 /**
  * Truncate a string to maxLen characters, appending an ellipsis if truncated.
  * For display-width-aware truncation (terminals), use truncateToWidth from @oh-my-pi/pi-tui.

package/src/index.ts

@@ -40,6 +40,7 @@ export * from "./tls-fetch";
 export * from "./type-guards";
 export * from "./version";
 export * from "./which";
+export * from "./yaml-config";
 
 function isPlainObject(val: object): val is Record<string, unknown> {
 	return Object.getPrototypeOf(val) === Object.prototype || Array.isArray(val);

package/src/json.ts

@@ -19,7 +19,18 @@ export function tryParseJson<T = unknown>(content: string): T | null {
  * only lossless JSON representation.
  */
 export function stringifyJson(value: unknown, space?: string | number): string | undefined {
-	return JSON.stringify(value, (_key, item) => (typeof item === "bigint" ? item.toString() : item), space);
+	// Fast path: a replacer forces the slow stringify on every call, but
+	// bigint payloads are vanishingly rare. Try plain stringify first and
+	// retry with the coercing replacer only on TypeError (the only error a
+	// bigint raises). A TypeError from elsewhere (circular value, throwing
+	// toJSON) recurs on the retry and surfaces from that second walk, so
+	// stateful serializers ahead of a bigint run twice on that path.
+	try {
+		return JSON.stringify(value, undefined, space);
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		return JSON.stringify(value, (_key, item) => (typeof item === "bigint" ? item.toString() : item), space);
+	}
 }
 
 function stableJsonClone(value: unknown): unknown {

package/src/logger/rotating-file.ts

@@ -47,6 +47,12 @@ export class RotatingFileSink {
 	#activePath: string | undefined;
 	#activeBytes = 0;
 	#closed = false;
+	// Held append fd: the old code did open+write+close per line
+	// (appendFileSync) plus a throwaway open in the constructor. A single fd
+	// per active file removes two syscalls per log line; it is reopened on
+	// rotation and closed on close()/rotation (required for Windows
+	// delete-on-prune semantics).
+	#fd: number | undefined;
 
 	constructor(options: RotatingFileOptions) {
 		this.#directory = options.directory;
@@ -61,26 +67,57 @@ export class RotatingFileSink {
 		const activePath = this.#activePath;
 		if (activePath) {
 			this.#registerFile(activePath, now.getTime());
-			fs.closeSync(fs.openSync(activePath, "a"));
+			this.#openFd(activePath);
+		}
+	}
+
+	#openFd(filePath: string): void {
+		this.#closeFd();
+		this.#fd = fs.openSync(filePath, "a");
+	}
+
+	#closeFd(): void {
+		if (this.#fd !== undefined) {
+			try {
+				fs.closeSync(this.#fd);
+			} catch {
+				// Best-effort: the fd may already be invalid after rotation.
+			}
+			this.#fd = undefined;
 		}
 	}
 
 	/** Append one already-formatted log record. */
 	write(line: string): void {
 		if (this.#closed) return;
+		const prevPath = this.#activePath;
 		const now = new Date();
 		this.#selectFile(this.#localDay(now));
 		const activePath = this.#activePath;
 		if (!activePath) return;
+		// Rotation moved the active path: close the old descriptor BEFORE
+		// registering the new path, because registration prunes beyond
+		// maxFiles — on Windows the pruned predecessor cannot be deleted
+		// while still open, which would leak it (audit entry removed, file
+		// left on disk, retention unbounded).
+		if (activePath !== prevPath) this.#closeFd();
 		this.#registerFile(activePath, now.getTime());
+		if (this.#fd === undefined) this.#openFd(activePath);
 		const record = `${line}${os.EOL}`;
-		fs.appendFileSync(activePath, record, "utf8");
-		this.#activeBytes += Buffer.byteLength(record);
+		const buf = Buffer.from(record, "utf8");
+		let off = 0;
+		while (off < buf.length) {
+			const written = fs.writeSync(this.#fd!, buf, off);
+			if (written <= 0) break;
+			off += written;
+		}
+		this.#activeBytes += buf.length;
 	}
 
 	/** Stop accepting records. Synchronous writes require no drain phase. */
 	close(): void {
 		this.#closed = true;
+		this.#closeFd();
 	}
 
 	#localDay(date: Date): string {

package/src/stream.ts

@@ -300,7 +300,9 @@ async function* readSseFrames<T>(
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
 ): AsyncGenerator<SseFrame<T>> {
-	for await (const sse of readSseEvents(stream, signal)) {
+	// The diagnostic observer is the only reader of `raw`; capture it exactly
+	// when one is attached so the hot path stays allocation-free.
+	for await (const sse of readSseEvents(stream, signal, onEvent ? { captureRaw: true } : undefined)) {
 		const isTrailing = trailingEvents.has(sse);
 		notifySseEventObserver(onEvent, sse);
 		const data = sse.data;
@@ -379,6 +381,15 @@ export async function* readSseJsonOrText<T>(
 export interface ServerSentEvent {
 	event: string | null;
 	data: string;
+	/**
+	 * Decoded wire lines for this event (`event:`/`data:`/etc.), for the
+	 * diagnostic pipeline. Populated only when the reader opts in via
+	 * {@link ReadSseEventsOptions.captureRaw} (or attaches an `onSseEvent`
+	 * observer to the JSON readers, which opt in automatically); otherwise
+	 * `[]`. Direct `readSseEvents` callers that need wire text must pass
+	 * `{ captureRaw: true }` — the field is allocation-free by default so
+	 * the token path pays no per-frame array/slice cost.
+	 */
 	raw: string[];
 	id?: string;
 	retry?: number;
@@ -391,7 +402,10 @@ interface SseEventState {
 	// of buffering an array and joining at flush. `null` means "no data: field
 	// seen yet" (distinct from a `data:` field with an empty value).
 	data: string | null;
-	raw: string[];
+	// Diagnostic wire lines, captured only when a reader asked for them (see
+	// `readSseEventsOptions.captureRaw`): per-frame array+slice allocation on
+	// the token path otherwise. `null` means capture is off.
+	raw: string[] | null;
 	id?: string;
 	retry?: number;
 }
@@ -402,19 +416,19 @@ const SSE_DECODER = new TextDecoder("utf-8");
 
 function flushSseEvent(state: SseEventState): ServerSentEvent | null {
 	if (state.event === null && state.data === null && state.id === undefined && state.retry === undefined) {
-		state.raw = [];
+		if (state.raw !== null) state.raw = [];
 		return null;
 	}
 	const event: ServerSentEvent = {
 		event: state.event,
 		data: state.data ?? "",
-		raw: state.raw,
+		raw: state.raw ?? [],
 	};
 	if (state.id !== undefined) event.id = state.id;
 	if (state.retry !== undefined) event.retry = state.retry;
 	state.event = null;
 	state.data = null;
-	state.raw = [];
+	if (state.raw !== null) state.raw = [];
 	state.id = undefined;
 	state.retry = undefined;
 	return event;
@@ -425,11 +439,11 @@ function pushSseLine(line: string, state: SseEventState): ServerSentEvent | null
 
 	// Comment line: keep in `raw` for diagnostic context, skip parsing.
 	if (line.charCodeAt(0) === 0x3a /* ':' */) {
-		state.raw.push(line);
+		state.raw?.push(line);
 		return null;
 	}
 
-	state.raw.push(line);
+	state.raw?.push(line);
 
 	const colon = line.indexOf(":");
 	const fieldName = colon === -1 ? line : line.slice(0, colon);
@@ -483,12 +497,24 @@ function pushSseLine(line: string, state: SseEventState): ServerSentEvent | null
  * }
  * ```
  */
+export interface ReadSseEventsOptions {
+	/**
+	 * Capture per-line wire text into `event.raw` for the diagnostic
+	 * pipeline (`onSseEvent` observers, raw-SSE viewer). Off by default:
+	 * every frame otherwise pays an array allocation plus one string slice
+	 * per line on the token path.
+	 */
+	captureRaw?: boolean;
+}
+
 export async function* readSseEvents(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
+	options?: ReadSseEventsOptions,
 ): AsyncGenerator<ServerSentEvent> {
 	const lineBuffer = new ConcatSink();
-	const state: SseEventState = { event: null, data: null, raw: [] };
+	const captureRaw = options?.captureRaw === true;
+	const state: SseEventState = { event: null, data: null, raw: captureRaw ? [] : null };
 	const source = abortableSource(stream, signal);
 	try {
 		for await (const chunk of source) {

package/src/which.ts

@@ -13,8 +13,6 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { isFullyQualifiedPath } from "./path";
 
-type CacheKey = string | bigint | number;
-
 // Tools shipped by Xcode / Command Line Tools that callers actually look up.
 // Keeps the set small so darwinWhich can fast-reject non-Xcode commands without
 // touching the filesystem.  Only needs entries for binaries that live *exclusively*
@@ -149,12 +147,12 @@ function getMacosToolPaths(): Map<string, string> {
 }
 
 // Map: cache key -> resolved binary path or null (not found)
-const toolCache = new Map<CacheKey, string | null>();
+const toolCache = new Map<string, string | null>();
 
 /**
  * Cache policy for which lookups.
  */
-export const enum WhichCachePolicy {
+export enum WhichCachePolicy {
 	/**
 	 * Use cached result if available.
 	 */
@@ -177,7 +175,7 @@ export const enum WhichCachePolicy {
 export interface WhichOptions extends Bun.WhichOptions {
 	/**
 	 * Cache policy for the lookup.
-	 * Defaults to `WhichCachePolicy.Fresh`.
+	 * Defaults to `WhichCachePolicy.Cached`.
 	 */
 	cache?: WhichCachePolicy;
 	/**
@@ -216,14 +214,14 @@ export const whichFresh =
 		? darwinWhich
 		: (command: string, options?: Bun.WhichOptions): string | null => Bun.which(command, options);
 
-// Derive stable cache key from command and lookup options
-function cacheKey(command: string, options?: Bun.WhichOptions): CacheKey {
+// Length-prefixed (command, cwd, PATH) tuple: exact, unlike the 64-bit hash
+// chain it replaced, and the length prefixes keep `("ab", "c")` and
+// `("a", "bc")` distinct without a separator that cwd/PATH could contain.
+function cacheKey(command: string, options?: Bun.WhichOptions): string {
 	if (!options) return command;
-	if (!options.cwd && !options.PATH) return command;
-	let h = Bun.hash(command);
-	if (options.cwd) h = Bun.hash(options.cwd, h);
-	if (options.PATH) h = Bun.hash(options.PATH, h);
-	return h;
+	const cwd = options?.cwd ?? "";
+	const binPath = options?.PATH ?? "";
+	return `${command.length}:${command}${cwd.length}:${cwd}${binPath.length}:${binPath}`;
 }
 
 /**
@@ -244,7 +242,7 @@ export function $which(command: string, options?: WhichOptions): string | null {
 		lookupOptions = { ...lookupOptions, PATH: safePath };
 	}
 
-	let key: CacheKey | undefined;
+	let key: string | undefined;
 
 	if (cachePolicy !== WhichCachePolicy.Bypass) {
 		key = cacheKey(command, lookupOptions);

package/src/yaml-config.ts

@@ -0,0 +1,8 @@
+import { YAML } from "bun";
+
+const YAML_MAPPING_HEADER_TRAILING_SPACE = /: +$/gm;
+
+/** Serialize config YAML without Bun's trailing space on block mapping headers. */
+export function stringifyYamlConfig(value: unknown): string {
+	return YAML.stringify(value, null, 2).replace(YAML_MAPPING_HEADER_TRAILING_SPACE, ":");
+}