crossbind 0.0.1 → 2.0.0-beta.51

package/src/utils/loadJs.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export default async function loadJs(path, fileName, fileExt = ['json', 'js', 'mjs', 'cjs', 'ts']) {
+    let filePath;
+    fileExt.some((e) => {
+        filePath = `${path}/${fileName}.${e}`;
+        if (!fs.existsSync(filePath)) {
+            filePath = null;
+            return false;
+        }
+        return true;
+    });
+
+    if (filePath) {
+        let file = filePath.endsWith('.json')
+            ? JSON.parse(fs.readFileSync(filePath, 'utf8'))
+            : await import(pathToFileURL(filePath).href);
+
+        if (file && file.default) file = file.default;
+
+        if (typeof file === 'function') {
+            return file();
+        }
+        if (typeof file === 'object') {
+            return file;
+        }
+    }
+
+    return null;
+}

package/src/utils/loadJson.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+
+export default function loadJson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+
+    try {
+        const stateContent = fs.readFileSync(filePath, { encoding: 'utf8', flag: 'r' });
+        const state = JSON.parse(stateContent);
+        return state;
+    } catch (e) {
+        console.error(e);
+        return null;
+    }
+}

package/src/utils/logger.js

@@ -0,0 +1,110 @@
+import logUpdate from 'log-update';
+import pc from 'picocolors';
+
+const isTTY = !!process.stdout.isTTY;
+
+let active = null;
+
+function ms(n) {
+    if (n == null) return '';
+    return n < 1000 ? `${Math.round(n)}ms` : `${(n / 1000).toFixed(1)}s`;
+}
+
+function colorTime(rawMs) {
+    const text = ms(rawMs);
+    if (rawMs < 1000) return pc.green(text);
+    if (rawMs < 5000) return pc.yellow(text);
+    return pc.red(text);
+}
+
+function fmtLabel(target, fileType) {
+    const path = pc.dim(target?.path || '');
+    const env = target?.runtimeEnv ? pc.dim('/') + pc.cyan(target.runtimeEnv) : '';
+    const ft = fileType ? ` ${pc.magenta(fileType)}` : '';
+    return `${path}${env}${ft}`;
+}
+
+function commit(text) {
+    if (isTTY) {
+        logUpdate(text);
+        logUpdate.done();
+    } else {
+        process.stdout.write(`${text}\n`);
+    }
+    active = null;
+}
+
+function show(text) {
+    if (isTTY) {
+        logUpdate(text);
+    } else {
+        process.stdout.write(`${text}\n`);
+    }
+}
+
+export function startStep(target, fileType) {
+    const label = fmtLabel(target, fileType);
+    active = { label, startedAt: Date.now() };
+    show(`${label}  ${pc.yellow('compiling...')}`);
+}
+
+export function doneStep(target, fileType, detail) {
+    const label = fmtLabel(target, fileType);
+    if (active && active.label === label) {
+        const total = Date.now() - active.startedAt;
+        const det = detail ? pc.dim(`  (${detail})`) : '';
+        commit(`${label}  ${colorTime(total)}${det}`);
+    } else {
+        commit(`${label}  ${pc.green(detail || 'done')}`);
+    }
+}
+
+export function cachedStep(target, fileType) {
+    commit(`${fmtLabel(target, fileType)}  ${pc.gray('cached')}`);
+}
+
+export function startTask(label) {
+    const styled = pc.magenta(label);
+    active = { label: styled, startedAt: Date.now() };
+    show(`${styled}  ${pc.yellow('working...')}`);
+}
+
+export function doneTask(label, detail) {
+    const styled = pc.magenta(label);
+    if (active && active.label === styled) {
+        const total = Date.now() - active.startedAt;
+        const det = detail ? pc.dim(`  (${detail})`) : '';
+        commit(`${styled}  ${colorTime(total)}${det}`);
+    } else {
+        commit(`${styled}  ${pc.green(detail || 'done')}`);
+    }
+}
+
+export function cachedTask(label) {
+    commit(`${pc.magenta(label)}  ${pc.gray('cached')}`);
+}
+
+export function info(text) {
+    if (active && isTTY) {
+        logUpdate.done();
+        active = null;
+    }
+    process.stdout.write(`${text}\n`);
+}
+
+export function error(text) {
+    if (active && isTTY) {
+        logUpdate.done();
+        active = null;
+    }
+    process.stderr.write(`${pc.red(text)}\n`);
+}
+
+process.on('SIGINT', () => {
+    if (active && isTTY) logUpdate.done();
+    process.exit(130);
+});
+
+export default {
+    startStep, doneStep, cachedStep, startTask, doneTask, cachedTask, info, error,
+};

package/src/utils/ociArtifact.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+// Fetches one layer out of a published OCI image over plain HTTPS - no docker, no oras, no second
+// copy of the bytes hosted anywhere. The sysroots already ship as an image; this is how a host
+// build (RUNNER=LOCAL) reads that same object instead of a repackaged tarball.
+//
+// Everything is verified against the ONE pinned digest the caller supplies. The index body must
+// hash to it; each descriptor inside a verified body then authenticates the next fetch, so the
+// chain index -> platform manifest -> layer needs no additional hashes to trust. Content
+// addressing does the work a separate sha256 would otherwise be doing by hand.
+
+const MANIFEST_TYPES = [
+    'application/vnd.oci.image.index.v1+json',
+    'application/vnd.docker.distribution.manifest.list.v2+json',
+    'application/vnd.oci.image.manifest.v1+json',
+    'application/vnd.docker.distribution.manifest.v2+json',
+].join(', ');
+
+const digestOf = (buf) => `sha256:${crypto.createHash('sha256').update(buf).digest('hex')}`;
+
+function parseRef(image) {
+    const slash = image.indexOf('/');
+    if (slash === -1) throw new Error(`crossbind: '${image}' is not a <registry>/<repository> reference.`);
+    return { registry: image.slice(0, slash), repository: image.slice(slash + 1) };
+}
+
+// The standard token dance: an anonymous pull gets a 401 naming the realm to ask. Following it from
+// the challenge rather than hardcoding a registry's endpoint keeps this portable.
+async function anonymousToken(registry, repository) {
+    const probe = await fetch(`https://${registry}/v2/`, { redirect: 'follow' });
+    if (probe.status !== 401) return null;
+    const challenge = probe.headers.get('www-authenticate') ?? '';
+    const field = (name) => challenge.match(new RegExp(`${name}="([^"]+)"`))?.[1];
+    const realm = field('realm');
+    if (!realm) return null;
+    const url = new URL(realm);
+    const service = field('service');
+    if (service) url.searchParams.set('service', service);
+    url.searchParams.set('scope', `repository:${repository}:pull`);
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok) throw new Error(`crossbind: ${registry} refused an anonymous pull token (HTTP ${res.status}).`);
+    const body = await res.json();
+    return body.token ?? body.access_token ?? null;
+}
+
+// Redirects are followed by hand for one reason: a blob download is redirected to a CDN on another
+// host, and the registry credential must not travel there. fetch's automatic redirect would be
+// spec-compliant about this, but "the runtime probably strips it" is not something to leave to
+// chance when the alternative is ten lines.
+async function get(url, { token, accept }) {
+    let current = url;
+    for (let hop = 0; hop < 5; hop += 1) {
+        const sameHost = new URL(current).host === new URL(url).host;
+        const headers = {};
+        if (accept) headers.Accept = accept;
+        if (token && sameHost) headers.Authorization = `Bearer ${token}`;
+        const res = await fetch(current, { headers, redirect: 'manual' });
+        if (res.status >= 300 && res.status < 400) {
+            const next = res.headers.get('location');
+            if (!next) throw new Error(`crossbind: ${current} redirected without a location header.`);
+            current = new URL(next, current).toString();
+            continue;
+        }
+        if (!res.ok) throw new Error(`crossbind: ${current} returned HTTP ${res.status}.`);
+        return res;
+    }
+    throw new Error(`crossbind: too many redirects fetching ${url}.`);
+}
+
+async function fetchVerified(base, token, digest) {
+    const res = await get(`${base}/manifests/${digest}`, { token, accept: MANIFEST_TYPES });
+    const body = Buffer.from(await res.arrayBuffer());
+    const got = digestOf(body);
+    if (got !== digest) {
+        throw new Error(`crossbind: ${base} served ${got} for ${digest} - the registry contradicted its own digest.`);
+    }
+    return JSON.parse(body.toString());
+}
+
+// Downloads the single layer of the platform manifest matching `arch`, streaming to `dest` while
+// hashing, and refuses anything whose bytes do not match the digest the manifest named.
+export default async function fetchOciLayer({
+    image, index, arch, dest,
+}) {
+    const { registry, repository } = parseRef(image);
+    const base = `https://${registry}/v2/${repository}`;
+    const token = await anonymousToken(registry, repository);
+
+    const root = await fetchVerified(base, token, index);
+    const leaves = root.manifests ?? [];
+    if (leaves.length === 0) throw new Error(`crossbind: ${image}@${index} is not a multi-platform index.`);
+    const leaf = leaves.find((m) => m.platform?.os === 'linux' && m.platform?.architecture === arch);
+    if (!leaf) {
+        const have = leaves.map((m) => `${m.platform?.os}/${m.platform?.architecture}`).join(', ');
+        throw new Error(`crossbind: ${image}@${index} has no linux/${arch} - it carries ${have}.`);
+    }
+
+    const manifest = await fetchVerified(base, token, leaf.digest);
+    const layers = manifest.layers ?? [];
+    if (layers.length !== 1) {
+        throw new Error(`crossbind: expected the sysroot image to be one layer, found ${layers.length}.`);
+    }
+    const [layer] = layers;
+    if (!/tar\+gzip$/.test(layer.mediaType ?? '')) {
+        throw new Error(`crossbind: the sysroot layer is ${layer.mediaType}, expected a gzipped tar.`);
+    }
+
+    const res = await get(`${base}/blobs/${layer.digest}`, { token });
+    const hash = crypto.createHash('sha256');
+    await pipeline(
+        Readable.fromWeb(res.body),
+        async function* (source) { for await (const chunk of source) { hash.update(chunk); yield chunk; } },
+        fs.createWriteStream(dest),
+    );
+    const got = `sha256:${hash.digest('hex')}`;
+    if (got !== layer.digest) {
+        fs.rmSync(dest, { force: true });
+        throw new Error(`crossbind: the sysroot layer hashed to ${got}, expected ${layer.digest}.`);
+    }
+    return { layer: layer.digest, platform: `linux/${arch}`, size: layer.size };
+}

package/src/utils/overrideDependency.js

@@ -0,0 +1,99 @@
+import { getContentHash } from './hash.js';
+
+const REPLACE_RECIPE_KEYS = [
+    'buildType', 'getURL', 'env', 'copyToSource', 'copyToDist',
+    'beforeRun', 'useIOSCMake', 'sourceReplaceList', 'getExtraLibs',
+];
+
+function identityNames(dep) {
+    return [dep.general?.name, dep.package?.name, dep.general?.alias?.package].filter(Boolean);
+}
+
+function matchEntry(map, dep) {
+    if (!map || typeof map !== 'object') return null;
+    for (const name of identityNames(dep)) {
+        if (Object.prototype.hasOwnProperty.call(map, name)) return { key: name, value: map[name] };
+    }
+    return null;
+}
+
+function normalizeOverride(value) {
+    if (!value || typeof value !== 'object') return null;
+    const { replace, rebuild, exclude, ...recipe } = value;
+    if (rebuild === true) return recipe;
+    if (Object.keys(recipe).length > 0) return recipe;
+    return null;
+}
+
+export function resolveDependencyOverride(overrides, dep) {
+    const match = matchEntry(overrides, dep);
+    if (!match) return null;
+    const override = normalizeOverride(match.value);
+    return override ? { key: match.key, override } : null;
+}
+
+export function resolveDependencyReplace(replaces, dep) {
+    const match = matchEntry(replaces, dep);
+    const replace = match?.value && typeof match.value === 'object' ? match.value.replace : null;
+    return replace || null;
+}
+
+export function resolveExcludedNames(overrides) {
+    if (!overrides || typeof overrides !== 'object') return [];
+    return Object.keys(overrides).filter((k) => overrides[k]?.exclude === true);
+}
+
+// Keep the old package's identity (name/alias/package.name/libName); take the new package's
+// implementation (paths, dependencies, build, targetSpecs, version) — so every consumer of the
+// old identity keeps resolving while artifacts come from the replacement.
+export function restampIdentity(newNode, oldNode) {
+    return {
+        ...newNode,
+        general: oldNode.general,
+        package: { ...newNode.package, name: oldNode.package?.name },
+        export: { ...newNode.export, libName: oldNode.export.libName },
+    };
+}
+
+export function mergeBuildOverride(recipe = {}, override = {}) {
+    if (!override) return recipe;
+    const merged = { ...recipe };
+
+    REPLACE_RECIPE_KEYS.forEach((key) => {
+        if (key in override) merged[key] = override[key];
+    });
+
+    if (override.replaceList) {
+        if (Array.isArray(override.replaceList)) {
+            merged.replaceList = [...(recipe.replaceList || []), ...override.replaceList];
+        } else if (override.replaceList.set) {
+            merged.replaceList = [...override.replaceList.set];
+        } else if (override.replaceList.append) {
+            merged.replaceList = [...(recipe.replaceList || []), ...override.replaceList.append];
+        }
+    }
+
+    if (typeof override.getBuildParams === 'function') {
+        const base = typeof recipe.getBuildParams === 'function' ? recipe.getBuildParams : () => [];
+        merged.getBuildParams = (...args) => override.getBuildParams(base, ...args);
+    }
+
+    return merged;
+}
+
+// Functions are keyed by their source text: editing the literal changes the key (rebuild),
+// but values captured from outer scope do NOT — an override function must stay self-contained
+// or a changed captured value silently keeps the stale cache.
+export function getOverrideKey(dep) {
+    const override = dep.overrideBuild || {};
+    const serial = JSON.stringify(
+        override,
+        (key, value) => (typeof value === 'function' ? `fn:${value.toString()}` : value),
+    );
+    const parts = [
+        dep.general?.name || '',
+        override.nativeVersion || dep.package?.nativeVersion || '',
+        serial,
+    ];
+    return getContentHash(parts.join(' '));
+}

package/src/utils/provenance.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import state from '../state/index.js';
+import familyManifestOf from './familyManifest.js';
+import { getDockerImage, imageRoleFor } from './pullDockerImage.js';
+import { resolveWasiSdkPath } from './wasiToolchain.js';
+
+// K4 (contract): -bin packages carry a machine-readable provenance block documenting
+// the reproducible recipe of the shipped binaries - producing recipe package, upstream
+// source hash and build environment. Everything is derived; nothing is hand-maintained.
+
+// wasi-sdk's VERSION file pins the sdk release plus its wasi-libc/llvm inputs.
+// Also consumed by the license machinery to pin toolchain-runtime notice links.
+export function wasiToolchainIdentity(sdkPath) {
+    const toolchain = { name: 'wasi-sdk' };
+    const versionFile = `${sdkPath}/VERSION`;
+    if (fs.existsSync(versionFile)) {
+        const [version, ...pins] = fs.readFileSync(versionFile, 'utf8').trim().split('\n');
+        toolchain.version = version.trim();
+        for (const line of pins) {
+            const match = line.match(/^([\w-]+):\s*(.+)$/);
+            if (match) toolchain[match[1]] = match[2].trim();
+        }
+    }
+    const clang = fs.realpathSync(`${sdkPath}/bin/clang`);
+    toolchain.clangSha256 = crypto.createHash('sha256').update(fs.readFileSync(clang)).digest('hex');
+    return toolchain;
+}
+
+export default function buildProvenance(target) {
+    const manifest = state.config.package || {};
+    const family = familyManifestOf(state.config);
+    if (!family) {
+        throw new Error(`crossbind: cannot resolve the family recipe package of "${manifest.name}" - required for provenance (contract K4).`);
+    }
+    const { getURL, sha256 } = state.config.build;
+    if (!sha256) {
+        throw new Error(`crossbind: the recipe of "${manifest.name}" declares no source sha256 - required for provenance (contract K4).`);
+    }
+    const wasiSdk = target.platform === 'wasi' ? resolveWasiSdkPath(state.config.system) : null;
+    return {
+        recipe: { name: family.manifest.name, version: family.manifest.version, nativeVersion: manifest.nativeVersion },
+        source: { url: getURL(manifest.nativeVersion), sha256 },
+        environment: {
+            builder: wasiSdk ? 'host' : 'docker',
+            // The digest-pinned image is the canonical reproduction environment either way.
+            dockerImage: getDockerImage(imageRoleFor(target)),
+            ...(wasiSdk ? { hostPlatform: `${os.platform()}-${os.arch()}`, toolchain: wasiToolchainIdentity(wasiSdk) } : {}),
+        },
+        // Full statically-linked component inventory with per-source hashes (contract E).
+        sbom: `dist/prebuilt/${target.path}/sbom.cdx.json`,
+    };
+}

package/src/utils/pullDockerImage.js

@@ -0,0 +1,105 @@
+import { execFileSync } from 'node:child_process';
+import { getContentHash } from './hash.js';
+
+// Digest-pinned so a re-pushed tag can't swap the compiler; IMAGE_VERSION only names containers
+// and records which release these digests came from - bump every pin via scripts/pin-docker-image.js.
+const REGISTRY = 'ghcr.io/crossbind';
+const IMAGE_VERSION = '1.0.2';
+
+// One entry per role in the image family. `ref` is the multi-arch index, which a native pull
+// resolves per platform; `amd64` is that index's linux/amd64 leaf, needed wherever the CLI forces
+// a platform, because the classic image store holds one platform per digest reference. The android
+// image is amd64-only - Google ships the linux NDK host tools for x86_64 alone - so its index
+// carries a single leaf and both of its refs resolve to the same platform.
+// Generated by scripts/pin-docker-image.js from a release digest table; do not edit by hand.
+const IMAGES = {
+    web: {
+        ref: `${REGISTRY}/web@sha256:c1d1d81a4775871cd90c8ac980e0a5f87cb7890822117f77be1c8345f51b1f47`,
+        amd64: `${REGISTRY}/web@sha256:9010948430c95120b8c19f73377f8684bc6b54e03537790f465237225e48dae2`,
+    },
+    android: {
+        ref: `${REGISTRY}/android@sha256:a3facbf2181f568f12a9fe89054188895665a63e2c147b790fd7e25f3e128ac8`,
+        amd64: `${REGISTRY}/android@sha256:4694c6210379a87d8cf0e7f8b56a76a9c74a8724a1aff037c943dcdb521f4de1`,
+    },
+};
+
+const OVERRIDE_KEYS = { web: 'CROSSBIND_IMAGE_WEB', android: 'CROSSBIND_IMAGE_ANDROID' };
+
+// Which image a target compiles in: wasm and wasi share the web image, ios never reaches docker.
+export function imageRoleFor(target) {
+    return target?.platform === 'android' ? 'android' : 'web';
+}
+
+const warned = new Set();
+function warnOnce(message) {
+    if (warned.has(message)) return;
+    warned.add(message);
+    console.warn(message);
+}
+
+// An override is one of three distinct situations, and only the first keeps the reproducibility
+// guarantee: same digest from another registry, a digest the release does not ship, or a bare tag.
+function resolveRef(role, expected) {
+    const key = OVERRIDE_KEYS[role];
+    const explicit = process.env[key];
+    if (explicit) {
+        if (explicit !== expected) {
+            warnOnce(explicit.includes('@sha256:')
+                ? `crossbind: unsupported toolchain override - ${key} pins a digest the release does not ship (${explicit}).`
+                : `crossbind: mutable override - ${key} names the tag ${explicit}; the reproducibility guarantee is disabled.`);
+        }
+        return explicit;
+    }
+
+    const mirror = process.env.CROSSBIND_REGISTRY_MIRROR;
+    const at = expected.indexOf('@');
+    if (mirror && at !== -1) {
+        warnOnce(`crossbind: pulling from the registry mirror ${mirror} (same digest as the release).`);
+        return `${mirror.replace(/\/+$/, '')}/${expected.slice(0, at).split('/').pop()}${expected.slice(at)}`;
+    }
+    return expected;
+}
+
+export function getDockerImage(role = 'web', platform) {
+    const image = IMAGES[role];
+    if (!image) throw new Error(`crossbind: unknown docker image role "${role}".`);
+    return resolveRef(role, platform === 'linux/amd64' ? image.amd64 : image.ref);
+}
+
+// One container per image: a web container carries no NDK, and android runs a forced platform.
+// The version is part of the name so an image bump cannot silently reuse a container built from
+// the previous toolchain.
+export function getDockerContainerName(base, role = 'web') {
+    return `crossbind-${IMAGE_VERSION}-${role}-${getContentHash(base)}`.replaceAll('/', '-').replaceAll(':', '-');
+}
+
+const pulledRefs = new Set();
+
+// `docker images -q` can't resolve digest refs; `inspect` handles both.
+function isImagePresent(ref) {
+    try {
+        execFileSync('docker', ['image', 'inspect', ref], { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export default function pullDockerImage(role = 'web', platform) {
+    const ref = getDockerImage(role, platform);
+    if (pulledRefs.has(ref)) return;
+
+    if (!isImagePresent(ref)) {
+        console.log('');
+        console.log('===========================================================');
+        console.log('============= Downloading the docker image... =============');
+        console.log('===========================================================');
+        console.log('');
+        execFileSync('docker', ['pull', ref], { stdio: 'inherit' });
+        console.log('');
+        console.log('===========================================================');
+        console.log('');
+    }
+
+    pulledRefs.add(ref);
+}

package/src/utils/replaceBasePathForDocker.js

@@ -0,0 +1,18 @@
+export const DOCKER_BASE = '/tmp/crossbind/live';
+
+export default function replaceBasePathForDocker(data, basePath) {
+    if (typeof data === 'string' || data instanceof String) {
+        return data.replaceAll(basePath, DOCKER_BASE);
+    }
+    if (Array.isArray(data)) {
+        return data.map((d) => replaceBasePathForDocker(d, basePath));
+    }
+    if (typeof data === 'object' && data !== null) {
+        const newData = {};
+        Object.entries(data).forEach(([key, value]) => {
+            newData[key] = replaceBasePathForDocker(value, basePath);
+        });
+        return newData;
+    }
+    return data;
+}

package/src/utils/resolveEmbindRust.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import state from '../state/index.js';
+
+// The Rust producer crate + adapters ship in @crossbind/core-embind-rust. The ENGINE never
+// depends on it (same direction rule as core-embind-jsi): the consumer declares it - directly,
+// or transitively through a platform plugin - and the engine only resolves it. pnpm keeps
+// transitive deps unhoisted, so resolution may need to hop through the declaring plugin.
+const PKG = '@crossbind/core-embind-rust';
+const PLUGIN_ANCHORS = [
+    '@crossbind/plugin-react-native',
+    '@crossbind/plugin-vite',
+    '@crossbind/plugin-rollup',
+    '@crossbind/plugin-metro',
+    '@crossbind/plugin-webpack',
+];
+
+let cached = null;
+
+export default function resolveEmbindRustRoot() {
+    if (cached) return cached;
+
+    const resolveFrom = (baseDir) => {
+        try {
+            const req = createRequire(path.join(baseDir, 'package.json'));
+            return path.dirname(fs.realpathSync(req.resolve(`${PKG}/package.json`)));
+        } catch (e) {
+            return null;
+        }
+    };
+
+    const project = state.config?.paths?.project;
+    let root = project ? resolveFrom(project) : null;
+    if (!root && project) {
+        for (const anchor of PLUGIN_ANCHORS) {
+            try {
+                const req = createRequire(path.join(project, 'package.json'));
+                const anchorDir = path.dirname(fs.realpathSync(req.resolve(`${anchor}/package.json`)));
+                root = resolveFrom(anchorDir);
+                if (root) break;
+            } catch (e) { /* this plugin is not installed - try the next anchor */ }
+        }
+    }
+    if (!root) {
+        // Monorepo layout: the package ships next to the engine.
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const sibling = path.resolve(here, '../../../embind-rust');
+        if (fs.existsSync(`${sibling}/crate/Cargo.toml`)) root = sibling;
+    }
+    if (!root) {
+        throw new Error(`crossbind: Rust bindings need ${PKG} - add it to your (dev)dependencies.`);
+    }
+    cached = root;
+    return root;
+}
+
+// The package version, stamped into generated bridge manifests for debuggability.
+export function embindRustVersion() {
+    try {
+        return JSON.parse(fs.readFileSync(`${resolveEmbindRustRoot()}/package.json`, 'utf8')).version ?? 'unknown';
+    } catch (e) {
+        return 'unknown';
+    }
+}