@mostra/sdk 0.0.0-stage → 0.2.0

package/dist/runtime-CUbnK5Za.js

@@ -0,0 +1,1010 @@
+import { createHash, randomBytes } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, readdir, readlink, rename, rm, stat, statfs, utimes, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { BUNDLE_PLATFORMS, BUNDLE_SETUP_MARKER, BundleAsset, BundleFiles, BundleInfo, BundlePins, BundleSetup, RpcError, bundleAssetName, createDiagnostic } from "@mostra/protocol";
+import { createReadStream, createWriteStream, existsSync, readFileSync } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import { EnvHttpProxyAgent, fetch } from "undici";
+import { x } from "tar";
+import { spawn } from "node:child_process";
+//#region src/bundle/download.ts
+/**
+* Fetching a pinned archive (RT-01): streamed to disk while it is hashed, never longer than the
+* pin says, through the environment's proxy (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`), retried on
+* failures that a retry can cure, and checked against the pin before anyone reads it.
+*/
+/** A failure a retry won't cure (an HTTP 4xx other than 408 and 429, a wrong size or digest). */
+var Final = class extends Error {};
+/**
+* Downloads `url` (`https:`, `http:` or `file:`) to `dest` and checks its size and SHA-256.
+* Throws `MOSTRA_ENV_BUNDLE_INVALID` when the bytes aren't the pinned ones and
+* `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED` otherwise; `dest` never survives a failure.
+*/
+async function download(url, dest, expected, options = {}) {
+	const attempts = options.attempts ?? 3;
+	let last;
+	for (let attempt = 1; attempt <= attempts; attempt++) try {
+		const actual = await once(url, dest, expected, options);
+		if (actual !== expected.sha256) throw invalid$1(`The download from ${redactUrl(url)} has SHA-256 ${actual}, not the pinned ${expected.sha256}.`);
+		return;
+	} catch (error) {
+		await rm(dest, { force: true });
+		last = error;
+		if (error instanceof RpcError || error instanceof Final || options.signal?.aborted) break;
+		if (error.code === "ENOSPC") break;
+		if (attempt < attempts) await delay(1e3 * 4 ** (attempt - 1), options.signal);
+	}
+	if (last instanceof RpcError) throw last;
+	if (options.signal?.aborted) throw options.signal.reason;
+	throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", { message: `Couldn't download ${redactUrl(url)}: ${scrubUrls(describe(last))}` }));
+}
+async function once(url, dest, expected, options) {
+	const hash = createHash("sha256");
+	let received = 0;
+	const stallMs = options.stallMs ?? 6e4;
+	const controller = new AbortController();
+	const abort = () => controller.abort(options.signal?.reason);
+	options.signal?.addEventListener("abort", abort, { once: true });
+	let timer;
+	const arm = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error(`no data for ${stallMs / 1e3} s`)), stallMs);
+	};
+	try {
+		arm();
+		const body = await open$1(url, controller.signal, options.env ?? process.env);
+		const counter = async function* (source) {
+			for await (const chunk of source) {
+				arm();
+				received += chunk.length;
+				if (received > expected.size) throw invalid$1(`The download from ${redactUrl(url)} is larger than the pinned ${expected.size} bytes.`);
+				hash.update(chunk);
+				options.onProgress?.({
+					received,
+					total: expected.size
+				});
+				yield chunk;
+			}
+		};
+		await pipeline(body, counter, createWriteStream(dest, { mode: 384 }), { signal: controller.signal });
+		if (received !== expected.size) throw invalid$1(`The download from ${redactUrl(url)} has ${received} bytes, not the pinned ${expected.size}.`);
+		return hash.digest("hex");
+	} catch (error) {
+		if (controller.signal.aborted && !(error instanceof RpcError)) {
+			const reason = controller.signal.reason;
+			throw reason instanceof Error ? reason : new Error(String(reason));
+		}
+		throw error;
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+		options.signal?.removeEventListener("abort", abort);
+	}
+}
+/** The body of `url` as a stream. */
+async function open$1(url, signal, env) {
+	const parsed = new URL(url);
+	if (parsed.protocol === "file:") return createReadStream(fileURLToPath(parsed), { signal });
+	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Final(`${parsed.protocol} URLs aren't supported`);
+	const headers = {
+		"user-agent": "mostra-sdk",
+		accept: "application/octet-stream"
+	};
+	if (parsed.username !== "" || parsed.password !== "") {
+		const user = decodeURIComponent(parsed.username);
+		const password = decodeURIComponent(parsed.password);
+		headers["authorization"] = `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+		parsed.username = "";
+		parsed.password = "";
+	}
+	const response = await fetch(parsed, {
+		dispatcher: proxyAgent(env),
+		redirect: "follow",
+		signal,
+		headers
+	});
+	if (!response.ok || response.body === null) {
+		const status = response.status;
+		await response.body?.cancel().catch(() => void 0);
+		const message = `HTTP ${status}${response.statusText ? ` ${response.statusText}` : ""}`;
+		if (status >= 400 && status < 500 && status !== 408 && status !== 429) throw new Final(message);
+		throw new Error(message);
+	}
+	return Readable.fromWeb(response.body);
+}
+const agents = /* @__PURE__ */ new Map();
+/**
+* The agent for `env`'s `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` (lowercase first, as curl
+* reads them), one per distinct setting. Each is passed explicitly, an empty one included, so
+* undici never falls back to `process.env` (GPT review finding 6).
+*/
+function proxyAgent(env) {
+	const settings = {
+		httpProxy: env["http_proxy"] ?? env["HTTP_PROXY"] ?? "",
+		httpsProxy: env["https_proxy"] ?? env["HTTPS_PROXY"] ?? "",
+		noProxy: env["no_proxy"] ?? env["NO_PROXY"] ?? ""
+	};
+	const key = JSON.stringify(settings);
+	let agent = agents.get(key);
+	if (agent === void 0) {
+		agent = new EnvHttpProxyAgent(settings);
+		agents.set(key, agent);
+	}
+	return agent;
+}
+/**
+* `text` with every URL in it reduced to {@link redactUrl}'s form: an error from the network stack
+* repeats the URL it failed on, credentials, query and all (a mirror's or a proxy's), and a
+* diagnostic is printed (GPT review finding 2).
+*/
+function scrubUrls(text) {
+	return text.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>()]+/gi, (url) => redactUrl(url));
+}
+function invalid$1(message) {
+	return new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message }));
+}
+/** A URL without credentials or a query, safe to print. */
+function redactUrl(url) {
+	try {
+		const parsed = new URL(url);
+		parsed.username = "";
+		parsed.password = "";
+		parsed.search = "";
+		parsed.hash = "";
+		return parsed.toString();
+	} catch {
+		return "(an invalid URL)";
+	}
+}
+function describe(error) {
+	if (!(error instanceof Error)) return String(error);
+	const code = error.cause?.code ?? error.code;
+	return code !== void 0 && !error.message.includes(code) ? `${error.message} (${code})` : error.message;
+}
+function delay(ms, signal) {
+	return new Promise((done) => {
+		const timer = setTimeout(done, ms);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(timer);
+			done();
+		}, { once: true });
+	});
+}
+//#endregion
+//#region src/bundle/extract.ts
+/**
+* Unpacking a downloaded archive (RT-01). Only regular files, directories and symbolic links are
+* accepted, all under the archive's one top directory, which is stripped. node-tar refuses
+* absolute paths, `..` and writing through a link; it does create a link whatever its target, so
+* setup then checks the whole tree against the bundle's file list (`checkTree`), which refuses any
+* file or link it doesn't list and any link that leaves the bundle. A pinned archive's SHA-256 is
+* checked before any of this.
+*/
+const ACCEPTED = /* @__PURE__ */ new Set([
+	"File",
+	"OldFile",
+	"ContiguousFile",
+	"Directory",
+	"SymbolicLink"
+]);
+/** Extracts `archive` (a `.tar.gz` with one top directory `top`) into the empty directory `into`. */
+async function extractBundle(archive, into, top) {
+	let refused;
+	try {
+		await x({
+			file: archive,
+			cwd: into,
+			strip: 1,
+			strict: true,
+			preservePaths: false,
+			preserveOwner: false,
+			noChmod: false,
+			filter: (path, entry) => {
+				const type = "type" in entry ? String(entry.type) : "File";
+				if (!(path === `${top}/` || path === top || path.startsWith(`${top}/`)) || !ACCEPTED.has(type)) {
+					refused ??= `${path} (${type})`;
+					return false;
+				}
+				return true;
+			}
+		});
+	} catch (error) {
+		const code = error.code;
+		if (typeof code === "string" && /^E[A-Z]+$/.test(code) && code !== "EOF") throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", { message: `The runtime bundle couldn't be written to ${into}: ${error.message}${code === "ENOSPC" ? " (the disk is full)" : ""}` }));
+		throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The runtime bundle's archive couldn't be read: ${error.message}` }));
+	}
+	if (refused !== void 0) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The runtime bundle's archive holds an entry a bundle never has: ${refused}.` }));
+}
+//#endregion
+//#region src/bundle/tree.ts
+/**
+* A bundle's files against its manifest (RT-01): one walk that both writes `files.json` (the
+* assembler) and checks an extracted bundle against it (setup), so the two can't disagree about
+* what counts. Links must stay inside the bundle; nothing may be missing, changed or extra.
+*/
+/** The SHA-256 and size of one file, read as a stream. */
+async function hashFile(path) {
+	const hash = createHash("sha256");
+	let size = 0;
+	for await (const chunk of createReadStream(path)) {
+		hash.update(chunk);
+		size += chunk.length;
+	}
+	return {
+		sha256: hash.digest("hex"),
+		size
+	};
+}
+/** Every file and link under `root`, sorted by path, skipping `exclude`d paths (and below). */
+async function walk(root, exclude) {
+	const out = [];
+	const visit = async (dir) => {
+		const entries = await readdir(join(root, dir), { withFileTypes: true });
+		for (const entry of entries) {
+			const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
+			if (exclude(path)) continue;
+			if (entry.isDirectory()) await visit(path);
+			else if (entry.isSymbolicLink()) out.push({
+				kind: "link",
+				path,
+				target: await readlink(join(root, path))
+			});
+			else if (entry.isFile()) {
+				const stats = await lstat(join(root, path));
+				out.push({
+					kind: "file",
+					path,
+					executable: (stats.mode & 64) !== 0
+				});
+			} else out.push({
+				kind: "other",
+				path
+			});
+		}
+	};
+	await visit("");
+	return out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+/** Runs `task` over `items`, at most `limit` at a time, keeping the order of results. */
+async function mapLimit(items, limit, task) {
+	const results = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const index = next++;
+			results[index] = await task(items[index]);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return results;
+}
+/** Whether a link's target is relative and resolves inside `root`. */
+function linkStaysInside(root, path, target) {
+	if (isAbsolute(target)) return false;
+	const base = resolve(root);
+	const resolved = resolve(base, dirname(path), target);
+	return resolved === base || resolved.startsWith(base + sep);
+}
+/** Whether a manifest path is a plain relative path: no absolute start, no `.` or `..` segment. */
+function safeRelative(path) {
+	if (path === "" || isAbsolute(path) || path.includes("\\") || path.includes("\0")) return false;
+	return path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+* The manifest of the tree under `root`: every regular file with its SHA-256, size and execute
+* bit, every link with its target. Throws on anything else (a device, a socket, a link leaving
+* the tree), which a bundle must never contain.
+*/
+async function describeTree(root, exclude = () => false) {
+	const walked = await walk(root, exclude);
+	const files = [];
+	const links = [];
+	const regular = walked.filter((entry) => entry.kind === "file");
+	const hashed = await mapLimit(regular, 32, (entry) => hashFile(join(root, entry.path)));
+	regular.forEach((entry, index) => {
+		const { sha256, size } = hashed[index];
+		files.push({
+			path: entry.path,
+			size,
+			sha256,
+			executable: entry.executable
+		});
+	});
+	for (const entry of walked) {
+		if (entry.kind === "other") throw new Error(`${entry.path} is neither a file nor a link.`);
+		if (entry.kind !== "link") continue;
+		if (!linkStaysInside(root, entry.path, entry.target)) throw new Error(`${entry.path} links outside the tree (${entry.target}).`);
+		links.push({
+			path: entry.path,
+			target: entry.target
+		});
+	}
+	return {
+		schemaVersion: 1,
+		files,
+		links
+	};
+}
+/**
+* Checks the tree under `root` against `manifest`: each listed file present, regular, with its
+* size, SHA-256 and execute bit; each link present with its target, staying inside; and nothing
+* else besides what `allowExtra` accepts. Reports at most `limit` problems.
+*/
+async function checkTree(root, manifest, options = {}) {
+	const limit = options.limit ?? 20;
+	const allowExtra = options.allowExtra ?? (() => false);
+	const problems = [];
+	const add = (problem) => {
+		if (problems.length < limit) problems.push(problem);
+	};
+	const expectedFiles = new Map(manifest.files.map((entry) => [entry.path, entry]));
+	const expectedLinks = new Map(manifest.links.map((entry) => [entry.path, entry]));
+	for (const path of [...expectedFiles.keys(), ...expectedLinks.keys()]) if (!safeRelative(path)) add(`${path}: not a plain relative path`);
+	if (problems.length > 0) return problems;
+	const listedDirs = /* @__PURE__ */ new Set();
+	for (const path of [...expectedFiles.keys(), ...expectedLinks.keys()]) {
+		const segments = path.split("/");
+		for (let index = 1; index < segments.length; index++) listedDirs.add(segments.slice(0, index).join("/"));
+	}
+	const walked = await walk(root, (path) => allowExtra(path) && !expectedFiles.has(path) && !expectedLinks.has(path) && !listedDirs.has(path));
+	const found = new Map(walked.map((entry) => [entry.path, entry]));
+	for (const entry of walked) if (!expectedFiles.has(entry.path) && !expectedLinks.has(entry.path)) {
+		if (!allowExtra(entry.path)) add(`${entry.path}: not in the bundle's file list`);
+	}
+	for (const [path, link] of expectedLinks) {
+		const actual = found.get(path);
+		if (actual?.kind !== "link") add(`${path}: missing link`);
+		else if (actual.target !== link.target) add(`${path}: links to ${actual.target}, not ${link.target}`);
+		else if (!linkStaysInside(root, path, link.target)) add(`${path}: links outside the bundle`);
+	}
+	const results = await mapLimit([...expectedFiles.values()], 32, async (entry) => {
+		const actual = found.get(entry.path);
+		if (actual?.kind !== "file") return `${entry.path}: missing file`;
+		if (actual.executable !== entry.executable) return `${entry.path}: ${entry.executable ? "not executable" : "executable"}`;
+		const { sha256, size } = await hashFile(join(root, entry.path));
+		if (size !== entry.size) return `${entry.path}: ${size} bytes, not ${entry.size}`;
+		if (sha256 !== entry.sha256) return `${entry.path}: its SHA-256 differs`;
+	});
+	for (const result of results) if (result !== void 0) add(result);
+	return problems;
+}
+//#endregion
+//#region src/bundle/setup.ts
+/**
+* Making an extracted bundle usable (RT-01, D142): its files checked against `files.json`, which
+* `bundle.json` pins by SHA-256; the verify browser fetched through the bundle's own Playwright
+* and checked against the bundle's pin; then `.mostra-setup.json`, the one marker every reader
+* trusts. The SDK runs it after a download; `bin/mostra-setup` runs it for a bundle extracted by
+* hand, and for the Rust crate (WP-12), so there is one implementation of what "ready" means.
+*/
+/** The directory Playwright's browsers live in, inside a bundle. */
+function browsersDir(root) {
+	return join(root, "browsers");
+}
+/** Whether `MOSTRA_OFFLINE` says Mostra is offline: any value but empty, `0`, `false` or `no`. */
+function offline(env) {
+	const value = env["MOSTRA_OFFLINE"]?.trim().toLowerCase();
+	return value !== void 0 && value !== "" && value !== "0" && value !== "false" && value !== "no";
+}
+function invalid(message) {
+	return new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message }));
+}
+/** Reads `bundle.json` at `root`. Throws `MOSTRA_ENV_BUNDLE_INVALID` when it isn't a bundle's. */
+async function readBundle(root) {
+	let text;
+	try {
+		text = await readFile(join(root, "bundle.json"), "utf8");
+	} catch (error) {
+		throw invalid(`${root} has no readable bundle.json (${error.message}).`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw invalid(`${join(root, "bundle.json")} isn't JSON.`);
+	}
+	const result = BundleInfo.safeParse(parsed);
+	if (!result.success) throw invalid(`${join(root, "bundle.json")} isn't a runtime bundle's.`);
+	const info = result.data;
+	if (![
+		info.node.path,
+		...Object.values(info.entries),
+		info.files.path,
+		info.browser.installer
+	].every(safeRelative)) throw invalid(`${join(root, "bundle.json")} names a path outside the bundle.`);
+	return {
+		root,
+		info
+	};
+}
+/** The setup marker, when it describes exactly this bundle. */
+async function readSetup(bundle) {
+	try {
+		const marker = BundleSetup.parse(JSON.parse(await readFile(join(bundle.root, BUNDLE_SETUP_MARKER), "utf8")));
+		const { info } = bundle;
+		return marker.files === info.files.sha256 && marker.version === info.version && marker.platform === info.platform && marker.browser.revision === info.browser.revision ? marker : void 0;
+	} catch {
+		return;
+	}
+}
+/** What `checkTree` may find besides the listed files: the bundle's own records and browsers. */
+function setupExtras(path) {
+	return path === "bundle.json" || path === "files.json" || path === "browsers" || path.startsWith("browsers/") || path === BUNDLE_SETUP_MARKER || path.startsWith(`${BUNDLE_SETUP_MARKER}.tmp-`);
+}
+/** Checks the bundle's files; throws `MOSTRA_ENV_BUNDLE_INVALID` naming what differs. */
+async function checkFiles(bundle) {
+	const { root, info } = bundle;
+	const listing = join(root, info.files.path);
+	const { sha256 } = await hashFile(listing).catch(() => ({ sha256: "" }));
+	if (sha256 !== info.files.sha256) throw invalid(`${info.files.path} doesn't match the SHA-256 that bundle.json pins.`);
+	const manifest = BundleFiles.safeParse(JSON.parse(await readFile(listing, "utf8")));
+	if (!manifest.success) throw invalid(`${info.files.path} isn't a bundle's file list.`);
+	const problems = await checkTree(root, manifest.data, { allowExtra: setupExtras });
+	if (problems.length > 0) throw invalid(`Mostra ${info.version}'s runtime bundle for ${info.platform} differs from its file list: ${problems.join("; ")}.`);
+}
+/** The browser files that differ from the pin, relative to `browsers/`. */
+async function checkBrowser(bundle) {
+	return await checkTree(browsersDir(bundle.root), {
+		schemaVersion: 1,
+		files: bundle.info.browser.files,
+		links: []
+	}, { allowExtra: () => true }).catch((error) => [`browsers: ${error.message}`]);
+}
+/** The environment the browser install runs in: proxies and Playwright's mirror pass through. */
+function installEnvironment(bundle, env) {
+	const out = {};
+	for (const [name, value] of Object.entries(env)) if (value !== void 0 && !name.startsWith("MOSTRA_") && name !== "PLAYWRIGHT_BROWSERS_PATH") out[name] = value;
+	out["PLAYWRIGHT_BROWSERS_PATH"] = browsersDir(bundle.root);
+	return out;
+}
+/** The variables whose URLs may carry credentials the browser's fetch uses. */
+const CREDENTIAL_URLS = [
+	"PLAYWRIGHT_DOWNLOAD_HOST",
+	"HTTPS_PROXY",
+	"https_proxy",
+	"HTTP_PROXY",
+	"http_proxy",
+	"ALL_PROXY",
+	"all_proxy"
+];
+/** `text` without URLs' credentials or queries, and without any password `env`'s URLs carry. */
+function scrubSecrets(text, env) {
+	let out = scrubUrls(text);
+	for (const name of CREDENTIAL_URLS) {
+		const value = env[name];
+		if (!value) continue;
+		const spelled = value.includes("://") ? value : `http://${value}`;
+		const parsed = URL.canParse(spelled) ? new URL(spelled) : void 0;
+		for (const secret of [parsed?.password, parsed?.username]) {
+			if (!secret) continue;
+			for (const form of /* @__PURE__ */ new Set([secret, decodeURIComponent(secret)])) if (form.length >= 3) out = out.split(form).join("***");
+		}
+	}
+	return out;
+}
+/** Runs the bundle's Playwright to fetch the pinned browser; at most 15 minutes. */
+async function installBrowser(bundle, options) {
+	const { root, info } = bundle;
+	const output = [];
+	const code = await new Promise((resolve) => {
+		const child = spawn(join(root, info.node.path), [
+			join(root, info.browser.installer),
+			"install",
+			"chromium-headless-shell"
+		], {
+			cwd: root,
+			env: installEnvironment(bundle, options.env ?? process.env),
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			...options.signal ? { signal: options.signal } : {},
+			timeout: 9e5
+		});
+		const keep = (chunk) => {
+			output.push(chunk.toString("utf8"));
+			if (output.length > 40) output.shift();
+		};
+		child.stdout.on("data", keep);
+		child.stderr.on("data", keep);
+		child.on("error", (error) => resolve(error.message));
+		child.on("close", (exit, signal) => resolve(exit ?? signal ?? "unknown"));
+	});
+	if (code === 0) return;
+	const tail = scrubSecrets(output.join("").trim().split("\n").slice(-6).join(" | "), options.env ?? process.env);
+	throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", { message: `Fetching the verify browser (${info.browser.name} ${info.browser.browserVersion}) failed (${code}): ${tail}` }));
+}
+/**
+* Makes the bundle at `root` ready: checks its files, fetches and checks the browser when it is
+* missing or differs, and writes `.mostra-setup.json`. Idempotent: a ready bundle returns its
+* marker after the checks. Throws `MOSTRA_ENV_BUNDLE_INVALID`, `MOSTRA_ENV_BUNDLE_UNAVAILABLE`
+* (offline with no browser) or `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`.
+*/
+async function setupBundle(root, options = {}) {
+	const env = options.env ?? process.env;
+	const bundle = await readBundle(root);
+	if (!options.filesChecked) {
+		options.onStep?.("files");
+		await checkFiles(bundle);
+	}
+	options.onStep?.("browser");
+	if ((await checkBrowser(bundle)).length > 0) {
+		if (offline(env)) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", { message: `The runtime bundle at ${root} has no verify browser yet, and MOSTRA_OFFLINE keeps Mostra from fetching it.` }));
+		await rm(browsersDir(root), {
+			recursive: true,
+			force: true
+		});
+		await installBrowser(bundle, options);
+		const problems = await checkBrowser(bundle);
+		if (problems.length > 0) throw invalid(`The verify browser Playwright fetched differs from the bundle's pin: ${problems.join("; ")}.`);
+	}
+	const marker = {
+		schemaVersion: 1,
+		version: bundle.info.version,
+		platform: bundle.info.platform,
+		files: bundle.info.files.sha256,
+		browser: { revision: bundle.info.browser.revision },
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	const temporary = join(root, `${BUNDLE_SETUP_MARKER}.tmp-${process.pid}`);
+	await writeFile(temporary, `${JSON.stringify(marker, null, 2)}\n`);
+	await rename(temporary, join(root, BUNDLE_SETUP_MARKER));
+	return marker;
+}
+//#endregion
+//#region src/bundle/cache.ts
+/**
+* The local cache of runtime bundles (RT-01): one directory per archive digest, so a bundle is
+* found by what it is, not by what it's called. A bundle enters the cache only through
+* {@link installPinned}: downloaded against its pin, extracted into a temporary directory, its
+* files checked, renamed into place, its browser fetched, and only then marked ready. Concurrent
+* installers of one bundle share a lock, so it is downloaded once; a crash leaves a temporary
+* directory the next install removes, never a half-ready bundle.
+*/
+/** Where the cache is: `MOSTRA_CACHE_DIR`, else the platform's per-user cache directory. */
+function cacheRoot(env, platform = process.platform) {
+	const override = env["MOSTRA_CACHE_DIR"];
+	if (override) return resolve(override);
+	const home = env["HOME"] || homedir();
+	if (platform === "darwin") return join(home, "Library", "Caches", "mostra");
+	const xdg = env["XDG_CACHE_HOME"];
+	return join(xdg?.startsWith("/") ? xdg : join(home, ".cache"), "mostra");
+}
+/** The directory a bundle with this archive digest lives in. */
+function bundleDir(env, sha256) {
+	return join(cacheRoot(env), "bundles", sha256);
+}
+/** The space an install needs beyond the archive and its files: the browser and some margin. */
+const BROWSER_ALLOWANCE = 524288e3;
+/**
+* The pinned bundle for this platform, ready to run: from the cache when it is there and ready,
+* else installed. `MOSTRA_BUNDLE_MIRROR` replaces the release URL (files keep their names).
+*/
+async function installPinned(pins, options) {
+	const asset = pins.assets[options.platform];
+	if (asset !== void 0 && (!BundleAsset.safeParse(asset).success || asset.file !== bundleAssetName(pins.version, options.platform))) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The pins name ${JSON.stringify(asset.file)} for ${options.platform}, not Mostra ${pins.version}'s archive ${bundleAssetName(pins.version, options.platform)}.` }));
+	if (asset === void 0) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", { message: `Mostra ${pins.version} has no runtime bundle for ${options.platform}.` }));
+	const dir = bundleDir(options.env, asset.sha256);
+	const ready = await readyAt(dir);
+	if (ready) return ready;
+	if (offline(options.env)) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", { message: `Mostra ${pins.version}'s runtime bundle isn't in the cache (${dir}), and MOSTRA_OFFLINE keeps Mostra from fetching it.` }));
+	const bundles = join(cacheRoot(options.env), "bundles");
+	await mkdir(bundles, {
+		recursive: true,
+		mode: 448
+	});
+	options.onProgress?.({ step: "lock" });
+	const release = await lock(join(bundles, `${asset.sha256}.lock`), options.signal);
+	try {
+		const raced = await readyAt(dir);
+		if (raced) return raced;
+		await sweep(bundles);
+		if (await exists(dir)) {
+			if (await filesIntact(dir)) return await finish(dir, {
+				...options,
+				filesChecked: true
+			});
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+		await fetchInto(pins, asset, dir, bundles, options);
+		return await finish(dir, {
+			...options,
+			filesChecked: true
+		});
+	} finally {
+		await release();
+	}
+}
+/**
+* Whether the bundle at `dir` holds exactly what its `files.json` lists. `false` only for
+* `MOSTRA_ENV_BUNDLE_INVALID` (a missing or changed file, a `bundle.json` that doesn't read);
+* every other error is thrown.
+*/
+async function filesIntact(dir) {
+	try {
+		await checkFiles(await readBundle(dir));
+		return true;
+	} catch (error) {
+		if (error instanceof RpcError && error.diagnostic.code === "MOSTRA_ENV_BUNDLE_INVALID") return false;
+		throw error;
+	}
+}
+/** The bundle at `dir` when it exists and its setup marker matches it. */
+async function readyAt(dir) {
+	const bundle = await readBundle(dir).catch(() => void 0);
+	if (bundle === void 0) return void 0;
+	return await readSetup(bundle) ? bundle : void 0;
+}
+async function finish(dir, options) {
+	await setupBundle(dir, {
+		env: options.env,
+		signal: options.signal,
+		filesChecked: options.filesChecked,
+		onStep: (step) => options.onProgress?.({ step })
+	});
+	return readBundle(dir);
+}
+/** Downloads, extracts and checks the archive, then renames it into `dir`. */
+async function fetchInto(pins, asset, dir, bundles, options) {
+	await requireSpace(bundles, asset);
+	const scratch = join(bundles, `.tmp-${process.pid}-${randomBytes(6).toString("hex")}`);
+	await mkdir(scratch, { mode: 448 });
+	try {
+		const archive = join(scratch, asset.file);
+		await download(`${withoutTrailingSlashes(options.env["MOSTRA_BUNDLE_MIRROR"] || pins.release)}/${encodeURIComponent(asset.file)}`, archive, asset, {
+			env: options.env,
+			signal: options.signal,
+			onProgress: (progress) => options.onProgress?.({
+				step: "download",
+				...progress
+			})
+		});
+		options.onProgress?.({ step: "extract" });
+		const root = join(scratch, "root");
+		await mkdir(root);
+		const top = asset.file.replace(/\.tar\.gz$/, "");
+		if (top !== bundleAssetName(pins.version, options.platform).replace(/\.tar\.gz$/, "")) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The pinned archive ${asset.file} isn't Mostra ${pins.version}'s bundle for ${options.platform}.` }));
+		await extractBundle(archive, root, top);
+		await rm(archive, { force: true });
+		const bundle = await readBundle(root);
+		if (bundle.info.version !== pins.version || bundle.info.platform !== options.platform) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The archive holds Mostra ${bundle.info.version} for ${bundle.info.platform}, not ${pins.version} for ${options.platform}.` }));
+		options.onProgress?.({ step: "files" });
+		await checkFiles(bundle);
+		try {
+			await rename(root, dir);
+		} catch (error) {
+			const code = error.code;
+			if (!(code === "ENOTEMPTY" || code === "EEXIST") || !await exists(dir)) throw error;
+		}
+	} finally {
+		await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Fails early when the cache's file system can't hold the bundle. */
+async function requireSpace(dir, asset) {
+	const fs = await statfs(dir).catch(() => void 0);
+	if (fs === void 0) return;
+	const free = Number(fs.bavail) * Number(fs.bsize);
+	const needed = asset.size + asset.unpackedSize + BROWSER_ALLOWANCE;
+	if (free < needed) {
+		const gib = (bytes) => `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+		throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED", { message: `The runtime bundle needs about ${gib(needed)} free in ${dir}, and ${gib(free)} is free (the disk is full).` }));
+	}
+}
+/** Removes temporary directories an interrupted install left, when their process is gone. */
+async function sweep(bundles) {
+	for (const name of await readdir(bundles).catch(() => [])) {
+		const match = /^\.tmp-(\d+)-/.exec(name);
+		if (match && !alive(Number(match[1]))) await rm(join(bundles, name), {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function exists(path) {
+	return stat(path).then(() => true, () => false);
+}
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+/** How old a lock may get before another installer takes it over whatever its owner. */
+const STALE_LOCK_MS = 36e5;
+/**
+* How often a held lock is touched, so an install longer than {@link STALE_LOCK_MS} (a slow
+* network, a large browser) is never taken from its live owner (Opus review of WP-12, finding 10).
+*/
+const LOCK_TOUCH_MS = 6e4;
+/** `url` without trailing slashes, in linear time (a regex would be quadratic on many slashes). */
+function withoutTrailingSlashes(url) {
+	let end = url.length;
+	while (end > 0 && url[end - 1] === "/") end -= 1;
+	return url.slice(0, end);
+}
+/**
+* Removes the lock at `path` when it is stale (its owner gone, or older than an hour) and says
+* whether it did. The lock is read and judged through one descriptor, then moved aside, and only
+* the file judged is removed: a fresh lock another installer took in between is put back (or,
+* if a third took one meanwhile, left to the next round). The lock only saves a second download;
+* the scratch directory and its rename keep the cache correct whatever happens here.
+*/
+async function takeOverIfStale(path) {
+	let handle;
+	try {
+		handle = await open(path, "r");
+	} catch {
+		return true;
+	}
+	let judged;
+	try {
+		const info = await handle.stat();
+		const owner = Number.parseInt(await handle.readFile("utf8"), 10);
+		if (!(Date.now() - info.mtimeMs > STALE_LOCK_MS || Number.isInteger(owner) && owner > 0 && !alive(owner))) return false;
+		judged = {
+			ino: info.ino,
+			dev: info.dev
+		};
+	} finally {
+		await handle.close();
+	}
+	const aside = `${path}.stale-${randomBytes(6).toString("hex")}`;
+	try {
+		await rename(path, aside);
+	} catch {
+		return true;
+	}
+	const moved = await stat(aside).catch(() => void 0);
+	if (moved && (moved.ino !== judged.ino || moved.dev !== judged.dev)) await link(aside, path).catch(() => void 0);
+	await rm(aside, { force: true });
+	return true;
+}
+/**
+* Takes the install lock at `path`: an exclusive create holding the owner's PID. A lock whose
+* owner is gone, or older than an hour, is taken over; otherwise the caller waits for it.
+*/
+async function lock(path, signal) {
+	const token = randomBytes(8).toString("hex");
+	for (;;) {
+		signal?.throwIfAborted();
+		try {
+			const handle = await open(path, "wx", 384);
+			await handle.writeFile(`${process.pid} ${token}\n`);
+			await handle.close();
+			const touch = setInterval(() => {
+				readFile(path, "utf8").then((text) => {
+					if (text.includes(token)) return utimes(path, /* @__PURE__ */ new Date(), /* @__PURE__ */ new Date());
+				}).catch(() => void 0);
+			}, LOCK_TOUCH_MS);
+			touch.unref();
+			return async () => {
+				clearInterval(touch);
+				const aside = `${path}.done-${randomBytes(6).toString("hex")}`;
+				if (!await rename(path, aside).then(() => true, () => false)) return;
+				if (!(await readFile(aside, "utf8").catch(() => "")).includes(token)) await link(aside, path).catch(() => void 0);
+				await rm(aside, { force: true });
+			};
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		if (await takeOverIfStale(path)) continue;
+		await new Promise((done) => setTimeout(done, 250));
+	}
+}
+//#endregion
+//#region src/platform.ts
+/**
+* Which runtime bundle this machine takes (RT-01, D35): one per operating system and architecture
+* of v1, glibc only on Linux. Anything else fails closed before a download starts.
+*/
+/**
+* The glibc release Node.js reports, read from its diagnostic report's header. The report runs in
+* the caller's process (a host's server, say) and by default resolves the name of every open TCP
+* handle, synchronously; with `excludeNetwork` it does none of that (Opus review finding 4), as
+* detect-libc does. The setting is restored after.
+*/
+function glibcRuntime(report) {
+	if (report === void 0) return void 0;
+	const before = report.excludeNetwork ?? false;
+	report.excludeNetwork = true;
+	try {
+		return report.getReport().header?.glibcVersionRuntime;
+	} finally {
+		report.excludeNetwork = before;
+	}
+}
+let facts;
+/** The facts of the running process, read once. */
+function currentPlatform() {
+	facts ??= process.platform === "linux" ? {
+		platform: process.platform,
+		arch: process.arch,
+		glibc: glibcRuntime(process.report)
+	} : {
+		platform: process.platform,
+		arch: process.arch
+	};
+	return facts;
+}
+/**
+* The bundle platform for these facts. Throws `MOSTRA_PLATFORM_UNSUPPORTED` for Windows, other
+* architectures and Linux without glibc, whose libraries the bundle's Node.js and browser need.
+*/
+function bundlePlatform(facts = currentPlatform()) {
+	const name = `${facts.platform}-${facts.arch}`;
+	const known = BUNDLE_PLATFORMS.includes(name);
+	if (known && facts.platform === "linux" && facts.glibc === void 0) throw unsupported(`Mostra's Linux bundle needs glibc, and this system has none (musl, as on Alpine Linux); it supports macOS and glibc-based Linux on x64 and arm64.`);
+	if (!known) throw unsupported(`Mostra doesn't run on ${facts.platform === "win32" ? `Windows (${name})` : name}; it supports macOS and Linux on x64 and arm64.`);
+	return name;
+}
+function unsupported(message) {
+	return new RpcError(createDiagnostic("MOSTRA_PLATFORM_UNSUPPORTED", { message }));
+}
+//#endregion
+//#region src/version.ts
+/** The SDK's own package: its root directory and its release. */
+let found;
+function own() {
+	if (found) return found;
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		try {
+			const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (manifest.name === "@mostra/sdk" && manifest.version) {
+				found = {
+					root: dir,
+					version: manifest.version
+				};
+				return found;
+			}
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("Couldn't find @mostra/sdk's package.json.");
+		dir = parent;
+	}
+}
+/** This SDK's release: the client version an SDK host reports by default. */
+function sdkVersion() {
+	return own().version;
+}
+/** The SDK package's directory; `dist/bundles.json` lives under it in a release. */
+function packageRoot() {
+	return own().root;
+}
+//#endregion
+//#region src/runtime.ts
+/**
+* Which runtime a host runs (RT-01, D85). In order:
+*
+* 1. `bundle`, a directory the caller names (the SDK's option), then `MOSTRA_BUNDLE`;
+* 2. `MOSTRA_RUNTIME_BIN`, a `mostra-runtime` entry run with this process's Node (tests and
+*    development);
+* 3. the bundle this package itself sits in (the CLI inside a bundle);
+* 4. the bundle this package's release pins (`bundles.json`), from the cache or downloaded;
+* 5. a development checkout's built runtime beside this package.
+*
+* Anything a bundle supplies is checked first: its setup marker must match it, or setup runs.
+*/
+/**
+* Where the pins are read from: `<package>/dist/bundles.json`, which the release writes before
+* publishing. `MOSTRA_TEST_BUNDLE_PINS` names another file only for a package that runs from a
+* development checkout (its real path outside any `node_modules`), where the tests use it: an
+* installed copy (npm's `node_modules`, or a bundle's `lib/node_modules`) ignores it, so a
+* variable leaked into a user's environment can't swap the pins npm's provenance covers (Opus
+* review finding 8).
+*/
+function pinsFile(env, root) {
+	const override = env["MOSTRA_TEST_BUNDLE_PINS"];
+	const installed = root.split(sep).includes("node_modules");
+	return override && !installed ? override : join(root, "dist", "bundles.json");
+}
+/** The pins this build carries: `dist/bundles.json` (a test override applies only in a development checkout). */
+function readPins(env) {
+	const file = pinsFile(env, packageRoot());
+	if (!existsSync(file)) return void 0;
+	let data;
+	try {
+		data = JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		data = void 0;
+	}
+	const parsed = BundlePins.safeParse(data);
+	if (!parsed.success) throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `${file} isn't a release's bundle pins.` }));
+	return parsed.data;
+}
+/** The bundle this package was installed into, if any: `<root>/lib/node_modules/@mostra/sdk`. */
+function enclosingBundle() {
+	const root = resolve(packageRoot(), "..", "..", "..", "..");
+	return existsSync(join(root, "bundle.json")) && existsSync(join(root, "lib", "node_modules", "@mostra", "sdk")) ? root : void 0;
+}
+/** The runtime described by a bundle, once it is set up. */
+async function fromBundle(root, options) {
+	let bundle = await readBundle(resolve(root));
+	if (!await readSetup(bundle)) {
+		await setupBundle(bundle.root, {
+			env: options.env,
+			signal: options.signal,
+			onStep: (step) => options.onProgress?.({ step })
+		});
+		bundle = await readBundle(bundle.root);
+	}
+	return runtimeOf(bundle);
+}
+/** A bundle's entry points as a runtime. */
+function runtimeOf(bundle) {
+	const { root, info } = bundle;
+	return {
+		source: "bundle",
+		node: join(root, info.node.path),
+		runtimeEntry: join(root, info.entries.runtime),
+		cliEntry: join(root, info.entries.cli),
+		bundle
+	};
+}
+/** A development checkout's runtime: `packages/runtime/dist/bin.js` beside this package. */
+function development() {
+	const root = packageRoot();
+	const entry = resolve(root, "..", "runtime", "dist", "bin.js");
+	if (!existsSync(entry)) return void 0;
+	const cli = resolve(root, "..", "cli", "dist", "bin.js");
+	return {
+		source: "development",
+		node: process.execPath,
+		runtimeEntry: entry,
+		...existsSync(cli) ? { cliEntry: cli } : {}
+	};
+}
+/**
+* Finds the runtime to spawn, downloading and setting up the pinned bundle when nothing nearer
+* exists. Throws `MOSTRA_PLATFORM_UNSUPPORTED`, `MOSTRA_ENV_RUNTIME_MISSING` (a
+* `MOSTRA_RUNTIME_BIN` that doesn't exist), `MOSTRA_ENV_BUNDLE_UNAVAILABLE`,
+* `MOSTRA_ENV_BUNDLE_INVALID` or `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`.
+*/
+async function resolveRuntime(options = {}) {
+	const env = options.env ?? process.env;
+	const named = options.bundle ?? (env["MOSTRA_BUNDLE"] || void 0);
+	if (named !== void 0) return fromBundle(named, {
+		...options,
+		env
+	});
+	const override = env["MOSTRA_RUNTIME_BIN"];
+	if (override) {
+		if (!existsSync(override)) throw new RpcError(createDiagnostic("MOSTRA_ENV_RUNTIME_MISSING", { message: `MOSTRA_RUNTIME_BIN names ${override}, which doesn't exist.` }));
+		return {
+			source: "override",
+			node: process.execPath,
+			runtimeEntry: override
+		};
+	}
+	const enclosing = enclosingBundle();
+	if (enclosing !== void 0) return fromBundle(enclosing, {
+		...options,
+		env
+	});
+	const pins = readPins(env);
+	if (pins !== void 0) return runtimeOf(await installPinned(pins, {
+		env,
+		platform: bundlePlatform(),
+		signal: options.signal,
+		onProgress: options.onProgress
+	}));
+	const checkout = development();
+	if (checkout !== void 0) return checkout;
+	throw new RpcError(createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", { message: "This build of @mostra/sdk pins no runtime bundle and has no runtime beside it; set MOSTRA_BUNDLE to an extracted bundle." }));
+}
+//#endregion
+export { safeRelative as C, linkStaysInside as S, setupBundle as _, sdkVersion as a, describeTree as b, bundleDir as c, browsersDir as d, checkBrowser as f, readSetup as g, readBundle as h, runtimeOf as i, cacheRoot as l, offline as m, readPins as n, bundlePlatform as o, checkFiles as p, resolveRuntime as r, currentPlatform as s, enclosingBundle as t, installPinned as u, setupExtras as v, redactUrl as w, hashFile as x, checkTree as y };
+
+//# sourceMappingURL=runtime-CUbnK5Za.js.map