@xopcai/xopc 0.0.191 → 0.0.193

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

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

@@ -0,0 +1,20 @@
+import { EventEmitter } from 'node:events';
+import type { ResolvedRuntime, RuntimeKind, RuntimeManagerOptions, RuntimeRequest, RuntimeStatus } from './types.js';
+export declare class ManagedRuntimeManager extends EventEmitter {
+    private readonly options;
+    private readonly inFlight;
+    constructor(options: RuntimeManagerOptions);
+    defaultVersion(runtime: RuntimeKind): string;
+    resolve(request: RuntimeRequest): Promise<ResolvedRuntime>;
+    private resolveUncached;
+    probeManaged(runtime: RuntimeKind, requestedVersion: string): Promise<ResolvedRuntime | null>;
+    install(runtime: RuntimeKind, version?: string, signal?: AbortSignal): Promise<ResolvedRuntime>;
+    private installDistribution;
+    private installPython;
+    private installBundledPython;
+    private uvEnvironment;
+    status(runtime: RuntimeKind): Promise<RuntimeStatus>;
+    statusAll(): Promise<RuntimeStatus[]>;
+    repair(runtime: RuntimeKind): Promise<ResolvedRuntime>;
+    private progress;
+}