@xopcai/xopc 0.0.190 → 0.0.192

package/dist/src/runtime-tools/catalog.js

@@ -0,0 +1,59 @@
+//#region src/runtime-tools/catalog.ts
+const RUNTIME_CATALOG_VERSION = "2026-08-23";
+const DEFAULT_RUNTIME_VERSIONS = {
+	node: "22.23.2",
+	uv: "0.8.12",
+	python: "3.12.11"
+};
+function detectRuntimePlatform(platform = process.platform, arch = process.arch) {
+	if (platform === "darwin" && arch === "arm64") return "darwin-arm64";
+	if (platform === "darwin" && arch === "x64") return "darwin-x64";
+	if (platform === "win32" && arch === "x64") return "win32-x64";
+	if (platform === "linux" && arch === "x64") return "linux-x64-gnu";
+	if (platform === "linux" && arch === "arm64") return "linux-arm64-gnu";
+	return null;
+}
+function nodePlatformSuffix(platform) {
+	return {
+		"darwin-arm64": "darwin-arm64",
+		"darwin-x64": "darwin-x64",
+		"win32-x64": "win-x64",
+		"linux-x64-gnu": "linux-x64",
+		"linux-arm64-gnu": "linux-arm64"
+	}[platform];
+}
+function uvPlatformSuffix(platform) {
+	return {
+		"darwin-arm64": "aarch64-apple-darwin",
+		"darwin-x64": "x86_64-apple-darwin",
+		"win32-x64": "x86_64-pc-windows-msvc",
+		"linux-x64-gnu": "x86_64-unknown-linux-gnu",
+		"linux-arm64-gnu": "aarch64-unknown-linux-gnu"
+	}[platform];
+}
+function resolveRuntimeAsset(params) {
+	if (params.runtime === "node") {
+		const ext = params.platform === "win32-x64" ? "zip" : "tar.gz";
+		const archiveFile = `node-v${params.version}-${nodePlatformSuffix(params.platform)}.${ext}`;
+		const releaseBase = `https://nodejs.org/download/release/v${params.version}`;
+		return {
+			...params,
+			archiveFile,
+			url: `${releaseBase}/${archiveFile}`,
+			checksumUrl: `${releaseBase}/SHASUMS256.txt`,
+			archiveType: ext
+		};
+	}
+	const ext = params.platform === "win32-x64" ? "zip" : "tar.gz";
+	const archiveFile = `uv-${uvPlatformSuffix(params.platform)}.${ext}`;
+	const base = `https://github.com/astral-sh/uv/releases/download/${params.version}`;
+	return {
+		...params,
+		archiveFile,
+		url: `${base}/${archiveFile}`,
+		checksumUrl: `${base}/${archiveFile}.sha256`,
+		archiveType: ext
+	};
+}
+//#endregion
+export { DEFAULT_RUNTIME_VERSIONS, RUNTIME_CATALOG_VERSION, detectRuntimePlatform, resolveRuntimeAsset };

package/dist/src/runtime-tools/command.d.ts

@@ -0,0 +1,15 @@
+export interface RuntimeCommandResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+}
+export declare function runRuntimeCommand(params: {
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<RuntimeCommandResult>;

package/dist/src/runtime-tools/command.js

@@ -0,0 +1,59 @@
+import { spawn } from "node:child_process";
+//#region src/runtime-tools/command.ts
+const DEFAULT_COMMAND_TIMEOUT_MS = 5e3;
+async function runRuntimeCommand(params) {
+	return await new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timedOut = false;
+		let aborted = false;
+		const child = spawn(params.command, params.args, {
+			env: params.env,
+			shell: false,
+			windowsHide: process.platform === "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		const finish = (exitCode) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			params.signal?.removeEventListener("abort", abort);
+			resolve({
+				ok: exitCode === 0 && !timedOut && !aborted,
+				stdout: stdout.trim(),
+				stderr: stderr.trim(),
+				exitCode,
+				timedOut,
+				aborted
+			});
+		};
+		const abort = () => {
+			aborted = true;
+			child.kill("SIGKILL");
+			finish(null);
+		};
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", () => finish(null));
+		child.once("close", finish);
+		const timeout = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGKILL");
+			finish(null);
+		}, params.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+		timeout.unref();
+		if (params.signal?.aborted) abort();
+		else params.signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+//#endregion
+export { runRuntimeCommand };

package/dist/src/runtime-tools/download-source.d.ts

@@ -0,0 +1,24 @@
+import type { RuntimeToolsConfig } from '../config/schema.js';
+import type { RuntimeAsset, RuntimePlatform } from './catalog.js';
+type DownloadConfig = RuntimeToolsConfig['download'];
+export interface ResolvedRuntimeDownload {
+    url: string;
+    sha256: string;
+    source: 'website' | 'direct';
+}
+export declare function runtimeGatewayPythonMirror(gatewayBaseUrl: string): string;
+export declare function canFallbackPythonInstall(output: string, timedOut: boolean): boolean;
+export declare function validateGatewayDescriptor(params: {
+    value: unknown;
+    gatewayBaseUrl: string;
+    asset: RuntimeAsset;
+    platform: RuntimePlatform;
+}): ResolvedRuntimeDownload;
+export declare function resolveRuntimeDownloadSource(params: {
+    asset: RuntimeAsset;
+    platform: RuntimePlatform;
+    config: DownloadConfig;
+    signal?: AbortSignal;
+    onFallback?: (message: string) => void;
+}): Promise<ResolvedRuntimeDownload>;
+export {};

package/dist/src/runtime-tools/download-source.js

@@ -0,0 +1,125 @@
+import { RuntimeError } from "./errors.js";
+import { fetchRuntimeResource, readRuntimeResponseText } from "./network.js";
+import { resolveExpectedChecksum } from "./downloader.js";
+//#region src/runtime-tools/download-source.ts
+const MAX_GATEWAY_RESPONSE_BYTES = 64 * 1024;
+function runtimeGatewayPythonMirror(gatewayBaseUrl) {
+	return `${gatewayBaseUrl.replace(/\/+$/, "")}/python-build-standalone`;
+}
+function canFallbackPythonInstall(output, timedOut) {
+	if (/checksum|digest|hash mismatch|integrity|verification failed|invalid archive/i.test(output)) return false;
+	return timedOut || /failed to download|request failed|error sending request|timed? out|connection|dns|429|50[234]/i.test(output);
+}
+var GatewayResolveError = class extends Error {
+	constructor(message, allowsDirectFallback, retrySameSource = allowsDirectFallback) {
+		super(message);
+		this.allowsDirectFallback = allowsDirectFallback;
+		this.retrySameSource = retrySameSource;
+	}
+};
+function descriptorUrl(baseUrl, asset, platform) {
+	const url = new URL(`${baseUrl.replace(/\/+$/, "")}/resolve`);
+	url.searchParams.set("runtime", asset.runtime);
+	url.searchParams.set("version", asset.version);
+	url.searchParams.set("platform", platform);
+	return url;
+}
+function validateGatewayDescriptor(params) {
+	const value = params.value;
+	const archive = value?.archive;
+	if (value?.schemaVersion !== 1 || value.runtime !== params.asset.runtime || value.version !== params.asset.version || value.platform !== params.platform || archive?.name !== params.asset.archiveFile || archive.archiveType !== params.asset.archiveType || typeof archive.url !== "string" || typeof archive.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(archive.sha256)) throw new GatewayResolveError("Runtime gateway returned an invalid descriptor", false);
+	const base = new URL(`${params.gatewayBaseUrl.replace(/\/+$/, "")}/`);
+	const artifact = new URL(archive.url);
+	const expectedPath = `${base.pathname}artifacts/${params.asset.runtime}/${params.asset.version}/${params.platform}/${params.asset.archiveFile}`;
+	if (artifact.origin !== base.origin || artifact.username || artifact.password || artifact.pathname !== expectedPath || artifact.search || artifact.hash) throw new GatewayResolveError("Runtime gateway returned an untrusted artifact URL", false);
+	return {
+		url: artifact.href,
+		sha256: archive.sha256,
+		source: "website"
+	};
+}
+async function resolveFromGateway(params) {
+	let lastError;
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		if (params.signal?.aborted) throw params.signal.reason;
+		try {
+			const response = await fetchRuntimeResource({
+				url: descriptorUrl(params.config.gatewayBaseUrl, params.asset, params.platform).href,
+				timeoutMs: params.config.timeoutMs,
+				proxy: params.config.proxy,
+				signal: params.signal,
+				init: {
+					headers: { "User-Agent": "xopc-runtime-manager/1" },
+					redirect: "error"
+				}
+			});
+			const declaredSize = Number(response.headers.get("content-length"));
+			if (Number.isFinite(declaredSize) && declaredSize > MAX_GATEWAY_RESPONSE_BYTES) {
+				await response.body?.cancel().catch(() => {});
+				throw new GatewayResolveError("Runtime gateway response exceeds the size limit", false);
+			}
+			let responseText;
+			try {
+				responseText = await readRuntimeResponseText(response, MAX_GATEWAY_RESPONSE_BYTES);
+			} catch {
+				throw new GatewayResolveError("Runtime gateway response exceeds the size limit", false);
+			}
+			if (!response.ok) {
+				let body = null;
+				try {
+					body = JSON.parse(responseText);
+				} catch {}
+				const unsupported = response.status === 404 && body?.error === "unsupported_catalog_entry";
+				const retryable = unsupported || response.status === 429 || response.status >= 500;
+				throw new GatewayResolveError(`Runtime gateway returned HTTP ${response.status}`, retryable, !unsupported && retryable);
+			}
+			let descriptor;
+			try {
+				descriptor = JSON.parse(responseText);
+			} catch {
+				throw new GatewayResolveError("Runtime gateway returned invalid JSON", false);
+			}
+			return validateGatewayDescriptor({
+				value: descriptor,
+				gatewayBaseUrl: params.config.gatewayBaseUrl,
+				asset: params.asset,
+				platform: params.platform
+			});
+		} catch (error) {
+			if (params.signal?.aborted) throw error;
+			const normalized = error instanceof GatewayResolveError ? error : new GatewayResolveError(error instanceof Error ? error.message : String(error), true);
+			if (!normalized.allowsDirectFallback) throw normalized;
+			lastError = normalized;
+			if (!normalized.retrySameSource) break;
+			if (attempt === 0) await new Promise((resolve) => setTimeout(resolve, 500));
+		}
+	}
+	throw lastError ?? new GatewayResolveError("Runtime gateway is unavailable", true);
+}
+async function resolveDirect(asset, config, signal) {
+	const sha256 = await resolveExpectedChecksum({
+		runtime: asset.runtime,
+		checksumUrl: asset.checksumUrl,
+		archiveFile: asset.archiveFile,
+		timeoutMs: config.timeoutMs,
+		proxy: config.proxy,
+		signal
+	});
+	return {
+		url: asset.url,
+		sha256,
+		source: "direct"
+	};
+}
+async function resolveRuntimeDownloadSource(params) {
+	if (params.config.source === "direct-only") return await resolveDirect(params.asset, params.config, params.signal);
+	try {
+		return await resolveFromGateway(params);
+	} catch (error) {
+		if (params.config.source === "website-only" || !(error instanceof GatewayResolveError) || !error.allowsDirectFallback) throw new RuntimeError(`Failed to resolve ${params.asset.runtime} from the runtime gateway: ${error instanceof Error ? error.message : String(error)}`, "RUNTIME_DOWNLOAD_FAILED", params.asset.runtime, "resolve_gateway", true, [], { cause: error });
+		params.onFallback?.(`Runtime gateway unavailable; downloading ${params.asset.runtime} directly`);
+		return await resolveDirect(params.asset, params.config, params.signal);
+	}
+}
+//#endregion
+export { canFallbackPythonInstall, resolveRuntimeDownloadSource, runtimeGatewayPythonMirror, validateGatewayDescriptor };

package/dist/src/runtime-tools/downloader.d.ts

@@ -0,0 +1,21 @@
+import type { RuntimeKind } from './types.js';
+export declare function canFallbackRuntimeDownload(error: unknown): boolean;
+export declare function resolveExpectedChecksum(params: {
+    runtime: 'node' | 'uv';
+    checksumUrl: string;
+    archiveFile: string;
+    timeoutMs: number;
+    proxy?: string;
+    signal?: AbortSignal;
+}): Promise<string>;
+export declare function sha256File(path: string): Promise<string>;
+export declare function downloadVerifiedArchive(params: {
+    runtime: RuntimeKind;
+    url: string;
+    targetPath: string;
+    expectedSha256: string;
+    timeoutMs: number;
+    proxy?: string;
+    signal?: AbortSignal;
+    onProgress?: (downloadedBytes: number, totalBytes?: number) => void;
+}): Promise<string>;

package/dist/src/runtime-tools/downloader.js

@@ -0,0 +1,137 @@
+import { RuntimeError } from "./errors.js";
+import { fetchRuntimeResource, readRuntimeResponseText } from "./network.js";
+import { dirname } from "node:path";
+import { createReadStream, createWriteStream } from "node:fs";
+import { createHash } from "node:crypto";
+import { access, mkdir, rename, rm, stat } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+//#region src/runtime-tools/downloader.ts
+const MAX_ARCHIVE_BYTES = 500 * 1024 * 1024;
+const MAX_CHECKSUM_BYTES = 1024 * 1024;
+var RuntimeDownloadTransportError = class extends Error {
+	constructor(message, allowsSourceFallback, options) {
+		super(message, options);
+		this.allowsSourceFallback = allowsSourceFallback;
+	}
+};
+var RuntimeDownloadContentError = class extends Error {};
+function canFallbackRuntimeDownload(error) {
+	return error instanceof RuntimeError && error.code === "RUNTIME_DOWNLOAD_FAILED" && error.cause instanceof RuntimeDownloadTransportError && error.cause.allowsSourceFallback;
+}
+async function fetchText(url, timeoutMs, proxy, signal) {
+	const response = await fetchRuntimeResource({
+		url,
+		timeoutMs,
+		proxy,
+		signal,
+		init: { redirect: "follow" }
+	});
+	if (!response.ok) {
+		await response.body?.cancel().catch(() => {});
+		throw new Error(`HTTP ${response.status} for ${url}`);
+	}
+	const declaredSize = Number(response.headers.get("content-length"));
+	if (Number.isFinite(declaredSize) && declaredSize > MAX_CHECKSUM_BYTES) {
+		await response.body?.cancel().catch(() => {});
+		throw new Error("Checksum response exceeds size limit");
+	}
+	return await readRuntimeResponseText(response, MAX_CHECKSUM_BYTES);
+}
+async function resolveExpectedChecksum(params) {
+	const lines = (await fetchText(params.checksumUrl, params.timeoutMs, params.proxy, params.signal)).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	for (const line of lines) {
+		const match = line.match(/^([a-fA-F0-9]{64})(?:\s+[*]?(.+))?$/);
+		if (!match) continue;
+		if (!match[2] || match[2] === params.archiveFile) return match[1].toLowerCase();
+	}
+	throw new RuntimeError(`Checksum for ${params.archiveFile} was not found`, "RUNTIME_CHECKSUM_MISMATCH", params.runtime, "resolve_checksum", true);
+}
+async function sha256File(path) {
+	const hash = createHash("sha256");
+	for await (const chunk of createReadStream(path)) hash.update(chunk);
+	return hash.digest("hex");
+}
+async function downloadVerifiedArchive(params) {
+	await mkdir(dirname(params.targetPath), { recursive: true });
+	const completedPath = params.targetPath.replace(/\.partial$/, "");
+	try {
+		await access(completedPath);
+		if (await sha256File(completedPath) === params.expectedSha256.toLowerCase()) return completedPath;
+		await rm(completedPath, { force: true });
+	} catch {}
+	try {
+		let resumeOffset = await stat(params.targetPath).then((info) => info.isFile() ? info.size : 0).catch(() => 0);
+		if (resumeOffset > MAX_ARCHIVE_BYTES) {
+			await rm(params.targetPath, { force: true });
+			resumeOffset = 0;
+		}
+		let response;
+		const request = async (offset) => {
+			try {
+				return await fetchRuntimeResource({
+					url: params.url,
+					timeoutMs: params.timeoutMs,
+					proxy: params.proxy,
+					signal: params.signal,
+					init: {
+						redirect: "follow",
+						headers: offset > 0 ? { Range: `bytes=${offset}-` } : void 0
+					}
+				});
+			} catch (error) {
+				throw new RuntimeDownloadTransportError(error instanceof Error ? error.message : String(error), !params.signal?.aborted, { cause: error });
+			}
+		};
+		response = await request(resumeOffset);
+		if (resumeOffset > 0 && response.status === 416) {
+			await response.body?.cancel().catch(() => {});
+			await rm(params.targetPath, { force: true });
+			resumeOffset = 0;
+			response = await request(0);
+		}
+		if (!response.ok || !response.body) {
+			await response.body?.cancel().catch(() => {});
+			throw new RuntimeDownloadTransportError(`HTTP ${response.status}`, response.status === 429 || response.status >= 500);
+		}
+		let total;
+		if (response.status === 206) {
+			const contentRange = response.headers.get("content-range")?.match(/^bytes (\d+)-(\d+)\/(\d+)$/);
+			if (!contentRange || Number(contentRange[1]) !== resumeOffset) {
+				await response.body.cancel().catch(() => {});
+				throw new RuntimeDownloadContentError("Invalid Content-Range response");
+			}
+			total = Number(contentRange[3]);
+		} else {
+			if (resumeOffset > 0) {
+				await rm(params.targetPath, { force: true });
+				resumeOffset = 0;
+			}
+			total = Number(response.headers.get("content-length")) || void 0;
+		}
+		if (total && total > MAX_ARCHIVE_BYTES) {
+			await response.body.cancel().catch(() => {});
+			throw new Error("Archive exceeds size limit");
+		}
+		let downloaded = resumeOffset;
+		const transform = new TransformStream({ transform(chunk, controller) {
+			downloaded += chunk.byteLength;
+			if (downloaded > MAX_ARCHIVE_BYTES) throw new Error("Archive exceeds size limit");
+			params.onProgress?.(downloaded, total);
+			controller.enqueue(chunk);
+		} });
+		await pipeline(response.body.pipeThrough(transform), createWriteStream(params.targetPath, {
+			flags: resumeOffset > 0 ? "a" : "w",
+			mode: 384
+		}));
+		if (total && downloaded !== total) throw new RuntimeDownloadTransportError("Archive download was truncated", true);
+		if (await sha256File(params.targetPath) !== params.expectedSha256.toLowerCase()) throw new RuntimeError(`Checksum mismatch for ${params.runtime} archive`, "RUNTIME_CHECKSUM_MISMATCH", params.runtime, "verify_archive", true);
+		await rename(params.targetPath, completedPath);
+		return completedPath;
+	} catch (error) {
+		if (error instanceof RuntimeDownloadContentError || error instanceof RuntimeError && error.code === "RUNTIME_CHECKSUM_MISMATCH" || error instanceof Error && error.message === "Archive exceeds size limit") await rm(params.targetPath, { force: true });
+		if (error instanceof RuntimeError) throw error;
+		throw new RuntimeError(`Failed to download ${params.runtime} runtime: ${error instanceof Error ? error.message : String(error)}`, "RUNTIME_DOWNLOAD_FAILED", params.runtime, "download", true, [], { cause: error });
+	}
+}
+//#endregion
+export { canFallbackRuntimeDownload, downloadVerifiedArchive, resolveExpectedChecksum, sha256File };

package/dist/src/runtime-tools/environment.d.ts

@@ -0,0 +1,20 @@
+import type { RuntimeToolsConfig } from '../config/schema.js';
+import type { ResolvedRuntime, RuntimeKind } from './types.js';
+export interface RuntimeEnvironmentOptions {
+    stateDir: string;
+    config: RuntimeToolsConfig;
+    baseEnv: Record<string, string>;
+    runtimes?: RuntimeKind[];
+    extraBinDirs?: string[];
+}
+export interface RuntimeEnvironmentResult {
+    env: Record<string, string>;
+    resolved: ResolvedRuntime[];
+}
+export declare function buildRuntimeEnvironment(options: RuntimeEnvironmentOptions): Promise<RuntimeEnvironmentResult>;
+export declare function resolveRuntimeCommand(params: {
+    command: string;
+    stateDir: string;
+    config: RuntimeToolsConfig;
+    allowProvision: boolean;
+}): Promise<string>;

package/dist/src/runtime-tools/environment.js

@@ -0,0 +1,113 @@
+import { applyPathPrepend } from "../infra/path-prepend.js";
+import { ManagedRuntimeManager } from "./manager.js";
+import { dirname, join } from "node:path";
+import { access, readdir } from "node:fs/promises";
+//#region src/runtime-tools/environment.ts
+const POLLUTING_ENV_KEYS = [
+	"NODE_OPTIONS",
+	"NODE_PATH",
+	"NPM_CONFIG_PREFIX",
+	"npm_config_prefix",
+	"PYTHONHOME",
+	"PYTHONPATH",
+	"VIRTUAL_ENV",
+	"CONDA_PREFIX",
+	"UV_PYTHON_INSTALL_DIR",
+	"UV_PYTHON_BIN_DIR",
+	"UV_TOOL_DIR",
+	"UV_TOOL_BIN_DIR",
+	"UV_CACHE_DIR",
+	"UV_PYTHON_INSTALL_MIRROR"
+];
+async function skillEnvironmentBinDirs(stateDir) {
+	const root = join(stateDir, "tools", "environments", "skills");
+	let environmentIds;
+	try {
+		environmentIds = await readdir(root);
+	} catch {
+		return [];
+	}
+	const candidates = environmentIds.flatMap((id) => [join(root, id, "bin"), join(root, id, "node_modules", ".bin")]);
+	return (await Promise.all(candidates.map(async (candidate) => {
+		try {
+			await access(candidate);
+			return candidate;
+		} catch {
+			return null;
+		}
+	}))).filter((candidate) => candidate !== null);
+}
+async function buildRuntimeEnvironment(options) {
+	const env = { ...options.baseEnv };
+	for (const key of POLLUTING_ENV_KEYS) delete env[key];
+	const manager = new ManagedRuntimeManager({
+		stateDir: options.stateDir,
+		config: options.config
+	});
+	const runtimes = options.runtimes ?? [
+		"node",
+		"uv",
+		"python"
+	];
+	const resolved = (await Promise.all(runtimes.map(async (runtime) => {
+		try {
+			return await manager.resolve({
+				runtime,
+				allowProvision: false
+			});
+		} catch {
+			return null;
+		}
+	}))).filter((item) => item !== null);
+	const managedBinDirs = resolved.filter((item) => item.source === "managed").map((item) => dirname(item.executable));
+	const skillBinDirs = await skillEnvironmentBinDirs(options.stateDir);
+	applyPathPrepend(env, [
+		...managedBinDirs,
+		...skillBinDirs,
+		...options.extraBinDirs ?? []
+	]);
+	if (resolved.some((item) => item.runtime === "python")) {
+		env.PYTHONNOUSERSITE = "1";
+		env.PIP_REQUIRE_VIRTUALENV = "1";
+	}
+	if (resolved.some((item) => item.runtime === "uv")) {
+		env.UV_PYTHON_INSTALL_DIR = resolved.find((item) => item.runtime === "python" && item.source === "managed")?.installDir ?? join(options.stateDir, "tools", "python", "versions");
+		env.UV_PYTHON_BIN_DIR = join(options.stateDir, "tools", "python", "bin");
+		env.UV_CACHE_DIR = join(options.stateDir, "tools", "cache", "uv");
+		env.UV_MANAGED_PYTHON = "1";
+		env.UV_NO_CONFIG = "1";
+	}
+	if (resolved.some((item) => item.runtime === "node")) {
+		env.COREPACK_HOME = join(options.stateDir, "tools", "cache", "corepack");
+		env.npm_config_cache = join(options.stateDir, "tools", "cache", "npm");
+	}
+	return {
+		env,
+		resolved
+	};
+}
+const COMMAND_RUNTIME = {
+	node: "node",
+	npm: "node",
+	npx: "node",
+	corepack: "node",
+	uv: "uv",
+	uvx: "uv",
+	python: "python",
+	python3: "python"
+};
+async function resolveRuntimeCommand(params) {
+	const runtime = COMMAND_RUNTIME[params.command.toLowerCase()];
+	if (!runtime) return params.command;
+	const resolved = await new ManagedRuntimeManager({
+		stateDir: params.stateDir,
+		config: params.config
+	}).resolve({
+		runtime,
+		allowProvision: params.allowProvision
+	});
+	const key = params.command.toLowerCase() === "python3" ? "python" : params.command.toLowerCase();
+	return resolved.executables[key] ?? resolved.executable;
+}
+//#endregion
+export { buildRuntimeEnvironment, resolveRuntimeCommand };

package/dist/src/runtime-tools/errors.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeKind } from './types.js';
+export type RuntimeErrorCode = 'RUNTIME_DISABLED' | 'RUNTIME_UNSUPPORTED' | 'RUNTIME_NOT_FOUND' | 'RUNTIME_VERSION_MISMATCH' | 'RUNTIME_DOWNLOAD_FAILED' | 'RUNTIME_CHECKSUM_MISMATCH' | 'RUNTIME_ARCHIVE_INVALID' | 'RUNTIME_INSTALL_LOCKED' | 'RUNTIME_PROBE_FAILED' | 'RUNTIME_CORRUPTED' | 'RUNTIME_PERMISSION_DENIED';
+export declare class RuntimeError extends Error {
+    readonly code: RuntimeErrorCode;
+    readonly runtime: RuntimeKind;
+    readonly phase: string;
+    readonly repairable: boolean;
+    readonly hints: string[];
+    constructor(message: string, code: RuntimeErrorCode, runtime: RuntimeKind, phase: string, repairable: boolean, hints?: string[], options?: ErrorOptions);
+}

package/dist/src/runtime-tools/errors.js

@@ -0,0 +1,14 @@
+//#region src/runtime-tools/errors.ts
+var RuntimeError = class extends Error {
+	constructor(message, code, runtime, phase, repairable, hints = [], options) {
+		super(message, options);
+		this.code = code;
+		this.runtime = runtime;
+		this.phase = phase;
+		this.repairable = repairable;
+		this.hints = hints;
+		this.name = "RuntimeError";
+	}
+};
+//#endregion
+export { RuntimeError };

package/dist/src/runtime-tools/index.d.ts

@@ -0,0 +1,7 @@
+export * from './errors.js';
+export * from './bootstrap.js';
+export * from './environment.js';
+export * from './manager.js';
+export * from './offline-bundle.js';
+export * from './prune.js';
+export * from './types.js';

package/dist/src/runtime-tools/index.js

@@ -0,0 +1,7 @@
+import { RuntimeError } from "./errors.js";
+import { bundledPythonArchiveName, resolveOfflineBundleArtifact } from "./offline-bundle.js";
+import { ManagedRuntimeManager } from "./manager.js";
+import { buildRuntimeEnvironment, resolveRuntimeCommand } from "./environment.js";
+import { provisionEagerRuntimes } from "./bootstrap.js";
+import { pruneRuntimeTools } from "./prune.js";
+export { ManagedRuntimeManager, RuntimeError, buildRuntimeEnvironment, bundledPythonArchiveName, provisionEagerRuntimes, pruneRuntimeTools, resolveOfflineBundleArtifact, resolveRuntimeCommand };

package/dist/src/runtime-tools/install-lock.d.ts

@@ -0,0 +1 @@
+export declare function withInstallLock<T>(path: string, metadata: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;

package/dist/src/runtime-tools/install-lock.js

@@ -0,0 +1,50 @@
+import { dirname } from "node:path";
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+//#region src/runtime-tools/install-lock.ts
+const LOCK_STALE_MS = 1800 * 1e3;
+const LOCK_WAIT_MS = 250;
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function staleLock(path) {
+	try {
+		const value = JSON.parse(await readFile(path, "utf8"));
+		const pid = typeof value.pid === "number" ? value.pid : 0;
+		const createdAt = typeof value.createdAt === "number" ? value.createdAt : 0;
+		return !isProcessAlive(pid) && Date.now() - createdAt > LOCK_STALE_MS;
+	} catch {
+		return true;
+	}
+}
+async function withInstallLock(path, metadata, fn) {
+	await mkdir(dirname(path), { recursive: true });
+	while (true) try {
+		const handle = await open(path, "wx", 384);
+		await handle.writeFile(JSON.stringify({
+			pid: process.pid,
+			createdAt: Date.now(),
+			...metadata
+		}));
+		await handle.close();
+		break;
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		if (await staleLock(path)) {
+			await unlink(path).catch(() => void 0);
+			continue;
+		}
+		await new Promise((resolve) => setTimeout(resolve, LOCK_WAIT_MS));
+	}
+	try {
+		return await fn();
+	} finally {
+		await unlink(path).catch(() => void 0);
+	}
+}
+//#endregion
+export { withInstallLock };