@oh-my-pi/pi-utils 16.2.13 → 16.3.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.3.0] - 2026-07-02
+
+### Added
+
+- Added `wrapFetchForExtraCa` and `withExtraCaFetch` utility functions to apply `NODE_EXTRA_CA_CERTS` to Bun's `RequestInit.tls.ca` configuration.
+
 ## [16.2.9] - 2026-06-30
 
 ### Added
@@ -109,24 +115,16 @@
 
 - Added profile-aware directory helpers and isolated profile state roots, while keeping the install ID shared across profiles.
 - Added a named-profile API to the `dirs` module — `setProfile()`, `getActiveProfile()`, `getProfileRootDir()`, and `normalizeProfileName()` — plus `resolveProfileEnv()`, which selects the active profile from `OMP_PROFILE` (canonical; takes precedence) then `PI_PROFILE` (legacy fallback, consulted only when `OMP_PROFILE` is unset).
-- Added the side-effect-free `@oh-my-pi/pi-utils/worker-host` module (`declareWorkerHostEntry()` / `workerHostEntry()`), extracted from `env` (still re-exported there) so worker spawn sites can resolve the self-dispatching CLI host entry without importing `env`'s side-effecting module graph.
-
-### Fixed
-
-- Fixed profile directory isolation when a profile's agent `.env` customizes directory roots: directory-affecting keys (`XDG_DATA_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME`, and a default-mode `PI_CODING_AGENT_DIR`) are now honored. The `env` loader rebuilds the `dirs` resolver after applying `.env` files (`refreshDirsFromEnv()`), so a profile `.env` that points XDG roots elsewhere no longer leaks state into the home-based config dir.
-- Fixed `installRuntimeModuleResolver()` to keep bare requests from runtime-cache modules inside that registered runtime before falling back to host/workspace packages.
-
-## [15.13.1] - 2026-06-15
-
-### Added
-
 - Added support for a runtime `overrides` map in `RuntimeInstallSpec`, which is now written into generated runtime `package.json` manifests to force dependency pins (including transitive ones) across the runtime tree
 - Added a lightweight loop-phase breadcrumb stack (`pushLoopPhase`/`popLoopPhase`/`currentLoopPhase`, plus `takeRecentLoopPhase` which returns the live phase or the most recently popped one and clears it) so the TUI event-loop watchdog can attribute a main-thread block to the phase that caused it — including a synchronous phase already popped before the watchdog's delayed tick runs ([#2485](https://github.com/can1357/oh-my-pi/issues/2485))
 - Added `FetchWithRetryOptions.timeout` (forwarded to the underlying `fetch` call). `false` disables Bun's native ~300s pre-response timeout; a positive number overrides the ceiling. Bare browser/Node fetch ignores it ([#2422](https://github.com/can1357/oh-my-pi/issues/2422))
+- Added the side-effect-free `@oh-my-pi/pi-utils/worker-host` module (`declareWorkerHostEntry()` / `workerHostEntry()`), extracted from `env` (still re-exported there) so worker spawn sites can resolve the self-dispatching CLI host entry without importing `env`'s side-effecting module graph.
 
 ### Fixed
 
+- Fixed profile directory isolation when a profile's agent `.env` customizes directory roots: directory-affecting keys (`XDG_DATA_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME`, and a default-mode `PI_CODING_AGENT_DIR`) are now honored. The `env` loader rebuilds the `dirs` resolver after applying `.env` files (`refreshDirsFromEnv()`), so a profile `.env` that points XDG roots elsewhere no longer leaks state into the home-based config dir.
 - Made `TempDir` cleanup retry transient Windows `EBUSY`/`EPERM`/`ENOTEMPTY` removal failures so tests are less likely to fail when deleting just-used temp directories.
+- Fixed `installRuntimeModuleResolver()` to keep bare requests from runtime-cache modules inside that registered runtime before falling back to host/workspace packages.
 
 ## [15.12.4] - 2026-06-13
 

package/dist/types/index.d.ts

@@ -29,6 +29,7 @@ export * from "./snowflake";
 export * from "./stream";
 export * from "./tab-spacing";
 export * from "./temp";
+export * from "./tls-fetch";
 export * from "./type-guards";
 export * from "./which";
 export declare function structuredCloneJSON<T>(value: T): T;

package/dist/types/tls-fetch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `fetch`-compatible function. Accepts any callable matching the standard
+ * fetch signature; `preconnect` is optional because non-Bun runtimes
+ * (browsers, test mocks) won't expose it.
+ */
+export type FetchImpl = ((input: string | URL | Request, init?: RequestInit) => Promise<Response>) & {
+    preconnect?: typeof globalThis.fetch.preconnect;
+};
+/**
+ * `NODE_EXTRA_CA_CERTS` was set but unusable (path does not exist). This is
+ * a config/contract error, not a transient transport fault — it is never
+ * retried.
+ */
+export declare class ExtraCaError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Test seam: drop the cached PEM so a follow-up call re-reads the env. */
+export declare function __resetExtraCaCache(): void;
+/**
+ * Wrap `fetchImpl` so every call honours `NODE_EXTRA_CA_CERTS`. Idempotent:
+ * a fetch already wrapped is returned unchanged so repeated composition
+ * (Anthropic auth-retry replays, request-debug fan-out) never stacks
+ * wrappers. When the env var is unset the original fetch is returned, so
+ * default deployments pay nothing.
+ */
+export declare function wrapFetchForExtraCa(fetchImpl: FetchImpl): FetchImpl;
+/**
+ * Convenience for options-bag composition (e.g. the stream-entry path in
+ * `@oh-my-pi/pi-ai`'s `stream.ts`, which mirrors `withRequestDebugFetch` so
+ * the proxy/debug/extra-CA wrappers compose uniformly). No-op when the env
+ * var is unset.
+ */
+export declare function withExtraCaFetch<T extends {
+    fetch?: FetchImpl;
+} | undefined>(options: T): T;

package/package.json

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

package/src/index.ts

@@ -29,6 +29,7 @@ export * from "./snowflake";
 export * from "./stream";
 export * from "./tab-spacing";
 export * from "./temp";
+export * from "./tls-fetch";
 export * from "./type-guards";
 export * from "./which";
 

package/src/tls-fetch.ts

@@ -0,0 +1,178 @@
+/**
+ * `NODE_EXTRA_CA_CERTS` shim for Bun's `fetch`.
+ *
+ * Node's TLS layer honours `NODE_EXTRA_CA_CERTS` natively, but Bun's
+ * `fetch` does not, and both the provider streams (`openai-responses`,
+ * `openai-completions`, `openai-codex-responses`, `ollama-chat`, ...) and
+ * catalog model discovery (`/models` probes) route every request through
+ * Bun's runtime. Without this wrapper, corporate relays and private
+ * gateways behind a custom CA bundle fail with
+ * `unknown certificate verification error` even when the env var is set.
+ *
+ * The wrapper merges the resolved CA bundle into Bun's `RequestInit.tls.ca`.
+ * Bun's `tls.ca` REPLACES the default trust store when set, so the wrapper
+ * always seeds {@link tls.rootCertificates} when the caller has not already
+ * curated their own CA list.
+ */
+import * as fs from "node:fs";
+import * as tls from "node:tls";
+import { $env } from "./env";
+import { isEnoent } from "./fs-error";
+
+/**
+ * `fetch`-compatible function. Accepts any callable matching the standard
+ * fetch signature; `preconnect` is optional because non-Bun runtimes
+ * (browsers, test mocks) won't expose it.
+ */
+export type FetchImpl = ((input: string | URL | Request, init?: RequestInit) => Promise<Response>) & {
+	preconnect?: typeof globalThis.fetch.preconnect;
+};
+
+/**
+ * `NODE_EXTRA_CA_CERTS` was set but unusable (path does not exist). This is
+ * a config/contract error, not a transient transport fault — it is never
+ * retried.
+ */
+export class ExtraCaError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ExtraCaError";
+	}
+}
+
+/** Bun extension to `RequestInit` for the TLS options we touch. */
+type BunTlsOptions = {
+	ca?: string | string[];
+	cert?: string;
+	key?: string;
+	rejectUnauthorized?: boolean;
+	serverName?: string;
+	ciphers?: string;
+};
+
+type BunTlsRequestInit = RequestInit & { tls?: BunTlsOptions };
+
+const EXTRA_CA_FETCH_MARKER = Symbol("omp.extraCaFetch");
+type ExtraCaFetch = FetchImpl & { [EXTRA_CA_FETCH_MARKER]?: true };
+
+/**
+ * Cached resolution of `NODE_EXTRA_CA_CERTS`. Keyed on the env value plus
+ * the file mtime for path values so on-disk cert rotation (short-lived
+ * corporate bundles) invalidates the cache instead of pinning the first
+ * read forever.
+ */
+let cacheKey: string | undefined;
+let cacheValue: string | undefined;
+
+/**
+ * Returns the PEM bytes referenced by `NODE_EXTRA_CA_CERTS`, or `undefined`
+ * when the env var is unset/empty.
+ *
+ * Accepts the same shapes Node accepts plus an inline-PEM escape hatch:
+ * - Inline PEM (`-----BEGIN CERTIFICATE-----...`). Literal `\n` escapes in
+ *   the env value are expanded so callers can ship single-line PEMs through
+ *   shell exports.
+ * - File path. Anything that does not contain a PEM header is treated as a
+ *   path, matching Node's "extensionless filename is still a path" contract.
+ *   `ENOENT` becomes {@link ExtraCaError}; other I/O errors bubble.
+ */
+function resolveExtraCa(): string | undefined {
+	const raw = $env.NODE_EXTRA_CA_CERTS?.trim();
+	if (!raw) return undefined;
+
+	let key: string;
+	if (raw.includes("-----BEGIN")) {
+		key = raw;
+	} else {
+		try {
+			key = `${raw}@${fs.statSync(raw).mtimeMs}`;
+		} catch {
+			key = raw;
+		}
+	}
+	if (key === cacheKey) return cacheValue;
+
+	if (raw.includes("-----BEGIN")) {
+		cacheValue = raw.replace(/\\n/g, "\n");
+	} else {
+		try {
+			cacheValue = fs.readFileSync(raw, "utf8");
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new ExtraCaError(`NODE_EXTRA_CA_CERTS path does not exist: ${raw}`);
+			}
+			throw error;
+		}
+	}
+	cacheKey = key;
+	return cacheValue;
+}
+
+/** Test seam: drop the cached PEM so a follow-up call re-reads the env. */
+export function __resetExtraCaCache(): void {
+	cacheKey = undefined;
+	cacheValue = undefined;
+}
+
+/**
+ * Merge `extraCa` into `init.tls.ca`. When the caller has not supplied a CA
+ * list, the system root store is included alongside the extra bundle —
+ * Bun's `tls.ca` replaces the default trust store, so omitting roots would
+ * break every public host. When the caller already curated a list (e.g.
+ * Anthropic Foundry's mTLS options, which already seed
+ * `tls.rootCertificates`), only the extra CA is appended.
+ */
+function withExtraCaInit(init: RequestInit | undefined, extraCa: string): RequestInit {
+	const existingTls = (init as BunTlsRequestInit | undefined)?.tls;
+	const existingCa = existingTls?.ca;
+	let mergedCa: string[];
+	if (existingCa === undefined) {
+		mergedCa = [...tls.rootCertificates, extraCa];
+	} else if (Array.isArray(existingCa)) {
+		mergedCa = [...existingCa, extraCa];
+	} else {
+		mergedCa = [existingCa, extraCa];
+	}
+	return { ...init, tls: { ...existingTls, ca: mergedCa } } as RequestInit;
+}
+
+/**
+ * Wrap `fetchImpl` so every call honours `NODE_EXTRA_CA_CERTS`. Idempotent:
+ * a fetch already wrapped is returned unchanged so repeated composition
+ * (Anthropic auth-retry replays, request-debug fan-out) never stacks
+ * wrappers. When the env var is unset the original fetch is returned, so
+ * default deployments pay nothing.
+ */
+export function wrapFetchForExtraCa(fetchImpl: FetchImpl): FetchImpl {
+	const maybeWrapped = fetchImpl as ExtraCaFetch;
+	if (maybeWrapped[EXTRA_CA_FETCH_MARKER]) return fetchImpl;
+	// Peek once at construction — if the env var is unset, skip the wrapper
+	// entirely so the hot fetch path stays a single function call. The env
+	// is evaluated again per request below to catch in-process updates from
+	// tests (`__resetExtraCaCache` + env mutation).
+	if (!$env.NODE_EXTRA_CA_CERTS?.trim()) return fetchImpl;
+
+	const wrapped = Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			const extraCa = resolveExtraCa();
+			return extraCa ? fetchImpl(input, withExtraCaInit(init, extraCa)) : fetchImpl(input, init);
+		},
+		fetchImpl.preconnect ? { preconnect: fetchImpl.preconnect } : {},
+		{ [EXTRA_CA_FETCH_MARKER]: true as const },
+	);
+	return wrapped;
+}
+
+/**
+ * Convenience for options-bag composition (e.g. the stream-entry path in
+ * `@oh-my-pi/pi-ai`'s `stream.ts`, which mirrors `withRequestDebugFetch` so
+ * the proxy/debug/extra-CA wrappers compose uniformly). No-op when the env
+ * var is unset.
+ */
+export function withExtraCaFetch<T extends { fetch?: FetchImpl } | undefined>(options: T): T {
+	if (!$env.NODE_EXTRA_CA_CERTS?.trim()) return options;
+	const fetchImpl = options?.fetch ?? (globalThis.fetch as FetchImpl);
+	const wrapped = wrapFetchForExtraCa(fetchImpl);
+	if (wrapped === fetchImpl && options?.fetch !== undefined) return options;
+	return { ...(options ?? {}), fetch: wrapped } as T;
+}