crossbind 2.0.0-beta.60 → 2.0.0-beta.63

package/src/utils/licenseReport.js

@@ -18,6 +18,12 @@ export function validateSpdx(expression) {
     }
 }
 
+// Longer than any run of backticks in the text, which would otherwise close the block early.
+function fenceFor(text) {
+    const longest = [...text.matchAll(/`+/g)].reduce((most, [run]) => Math.max(most, run.length), 0);
+    return '`'.repeat(Math.max(3, longest + 1));
+}
+
 export function formatNoticeSections(rows) {
     return [...rows]
         .sort((a, b) => a.name.localeCompare(b.name))
@@ -29,7 +35,10 @@ export function formatNoticeSections(rows) {
             if (row.licenseSelected) lines.push(`- license election: ${row.licenseSelected} (declared: ${row.licenseDeclared})`);
             else if (/\bOR\b/.test(row.license || '')) lines.push(`- no license election recorded; the declared expression applies${row.licenseText ? ' and all texts are included' : ' (texts linked above)'}`);
             if (row.licenseNotes) lines.push(`- note: ${row.licenseNotes}`);
-            if (row.licenseText) lines.push('', '```', row.licenseText.trim(), '```');
+            if (row.licenseText) {
+                const fence = fenceFor(row.licenseText);
+                lines.push('', fence, row.licenseText.trim(), fence);
+            }
             return lines.join('\n');
         });
 }
@@ -84,7 +93,7 @@ export function formatCycloneDxSbom(rows, target = {}) {
                 type: 'library',
                 name: row.name,
                 ...(row.nativeVersion ? { version: row.nativeVersion } : {}),
-                ...(row.nativeVersion ? { purl: `pkg:generic/${row.name}@${row.nativeVersion}` } : {}),
+                ...(row.nativeVersion ? { purl: row.purl ?? `pkg:generic/${row.name}@${row.nativeVersion}` } : {}),
                 ...(row.license ? { licenses: [{ expression: row.license }] } : {}),
                 ...(row.sha256 ? { hashes: [{ alg: 'SHA-256', content: row.sha256 }] } : {}),
                 ...(row.sourceUrl ? { externalReferences: [{ type: 'distribution', url: row.sourceUrl }] } : {}),

package/src/utils/linkLayout.js

@@ -13,7 +13,9 @@ export function libNameOf(libPath) {
     return match ? match[1] : base;
 }
 
-export function buildLinkLibArgs(libs, { wholeArchiveAll = false, wholeArchiveNames = new Set(), wrapLast = true } = {}) {
+export function buildLinkLibArgs(libs, {
+    wholeArchiveAll = false, wholeArchiveNames = new Set(), wrapLast = true, forceLoad = false,
+} = {}) {
     const args = [];
     let wrapped = false;
     libs.forEach((lib, index) => {
@@ -21,6 +23,11 @@ export function buildLinkLibArgs(libs, { wholeArchiveAll = false, wholeArchiveNa
         // have no bridge (main() is the GC root), so they pass false.
         const isBridge = wrapLast && index === libs.length - 1;
         const wantWrap = wholeArchiveAll || isBridge || wholeArchiveNames.has(libNameOf(lib));
+        // Apple's ld64 has no --whole-archive groups; it keeps archives one at a time.
+        if (forceLoad) {
+            args.push(wantWrap ? `-Wl,-force_load,${lib}` : lib);
+            return;
+        }
         if (wantWrap !== wrapped) {
             args.push(wantWrap ? '-Wl,--whole-archive' : '-Wl,--no-whole-archive');
             wrapped = wantWrap;

package/src/utils/linuxToolchain.js

@@ -0,0 +1,24 @@
+// The linux image's clang wrappers and CMake toolchain files, one per target triple, and the flags every
+// Linux archive is built with: port archives and Conan packages link into the same addon, so they move
+// together.
+const LINUX_TOOLCHAIN = '/opt/crossbind/linux';
+const LINUX_TRIPLES = {
+    linux: { x64: 'x86_64-linux-gnu', arm64: 'aarch64-linux-gnu' },
+    linuxmusl: { x64: 'x86_64-alpine-linux-musl', arm64: 'aarch64-alpine-linux-musl' },
+};
+// Every archive ends up inside a loadable .node module, so -fPIC holds even where a project turns
+// position-independent code off for static builds, as GDAL does.
+export const LINUX_ARCHIVE_FLAGS = ['-fPIC'];
+
+export const linuxTriple = (target) => LINUX_TRIPLES[target.platform][target.arch];
+export const linuxToolchainFile = (target) => `${LINUX_TOOLCHAIN}/${linuxTriple(target)}.cmake`;
+export const linuxTool = (target, name) => `${LINUX_TOOLCHAIN}/bin/${linuxTriple(target)}-${name}`;
+
+// The compilers and archive tools of the target's triple, by the variables build systems read them from.
+// The image's own .pc files describe its libraries, not the sysroot's, so pkg-config reads none of them.
+export const linuxBuildEnv = (target) => ({
+    ...Object.fromEntries(Object.entries({
+        CC: 'clang', CXX: 'clang++', AR: 'ar', RANLIB: 'ranlib', NM: 'nm', STRIP: 'strip',
+    }).map(([variable, tool]) => [variable, linuxTool(target, tool)])),
+    PKG_CONFIG_LIBDIR: '',
+});

package/src/utils/makeTreeWritable.js

@@ -0,0 +1,12 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// A read-only directory cannot be emptied, so `rm -rf`, a restage and the cleanup of a conan run
+// would all fail on one. fs.cpSync gives each directory it makes its source's mode. Links are left
+// alone: they can point anywhere.
+export default function makeTreeWritable(dir) {
+    const stat = fs.lstatSync(dir);
+    if (!stat.isDirectory()) return;
+    fs.chmodSync(dir, stat.mode | 0o700);
+    fs.readdirSync(dir).forEach((name) => makeTreeWritable(path.join(dir, name)));
+}

package/src/utils/nativeImports.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import appSourceFiles from './appSources.js';
+
+// Static imports and re-exports, side-effect imports, and import() or require() of a literal. A specifier
+// built at run time is not found.
+const IMPORT_SPECIFIER = /\b(?:from|import\s*\(?|require\s*\()\s*(['"])([^'"\n]+)\1/g;
+
+export function findImportSpecifiers(text) {
+    return [...new Set([...text.matchAll(IMPORT_SPECIFIER)].map((match) => match[2]))];
+}
+
+export const nativeExtensions = ({ header, module }) => [...header, ...module, 'rs'];
+
+export const nativeSpecifierTest = (ext) => {
+    const extension = new RegExp(`\\.(${nativeExtensions(ext).join('|')})$`);
+    return (specifier) => /^(cargo|conan):/.test(specifier) || extension.test(specifier);
+};
+
+export function findNativeImportsIn(projectDir, isNative) {
+    return appSourceFiles(projectDir).flatMap((importer) => findImportSpecifiers(fs.readFileSync(importer, 'utf8'))
+        .filter(isNative)
+        .map((specifier) => ({ importer, specifier })));
+}

package/src/utils/nativeSourceStamp.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getContentHash } from './hash.js';
+
+// Names matter as well as dates: removing or renaming a source must invalidate its archive.
+export function nativeSourceStamp(directories = []) {
+    const entries = [];
+    const visit = (file) => {
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        if (!stat) { entries.push([file, 'missing']); return; }
+        if (stat.isDirectory()) {
+            entries.push([file, 'directory']);
+            for (const entry of fs.readdirSync(file, { withFileTypes: true })) {
+                // Match the source walk's treatment of links and avoid cycles.
+                if (entry.isFile() || entry.isDirectory()) visit(path.join(file, entry.name));
+            }
+        } else if (stat.isFile()) entries.push([file, stat.size, stat.mtimeMs]);
+    };
+    directories.forEach(visit);
+    return getContentHash(JSON.stringify(entries.sort(([a], [b]) => a.localeCompare(b))));
+}
+
+const stampFile = (artifact) => `${artifact}.sources`;
+
+export function nativeSourceStampChanged(artifact, directories = []) {
+    // No local sources: prebuilt ports retain their existing upstream fingerprint contract.
+    if (!directories.length) return false;
+    const file = stampFile(artifact);
+    return !fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== nativeSourceStamp(directories);
+}
+
+export function writeNativeSourceStamp(artifact, directories = []) {
+    if (!directories.length) return;
+    fs.mkdirSync(path.dirname(stampFile(artifact)), { recursive: true });
+    fs.writeFileSync(stampFile(artifact), nativeSourceStamp(directories));
+}

package/src/utils/nodeDevBuild.js

@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import upath from 'upath';
+import loadJson from './loadJson.js';
+import { computeInputStamp } from './inputStamp.js';
+import { findHeaderImportsIn } from './headerImports.js';
+import { findNativeImportsIn, nativeSpecifierTest } from './nativeImports.js';
+
+// Set on the build a dev start runs: that build is a Node process too, which NODE_OPTIONS may hand the dev hooks again.
+export const DEV_BUILD_ENV = 'CROSSBIND_DEV_BUILD';
+
+const CLI = fileURLToPath(new URL('../bin.js', import.meta.url));
+const CONFIG_EXTENSIONS = ['json', 'js', 'mjs', 'cjs', 'ts'];
+// This machine's binary, built the way the Node.js playbook builds it.
+const BUILD_ARGS = {
+    napi: ['-p', 'host', '-a', process.arch, '-e', 'node', '-b', 'release'],
+    wasm: ['-p', 'wasm', '-a', 'wasm32', '-r', 'st', '-e', 'node', '-b', 'release'],
+};
+
+const hasConfig = (dir) => CONFIG_EXTENSIONS.some((ext) => fs.existsSync(`${dir}/crossbind.config.${ext}`));
+const hasNapiRuntime = (dir) => fs.existsSync(`${dir}/node_modules/@crossbind/core-embind-napi/package.json`);
+
+function dirAbove(start, test) {
+    let dir = upath.resolve(start);
+    while (!test(dir)) {
+        const parent = upath.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+    return dir;
+}
+
+// The nearest directory with a crossbind.config above the app's main module, else above the working directory.
+export function projectDirOf(main, cwd = process.cwd()) {
+    const project = (main && dirAbove(upath.dirname(main), hasConfig)) ?? dirAbove(cwd, hasConfig);
+    if (!project) throw new Error(`crossbind: no crossbind.config above ${main ?? cwd}; start Node in the app, or leave out --import crossbind/node/dev.`);
+    return project;
+}
+
+// A project that installs the Node-API runtime runs its addon, any other its wasm build. Looked up through the
+// node_modules above the project only: pnpm's bin shims set NODE_PATH to the whole workspace.
+export function devFormatOf(project) {
+    return dirAbove(project, hasNapiRuntime) ? 'napi' : 'wasm';
+}
+
+// What decides whether a build is still current: the project's native sources, the files its relative native imports
+// name, its config and manifest, and which native files and names its JavaScript imports - not the rest of its code.
+export function nativeInputsFingerprint(config) {
+    const { project, native, header, module: modules } = config.paths;
+    const relativeTo = (importer) => upath.relative(project, importer);
+    const imports = findNativeImportsIn(project, nativeSpecifierTest(config.ext))
+        .map(({ importer, specifier }) => ({ importer: relativeTo(importer), specifier }));
+    const names = findHeaderImportsIn(project, config.ext.header)
+        .map(({ importer, specifier, names: taken }) => JSON.stringify([relativeTo(importer), specifier, taken]));
+    const importedFiles = imports.filter(({ specifier }) => specifier.startsWith('.'))
+        .map(({ importer, specifier }) => upath.resolve(project, upath.dirname(importer), specifier));
+    const projectFiles = [...CONFIG_EXTENSIONS.flatMap((ext) => [`crossbind.config.${ext}`, `crossbind.overrides.${ext}`]), 'package.json']
+        .map((file) => `${project}/${file}`);
+    const salt = JSON.stringify({ imports: imports.map((entry) => JSON.stringify(entry)).sort(), names: names.sort() });
+    return computeInputStamp(
+        [...native, ...header, ...modules],
+        [...config.ext.header, ...config.ext.source, ...config.ext.module, 'rs'],
+        [...projectFiles, ...importedFiles],
+        salt,
+    );
+}
+
+function runBuild(project, args) {
+    const command = `crossbind build ${args.join(' ')}`;
+    console.error(`crossbind: native sources changed since the last build - ${command}`);
+    const { status, error } = spawnSync(process.execPath, [CLI, 'build', ...args], {
+        cwd: project, stdio: ['ignore', 2, 2], env: { ...process.env, [DEV_BUILD_ENV]: '1' },
+    });
+    if (error || status !== 0) throw new Error(`crossbind: ${command} failed; fix what it reports and start the app again.`, { cause: error });
+}
+
+// Builds this machine's binary when the native inputs changed since the last build a dev start ran, or when its output
+// is gone, and returns the hooks that build wrote, or null for an app that imports nothing native.
+export function ensureDevBuild(config, { run = runBuild } = {}) {
+    const { project, cache, output } = config.paths;
+    const format = devFormatOf(project);
+    const stamp = `${cache}/node-dev/${format}.json`;
+    const fingerprint = nativeInputsFingerprint(config);
+    if (!fs.existsSync(`${output}/node/${format}.mjs`) || loadJson(stamp)?.fingerprint !== fingerprint) {
+        run(project, BUILD_ARGS[format]);
+        fs.mkdirSync(upath.dirname(stamp), { recursive: true });
+        fs.writeFileSync(stamp, JSON.stringify({ fingerprint }));
+    }
+    const hooks = `${output}/node/${format}.register.mjs`;
+    return fs.existsSync(hooks) ? hooks : null;
+}

package/src/utils/packageLicense.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { deriveLicenseExpression, formatCycloneDxSbom, formatNoticeSections } from './licenseReport.js';
+
+export const SBOM_FILE = 'sbom.cdx.json';
+const RULE = '-'.repeat(70);
+
+export function lgplRows(rows) {
+    return rows.filter((row) => /\bLGPL\b/.test(row.license ?? ''));
+}
+
+// The LLVM exception waives the notice for runtime parts compiled into a binary; every other
+// component needs its text in the package.
+function assertTexts(name, rows) {
+    const missing = rows.filter(
+        (row) => (!row.licenseText || row.licenseText.includes('(missing:')) && !/\bLLVM-exception\b/.test(row.license ?? ''),
+    );
+    if (missing.length) {
+        throw new Error(
+            `${name}: no license text for ${missing.map((row) => row.name).join(', ')}; build the package so crossbind licenses can read it.`,
+        );
+    }
+}
+
+const listOf = (names) => (names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names[0]);
+
+function relinkSection({ name, version, repository, projectPath, addonFile, rows }) {
+    const tag = `${name}@${version}`;
+    const repo = repository.replace(/\.git$/, '');
+    return [
+        '## Relinking the LGPL libraries',
+        '',
+        `This addon links ${listOf(rows.map((row) => row.name))} statically; their sections below give their licenses.`,
+        'You may replace them with modified versions and relink the addon:',
+        '',
+        `1. Get the corresponding source. This package was built from ${repo} at the tag ${tag}:`,
+        `   ${repo}/tree/${tag}`,
+        '   The upstream sources are the tarballs the sections below list, with their SHA-256.',
+        `2. In ${projectPath}, point the library at your modified source with a crossbind.overrides.js file`,
+        '   (docs/playbooks/override-dependencies.md in that repository).',
+        `3. Build the addon with \`pnpm install\` and \`pnpm --dir ${projectPath} build\`. Linux and Windows`,
+        '   addons build in Docker, macOS addons on a Mac.',
+        `4. The build writes ${addonFile} in ${projectPath}; it replaces the file of that name in this package.`,
+    ].join('\n');
+}
+
+export function nodePackageLicense({ name, version, repository, projectPath, addonFile = null, rows }) {
+    assertTexts(name, rows);
+    const expression = deriveLicenseExpression(rows);
+    const relinked = addonFile ? lgplRows(rows) : [];
+    const lines = [
+        addonFile
+            ? `${name} ships a Node-API addon that links the components below statically.`
+            : `${name} ships the JavaScript bindings, types and data of the components below; the addons that link them are in its platform packages.`,
+        'The full license text of every component follows.',
+        '',
+        'Effective license expression (also package.json "license"):',
+        '',
+        `    ${expression}`,
+        '',
+        `The machine-readable component inventory is ${SBOM_FILE} next to this file.`,
+        '',
+        'GENERATED by `crossbind licenses --package` - do not edit. This file states facts and is not legal',
+        'advice; the compliance assessment is yours.',
+        '',
+        RULE,
+        '',
+        ...(relinked.length ? [relinkSection({ name, version, repository, projectPath, addonFile, rows: relinked }), '', RULE, ''] : []),
+        formatNoticeSections(rows).join('\n\n'),
+        '',
+    ];
+    return { expression, text: lines.join('\n') };
+}
+
+export function setManifestLicense(dir, expression) {
+    const file = path.join(dir, 'package.json');
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (manifest.license === expression) return;
+    fs.writeFileSync(file, `${JSON.stringify({ ...manifest, license: expression }, null, 4)}\n`);
+}
+
+export function writeNodePackageLicense(dir, meta) {
+    const { expression, text } = nodePackageLicense(meta);
+    fs.writeFileSync(path.join(dir, 'LICENSE'), text);
+    fs.writeFileSync(path.join(dir, SBOM_FILE), formatCycloneDxSbom(meta.rows, { name: meta.name, version: meta.version }));
+    setManifestLicense(dir, expression);
+    return expression;
+}
+
+// What a Node-API package's license names, from its manifest and its place in the repository it builds
+// from: an addon package's is the addon its own build writes.
+export function nodePackageMeta({ package: manifest = {}, paths }) {
+    const repository = typeof manifest.repository === 'string' ? manifest.repository : (manifest.repository?.url ?? '');
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        repository,
+        projectPath: path.relative(paths.base, paths.project).split(path.sep).join('/') || '.',
+        addonFile: manifest.os && /\.node$/.test(manifest.main ?? '') ? manifest.main : null,
+    };
+}

package/src/utils/pthreadMainScript.js

@@ -0,0 +1,14 @@
+// The pthread bootstrap spawns its workers from _scriptName, which the glue captures from document.currentScript
+// when it loads: undefined for a bridge loaded as a module script, so the workers fetch "/undefined" and a
+// direct-mode mt init hangs. The spawn reads Module.crossbindMainScript first, which the browser adapter sets from
+// paths.worker/paths.js (emscripten's own mainScriptUrlOrBlob trips emsdk 6 debug assertions on st targets).
+
+// The release glue spells it `pthreadMainJs=_scriptName`, the debug glue `pthreadMainJs = _scriptName`.
+const SPAWN = /pthreadMainJs\s*=\s*_scriptName/g;
+const MAIN_SCRIPT = 'pthreadMainJs=Module["crossbindMainScript"]||_scriptName';
+
+// Returns the rewritten glue and whether it spawns pthreads from a script this rewrite does not recognise.
+export function spawnPthreadsFromMainScript(glue) {
+    const text = glue.replace(SPAWN, MAIN_SCRIPT);
+    return { text, missed: text.includes('pthreadMainJs') && !text.includes(MAIN_SCRIPT) };
+}

package/src/utils/pullDockerImage.js

@@ -7,8 +7,11 @@ import { getContentHash } from './hash.js';
 const table = createRequire(import.meta.url)('../assets/toolchain-digests.json');
 const REGISTRY = table.registry;
 const IMAGE_VERSION = table.version;
+const OVERRIDE_KEYS = {
+    web: 'CROSSBIND_IMAGE_WEB', android: 'CROSSBIND_IMAGE_ANDROID', linux: 'CROSSBIND_IMAGE_LINUX', windows: 'CROSSBIND_IMAGE_WINDOWS',
+};
 const IMAGES = Object.fromEntries(
-    ['web', 'android'].map((role) => [
+    Object.keys(OVERRIDE_KEYS).map((role) => [
         role,
         {
             ref: `${REGISTRY}/${role}@${table.images[role].index}`,
@@ -17,11 +20,13 @@ const IMAGES = Object.fromEntries(
     ]),
 );
 
-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.
+// Which image a target compiles in: wasm and wasi share the web image, linux and linuxmusl the linux
+// image, ios and darwin never reach docker.
 export function imageRoleFor(target) {
-    return target?.platform === 'android' ? 'android' : 'web';
+    if (target?.platform === 'android' || target?.platform === 'linux') return target.platform;
+    if (target?.platform === 'linuxmusl') return 'linux';
+    if (target?.platform === 'win32') return 'windows';
+    return 'web';
 }
 
 const warned = new Set();

package/src/utils/relocatePrebuilt.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import upath from 'upath';
+
+// pkg-config files, libtool archives, CMake configs and -config scripts record absolute paths of
+// the machine that built them, so a published prebuilt only resolves there. These rewrites make
+// every path relative to where the tree lands; whatever they cannot rewrite is left for the
+// publish gate to report. Some upstream templates also name libstdc++, which no crossbind
+// toolchain links: every one of them builds against libc++.
+
+const PREFIX_VARIABLE = 'crossbind_prefix';
+const ASSIGNMENT = /^(\s*[A-Za-z_][A-Za-z0-9_]*=)(.*)$/;
+const SINGLE_QUOTED = /^'([^']*)'$/;
+const DOUBLE_QUOTED = /^"((?:[^"\\]|\\.)*)"$/;
+const BARE_WORD = /^[^\s'"\\]*$/;
+const EXPANDS_IN_DOUBLE_QUOTES = /[$`"\\]/;
+const PERMISSION_BITS = 0o7777;
+const OWNER_WRITE = 0o200;
+const LIBSTDCXX_FLAG = /(^|[\s"'=])-lstdc\+\+(?=[\s"']|$)/gm;
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const nameLibcxx = (text) => text.replace(LIBSTDCXX_FLAG, '$1-lc++');
+
+const replaceEach = (text, needles, replacement) => needles
+    .reduce((result, needle) => result.replaceAll(needle, () => replacement), text);
+
+// CMake installs programs without the owner write bit, so the rewrite borrows it and gives it back.
+function rewrite(file, before, after) {
+    if (before === after) return;
+    const mode = fs.statSync(file).mode & PERMISSION_BITS;
+    fs.chmodSync(file, mode | OWNER_WRITE);
+    fs.writeFileSync(file, after);
+    fs.chmodSync(file, mode);
+}
+
+function filesUnder(dir) {
+    return fs.readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => upath.join(entry.parentPath, entry.name));
+}
+
+const isUnder = (path, prefixes) => prefixes.some((prefix) => path.startsWith(prefix));
+
+// Another package's files are only known by name once the tree leaves the build machine. Its
+// archive may sit in a lib directory or, from an xcframework, in a slice directory.
+function nameForeignArchives(text, { installPrefixes, buildBases }, spell) {
+    return buildBases.reduce((result, base) => result.replace(
+        new RegExp(`${escapeRegExp(base)}/[^\\s'";]*?/lib([\\w+.-]+)\\.a`, 'g'),
+        (archive, name) => (isUnder(archive, installPrefixes) ? archive : spell(name)),
+    ), text);
+}
+
+// Search paths into other packages, and object files of the build tree such as the WASI runtime
+// stubs a configure build links through LIBS.
+function dropForeignPaths(text, { installPrefixes, buildBases }) {
+    return buildBases.reduce((result, base) => result
+        .replace(
+            new RegExp(`\\s-[LI]${escapeRegExp(base)}/[^\\s'";]*`, 'g'),
+            (flag) => (isUnder(flag.trim().slice(2), installPrefixes) ? flag : ''),
+        )
+        .replace(
+            new RegExp(`\\s${escapeRegExp(base)}/[^\\s'";]*\\.o(?=[\\s'";]|$)`, 'gm'),
+            (object) => (isUnder(object.trim(), installPrefixes) ? object : ''),
+        ), text);
+}
+
+function relocatePkgConfig(file, prefixDir, paths) {
+    const toPrefix = upath.relative(upath.dirname(file), prefixDir);
+    const before = fs.readFileSync(file, 'utf8');
+    const own = replaceEach(before, paths.installPrefixes, `\${pcfiledir}/${toPrefix}`);
+    const foreign = nameForeignArchives(dropForeignPaths(own, paths), paths, (name) => `-l${name}`);
+    rewrite(file, before, nameLibcxx(foreign));
+}
+
+function relocateCMake(file, paths) {
+    const before = fs.readFileSync(file, 'utf8');
+    rewrite(file, before, nameForeignArchives(before, paths, (name) => name));
+}
+
+// The text of an assignment value as it reads between double quotes, or null when its quoting
+// is anything but one plain word.
+function doubleQuotedContent(value) {
+    const single = SINGLE_QUOTED.exec(value);
+    if (single) return EXPANDS_IN_DOUBLE_QUOTES.test(single[1]) ? null : single[1];
+    const double = DOUBLE_QUOTED.exec(value);
+    if (double) return double[1];
+    return BARE_WORD.test(value) ? value : null;
+}
+
+function relocateAssignment(line, installPrefixes) {
+    const match = ASSIGNMENT.exec(line);
+    if (!match || !installPrefixes.some((prefix) => line.includes(prefix))) return line;
+    const content = doubleQuotedContent(match[2]);
+    if (content === null) return line;
+    return `${match[1]}"${replaceEach(content, installPrefixes, `\${${PREFIX_VARIABLE}}`)}"`;
+}
+
+function relocateConfigScript(file, prefixDir, installPrefixes) {
+    const before = fs.readFileSync(file, 'utf8');
+    const lines = before.split('\n');
+    if (!/^#!.*sh/.test(lines[0])) return;
+    const relocated = lines.map((line) => relocateAssignment(line, installPrefixes));
+    const isPrefixRelocated = relocated.some((line, index) => line !== lines[index]);
+    const toPrefix = upath.relative(upath.dirname(file), prefixDir);
+    const definition = `${PREFIX_VARIABLE}=$(cd "$(dirname "$0")/${toPrefix}" && pwd)`;
+    const after = isPrefixRelocated ? [relocated[0], definition, ...relocated.slice(1)] : relocated;
+    rewrite(file, before, nameLibcxx(after.join('\n')));
+}
+
+const isConfigScript = (file) => file.endsWith('-config') && upath.basename(upath.dirname(file)) === 'bin';
+
+export default function relocatePrebuilt(prefixDir, paths) {
+    filesUnder(prefixDir).forEach((file) => {
+        if (file.endsWith('.la')) fs.rmSync(file);
+        else if (file.endsWith('.pc')) relocatePkgConfig(file, prefixDir, paths);
+        else if (file.endsWith('.cmake')) relocateCMake(file, paths);
+        else if (isConfigScript(file)) relocateConfigScript(file, prefixDir, paths.installPrefixes);
+    });
+}

package/src/utils/remoteClient.js

@@ -0,0 +1,127 @@
+// One toolchain step on the remote runner: send what changed below each mount's input roots, stream the
+// step's output, write the files it produced back through the mounts, exit with its exit code.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { walk, hashIndex, presentUnits } from '../runner/files.js';
+import { isHash } from '../runner/blobs.js';
+import { getContentHash } from './hash.js';
+import { outputTarget, writeOutputFile, removeOutputFile } from './remoteOutputs.js';
+import { request, expectOk, uploadMissing } from './remoteUpload.js';
+
+const INDEX_DIR = path.join(os.homedir(), '.crossbind', 'remote-index');
+
+const indexFileOf = (mount) => path.join(INDEX_DIR, `${getContentHash(`${mount.host}\n${mount.container}`).slice(0, 16)}.json`);
+
+function loadIndex(mount) {
+    try {
+        return new Map(Object.entries(JSON.parse(fs.readFileSync(indexFileOf(mount), 'utf8'))));
+    } catch {
+        return new Map();
+    }
+}
+
+function saveIndex(mount, index) {
+    fs.mkdirSync(INDEX_DIR, { recursive: true });
+    fs.writeFileSync(indexFileOf(mount), JSON.stringify(Object.fromEntries(index)));
+}
+
+function describeMount(mount, rules, index) {
+    const { files, dirs } = walk(mount.host, mount.inputRoots, rules);
+    const hashes = hashIndex(mount.host, files, index);
+    const manifest = Object.fromEntries([...hashes].map(([rel, sha256]) => [rel, { sha256, mode: files.get(rel).mode }]));
+    const sources = [...hashes].map(([rel, sha256]) => [sha256, path.join(mount.host, rel)]);
+    return { manifest, dirs, sources };
+}
+
+function writeOutput(target, entry, data, indexes) {
+    if (getContentHash(data) !== entry.sha256) throw new Error(`crossbind: ${target.file} arrived from the remote runner with the wrong content.`);
+    writeOutputFile(target, data, entry.mode);
+    const { size, mtimeMs } = fs.statSync(target.file);
+    indexes.get(target.mount).set(target.rel, { size, mtimeMs, sha256: entry.sha256 });
+}
+
+async function runStep(payload, described, present, indexes, received) {
+    const body = {
+        role: payload.role,
+        image: payload.image,
+        rules: payload.rules,
+        cwd: payload.cwd,
+        argv: payload.argv,
+        env: payload.env,
+        mounts: payload.mounts.map((mount, i) => ({
+            path: mount.container,
+            roots: mount.inputRoots,
+            outputRoots: mount.outputRoots,
+            manifest: described[i].manifest,
+            dirs: described[i].dirs,
+            present: present[i],
+        })),
+    };
+    const response = await request(payload.url, '/v1/exec', { method: 'POST', body: JSON.stringify(body) });
+    if (response.status !== 200) await expectOk(response, 'to run the step');
+
+    const decoder = new TextDecoder();
+    let pending = '';
+    let result = null;
+    const handle = (record) => {
+        if ('exit' in record) result = record;
+        if (record.stdout) process.stdout.write(record.stdout);
+        if (record.stderr) process.stderr.write(record.stderr);
+        if (record.file) {
+            writeOutput(outputTarget(payload.mounts, present, record.file), record, Buffer.from(record.data, 'base64'), indexes);
+            received.add(record.file);
+        }
+    };
+    for await (const chunk of response.body) {
+        pending += decoder.decode(chunk, { stream: true });
+        let newline = pending.indexOf('\n');
+        while (newline !== -1) {
+            if (newline > 0) handle(JSON.parse(pending.slice(0, newline)));
+            pending = pending.slice(newline + 1);
+            newline = pending.indexOf('\n');
+        }
+    }
+    if (!result) throw new Error('crossbind: the remote runner closed the connection before the step finished.');
+    if (result.error) throw new Error(`crossbind: the remote runner failed during the step: ${result.error}.`);
+    return result;
+}
+
+// Outputs too large for the stream are fetched by hash.
+async function writeOutputs(payload, result, present, indexes, received) {
+    for (const [file, entry] of Object.entries(result.outputs).filter(([name]) => !received.has(name))) {
+        const target = outputTarget(payload.mounts, present, file);
+        if (!isHash(entry.sha256)) throw new Error(`crossbind: the remote runner named ${file} without a sha256 digest.`);
+        const response = await request(payload.url, `/v1/blobs/${entry.sha256}`);
+        if (response.status !== 200) throw new Error(`crossbind: could not download ${file} from the remote runner (${response.status}).`);
+        writeOutput(target, entry, Buffer.from(await response.arrayBuffer()), indexes);
+    }
+    result.removed.forEach((file) => {
+        const target = outputTarget(payload.mounts, present, file);
+        removeOutputFile(target);
+        indexes.get(target.mount).delete(target.rel);
+    });
+}
+
+async function main() {
+    const payload = JSON.parse(process.argv[2]);
+    const indexes = new Map(payload.mounts.map((mount) => [mount, loadIndex(mount)]));
+    const described = payload.mounts.map((mount) => describeMount(mount, payload.rules, indexes.get(mount)));
+    await uploadMissing(payload.url, new Map(described.flatMap((d) => d.sources)));
+
+    // The store units this machine holds before the step: the runner sends only the others, and may write only those.
+    const present = payload.mounts.map((mount) => presentUnits(mount.host, mount.outputRoots));
+    const received = new Set();
+    const result = await runStep(payload, described, present, indexes, received);
+    await writeOutputs(payload, result, present, indexes, received);
+    indexes.forEach((index, mount) => saveIndex(mount, index));
+    return result.exit;
+}
+
+main().then(
+    (code) => process.exit(code),
+    (error) => {
+        process.stderr.write(`${error.message}\n`);
+        process.exit(1);
+    },
+);