@f5xc-salesdemos/pi-utils 14.0.2

package/src/stream.ts

@@ -0,0 +1,316 @@
+import { createAbortableStream } from "./abortable";
+
+const LF = 0x0a;
+type JsonlChunkResult = {
+	values: unknown[];
+	error: unknown;
+	read: number;
+	done: boolean;
+};
+
+function parseJsonlChunkCompat(input: Uint8Array, beg?: number, end?: number): JsonlChunkResult;
+function parseJsonlChunkCompat(input: string): JsonlChunkResult;
+function parseJsonlChunkCompat(input: Uint8Array | string, beg?: number, end?: number): JsonlChunkResult {
+	if (typeof input === "string") {
+		const { values, error, read, done } = Bun.JSONL.parseChunk(input);
+		return { values, error, read, done };
+	}
+	const start = beg ?? 0;
+	const stop = end ?? input.length;
+	const { values, error, read, done } = Bun.JSONL.parseChunk(input, start, stop);
+	return { values, error, read, done };
+}
+
+export async function* readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array> {
+	const buffer = new ConcatSink();
+	const source = createAbortableStream(stream, signal);
+	try {
+		for await (const chunk of source) {
+			for (const line of buffer.appendAndFlushLines(chunk)) {
+				yield line;
+			}
+		}
+		if (!buffer.isEmpty) {
+			const tail = buffer.flush();
+			if (tail) {
+				buffer.clear();
+				yield tail;
+			}
+		}
+	} catch (err) {
+		// Abort errors are expected — just stop the generator.
+		if (signal?.aborted) return;
+		throw err;
+	}
+}
+
+export async function* readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T> {
+	const buffer = new ConcatSink();
+	const source = createAbortableStream(stream, signal);
+	try {
+		for await (const chunk of source) {
+			yield* buffer.pullJSONL<T>(chunk, 0, chunk.length);
+		}
+		if (!buffer.isEmpty) {
+			const tail = buffer.flush();
+			if (tail) {
+				buffer.clear();
+				const { values, error, done } = parseJsonlChunkCompat(tail, 0, tail.length);
+				if (values.length > 0) {
+					yield* values as T[];
+				}
+				if (error) throw error;
+				if (!done) {
+					throw new Error("JSONL stream ended unexpectedly");
+				}
+			}
+		}
+	} catch (err) {
+		// Abort errors are expected — just stop the generator.
+		if (signal?.aborted) return;
+		throw err;
+	}
+}
+
+// =============================================================================
+// SSE (Server-Sent Events)
+// =============================================================================
+
+/** Byte lookup table: 1 = whitespace, 0 = not. */
+const WS = new Uint8Array(256);
+WS[0x09] = 1; // tab
+WS[0x0a] = 1; // LF
+WS[0x0d] = 1; // CR
+WS[0x20] = 1; // space
+
+const createPattern = (prefix: string) => {
+	const pre = Buffer.from(prefix, "utf-8");
+	return {
+		strip(buf: Uint8Array): number | null {
+			const n = pre.length;
+			if (buf.length < n) return null;
+			if (pre.equals(buf.subarray(0, n))) {
+				return n;
+			}
+			return null;
+		},
+	};
+};
+
+const PAT_DATA = createPattern("data:");
+
+const PAT_DONE = createPattern("[DONE]");
+
+class ConcatSink {
+	#space?: Buffer;
+	#length = 0;
+
+	#ensureCapacity(size: number): Buffer {
+		const space = this.#space;
+		if (space && space.length >= size) return space;
+		const nextSize = space ? Math.max(size, space.length * 2) : size;
+		const next = Buffer.allocUnsafe(nextSize);
+		if (space && this.#length > 0) {
+			space.copy(next, 0, 0, this.#length);
+		}
+		this.#space = next;
+		return next;
+	}
+
+	append(chunk: Uint8Array) {
+		const n = chunk.length;
+		if (!n) return;
+		const offset = this.#length;
+		const space = this.#ensureCapacity(offset + n);
+		space.set(chunk, offset);
+		this.#length += n;
+	}
+
+	reset(chunk: Uint8Array) {
+		const n = chunk.length;
+		if (!n) {
+			this.#length = 0;
+			return;
+		}
+		const space = this.#ensureCapacity(n);
+		space.set(chunk, 0);
+		this.#length = n;
+	}
+
+	get isEmpty(): boolean {
+		return this.#length === 0;
+	}
+
+	flush(): Uint8Array | undefined {
+		if (!this.#length) return undefined;
+		return this.#space!.subarray(0, this.#length);
+	}
+
+	clear() {
+		this.#length = 0;
+	}
+
+	*appendAndFlushLines(chunk: Uint8Array) {
+		let pos = 0;
+		while (pos < chunk.length) {
+			const nl = chunk.indexOf(LF, pos);
+			if (nl === -1) {
+				this.append(chunk.subarray(pos));
+				return;
+			}
+			const suffix = chunk.subarray(pos, nl);
+			pos = nl + 1;
+			if (this.isEmpty) {
+				yield suffix;
+			} else {
+				this.append(suffix);
+				const payload = this.flush();
+				if (payload) {
+					yield payload;
+					this.clear();
+				}
+			}
+		}
+	}
+	*pullJSONL<T>(chunk: Uint8Array, beg: number, end: number) {
+		if (this.isEmpty) {
+			const { values, error, read, done } = parseJsonlChunkCompat(chunk, beg, end);
+			if (values.length > 0) {
+				yield* values as T[];
+			}
+			if (error) throw error;
+			if (done) return;
+			this.reset(chunk.subarray(read, end));
+			return;
+		}
+
+		const offset = this.#length;
+		const n = end - beg;
+		const total = offset + n;
+		const space = this.#ensureCapacity(total);
+		space.set(chunk.subarray(beg, end), offset);
+		this.#length = total;
+
+		const { values, error, read, done } = parseJsonlChunkCompat(space.subarray(0, total), 0, total);
+		if (values.length > 0) {
+			yield* values as T[];
+		}
+		if (error) throw error;
+		if (done) {
+			this.#length = 0;
+			return;
+		}
+		const rem = total - read;
+		if (rem < total) {
+			space.copyWithin(0, read, total);
+		}
+		this.#length = rem;
+	}
+}
+
+const kDoneError = new Error("SSE stream done");
+
+/**
+ * Stream parsed JSON objects from SSE `data:` lines.
+ *
+ * @example
+ * ```ts
+ * for await (const obj of readSseJson(response.body!)) {
+ *   console.log(obj);
+ * }
+ * ```
+ */
+export async function* readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T> {
+	const lineBuffer = new ConcatSink();
+	const jsonBuffer = new ConcatSink();
+
+	// pipeThrough with { signal } makes the stream abort-aware: the pipe
+	// cancels the source and errors the output when the signal fires,
+	// so for-await-of exits cleanly without manual reader/listener management.
+	stream = createAbortableStream(stream, signal);
+	try {
+		const processLine = function* (line: Uint8Array) {
+			// Strip trailing spaces including \r.
+			let end = line.length;
+			while (end && WS[line[end - 1]]) {
+				--end;
+			}
+			if (!end) return; // blank line
+
+			const trimmed = end === line.length ? line : line.subarray(0, end);
+
+			// Check "data:" prefix and optional space afterwards.
+			let beg = PAT_DATA.strip(trimmed);
+			if (beg === null) return;
+			while (beg < end && WS[trimmed[beg]]) {
+				++beg;
+			}
+			if (beg >= end) return;
+
+			// Fast-path: the OpenAI-style done marker isn't JSON.
+			const donePrefix = PAT_DONE.strip(trimmed.subarray(beg, end));
+			if (donePrefix !== null && donePrefix === end - beg) {
+				throw kDoneError;
+			}
+
+			yield* jsonBuffer.pullJSONL<T>(trimmed, beg, end);
+		};
+		for await (const chunk of stream) {
+			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
+				yield* processLine(line);
+			}
+		}
+		if (!lineBuffer.isEmpty) {
+			const tail = lineBuffer.flush();
+			if (tail) {
+				lineBuffer.clear();
+				yield* processLine(tail);
+			}
+		}
+	} catch (err) {
+		if (err === kDoneError) return;
+		// Abort errors are expected — just stop the generator.
+		if (signal?.aborted) return;
+		throw err;
+	}
+	if (!jsonBuffer.isEmpty) {
+		throw new Error("SSE stream ended unexpectedly");
+	}
+}
+
+/**
+ * Parse a complete JSONL string, skipping malformed lines instead of throwing.
+ *
+ * Uses `Bun.JSONL.parseChunk` internally. On parse errors, the malformed
+ * region is skipped up to the next newline and parsing continues.
+ *
+ * @example
+ * ```ts
+ * const entries = parseJsonlLenient<MyType>(fileContents);
+ * ```
+ */
+export function parseJsonlLenient<T>(buffer: string): T[] {
+	let entries: T[] | undefined;
+
+	while (buffer.length > 0) {
+		const { values, error, read, done } = parseJsonlChunkCompat(buffer);
+		if (values.length > 0) {
+			const ext = values as T[];
+			if (!entries) {
+				entries = ext;
+			} else {
+				entries.push(...ext);
+			}
+		}
+		if (error) {
+			const nextNewline = buffer.indexOf("\n", read);
+			if (nextNewline === -1) break;
+			buffer = buffer.substring(nextNewline + 1);
+			continue;
+		}
+		if (read === 0) break;
+		buffer = buffer.substring(read);
+		if (done) break;
+	}
+	return entries ?? [];
+}

package/src/temp.ts

@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export class TempDir {
+	#path: string;
+	private constructor(path: string) {
+		this.#path = path;
+	}
+
+	static createSync(prefix?: string): TempDir {
+		return new TempDir(fs.mkdtempSync(normalizePrefix(prefix)));
+	}
+
+	static async create(prefix?: string): Promise<TempDir> {
+		return new TempDir(await fs.promises.mkdtemp(normalizePrefix(prefix)));
+	}
+
+	#removePromise: Promise<void> | null = null;
+
+	path(): string {
+		return this.#path;
+	}
+
+	absolute(): string {
+		return path.resolve(this.#path);
+	}
+
+	remove(): Promise<void> {
+		if (this.#removePromise) {
+			return this.#removePromise;
+		}
+		const removePromise = fs.promises.rm(this.#path, { recursive: true, force: true });
+		this.#removePromise = removePromise;
+		return removePromise;
+	}
+
+	removeSync(): void {
+		fs.rmSync(this.#path, { recursive: true, force: true });
+		this.#removePromise = Promise.resolve();
+	}
+
+	toString(): string {
+		return this.#path;
+	}
+
+	join(...paths: string[]): string {
+		return path.join(this.#path, ...paths);
+	}
+
+	async [Symbol.asyncDispose](): Promise<void> {
+		try {
+			await this.remove();
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+
+	[Symbol.dispose](): void {
+		try {
+			this.removeSync();
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}
+
+const kTempDir = os.tmpdir();
+
+function normalizePrefix(prefix?: string): string {
+	if (!prefix) {
+		return `${kTempDir}${path.sep}pi-temp-`;
+	} else if (prefix.startsWith("@")) {
+		return path.join(kTempDir, prefix.slice(1));
+	}
+	return prefix;
+}

package/src/type-guards.ts

@@ -0,0 +1,11 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+	return isRecord(value) ? value : null;
+}
+
+export function toError(value: unknown): Error {
+	return value instanceof Error ? value : new Error(String(value));
+}

package/src/which.ts

@@ -0,0 +1,230 @@
+// OS-agnostic "which" helper with robust macOS toolchain lookup and flexible cache control.
+//
+// - Falls back to macOS Xcode/CLT toolchain directories if standard `Bun.which()` fails on Darwin.
+//   Resolves the active developer directory via $DEVELOPER_DIR / /var/db/xcode_select_link symlink
+//   to avoid spawning xcrun subprocesses.
+// - Supports four cache modes (`none`, `fresh`, `ro`, `cached`) for control over discovery cost and determinism.
+// - Computes a stable cache key from command + options to avoid redundant lookups within a process.
+// - Returns path to resolved binary or null if not found.
+//
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// 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*
+// in toolchain dirs (not on a typical $PATH).
+const XCODE_BINS = new Set([
+	// Compilers & driver aliases
+	"clang",
+	"clang++",
+	"gcc",
+	"g++",
+	"cc",
+	"c++",
+	"cpp",
+	"c89",
+	"c99",
+	"swift",
+	"swiftc",
+	"swift-frontend",
+	// Language servers (LSP)
+	"clangd",
+	"sourcekit-lsp",
+	// Linker & archive tools
+	"ld",
+	"ld-classic",
+	"ar",
+	"ranlib",
+	"libtool",
+	"as",
+	"lipo",
+	"install_name_tool",
+	"codesign_allocate",
+	// Build utilities
+	"make",
+	"gnumake",
+	"m4",
+	"flex",
+	"bison",
+	"yacc",
+	"lex",
+	// VCS (CLT ships git)
+	"git",
+	"git-receive-pack",
+	"git-upload-pack",
+	"git-upload-archive",
+	"git-shell",
+	"scalar",
+	// Debugger
+	"lldb",
+	"lldb-dap",
+	// Binary inspection
+	"nm",
+	"otool",
+	"objdump",
+	"strings",
+	"strip",
+	"size",
+	"dsymutil",
+	"dwarfdump",
+	"lipo",
+	"vtool",
+	// Clang tooling
+	"clang-format",
+	"swift-format",
+]);
+
+// Prefixes for versioned binaries (e.g. python3.9, pip3.12, pydoc3.9, 2to3-3.9)
+const XCODE_BIN_PREFIXES = ["python", "pip", "pydoc", "2to3"];
+
+function isXcodeBin(command: string): boolean {
+	if (XCODE_BINS.has(command)) return true;
+	for (const prefix of XCODE_BIN_PREFIXES) {
+		if (command.startsWith(prefix)) return true;
+	}
+	return false;
+}
+
+// Resolve the active Xcode developer directory once, without spawning any process.
+// Priority: $DEVELOPER_DIR env → /var/db/xcode_select_link symlink → common fallback paths.
+function getDeveloperDirs(): string | null {
+	// 1. Explicit env override
+	const envDir = process.env.DEVELOPER_DIR;
+	if (envDir && fs.existsSync(envDir)) {
+		return envDir;
+	}
+
+	// 2. xcode-select stores the active path as a symlink
+	try {
+		return fs.readlinkSync("/var/db/xcode_select_link");
+	} catch {
+		// symlink may not exist on minimal installs
+	}
+	// 3. Common locations
+	for (const candidate of ["/Applications/Xcode.app/Contents/Developer", "/Library/Developer/CommandLineTools"]) {
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+// Build the list of extra toolchain bin directories to check on macOS.
+// Computed lazily once from the resolved developer directory.
+let macosToolPaths: Map<string, string> | undefined;
+function getMacosToolPaths(): Map<string, string> {
+	if (macosToolPaths) return macosToolPaths;
+	const paths: string[] = [
+		// Always check Command Line Tools (may be independent of Xcode)
+		"/Library/Developer/CommandLineTools/usr/bin",
+	];
+	const devDir = getDeveloperDirs();
+	if (devDir) {
+		paths.push(path.join(devDir, "usr/bin"), path.join(devDir, "Toolchains/XcodeDefault.xctoolchain/usr/bin"));
+	}
+
+	// Deduplicate (e.g. devDir may already be CommandLineTools)
+	macosToolPaths = new Map<string, string>();
+	for (const dir of Array.from(new Set(paths))) {
+		try {
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				if (entry.isFile() || entry.isSymbolicLink()) {
+					if (macosToolPaths.has(entry.name)) {
+						continue;
+					}
+					macosToolPaths.set(entry.name, path.join(dir, entry.name));
+				}
+			}
+		} catch {
+			// dir doesn't exist or isn't readable
+		}
+	}
+	return macosToolPaths;
+}
+
+// Map: cache key -> resolved binary path or null (not found)
+const toolCache = new Map<string | bigint, string | null>();
+
+/**
+ * Cache policy for which lookups.
+ */
+export const enum WhichCachePolicy {
+	/**
+	 * Use cached result if available.
+	 */
+	Cached = 0,
+	/**
+	 * Bypass cache and perform a new lookup.
+	 */
+	Bypass,
+	/**
+	 * Always update cache.
+	 */
+	Fresh,
+	/**
+	 * Read-only, serves from cache if present, but doesn't write.
+	 */
+	ReadOnly,
+}
+
+// Extension: additional cache policy for tool path lookup
+export interface WhichOptions extends Bun.WhichOptions {
+	/**
+	 * Cache policy for the lookup.
+	 * Defaults to `WhichCachePolicy.Fresh`.
+	 */
+	cache?: WhichCachePolicy;
+}
+
+// Darwin-specific "which" shim: consult Xcode/CLT toolchain directories after $PATH.
+// Uses cached directory listings instead of per-command existsSync or xcrun subprocesses.
+function darwinWhich(command: string, _options?: Bun.WhichOptions): string | null {
+	const regular = Bun.which(command);
+	if (regular) return regular;
+	if (isXcodeBin(command)) {
+		return getMacosToolPaths().get(command) ?? null;
+	}
+	return null;
+}
+
+// Which function that incorporates Darwin Xcode logic if platform reports as 'darwin'
+export const whichFresh = os.platform() === "darwin" ? darwinWhich : Bun.which;
+
+// Derive stable cache key from command and lookup options
+function cacheKey(command: string, options?: Bun.WhichOptions): string | bigint {
+	if (!options) return command;
+	if (!options.cwd && !options.PATH) return command;
+	let h = Bun.hash.xxHash64(command);
+	if (options.cwd) h = Bun.hash.xxHash64(options.cwd, h);
+	if (options.PATH) h = Bun.hash.xxHash64(options.PATH, h);
+	return h;
+}
+
+/**
+ * Locate binary on PATH (with flexible caching).
+ *
+ * @param command - Binary name to resolve
+ * @param options - Bun.WhichOptions plus `cache` control
+ * @returns Filesystem path if found, else null
+ */
+export function $which(command: string, options?: WhichOptions): string | null {
+	const cachePolicy = options?.cache ?? WhichCachePolicy.Cached;
+	let key: string | bigint | undefined;
+
+	if (cachePolicy !== WhichCachePolicy.Bypass) {
+		key = cacheKey(command, options);
+		if (cachePolicy !== WhichCachePolicy.Fresh) {
+			const cached = toolCache.get(key);
+			if (cached !== undefined) return cached;
+		}
+	}
+
+	const result = whichFresh(command, options);
+	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
+		toolCache.set(key, result);
+	}
+	return result;
+}