@prometheus-ai/utils 0.5.4 → 0.5.8

package/src/module-timer.ts

@@ -0,0 +1,148 @@
+/**
+ * Module-load timing preload.
+ *
+ * `bun --preload .../module-timer.ts <entry>` installs Bun plugin hooks (only
+ * when `PROMETHEUS_TIMING` is set) that record an inclusive module window plus resolved
+ * static child edges:
+ *
+ *   onLoad start → appended end marker after the module's top-level body
+ *
+ * Events are pushed into a process-global buffer that {@link logger.printTimings}
+ * drains and renders as a module DAG/tree. Each module row can therefore show
+ * both total time and `self` time after subtracting child module intervals.
+ *
+ * Why a preload (and not a normal import): Bun reads the *entire* statically
+ * reachable graph before evaluating any module, so hooks installed from inside
+ * that graph cannot observe its own loading — they only catch later dynamically
+ * loaded modules. A preload runs first, so it sees the static-import phase that
+ * dominates startup.
+ *
+ * Kept dependency-free on purpose: the sole import is Bun's `plugin`, so this is
+ * cheap to preload before pi-utils (and winston) exist. The buffer is shared with
+ * the logger via a registry Symbol so neither side needs to import the other.
+ *
+ * **What is measured:** an inclusive per-module window. `onLoad` stamps the
+ * start before reading source; the returned source has a tiny marker appended at
+ * the end of the module. That marker runs after Bun parses/transpiles the module
+ * and after any top-level await in that module completes, so the duration
+ * includes read + parse/transpile + dependency wait + top-level execution/TLA.
+ * If a module throws before its final statement, no end marker is recorded.
+ *
+ * **Tree shape:** `onResolve` observes importer → specifier edges and resolves
+ * them with `Bun.resolveSync` without taking over Bun's real resolution. The
+ * logger renders these edges as a DAG/tree and computes module `self` time by
+ * subtracting the union of child intervals, avoiding misleading flat inclusive
+ * totals.
+ *
+ * **Coverage limits:**
+ * - TS/TSX only — intercepting `node_modules` CJS `.js`/`.cjs` and forcing ESM
+ *   breaks their default-export detection, so they are left to Bun's default path.
+ * - **Dev runs only.** In the compiled `prometheus` binary every module is pre-bundled
+ *   into bunfs, so `onLoad` never fires; profile with a `bun --preload` dev run.
+ */
+import { plugin } from "bun";
+import { moduleLoadBuffer } from "./timing-buffer";
+
+// Restrict to TS/TSX only. node_modules ships CommonJS `.js`/`.cjs` that Bun
+// auto-detects when loaded via its default path; if we intercept and return
+// `{ contents, loader: "js" }`, Bun forces ESM and CJS modules fail to load
+// (e.g. `Missing 'default' export`). Our own source tree (where the interesting
+// timing lives) is uniformly TypeScript, so a TS-only filter is both safe and
+// sufficient.
+const MODULE_LOADER_FILTER = /\.[mc]?tsx?$/;
+const MODULE_COMPLETE_KEY: symbol = Symbol.for("prometheus.moduleLoadComplete");
+const MODULE_BODY_START_KEY: symbol = Symbol.for("prometheus.moduleBodyStart");
+const STATIC_IMPORT_PATTERN =
+	/\b(?:import|export)\s+(?:type\s+)?(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+type CompleteStore = Record<symbol, ((path: string) => void) | undefined>;
+
+function bodyStartMarker(path: string): string {
+	return `;globalThis[Symbol.for("prometheus.moduleBodyStart")]?.(${JSON.stringify(path)});\n`;
+}
+
+function completionMarker(path: string): string {
+	return `\n;globalThis[Symbol.for("prometheus.moduleLoadComplete")]?.(${JSON.stringify(path)});\n`;
+}
+
+function instrumentContents(path: string, contents: string): string {
+	const start = bodyStartMarker(path);
+	const end = completionMarker(path);
+	if (!contents.startsWith("#!")) return `${start}${contents}${end}`;
+	const newline = contents.indexOf("\n");
+	if (newline === -1) return `${contents}\n${start}${end}`;
+	return `${contents.slice(0, newline + 1)}${start}${contents.slice(newline + 1)}${end}`;
+}
+function importerDir(importer: string): string {
+	const slash = importer.lastIndexOf("/");
+	if (slash === -1) return ".";
+	return importer.slice(0, slash);
+}
+
+function childSetFor(importsByPath: Map<string, Set<string>>, path: string): Set<string> {
+	let children = importsByPath.get(path);
+	if (!children) {
+		children = new Set<string>();
+		importsByPath.set(path, children);
+	}
+	return children;
+}
+
+function addImportEdges(importsByPath: Map<string, Set<string>>, importer: string, contents: string): void {
+	STATIC_IMPORT_PATTERN.lastIndex = 0;
+	for (const match of contents.matchAll(STATIC_IMPORT_PATTERN)) {
+		const specifier = match[1] ?? match[2];
+		if (!specifier) continue;
+		try {
+			const resolved = Bun.resolveSync(specifier, importerDir(importer));
+			if (MODULE_LOADER_FILTER.test(resolved) && resolved !== importer) {
+				childSetFor(importsByPath, importer).add(resolved);
+			}
+		} catch {
+			// Leave Bun's real resolver/runtime to surface any error. This scanner is only an observer.
+		}
+	}
+}
+
+if (process.env.PROMETHEUS_TIMING) {
+	const buffer = moduleLoadBuffer();
+	const starts = new Map<string, number>();
+	const bodyStarts = new Map<string, number>();
+	const importsByPath = new Map<string, Set<string>>();
+	const store = globalThis as unknown as CompleteStore;
+	store[MODULE_BODY_START_KEY] = (path: string): void => {
+		bodyStarts.set(path, performance.now());
+	};
+	store[MODULE_COMPLETE_KEY] = (path: string): void => {
+		const start = starts.get(path);
+		if (start === undefined) return;
+		starts.delete(path);
+		const end = performance.now();
+		const bodyStart = bodyStarts.get(path);
+		bodyStarts.delete(path);
+		const imports = importsByPath.get(path);
+		buffer.push({
+			path,
+			start,
+			durationMs: end - start,
+			bodyMs: bodyStart === undefined ? undefined : end - bodyStart,
+			imports: imports ? [...imports] : [],
+		});
+	};
+
+	plugin({
+		name: "pi-module-load-timer",
+		setup(build) {
+			build.onLoad({ filter: MODULE_LOADER_FILTER }, async args => {
+				starts.set(args.path, performance.now());
+				childSetFor(importsByPath, args.path);
+				const contents = await Bun.file(args.path).text();
+				addImportEdges(importsByPath, args.path, contents);
+				return {
+					contents: instrumentContents(args.path, contents),
+					loader: args.path.endsWith(".tsx") ? "tsx" : "ts",
+				};
+			});
+		},
+	});
+}

package/src/path-tree.ts

@@ -0,0 +1,147 @@
+/**
+ * Multi-level path tree shared by grouped file listings (find / grep / ast tools)
+ * and compaction file-operation lists.
+ *
+ * Flat path lists used to group by the *immediate* parent directory and print the
+ * full directory path in every header. For results spread across a deep tree — or
+ * rooted outside cwd, where paths stay absolute — that repeated the shared prefix
+ * on every line. The tree below folds single-child directory chains (so the common
+ * prefix collapses into one header) and nests the rest, charging the model one
+ * token per path segment instead of one per file.
+ */
+
+const URL_LIKE_PATH_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** True for `scheme://…` entries that have no meaningful directory structure. */
+export function isUrlLikePath(filePath: string): boolean {
+	return URL_LIKE_PATH_RE.test(filePath);
+}
+
+export interface PathTreeNode {
+	/** Direct file leaves, in first-seen order. */
+	files: Array<{ name: string; key: string }>;
+	/** Dedup set for `files` (a glob can surface the same path twice on retry). */
+	fileNames: Set<string>;
+	/** Child directories, in first-seen order. */
+	subdirs: Array<{ name: string; node: PathTreeNode }>;
+	/** Dedup index for `subdirs`. */
+	dirIndex: Map<string, PathTreeNode>;
+}
+
+export interface PathTreeInput {
+	/** Path string; absolute, cwd-relative, or url-like. Backslashes are normalized. */
+	path: string;
+	/** Whether the leaf itself is a directory (trailing-slash match from find). */
+	isDir: boolean;
+	/** Opaque key carried onto file events for section lookup. Defaults to `path`. */
+	key?: string;
+}
+
+/** One node emitted while walking the tree: a folded directory or a file leaf. */
+export interface GroupedTreeEvent {
+	kind: "dir" | "file";
+	/** 0-based nesting depth (root children are depth 0). */
+	depth: number;
+	/** Folded chain for dirs (e.g. `a/b/c`, no trailing slash); basename for files. */
+	name: string;
+	/** File key for `kind === "file"`; empty string for directories. */
+	key: string;
+}
+
+function createNode(): PathTreeNode {
+	return { files: [], fileNames: new Set(), subdirs: [], dirIndex: new Map() };
+}
+
+function addFile(node: PathTreeNode, name: string, key: string): void {
+	if (node.fileNames.has(name)) return;
+	node.fileNames.add(name);
+	node.files.push({ name, key });
+}
+
+/**
+ * Build a directory tree from a flat list of paths. URL-like entries are kept
+ * whole as root-level file leaves (they have no meaningful directory structure).
+ * Absolute paths carry a leading empty segment so they share a common `/` root
+ * and fold like any other prefix.
+ */
+export function buildPathTree(entries: Iterable<PathTreeInput>): PathTreeNode {
+	const root = createNode();
+	for (const { path: rawPath, isDir, key } of entries) {
+		const normalized = rawPath.replace(/\\/g, "/");
+		const fileKey = key ?? rawPath;
+		if (isUrlLikePath(normalized)) {
+			addFile(root, normalized, fileKey);
+			continue;
+		}
+		const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+		if (trimmed.length === 0) continue;
+		const segments = trimmed.split("/");
+		const dirCount = isDir ? segments.length : segments.length - 1;
+		let node = root;
+		for (let i = 0; i < dirCount; i++) {
+			const segment = segments[i]!;
+			let child = node.dirIndex.get(segment);
+			if (!child) {
+				child = createNode();
+				node.dirIndex.set(segment, child);
+				node.subdirs.push({ name: segment, node: child });
+			}
+			node = child;
+		}
+		if (!isDir) {
+			addFile(node, segments[segments.length - 1]!, fileKey);
+		}
+	}
+	return root;
+}
+
+/**
+ * Depth-first walk yielding directory and file events. Directories collapse their
+ * single-child chains (`a` → `a/b` → `a/b/c`) so a shared prefix becomes one
+ * header. Each node's direct files are emitted before its subdirectories, keeping
+ * a file unambiguously attached to the header above it.
+ */
+export function* walkPathTree(node: PathTreeNode, depth = 0): Generator<GroupedTreeEvent> {
+	for (const file of node.files) {
+		yield { kind: "file", depth, name: file.name, key: file.key };
+	}
+	for (const subdir of node.subdirs) {
+		let dirNode = subdir.node;
+		const parts = [subdir.name];
+		while (dirNode.files.length === 0 && dirNode.subdirs.length === 1) {
+			const only = dirNode.subdirs[0]!;
+			parts.push(only.name);
+			dirNode = only.node;
+		}
+		yield { kind: "dir", depth, name: parts.join("/"), key: "" };
+		yield* walkPathTree(dirNode, depth + 1);
+	}
+}
+
+/**
+ * Render a flat path list as a grouped, prefix-folded directory tree without
+ * per-file bodies (find-tool output shape, also used by compaction `<files>`
+ * lists). Single-child directory chains fold into one header (`# a/b/c/`),
+ * each level adds one `#`, and files are listed bare under the deepest
+ * directory header that owns them. Trailing-slash entries are directory
+ * leaves and keep their slash in the header.
+ *
+ * `annotate` receives each file's full original path and its return value is
+ * appended verbatim to the file line (e.g. ` (RW)`).
+ *
+ * Order follows the input: a directory appears when its first member is
+ * emitted, and a node's own files precede its subdirectories.
+ */
+export function formatGroupedPaths(paths: readonly string[], annotate?: (path: string) => string): string {
+	if (paths.length === 0) return "";
+	const tree = buildPathTree(paths.map(entry => ({ path: entry, isDir: entry.endsWith("/") })));
+	const lines: string[] = [];
+	for (const event of walkPathTree(tree)) {
+		if (event.kind === "dir") {
+			lines.push(`${"#".repeat(event.depth + 1)} ${event.name}/`);
+		} else {
+			lines.push(annotate ? `${event.name}${annotate(event.key)}` : event.name);
+		}
+	}
+	return lines.join("\n");
+}

package/src/procmgr.ts

@@ -16,7 +16,7 @@ let cachedShellConfig: ShellConfig | null = null;
 /**
  * Check if a shell binary is executable.
  */
-function isExecutable(path: string): boolean {
+export function isExecutable(path: string): boolean {
 	try {
 		fs.accessSync(path, fs.constants.X_OK);
 		return true;

package/src/runtime-install.ts

@@ -0,0 +1,372 @@
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as Module from "node:module";
+import * as path from "node:path";
+
+/**
+ * On-demand runtime dependency support for native-heavy optional packages
+ * (Transformers.js, fastembed) that are never bundled into the CLI or the
+ * compiled binary. Consumers `bun install` a pinned dependency set into a
+ * cache directory on first use ({@link ensureRuntimeInstalled}) and load the
+ * entrypoint via `createRequire`.
+ *
+ * Bun's compiled-binary module resolver only finds `<pkg>/index.js` for bare
+ * specifiers loaded from the *real* filesystem — it ignores `main`/`exports`
+ * (issue #1763). Runtime-installed graphs (`@huggingface/transformers` →
+ * `onnxruntime-node` → `onnxruntime-common`, `fastembed` →
+ * `@anush008/tokenizers` → platform binding) all point `main`/`exports` at
+ * nested files, so the stock resolver cannot load any of them. We patch
+ * `Module._resolveFilename` to resolve those bare specifiers against the
+ * registered runtime caches ourselves, honoring `main`/`exports`.
+ *
+ * This module is filesystem-pure aside from {@link installRuntimeModuleResolver}
+ * mutating the `node:module` resolver, so the resolution logic is unit-testable
+ * without a compiled binary.
+ */
+
+/** Conditions honored when resolving an `exports` map for a CommonJS `require`. */
+const RUNTIME_CONDITIONS: Record<string, true> = { node: true, require: true, default: true };
+
+/** Extension probes appended to a `main`/`exports` target that lacks one. */
+const RUNTIME_EXTENSIONS: readonly string[] = [".js", ".cjs", ".mjs", ".json", ".node"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Walk a conditional `exports` target (string, array of fallbacks, or a
+ * condition object) and return the first relative path that matches a runtime
+ * condition in declaration order. Returns `null` when nothing applies (e.g.
+ * an `import`-only entry).
+ */
+export function selectConditionalTarget(target: unknown): string | null {
+	if (typeof target === "string") return target;
+	if (Array.isArray(target)) {
+		for (const entry of target) {
+			const resolved = selectConditionalTarget(entry);
+			if (resolved) return resolved;
+		}
+		return null;
+	}
+	if (isRecord(target)) {
+		for (const condition in target) {
+			if (!RUNTIME_CONDITIONS[condition]) continue;
+			const resolved = selectConditionalTarget(target[condition]);
+			if (resolved) return resolved;
+		}
+	}
+	return null;
+}
+
+/** Resolve a relative target inside a package to a concrete file path, probing extensions and `index`. */
+function resolveFileTarget(pkgDir: string, relative: string): string | null {
+	const base = path.join(pkgDir, relative);
+	const candidates = [base, ...RUNTIME_EXTENSIONS.map(ext => base + ext)];
+	for (const candidate of candidates) {
+		try {
+			const stat = fs.statSync(candidate);
+			if (stat.isFile()) return candidate;
+			if (stat.isDirectory()) {
+				const indexed = resolveFileTarget(candidate, "index");
+				if (indexed) return indexed;
+			}
+		} catch {
+			// missing candidate — keep probing
+		}
+	}
+	return null;
+}
+
+function resolveExportsEntry(
+	pkgDir: string,
+	exports: Record<string, unknown>,
+	subpath: string | undefined,
+): string | null {
+	let subpathMap = false;
+	for (const key in exports) {
+		subpathMap = key === "." || key.startsWith("./");
+		break;
+	}
+	if (subpathMap) {
+		const key = subpath ? `./${subpath}` : ".";
+		if (!(key in exports)) return null;
+		const target = selectConditionalTarget(exports[key]);
+		return target ? resolveFileTarget(pkgDir, target) : null;
+	}
+	// A bare condition map only describes the package root, so a subpath
+	// request falls through to plain path joining at the call site.
+	if (subpath) return null;
+	const target = selectConditionalTarget(exports);
+	return target ? resolveFileTarget(pkgDir, target) : null;
+}
+
+/**
+ * Split a bare specifier into its package name and optional subpath, handling
+ * scoped packages (`@scope/name/sub` → `@scope/name` + `sub`).
+ */
+export function splitBareSpecifier(specifier: string): { packageName: string; subpath: string | undefined } {
+	const segments = specifier.split("/");
+	const take = specifier.startsWith("@") ? 2 : 1;
+	const packageName = segments.slice(0, take).join("/");
+	const subpath = segments.length > take ? segments.slice(take).join("/") : undefined;
+	return { packageName, subpath };
+}
+
+/**
+ * Resolve a bare specifier against an installed `node_modules` directory,
+ * honoring `exports` (CommonJS conditions), then `main`, then `index.js`.
+ * Returns an absolute file path, or `null` when the package/entry is absent.
+ */
+export function resolveRuntimeModule(runtimeNodeModules: string, specifier: string): string | null {
+	const { packageName, subpath } = splitBareSpecifier(specifier);
+	const pkgDir = path.join(runtimeNodeModules, ...packageName.split("/"));
+	const manifest = readManifest(pkgDir);
+	if (!manifest) return subpath ? resolveFileTarget(pkgDir, subpath) : null;
+
+	const { exports } = manifest;
+	if (typeof exports === "string" || isRecord(exports)) {
+		const map = typeof exports === "string" ? { ".": exports } : exports;
+		const resolved = resolveExportsEntry(pkgDir, map, subpath);
+		if (resolved) return resolved;
+	}
+	if (subpath) return resolveFileTarget(pkgDir, subpath);
+	if (typeof manifest.main === "string") {
+		const resolved = resolveFileTarget(pkgDir, manifest.main);
+		if (resolved) return resolved;
+	}
+	return resolveFileTarget(pkgDir, "index.js");
+}
+
+function readManifest(pkgDir: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+		return isRecord(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+interface ModuleResolver {
+	_resolveFilename(request: string, parent: unknown, isMain: boolean, options?: unknown): string;
+}
+
+interface ResolverRegistration {
+	runtimeNodeModules: string;
+	stubs: Record<string, string>;
+}
+
+const REGISTRY = Symbol.for("prometheus.runtimeModuleResolver.registry");
+const PATCHED = Symbol.for("prometheus.runtimeModuleResolver.patched");
+
+/**
+ * The registration list lives on `globalThis` so a bundled copy and a
+ * source copy of this module in one process share the same registry — the
+ * resolver is patched once per process, and the patched closure must see
+ * every registration.
+ */
+function resolverRegistry(): ResolverRegistration[] {
+	const holder = globalThis as { [REGISTRY]?: ResolverRegistration[] };
+	holder[REGISTRY] ??= [];
+	return holder[REGISTRY];
+}
+function pathContains(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function parentFilename(parent: unknown): string | null {
+	if (!isRecord(parent)) return null;
+	const filename = parent.filename;
+	return typeof filename === "string" ? filename : null;
+}
+
+export interface RuntimeResolverOptions {
+	/** Absolute path to the runtime cache's `node_modules`. */
+	runtimeNodeModules: string;
+	/** Bare specifier → absolute file path overrides (e.g. `sharp` → no-op stub). */
+	stubs?: Record<string, string>;
+}
+
+/**
+ * Patch `node:module`'s resolver (idempotently) so bare specifiers that the
+ * stock compiled-binary resolver cannot find fall back to the registered
+ * runtime caches. Stock resolution is tried first and kept for anything
+ * outside the registered roots (bundled imports, node builtins, host or
+ * extension trees). Multiple runtime roots may register; they are consulted
+ * in registration order.
+ *
+ * One stock "success" is distrusted: the compiled-binary resolver ignores
+ * `main`/`exports` for real-FS packages (Bun #1763), so a package shipping
+ * its TS source next to `dist/` (e.g. `@huggingface/hub`'s root `index.ts`)
+ * resolves to the wrong file. When the stock hit lands inside a registered
+ * runtime root, the manifest-aware resolution wins.
+ */
+export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }: RuntimeResolverOptions): void {
+	const registry = resolverRegistry();
+	const existing = registry.find(entry => entry.runtimeNodeModules === runtimeNodeModules);
+	if (existing) Object.assign(existing.stubs, stubs);
+	else registry.push({ runtimeNodeModules, stubs: { ...stubs } });
+
+	const resolver = (Module as unknown as { default?: ModuleResolver } & ModuleResolver).default ?? Module;
+	const target = resolver as unknown as ModuleResolver & { [PATCHED]?: boolean };
+	if (target[PATCHED]) return;
+	const original = target._resolveFilename.bind(target);
+	target._resolveFilename = (request: string, parent: unknown, isMain: boolean, options?: unknown): string => {
+		let stockResolved: string | null = null;
+		let stockError: unknown;
+		try {
+			stockResolved = original(request, parent, isMain, options);
+		} catch (error) {
+			stockError = error;
+		}
+		const bare = !request.startsWith(".") && !request.startsWith("node:") && !path.isAbsolute(request);
+		if (bare) {
+			const parentFile = parentFilename(parent);
+			for (const registration of resolverRegistry()) {
+				const parentInRuntime = parentFile !== null && pathContains(registration.runtimeNodeModules, parentFile);
+				if (parentInRuntime) {
+					const stub = registration.stubs[request];
+					if (stub) return stub;
+					if (!stockResolved || !pathContains(registration.runtimeNodeModules, stockResolved)) {
+						const fallback = resolveRuntimeModule(registration.runtimeNodeModules, request);
+						if (fallback) return fallback;
+					}
+				}
+				if (stockResolved) {
+					// Correct a stock hit only inside the top-level package the
+					// request names. A hit in a nested node_modules (e.g. tar's
+					// minizlib resolving its own minipass@3 under
+					// <root>/minizlib/node_modules/) is version-correct — overriding
+					// it with the top-level instance would cross major versions.
+					const { packageName } = splitBareSpecifier(request);
+					const pkgDir = path.join(registration.runtimeNodeModules, ...packageName.split("/"));
+					if (!stockResolved.startsWith(pkgDir + path.sep)) continue;
+					if (path.relative(pkgDir, stockResolved).split(path.sep).includes("node_modules")) continue;
+					const expected = resolveRuntimeModule(registration.runtimeNodeModules, request);
+					if (expected) return expected;
+				} else {
+					const stub = registration.stubs[request];
+					if (stub) return stub;
+					const fallback = resolveRuntimeModule(registration.runtimeNodeModules, request);
+					if (fallback) return fallback;
+				}
+			}
+		}
+		if (stockResolved) return stockResolved;
+		throw stockError;
+	};
+	target[PATCHED] = true;
+}
+
+/** Pinned dependency set materialized into a runtime cache directory. */
+export interface RuntimeInstallSpec {
+	dependencies: Record<string, string>;
+	/** Version pins forced across the whole runtime tree (bun `overrides`), e.g. dislodging a transitive dep. */
+	overrides?: Record<string, string>;
+	/** Packages whose lifecycle scripts bun may run during the install. */
+	trustedDependencies?: string[];
+}
+
+export type RuntimeInstallPhase = "initiate" | "download" | "done";
+
+export interface EnsureRuntimeInstalledOptions {
+	/** Directory owning the runtime `package.json` + `node_modules`. */
+	runtimeDir: string;
+	install: RuntimeInstallSpec;
+	/** Package whose installed manifest marks the runtime complete; defaults to the first dependency. */
+	probePackage?: string;
+	/** Phase notifications (progress UI); not emitted when already installed. */
+	onPhase?: (phase: RuntimeInstallPhase) => void;
+	lockAttempts?: number;
+	lockSleepMs?: number;
+}
+
+function isErrnoCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+async function acquireInstallLock(runtimeDir: string, attempts: number, sleepMs: number): Promise<() => Promise<void>> {
+	const lockDir = `${runtimeDir}.lock`;
+	await fsp.mkdir(path.dirname(lockDir), { recursive: true });
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		try {
+			await fsp.mkdir(lockDir);
+			return async () => {
+				await fsp.rm(lockDir, { recursive: true, force: true });
+			};
+		} catch (error) {
+			if (!isErrnoCode(error, "EEXIST")) throw error;
+			await Bun.sleep(sleepMs);
+		}
+	}
+	throw new Error(`Timed out waiting for runtime install lock: ${lockDir}`);
+}
+
+export async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
+	await fsp.mkdir(runtimeDir, { recursive: true });
+	const manifest: Record<string, unknown> = {
+		private: true,
+		type: "module",
+		dependencies: install.dependencies,
+	};
+	if (install.overrides && Object.keys(install.overrides).length) manifest.overrides = install.overrides;
+	if (install.trustedDependencies?.length) manifest.trustedDependencies = install.trustedDependencies;
+	await Bun.write(path.join(runtimeDir, "package.json"), `${JSON.stringify(manifest, null, "\t")}\n`);
+}
+
+async function readPipe(stream: ReadableStream<Uint8Array> | null): Promise<string> {
+	if (!stream) return "";
+	return new Response(stream).text();
+}
+
+async function runRuntimeInstall(runtimeDir: string): Promise<void> {
+	// `process.execPath` is plain bun in source/bundle mode and the compiled
+	// binary otherwise; BUN_BE_BUN makes the compiled binary act as bun.
+	const proc = Bun.spawn([process.execPath, "install", "--cwd", runtimeDir, "--production"], {
+		env: { ...Bun.env, BUN_BE_BUN: "1" },
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		readPipe(proc.stdout as ReadableStream<Uint8Array> | null),
+		readPipe(proc.stderr as ReadableStream<Uint8Array> | null),
+		proc.exited,
+	]);
+	if (exitCode === 0) return;
+	const output = `${stdout}\n${stderr}`.trim();
+	throw new Error(
+		`Failed to install runtime at ${runtimeDir} with ${process.execPath} install (exit ${exitCode}): ${output}`,
+	);
+}
+
+/**
+ * Materialize a pinned dependency set into `runtimeDir` (idempotent,
+ * cross-process safe via a lock directory). Returns `runtimeDir`.
+ */
+export async function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string> {
+	const { runtimeDir, install, onPhase, lockAttempts = 240, lockSleepMs = 250 } = options;
+	let probePackage = options.probePackage;
+	if (!probePackage) {
+		for (const name in install.dependencies) {
+			probePackage = name;
+			break;
+		}
+	}
+	if (!probePackage) throw new Error(`Runtime install at ${runtimeDir} declares no dependencies`);
+	const probeManifest = Bun.file(path.join(runtimeDir, "node_modules", ...probePackage.split("/"), "package.json"));
+	if (await probeManifest.exists()) return runtimeDir;
+
+	onPhase?.("initiate");
+	const releaseLock = await acquireInstallLock(runtimeDir, lockAttempts, lockSleepMs);
+	try {
+		if (await probeManifest.exists()) return runtimeDir;
+		await writeRuntimeManifest(runtimeDir, install);
+		onPhase?.("download");
+		await runRuntimeInstall(runtimeDir);
+		onPhase?.("done");
+		return runtimeDir;
+	} finally {
+		await releaseLock();
+	}
+}