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

package/src/tab-spacing.ts

@@ -0,0 +1,336 @@
+/**
+ * Default tab width (display / tab expansion) and per-file width from `.editorconfig`.
+ * Mirrors former `pi-natives` `indent` + `text` default-tab-width behavior (no N-API).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isFsError } from "./fs-error";
+
+export const MIN_TAB_WIDTH = 1;
+export const MAX_TAB_WIDTH = 16;
+export const DEFAULT_TAB_WIDTH = 3;
+
+/**
+ * Per-component path length cap on common filesystems (`NAME_MAX = 255` on
+ * Linux ext4 / macOS APFS / Windows NTFS). Paths with components longer than
+ * this cannot be opened at all, so editorconfig discovery short-circuits to
+ * the default instead of running into `ENAMETOOLONG` from `readFileSync`.
+ */
+const NAME_MAX_BYTES = 255;
+
+const EDITORCONFIG_NAME = ".editorconfig";
+
+const editorConfigCache = new Map<string, ParsedEditorConfig | null>();
+const editorConfigChainCache = new Map<string, ChainEntry[]>();
+
+interface EditorConfigSection {
+	pattern: string;
+	properties: Map<string, string>;
+}
+
+interface ParsedEditorConfig {
+	root: boolean;
+	sections: EditorConfigSection[];
+}
+
+interface ChainEntry {
+	dir: string;
+	parsed: ParsedEditorConfig;
+}
+
+const enum IndentStyle {
+	Space,
+	Tab,
+}
+
+type IndentSize = { kind: "spaces"; n: number } | { kind: "tab" };
+
+interface EditorConfigMatch {
+	indentStyle?: IndentStyle;
+	indentSize?: IndentSize;
+	tabWidth?: number;
+}
+
+function clampTabWidth(value: number): number {
+	return Math.min(MAX_TAB_WIDTH, Math.max(MIN_TAB_WIDTH, Math.trunc(value)));
+}
+
+function parsePositiveInteger(raw: string | undefined): number | undefined {
+	if (raw === undefined) return undefined;
+	if (!/^\d+$/.test(raw)) return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	if (parsed === 0) return undefined;
+	return clampTabWidth(parsed);
+}
+
+function fixUnclosedBraces(pattern: string): string {
+	const opens = [...pattern].filter(c => c === "{").length;
+	const closes = [...pattern].filter(c => c === "}").length;
+	if (opens > closes) {
+		return pattern + "}".repeat(opens - closes);
+	}
+	return pattern;
+}
+
+/** Match `crates/pi-natives/src/glob_util.rs` `build_glob_pattern`. */
+function buildGlobPattern(globStr: string, recursive: boolean): string {
+	const normalized = globStr.replace(/\\/g, "/");
+	const pattern =
+		!recursive || normalized.includes("/") || normalized.startsWith("**") ? normalized : `**/${normalized}`;
+	return fixUnclosedBraces(pattern);
+}
+
+function globMatches(pattern: string, relativePath: string): boolean {
+	try {
+		const g = new Bun.Glob(pattern);
+		return g.match(relativePath);
+	} catch {
+		return false;
+	}
+}
+
+function matchesEditorConfigPattern(pattern: string, relativePath: string): boolean {
+	const normalized = pattern.replace(/^\/+/, "");
+	if (!normalized) {
+		return false;
+	}
+
+	const candidates = normalized.includes("/")
+		? [buildGlobPattern(normalized, false)]
+		: [buildGlobPattern(normalized, false), buildGlobPattern(normalized, true)];
+
+	for (const p of candidates) {
+		if (globMatches(p, relativePath)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function parseEditorConfigFile(content: string): ParsedEditorConfig {
+	const parsed: ParsedEditorConfig = { root: false, sections: [] };
+	let currentSectionIdx: number | undefined;
+
+	for (const rawLine of content.split(/\n/)) {
+		const line = rawLine.trim();
+		if (line === "") continue;
+		if (line.startsWith("#") || line.startsWith(";")) continue;
+
+		if (line.startsWith("[") && line.endsWith("]") && line.length >= 2) {
+			const secPattern = line.slice(1, -1).trim();
+			if (secPattern === "") {
+				currentSectionIdx = undefined;
+				continue;
+			}
+			parsed.sections.push({ pattern: secPattern, properties: new Map() });
+			currentSectionIdx = parsed.sections.length - 1;
+			continue;
+		}
+
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		const key = line.slice(0, eq).trim().toLowerCase();
+		const value = line
+			.slice(eq + 1)
+			.trim()
+			.toLowerCase();
+		if (key === "") continue;
+
+		if (currentSectionIdx !== undefined) {
+			parsed.sections[currentSectionIdx]!.properties.set(key, value);
+		} else if (key === "root") {
+			parsed.root = value === "true";
+		}
+	}
+
+	return parsed;
+}
+
+function parseCachedEditorConfig(configPath: string): ParsedEditorConfig | undefined {
+	const key = path.resolve(configPath);
+	const hit = editorConfigCache.get(key);
+	if (hit !== undefined) {
+		return hit ?? undefined;
+	}
+
+	let content: string;
+	try {
+		content = fs.readFileSync(key, "utf8");
+	} catch (err) {
+		// editorconfig discovery is best-effort. Any filesystem error
+		// (`ENOENT`, `ENAMETOOLONG`, `ENOTDIR`, `EACCES`, `ELOOP`, `EINVAL`,
+		// …) means "no usable config at this path" — never a fatal condition
+		// for callers like the edit renderer that hand us arbitrary strings.
+		if (isFsError(err)) return undefined;
+		throw err;
+	}
+	const parsed = parseEditorConfigFile(content);
+	editorConfigCache.set(key, parsed);
+	return parsed;
+}
+
+function resolveFilePath(projectDir: string, file: string): string {
+	if (path.isAbsolute(file)) {
+		return path.normalize(path.resolve(file));
+	}
+	return path.normalize(path.resolve(projectDir, file));
+}
+
+/** Like `pathdiff::diff_paths` + forward slashes (see `indent.rs`). */
+function relativePathUnified(baseDir: string, absoluteFile: string): string {
+	const base = path.resolve(baseDir);
+	const file = path.resolve(absoluteFile);
+	const rel = path.relative(base, file);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) {
+		return ".";
+	}
+	return rel.replace(/\\/g, "/");
+}
+
+function collectEditorConfigChain(startDir: string): ChainEntry[] {
+	const key = path.resolve(startDir);
+	const cached = editorConfigChainCache.get(key);
+	if (cached !== undefined) {
+		return cached;
+	}
+
+	const chain: ChainEntry[] = [];
+	let cursor = key;
+	for (;;) {
+		const configPath = path.join(cursor, EDITORCONFIG_NAME);
+		const parsed = parseCachedEditorConfig(configPath);
+		if (parsed !== undefined) {
+			chain.push({ dir: cursor, parsed });
+			if (parsed.root) {
+				break;
+			}
+		}
+
+		const parent = path.dirname(cursor);
+		if (parent === cursor) {
+			break;
+		}
+		cursor = parent;
+	}
+
+	chain.reverse();
+	editorConfigChainCache.set(key, chain);
+	return chain;
+}
+
+function resolveEditorConfigMatch(absoluteFile: string): EditorConfigMatch | undefined {
+	const fileDir = path.dirname(absoluteFile);
+	const chain = collectEditorConfigChain(fileDir);
+	if (chain.length === 0) {
+		return undefined;
+	}
+
+	const match: EditorConfigMatch = {};
+	for (const { dir, parsed } of chain) {
+		const relativePath = relativePathUnified(dir, absoluteFile);
+		for (const section of parsed.sections) {
+			if (!matchesEditorConfigPattern(section.pattern, relativePath)) {
+				continue;
+			}
+
+			const style = section.properties.get("indent_style");
+			if (style === "space") {
+				match.indentStyle = IndentStyle.Space;
+			} else if (style === "tab") {
+				match.indentStyle = IndentStyle.Tab;
+			}
+
+			const rawSize = section.properties.get("indent_size");
+			if (rawSize === "tab") {
+				match.indentSize = { kind: "tab" };
+			} else if (rawSize !== undefined) {
+				const n = parsePositiveInteger(rawSize);
+				if (n !== undefined) {
+					match.indentSize = { kind: "spaces", n };
+				}
+			}
+
+			const tw = parsePositiveInteger(section.properties.get("tab_width"));
+			if (tw !== undefined) {
+				match.tabWidth = tw;
+			}
+		}
+	}
+
+	if (match.indentStyle === undefined && match.indentSize === undefined && match.tabWidth === undefined) {
+		return undefined;
+	}
+	return match;
+}
+
+function hasOverlongPathComponent(filePath: string): boolean {
+	for (const part of filePath.split(/[\\/]/)) {
+		if (part.length > 0 && Buffer.byteLength(part) > NAME_MAX_BYTES) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * `.editorconfig`-derived formatting options for an LSP `textDocument/formatting` request.
+ *
+ * Both fields are absent when the resolved `.editorconfig` chain does not pin them, so callers
+ * can layer their own fallbacks (content sniffing, project defaults) underneath. Returned values
+ * are clamped to {@link MIN_TAB_WIDTH}..{@link MAX_TAB_WIDTH}.
+ */
+export interface EditorConfigFormatting {
+	/** Effective indent width in columns, from `indent_size` or `tab_width`. */
+	tabSize?: number;
+	/** `true` for `indent_style = space`, `false` for `indent_style = tab` (or `indent_size = tab`). */
+	insertSpaces?: boolean;
+}
+
+/**
+ * Resolve `.editorconfig` formatting hints for `file` without falling back to any default.
+ *
+ * Used by the LSP format-on-write path so a missing `.editorconfig` declaration falls through
+ * to caller-provided defaults instead of clobbering the file with the renderer's
+ * display tab width (issue #2329).
+ */
+export function getEditorConfigFormatting(file?: string | null, projectDir?: string | null): EditorConfigFormatting {
+	if (file === undefined || file === null || file === "") {
+		return {};
+	}
+
+	const cwd = projectDir ?? process.cwd();
+	const absoluteFile = resolveFilePath(cwd, file);
+
+	// NAME_MAX guard: editorconfig discovery is
+	// best-effort and must never escape as `ENAMETOOLONG` from a renderer's
+	// stray gibberish path.
+	if (hasOverlongPathComponent(absoluteFile)) {
+		return {};
+	}
+
+	const match = resolveEditorConfigMatch(absoluteFile);
+	if (match === undefined) {
+		return {};
+	}
+
+	const result: EditorConfigFormatting = {};
+
+	if (match.indentSize?.kind === "spaces") {
+		result.tabSize = clampTabWidth(match.indentSize.n);
+	} else if (match.tabWidth !== undefined) {
+		result.tabSize = clampTabWidth(match.tabWidth);
+	}
+
+	if (match.indentStyle === IndentStyle.Space) {
+		result.insertSpaces = true;
+	} else if (match.indentStyle === IndentStyle.Tab || match.indentSize?.kind === "tab") {
+		result.insertSpaces = false;
+	} else if (match.indentSize?.kind === "spaces") {
+		// `indent_size = <n>` without an explicit `indent_style` is universally
+		// read as "indent with N spaces" — both VSCode and Sublime infer
+		// `indent_style = space` in that case.
+		result.insertSpaces = true;
+	}
+
+	return result;
+}

package/src/temp.ts

@@ -0,0 +1,134 @@
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+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 fsPromises.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 = removeWithRetries(this.#path);
+		this.#removePromise = removePromise;
+		return removePromise;
+	}
+
+	removeSync(): void {
+		removeSyncWithRetries(this.#path);
+		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;
+}
+
+const kRemoveOptions = { recursive: true, force: true } as const;
+const kRemoveRetries = 40;
+// 50ms × 40 retries = 2s total retry window. Windows holds file locks on
+// SQLite DBs for up to ~1.5s after close(); the previous 25ms (1s total)
+// was too short for some test cleanup scenarios.
+const kRemoveRetryDelayMs = 50;
+const kRetryableRemoveErrorCodes = new Set(["EBUSY", "EPERM", "ENOTEMPTY"]);
+const kSleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+
+/** Removes a path recursively, retrying transient Windows deletion failures. */
+export async function removeWithRetries(target: string): Promise<void> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			await fsPromises.rm(target, kRemoveOptions);
+			return;
+		} catch (err) {
+			if (!shouldRetryRemove(err, attempt)) throw err;
+			await Bun.sleep(kRemoveRetryDelayMs);
+		}
+	}
+}
+
+export function removeSyncWithRetries(target: string): void {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			fs.rmSync(target, kRemoveOptions);
+			return;
+		} catch (err) {
+			if (!shouldRetryRemove(err, attempt)) throw err;
+			sleepSync(kRemoveRetryDelayMs);
+		}
+	}
+}
+
+function shouldRetryRemove(err: unknown, attempt: number): boolean {
+	return attempt < kRemoveRetries && process.platform === "win32" && isRetryableRemoveError(err);
+}
+
+function isRetryableRemoveError(err: unknown): boolean {
+	return (
+		typeof err === "object" &&
+		err !== null &&
+		"code" in err &&
+		typeof err.code === "string" &&
+		kRetryableRemoveErrorCodes.has(err.code)
+	);
+}
+
+function sleepSync(ms: number): void {
+	if ("sleepSync" in Bun && typeof Bun.sleepSync === "function") {
+		Bun.sleepSync(ms);
+		return;
+	}
+	Atomics.wait(kSleepBuffer, 0, 0, ms);
+}

package/src/timing-buffer.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared contract between the {@link module-timer} preload and {@link logger}'s
+ * timing tree. Kept in its own dependency-free module so the preload can import
+ * it without pulling in winston (via logger) and the logger can drain the buffer
+ * without importing the Bun-plugin preload.
+ */
+
+export interface ModuleLoadEvent {
+	/** Absolute or Bun-resolved module path. */
+	path: string;
+	/** `performance.now()` timestamp captured at Bun `onLoad` entry. */
+	start: number;
+	/** Inclusive module window: `onLoad` entry → appended final marker. */
+	durationMs: number;
+	/** Own top-level body / TLA time: prepended body marker → appended final marker. */
+	bodyMs?: number;
+	/** Resolved static children imported by this module. */
+	imports: string[];
+}
+
+/**
+ * Registry-global key under which the preload accumulates module-load events.
+ * `Symbol.for` so both modules resolve the same symbol independently.
+ */
+const KEY: symbol = Symbol.for("omp.moduleLoadBuffer");
+
+type Store = Record<symbol, ModuleLoadEvent[] | undefined>;
+
+/** The append-only buffer the preload pushes into (created on first access). */
+export function moduleLoadBuffer(): ModuleLoadEvent[] {
+	const store = globalThis as unknown as Store;
+	let buffer = store[KEY];
+	if (!buffer) {
+		buffer = [];
+		store[KEY] = buffer;
+	}
+	return buffer;
+}
+
+/** Drain and return all buffered events, leaving the buffer empty. */
+export function drainModuleLoadEvents(): ModuleLoadEvent[] {
+	const store = globalThis as unknown as Store;
+	const buffer = store[KEY];
+	if (!buffer || buffer.length === 0) return [];
+	store[KEY] = [];
+	return buffer;
+}

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-zen/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;
+}

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));
+}