@oh-my-pi-zen/pi-utils 16.3.6-zen.1

package/dist/types/which.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cache policy for which lookups.
+ */
+export declare const enum WhichCachePolicy {
+    /**
+     * Use cached result if available.
+     */
+    Cached = 0,
+    /**
+     * Bypass cache and perform a new lookup.
+     */
+    Bypass = 1,
+    /**
+     * Always update cache.
+     */
+    Fresh = 2,
+    /**
+     * Read-only, serves from cache if present, but doesn't write.
+     */
+    ReadOnly = 3
+}
+export interface WhichOptions extends Bun.WhichOptions {
+    /**
+     * Cache policy for the lookup.
+     * Defaults to `WhichCachePolicy.Fresh`.
+     */
+    cache?: WhichCachePolicy;
+}
+export declare const whichFresh: typeof Bun.which;
+/**
+ * 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 declare function $which(command: string, options?: WhichOptions): string | null;

package/dist/types/worker-host.d.ts

@@ -0,0 +1,47 @@
+/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
+export declare function declareWorkerHostEntry(): void;
+/** Main-module path of the self-dispatching CLI host, or null outside it. */
+export declare function workerHostEntry(): string | null;
+/**
+ * Buffers messages a Bun worker thread receives before its real handler is
+ * attached, then hands them off once it is.
+ *
+ * Bun delivers messages the parent posted before the worker spawned exactly
+ * once — when the worker entry module's top-level evaluation completes — to the
+ * `message` listeners present at that moment. A worker whose handler attaches
+ * via a later `await import(...)` therefore misses that flush. The
+ * self-dispatching CLI host imports each worker module dynamically from inside
+ * its argv dispatch, so the worker's own `parentPort.on("message")` lands after
+ * the flush and the parent's synchronously-posted `init` handshake is dropped —
+ * every run then stalls until the init timeout fires and silently falls back to
+ * the inline worker (issue: eval cells always taking the full timeout).
+ *
+ * The host calls {@link installWorkerInbox} synchronously in the entry's sync
+ * prefix (before importing the worker module) so a `parentPort` listener exists
+ * at flush time; the worker module then {@link consumeWorkerInbox}es it and
+ * binds the real handler, replaying anything buffered. Re-dispatching through
+ * `parentPort.emit("message", …)` is not an option — Bun's port is an
+ * `EventTarget` whose `emit` throws — so the inbox calls the handler directly.
+ */
+export interface WorkerInbox {
+    /** Route buffered and subsequent messages to `handler`; returns an unbind fn. */
+    bind(handler: (message: unknown) => void): () => void;
+}
+/** Minimal `parentPort` surface the inbox needs (Node/Bun `MessagePort`). */
+interface MessageListenerPort {
+    on(event: "message", listener: (value: unknown) => void): unknown;
+}
+/**
+ * Attach a buffering `message` listener on `port` synchronously and stash the
+ * resulting inbox for the worker module to {@link consumeWorkerInbox}. MUST be
+ * called in the entry module's synchronous prefix — before the worker module is
+ * imported — so the listener exists when Bun flushes pre-spawn messages.
+ */
+export declare function installWorkerInbox(port: MessageListenerPort): WorkerInbox;
+/**
+ * Take the inbox installed by {@link installWorkerInbox} for this worker, or
+ * `null` when the worker module was loaded directly (no host pre-buffering, so
+ * the module's own synchronous top-level listener already wins the flush).
+ */
+export declare function consumeWorkerInbox(): WorkerInbox | null;
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+	"type": "module",
+	"name": "@oh-my-pi-zen/pi-utils",
+	"version": "16.3.6-zen.1",
+	"description": "Shared utilities for pi packages",
+	"homepage": "https://omp.sh",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cagedbird043/oh-my-pi-zen.git",
+		"directory": "packages/utils"
+	},
+	"bugs": {
+		"url": "https://github.com/cagedbird043/oh-my-pi-zen/issues"
+	},
+	"keywords": [
+		"utilities",
+		"cli",
+		"logging",
+		"streams"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@oh-my-pi-zen/pi-natives": "16.3.6-zen.1",
+		"handlebars": "^4.7.9",
+		"winston": "^3.19.0",
+		"winston-daily-rotate-file": "^5.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}

package/src/abortable.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+
+export class AbortError extends Error {
+	constructor(signal: AbortSignal) {
+		assert(signal.aborted, "Abort signal must be aborted");
+
+		const message = signal.reason instanceof Error ? signal.reason.message : "Cancelled";
+		super(`Aborted: ${message}`, { cause: signal.reason });
+		this.name = "AbortError";
+	}
+}
+
+/**
+ * Abortable async iteration over a {@link ReadableStream}. Reads the source
+ * reader directly and yields each chunk, so the consumer's `for await` drives a
+ * single read loop with no intermediate stream or per-chunk enqueue.
+ *
+ * Unlike `stream.pipeThrough(..., { signal })`, this explicitly cancels the
+ * source reader on abort or early `break`, propagating HTTP-client disconnects
+ * and watchdog timeouts to the backend request instead of only stopping the
+ * local consumer. On abort it throws {@link AbortError}; the lock is released
+ * on completion, abort, throw, or early exit. The source is cancelled only on
+ * abort or early exit — never on natural EOF.
+ */
+export async function* abortableSource<T>(stream: ReadableStream<T>, signal?: AbortSignal): AsyncGenerator<T> {
+	if (signal?.aborted) throw new AbortError(signal);
+	const reader = stream.getReader();
+	let onAbort: (() => void) | undefined;
+	if (signal) {
+		onAbort = () => {
+			void reader.cancel(signal.reason).catch(() => {});
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	}
+	let completed = false;
+	try {
+		for (;;) {
+			const result = await reader.read();
+			if (signal?.aborted) throw new AbortError(signal);
+			if (result.done) {
+				completed = true;
+				return;
+			}
+			yield result.value;
+		}
+	} finally {
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		// Propagate early-exit (`break`/`return`) and abort to the backend; skip
+		// on natural EOF where the stream already closed itself.
+		if (!completed) {
+			try {
+				await reader.cancel();
+			} catch {}
+		}
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+}
+
+/**
+ * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
+ * execution, the promise is rejected with a standard error.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @param pr - Function returning a promise to run
+ * @returns Promise resolving as `pr` would, or rejecting on abort
+ */
+export function untilAborted<T>(
+	signal: AbortSignal | undefined | null,
+	pr: Promise<T> | (() => Promise<T>),
+): Promise<T> {
+	if (!signal) return typeof pr === "function" ? pr() : pr;
+	if (signal.aborted) return Promise.reject(new AbortError(signal));
+
+	const { promise, resolve, reject } = Promise.withResolvers<T>();
+	const onAbort = () => reject(new AbortError(signal));
+	signal.addEventListener("abort", onAbort, { once: true });
+
+	void (async () => {
+		try {
+			resolve(await (typeof pr === "function" ? pr() : pr));
+		} catch (err) {
+			reject(err);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	})();
+
+	return promise;
+}
+
+/**
+ * Memoizes a function with no arguments, calling it once and caching the result.
+ *
+ * @param fn - Function to be called once
+ * @returns A function that returns the cached result of `fn`
+ */
+export function once<T>(fn: () => T): () => T {
+	let store = undefined as { value: T } | undefined;
+	return () => {
+		if (store) {
+			return store.value;
+		}
+		const value = fn();
+		store = { value };
+		return value;
+	};
+}

package/src/async.ts

@@ -0,0 +1,50 @@
+/**
+ * Wrap a promise with a timeout and optional abort signal.
+ * Rejects with the given message if the timeout fires first.
+ * Cleans up all listeners on settlement.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T> {
+	if (signal?.aborted) {
+		const reason = signal.reason instanceof Error ? signal.reason : new Error("Aborted");
+		return Promise.reject(reason);
+	}
+
+	const { promise: wrapped, resolve, reject } = Promise.withResolvers<T>();
+	let settled = false;
+	const timeoutId = setTimeout(() => {
+		if (settled) return;
+		settled = true;
+		if (signal) signal.removeEventListener("abort", onAbort);
+		reject(new Error(message));
+	}, ms);
+
+	const onAbort = () => {
+		if (settled) return;
+		settled = true;
+		clearTimeout(timeoutId);
+		reject(signal?.reason instanceof Error ? signal.reason : new Error("Aborted"));
+	};
+
+	if (signal) {
+		signal.addEventListener("abort", onAbort, { once: true });
+	}
+
+	promise.then(
+		value => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		},
+		err => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			reject(err);
+		},
+	);
+
+	return wrapped;
+}

package/src/binary.ts

@@ -0,0 +1,50 @@
+/**
+ * Content-based binary/text classification for files that are about to be
+ * decoded as UTF-8 text and shown to a model or user.
+ *
+ * The read tool and `@file` auto-read both materialize file bytes as UTF-8
+ * strings. For a binary file (font, object, archive, packed blob) that decode
+ * is lossy: NUL bytes and invalid sequences survive as control characters and
+ * U+FFFD replacements, which corrupt terminal rendering and waste the context
+ * window with mojibake. Sniff the header first and refuse instead.
+ *
+ * @example
+ * if (await isProbablyBinary(path)) return "[binary file omitted]";
+ * const text = await Bun.file(path).text();
+ */
+import { peekFile, peekFileSync } from "./peek-file";
+
+/** Header window sniffed for the binary heuristic; mirrors git's 8000-byte scan. */
+const BINARY_SNIFF_BYTES = 8192;
+
+/**
+ * Classify an in-memory byte header as binary (non-UTF-8-text).
+ *
+ * Binary when the header contains a NUL byte (true binary, plus UTF-16/UTF-32
+ * text whose ASCII range is NUL-padded) or when it is not valid UTF-8. The
+ * decode runs in streaming mode so a multibyte sequence truncated at the header
+ * boundary is tolerated, while any genuinely invalid byte still fails — matching
+ * the strict `fatal` decode the `local://`/`ssh://` read paths already use.
+ */
+export function isProbablyBinaryHeader(header: Uint8Array): boolean {
+	if (header.indexOf(0) !== -1) return true;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(header, { stream: true });
+		return false;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Sniff the first {@link BINARY_SNIFF_BYTES} of `filePath` and report whether it
+ * is binary (non-UTF-8-text). See {@link isProbablyBinaryHeader} for the rule.
+ */
+export function isProbablyBinary(filePath: string, maxBytes = BINARY_SNIFF_BYTES): Promise<boolean> {
+	return peekFile(filePath, maxBytes, isProbablyBinaryHeader);
+}
+
+/** Synchronous {@link isProbablyBinary}. */
+export function isProbablyBinarySync(filePath: string, maxBytes = BINARY_SNIFF_BYTES): boolean {
+	return peekFileSync(filePath, maxBytes, isProbablyBinaryHeader);
+}