@oh-my-pi/pi-utils 16.1.1 → 16.1.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [16.1.2] - 2026-06-19
+
+### Added
+
+- Added `directoryExists(dir)` to `dirs`: resolves whether a path is an existing directory, returning `false` on any stat failure (ENOENT, permission, non-directory). Lets callers check a directory is safe to `chdir` into before `setProjectDir` throws.
+
+### Removed
+
+- Removed the public `createAbortableStream` API from `@oh-my-pi/pi-utils`. Consumers should use the lighter, direct-reader `abortableSource` async generator inside `@oh-my-pi/pi-utils/stream` to avoid the extra ReadableStream wrapper layer and per-chunk enqueue overhead.
+
 ## [16.0.11] - 2026-06-19
 
 ### Removed

package/dist/types/abortable.d.ts

@@ -2,18 +2,18 @@ export declare class AbortError extends Error {
     constructor(signal: AbortSignal);
 }
 /**
- * Creates an abortable stream from a given stream and signal.
+ * 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 when the signal aborts. That propagates HTTP-client disconnects
- * and stream watchdog timeouts all the way to the backend request instead of
- * only stopping the local consumer.
- *
- * @param stream - The stream to make abortable
- * @param signal - The signal to abort the stream
- * @returns The abortable stream
+ * 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 declare function createAbortableStream<T>(stream: ReadableStream<T>, signal?: AbortSignal): ReadableStream<T>;
+export declare function abortableSource<T>(stream: ReadableStream<T>, signal?: AbortSignal): AsyncGenerator<T>;
 /**
  * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
  * execution, the promise is rejected with a standard error.

package/dist/types/dirs.d.ts

@@ -44,6 +44,13 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
+/**
+ * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
+ * path (ENOENT), permission error, or a non-directory — returns `false`, so
+ * callers can decide whether a directory is safe to `chdir` into or adopt as a
+ * working directory before {@link setProjectDir} throws on it.
+ */
+export declare function directoryExists(dir: string): Promise<boolean>;
 /** Get the config directory name relative to home (e.g. ".omp" or PI_CONFIG_DIR override). */
 export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".omp/agent" or PI_CONFIG_DIR + "/agent"). */

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { createAbortableStream, once, untilAborted } from "./abortable";
+export { once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./color";
 export * from "./dirs";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "16.1.1",
+	"version": "16.1.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.1.1",
+		"@oh-my-pi/pi-natives": "16.1.2",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "^5.0.0"

package/src/abortable.ts

@@ -10,101 +10,52 @@ export class AbortError extends Error {
 	}
 }
 
-type AbortableStreamReadResult<T> = { done: true; value?: T } | { done: false; value: T };
-
-interface AbortableStreamReader<T> {
-	read(): Promise<AbortableStreamReadResult<T>>;
-	cancel(reason?: unknown): Promise<void>;
-	releaseLock(): void;
-}
-
 /**
- * Creates an abortable stream from a given stream and signal.
+ * 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 when the signal aborts. That propagates HTTP-client disconnects
- * and stream watchdog timeouts all the way to the backend request instead of
- * only stopping the local consumer.
- *
- * @param stream - The stream to make abortable
- * @param signal - The signal to abort the stream
- * @returns The abortable stream
+ * 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 function createAbortableStream<T>(stream: ReadableStream<T>, signal?: AbortSignal): ReadableStream<T> {
-	if (!signal) return stream;
-	let reader: AbortableStreamReader<T> | undefined;
-	let closed = false;
+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;
-
-	const cleanup = () => {
-		if (onAbort) signal.removeEventListener("abort", onAbort);
-		onAbort = undefined;
-		const currentReader = reader;
-		reader = undefined;
-		try {
-			currentReader?.releaseLock();
-		} catch {}
-	};
-
-	const cancelReader = (reason: unknown): Promise<void> => {
-		if (closed) return Promise.resolve();
-		closed = true;
-		const currentReader = reader;
-		reader = undefined;
-		if (onAbort) signal.removeEventListener("abort", onAbort);
-		onAbort = undefined;
-		if (!currentReader) return Promise.resolve();
-		return currentReader
-			.cancel(reason)
-			.catch(() => {})
-			.finally(() => {
-				try {
-					currentReader.releaseLock();
-				} catch {}
-			});
-	};
-
-	return new ReadableStream<T>({
-		start(controller) {
-			reader = stream.getReader();
-			onAbort = () => {
-				void cancelReader(signal.reason);
-				try {
-					controller.error(new AbortError(signal));
-				} catch {}
-			};
-			if (signal.aborted) {
-				onAbort();
+	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;
 			}
-			signal.addEventListener("abort", onAbort, { once: true });
-			void (async () => {
-				try {
-					for (;;) {
-						const currentReader = reader;
-						if (!currentReader) return;
-						const { value, done } = await currentReader.read();
-						if (closed) return;
-						if (done) {
-							closed = true;
-							cleanup();
-							controller.close();
-							return;
-						}
-						controller.enqueue(value);
-					}
-				} catch (error) {
-					if (closed) return;
-					closed = true;
-					cleanup();
-					controller.error(signal.aborted ? new AbortError(signal) : error);
-				}
-			})();
-		},
-		cancel(reason) {
-			return cancelReader(reason);
-		},
-	});
+			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 {}
+	}
 }
 
 /**

package/src/dirs.ts

@@ -185,6 +185,20 @@ export function setProjectDir(dir: string): void {
 	process.chdir(projectDir);
 }
 
+/**
+ * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
+ * path (ENOENT), permission error, or a non-directory — returns `false`, so
+ * callers can decide whether a directory is safe to `chdir` into or adopt as a
+ * working directory before {@link setProjectDir} throws on it.
+ */
+export async function directoryExists(dir: string): Promise<boolean> {
+	try {
+		return (await fs.promises.stat(dir)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
 /** Get the config directory name relative to home (e.g. ".omp" or PI_CONFIG_DIR override). */
 export function getConfigDirName(): string {
 	return process.env.PI_CONFIG_DIR || CONFIG_DIR_NAME;

package/src/index.ts

@@ -1,4 +1,4 @@
-export { createAbortableStream, once, untilAborted } from "./abortable";
+export { once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./color";
 export * from "./dirs";

package/src/stream.ts

@@ -1,4 +1,4 @@
-import { createAbortableStream } from "./abortable";
+import { abortableSource } from "./abortable";
 
 const LF = 0x0a;
 type JsonlChunkResult = {
@@ -23,7 +23,7 @@ function parseJsonlChunkCompat(input: Uint8Array | string, beg?: number, end?: n
 
 export async function* readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array> {
 	const buffer = new ConcatSink();
-	const source = createAbortableStream(stream, signal);
+	const source = abortableSource(stream, signal);
 	try {
 		for await (const chunk of source) {
 			for (const line of buffer.appendAndFlushLines(chunk)) {
@@ -46,7 +46,7 @@ export async function* readLines(stream: ReadableStream<Uint8Array>, signal?: Ab
 
 export async function* readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T> {
 	const buffer = new ConcatSink();
-	const source = createAbortableStream(stream, signal);
+	const source = abortableSource(stream, signal);
 	try {
 		for await (const chunk of source) {
 			yield* buffer.pullJSONL<T>(chunk, 0, chunk.length);
@@ -339,7 +339,7 @@ export async function* readSseEvents(
 ): AsyncGenerator<ServerSentEvent> {
 	const lineBuffer = new ConcatSink();
 	const state: SseEventState = { event: null, data: null, raw: [] };
-	const source = createAbortableStream(stream, signal);
+	const source = abortableSource(stream, signal);
 	try {
 		for await (const chunk of source) {
 			for (const line of lineBuffer.appendAndFlushLines(chunk)) {