@oh-my-pi/pi-utils 18.2.0 → 18.2.2

package/src/stream.ts

@@ -57,11 +57,16 @@ export async function* readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?:
 	}
 }
 
-// =============================================================================
-// SSE (Server-Sent Events)
-// =============================================================================
-
-class ConcatSink {
+/**
+ * Amortized byte accumulator for chunked stream readers.
+ *
+ * Holds the unconsumed tail of a stream in a single growing `Buffer` so that
+ * appending N chunks costs O(total bytes) instead of re-copying the whole
+ * prefix per chunk. Backs {@link readLines}, {@link readJsonl} and
+ * {@link readSseEvents}; also usable directly when a reader needs its own
+ * framing loop (see `consume` and `flush`).
+ */
+export class ConcatSink {
 	#space?: Buffer;
 	#length = 0;
 	#skipLeadingLf = false;
@@ -102,11 +107,26 @@ class ConcatSink {
 		return this.#length === 0;
 	}
 
+	/**
+	 * The buffered bytes as a live view — invalidated by the next `append`,
+	 * `reset` or `consume`.
+	 */
 	flush(): Uint8Array | undefined {
 		if (!this.#length) return undefined;
 		return this.#space!.subarray(0, this.#length);
 	}
 
+	/** Drop the first `count` buffered bytes, keeping the remainder. */
+	consume(count: number) {
+		if (count <= 0) return;
+		if (count >= this.#length) {
+			this.#length = 0;
+			return;
+		}
+		this.#space!.copyWithin(0, count, this.#length);
+		this.#length -= count;
+	}
+
 	clear() {
 		this.#length = 0;
 	}
@@ -207,6 +227,10 @@ class ConcatSink {
 	}
 }
 
+// =============================================================================
+// SSE (Server-Sent Events)
+// =============================================================================
+
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *
@@ -246,11 +270,24 @@ function isRecoverableTrailingJson(data: string): boolean {
 	return typeof recovered === "object" && recovered !== null;
 }
 
-export async function* readSseJson<T>(
+/**
+ * One dispatched `data:` frame from {@link readSseFrames}: either the parsed JSON
+ * value, or the text of a frame `JSON.parse` rejected together with the
+ * `SyntaxError` it raised (so the strict reader can rethrow it unchanged).
+ */
+type SseFrame<T> = { ok: true; value: T } | { ok: false; raw: string; error: SyntaxError };
+
+/**
+ * Shared `data:`-line framing for {@link readSseJson} and
+ * {@link readSseJsonOrText}: skips empty events, stops at the OpenAI `[DONE]`
+ * sentinel, notifies the diagnostic observer, and treats a container-shaped
+ * stream tail as a clean end of iteration.
+ */
+async function* readSseFrames<T>(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
-): AsyncGenerator<T> {
+): AsyncGenerator<SseFrame<T>> {
 	for await (const sse of readSseEvents(stream, signal)) {
 		const isTrailing = trailingEvents.has(sse);
 		notifySseEventObserver(onEvent, sse);
@@ -260,16 +297,60 @@ export async function* readSseJson<T>(
 			continue;
 		}
 		try {
-			yield JSON.parse(data) as T;
+			yield { ok: true, value: JSON.parse(data) as T };
 		} catch (err) {
 			if (err instanceof SyntaxError && isTrailing && isRecoverableTrailingJson(data)) {
 				return;
 			}
+			if (err instanceof SyntaxError) {
+				yield { ok: false, raw: data, error: err };
+				continue;
+			}
 			throw err;
 		}
 	}
 }
 
+export async function* readSseJson<T>(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+	onEvent?: SseEventObserver,
+): AsyncGenerator<T> {
+	for await (const frame of readSseFrames<T>(stream, signal, onEvent)) {
+		if (!frame.ok) throw frame.error;
+		yield frame.value;
+	}
+}
+
+/**
+ * Like {@link readSseJson}, but a `data:` frame that is not valid JSON is yielded
+ * as its raw text instead of raising a `SyntaxError`. Cut-off container-shaped
+ * stream tails stay recoverable, exactly as they are in {@link readSseJson}.
+ *
+ * Consumers that only understand objects must treat a `string` yield as a
+ * transport-level failure (for example a `429 Too Many Requests` or an HTML
+ * throttle page from a reverse proxy that already committed to the stream). This
+ * exists because `readSseJson`'s baseline consumers span unrelated transports
+ * whose error handling a text yield would subtly change; new call sites opt in.
+ *
+ * Note that the text lane is only the frames `JSON.parse` *rejected*: a frame
+ * carrying a JSON-encoded string (`data: "429 Too Many Requests"`) parses, so it
+ * is yielded as that string and is indistinguishable from a rejected frame by
+ * type alone. Consumers branching on `typeof === "string"` therefore see both,
+ * which is the safe direction — each is classified as text rather than trusted as
+ * an event object.
+ */
+export async function* readSseJsonOrText<T>(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+	onEvent?: SseEventObserver,
+): AsyncGenerator<T | string> {
+	for await (const frame of readSseFrames<T>(stream, signal, onEvent)) {
+		if (!frame.ok) yield frame.raw;
+		else yield frame.value;
+	}
+}
+
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *

package/src/which.ts

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { isFullyQualifiedPath } from "./path";
 
 type CacheKey = string | bigint | number;
 
@@ -179,6 +180,12 @@ export interface WhichOptions extends Bun.WhichOptions {
 	 * Defaults to `WhichCachePolicy.Fresh`.
 	 */
 	cache?: WhichCachePolicy;
+	/**
+	 * Only search absolute directory entries in PATH, ignoring relative entries
+	 * (e.g. `.` or `./bin`) and empty components to prevent resolving against
+	 * an untrusted working directory.
+	 */
+	requireAbsolutePaths?: boolean;
 }
 
 // Darwin-specific "which" shim: consult Xcode/CLT toolchain directories after $PATH.
@@ -192,6 +199,15 @@ function darwinWhich(command: string, options?: Bun.WhichOptions): string | null
 	return null;
 }
 
+function filterAbsoluteSearchPath(rawPath: string | undefined): string | null {
+	if (!rawPath) return null;
+	const safePath = rawPath
+		.split(path.delimiter)
+		.filter(dir => dir.length > 0 && isFullyQualifiedPath(dir))
+		.join(path.delimiter);
+	return safePath || null;
+}
+
 // Which function that incorporates Darwin Xcode logic if platform reports as 'darwin'.
 // Look `Bun.which` up per call rather than capturing it at import, so a `Bun.which`
 // stub installed later (the per-test seam) is honoured on every platform.
@@ -219,8 +235,15 @@ function cacheKey(command: string, options?: Bun.WhichOptions): CacheKey {
  */
 export function $which(command: string, options?: WhichOptions): string | null {
 	const cachePolicy = options?.cache ?? WhichCachePolicy.Cached;
-	const lookupOptions =
+	let lookupOptions =
 		options?.PATH !== undefined || process.env.PATH === undefined ? options : { ...options, PATH: process.env.PATH };
+
+	if (options?.requireAbsolutePaths) {
+		const safePath = filterAbsoluteSearchPath(lookupOptions?.PATH);
+		if (!safePath) return null;
+		lookupOptions = { ...lookupOptions, PATH: safePath };
+	}
+
 	let key: CacheKey | undefined;
 
 	if (cachePolicy !== WhichCachePolicy.Bypass) {
@@ -232,6 +255,9 @@ export function $which(command: string, options?: WhichOptions): string | null {
 	}
 
 	const result = whichFresh(command, lookupOptions);
+	if (result && options?.requireAbsolutePaths && !isFullyQualifiedPath(result)) {
+		return null;
+	}
 	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
 		toolCache.set(key, result);
 	}

package/src/xml.ts

@@ -104,6 +104,12 @@ class XmlReader {
 				this.#readProcessingInstruction(document);
 				continue;
 			}
+			if (this.#xml.startsWith("</", this.#position)) {
+				// Stray end tag with no element open: skip it instead of parsing it as a new element,
+				// whose empty name would leave #readElement stuck on the `/`.
+				this.#skipThrough(">");
+				continue;
+			}
 			if (this.#xml[this.#position] === "<") {
 				const element = this.#readElement("");
 				this.#addValue(document, element.name, element.name, element.value, element.leaf, null);
@@ -138,6 +144,11 @@ class XmlReader {
 				this.#position++;
 				this.#skipWhitespace();
 				value = this.#readAttributeValue();
+			} else if (attributeName === "") {
+				// Markup #readName cannot consume (the stray `/` in `<a / >`): skip the character
+				// so the loop always makes progress.
+				this.#position++;
+				continue;
 			}
 			attributes.push([attributeName, value]);
 		}
@@ -153,6 +164,11 @@ class XmlReader {
 					this.#position = close < 0 ? this.#xml.length : close + 1;
 					break;
 				}
+				if (this.#xml.startsWith("</", this.#position)) {
+					// End tag for an ancestor (an unclosed `<br>` inside `<p>`, or plain mismatched
+					// markup): close this element implicitly and leave the tag to its owner.
+					break;
+				}
 				if (this.#xml.startsWith("<![CDATA[", this.#position)) {
 					const end = this.#xml.indexOf("]]>", this.#position + 9);
 					const raw = this.#xml.slice(this.#position + 9, end < 0 ? this.#xml.length : end);