crossbind 2.0.0-beta.62 → 2.0.0-beta.63

package/src/utils/downloadAndExtractFile.js

@@ -4,14 +4,23 @@ import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import logger from './logger.js';
 
-export default async function downloadAndExtractFile(url, output, sha256) {
+// Upstream hosts drop a request now and then (ftp.gnu.org refused eight parallel libiconv fetches at once), so a
+// request that failed for a passing reason is tried again after these pauses. Any other 4xx is the server's answer.
+const RETRY_DELAYS_MS = [1000, 2000, 4000];
+const RETRYABLE_STATUS = new Set([408, 429]);
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const retryable = (error) => Object.assign(error, { retryable: true });
+
+export default async function downloadAndExtractFile(url, output, sha256, options = {}) {
     const archive = path.basename(url);
     if (fs.existsSync(`${output}/source`) && sourceCameFrom(output, archive)) {
         return false;
     }
     fs.rmSync(`${output}/source`, { recursive: true, force: true });
-    const filePath = await downloadFile(url, output);
+    const filePath = await downloadFile(url, output, options);
     verifyIntegrity(filePath, url, sha256);
     extractArchive(filePath, url, output);
     fs.writeFileSync(`${output}/source.archive`, archive);
@@ -86,29 +95,47 @@ export function assertHttps(target, context = target) {
 
 // fetch follows redirects itself, which release downloads rely on (github and the osgeo
 // mirrors both bounce), so the download needs no redirect library of its own.
-export async function downloadFile(url, folder) {
+export async function downloadFile(url, folder, { retryDelaysMs = RETRY_DELAYS_MS } = {}) {
     mkdirSync(folder, { recursive: true });
     const dest = `${folder}/${path.basename(url)}`;
     if (fs.existsSync(dest)) return dest;
 
     assertHttps(url);
+    for (let attempt = 1; ; attempt += 1) {
+        try {
+            await fetchTo(url, dest);
+            return dest;
+        } catch (err) {
+            if (!err.retryable) throw err;
+            if (attempt > retryDelaysMs.length) {
+                throw new Error(`${err.message} (after ${attempt} attempts)`, { cause: err });
+            }
+            const delay = retryDelaysMs[attempt - 1];
+            logger.info(`${err.message} Trying again in ${delay / 1000}s…`);
+            await sleep(delay);
+        }
+    }
+}
+
+async function fetchTo(url, dest) {
     let response;
     try {
         response = await fetch(url, { headers: { 'User-Agent': 'curl/8.7.1' }, redirect: 'follow' });
     } catch (err) {
-        throw new Error(`crossbind: cannot reach ${url}: ${err.message}`, { cause: err });
+        throw retryable(new Error(`crossbind: cannot reach ${url}: ${err.message}`, { cause: err }));
     }
     // A redirect chain must not be able to downgrade the transport on its last hop.
     if (response.url) assertHttps(response.url, `${url} (redirected to ${response.url})`);
     if (!response.ok) {
-        throw new Error(`crossbind: download failed for ${url} — HTTP ${response.status}.`);
+        await response.body?.cancel();
+        const error = new Error(`crossbind: download failed for ${url} — HTTP ${response.status}.`);
+        throw response.status >= 500 || RETRYABLE_STATUS.has(response.status) ? retryable(error) : error;
     }
     try {
         await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(dest));
     } catch (err) {
         // A half-written archive would fail its hash check later with a confusing message.
         fs.rmSync(dest, { force: true });
-        throw new Error(`crossbind: download failed for ${url}: ${err.message}`, { cause: err });
+        throw retryable(new Error(`crossbind: download failed for ${url}: ${err.message}`, { cause: err }));
     }
-    return dest;
 }

package/src/utils/embindArgumentGuards.js

@@ -36,10 +36,49 @@ export function guardBigIntArguments(glue) {
     return { text, missed: text.includes('_embind_register_bigint') && !text.includes('Number.isSafeInteger(value)') };
 }
 
+// The debug glue the dev servers load spells both registrations over lines, and its integer conversion already
+// throws for anything but a number or a boolean, so the member and character conversions go ahead of that check.
+// Each applies inside its own registration only: the debug float conversion reads the same as the integer one.
+const DEBUG_GUARDS = [
+    {
+        registration: '__embind_register_integer',
+        end: 'readValueFromPointer: integerReadValueFromPointer(',
+        from: /toWireType: \(destructors, value\) => \{(\s*)(?=if \(typeof value != ["']number["'])/,
+        to: 'toWireType: (destructors, value) => {$1'
+            + 'if (typeof value == "string" && size == 1 && value.length == 1) value = value.charCodeAt(0);$1'
+            + 'if (value !== null && typeof value == "object" && typeof value.value == "number") value = value.value;$1',
+        applied: 'value = value.charCodeAt(0);',
+    },
+    {
+        registration: '__embind_register_enum',
+        end: 'readValueFromPointer: enumReadValueFromPointer(',
+        from: /toWireType: \(destructors, c\) => c\.value,/,
+        to: 'toWireType: (destructors, c) => {'
+            + 'if (typeof c == "number") return c;'
+            + 'if (c !== null && typeof c == "object" && typeof c.value == "number") return c.value;'
+            + 'throw new TypeError(name + " takes a member of the enum or its number, got " + (typeof c == "string" ? JSON.stringify(c) : c === null ? "null" : typeof c))'
+            + '},',
+        applied: 'takes a member of the enum or its number',
+    },
+];
+
+function guardDebugRegistration(glue, { registration, end, from, to, applied }) {
+    const start = glue.indexOf(`var ${registration} = `);
+    const stop = start < 0 ? -1 : glue.indexOf(end, start);
+    if (stop < 0) return { text: glue, missed: false };
+    const code = glue.slice(start, stop);
+    if (code.includes(applied)) return { text: glue, missed: false };
+    const rewritten = code.replace(from, to);
+    return { text: glue.slice(0, start) + rewritten + glue.slice(stop), missed: rewritten === code };
+}
+
 // Returns the rewritten glue and the registrations whose code no longer looks the way these rewrites expect.
 export function guardEmbindArguments(glue) {
     const missed = GUARDS.filter(({ registration, from, to }) => glue.includes(`${registration}=`) && !glue.includes(from) && !glue.includes(to))
         .map(({ registration }) => registration);
-    const text = GUARDS.reduce((current, { from, to }) => current.split(from).join(to), glue);
-    return { text, missed };
+    const released = GUARDS.reduce((current, { from, to }) => current.split(from).join(to), glue);
+    return DEBUG_GUARDS.reduce(({ text, missed: names }, guard) => {
+        const result = guardDebugRegistration(text, guard);
+        return { text: result.text, missed: result.missed ? [...names, guard.registration] : names };
+    }, { text: released, missed });
 }

package/src/utils/embindCallArguments.js

@@ -0,0 +1,19 @@
+// Linked with -sDYNAMIC_EXECUTION=0, embind's craftInvokerFunction keeps argsWired, invokerFuncArgs and
+// destructors once per bound function, shared by all its calls. A call frees its arguments from there
+// once it returns, or once its promise settles for an async (_JSPI) function, so a call started before
+// then overwrites them and the earlier call frees the later call's arguments instead of its own, which
+// leak: two pending calls of one _JSPI method, or a method called again from a JavaScript callback it
+// runs. Emscripten 6.0.9 builds it this way, as did upstream main on 2026-09-30; this rewrite declares
+// the three inside the invoker, so each call gets its own.
+
+// The release glue spells it on one line, the debug glue one statement per line with an argument
+// count check first.
+const SHARED = /var argsWired\s*=\s*new Array\(expectedArgCount\);\s*var invokerFuncArgs\s*=\s*\[\];\s*var destructors\s*=\s*\[\];\s*var invokerFn\s*=\s*function\s*\(\.\.\.args\)\s*\{(\s*(?:checkArgCount\([^;]*\);\s*)?)destructors\.length\s*=\s*0;/g;
+const PER_CALL = 'var invokerFn=function(...args){$1var argsWired=new Array(expectedArgCount);var invokerFuncArgs=[];var destructors=[];';
+const SEPARATED = /var invokerFn\s*=\s*function\s*\(\.\.\.args\)\s*\{\s*(?:checkArgCount\([^;]*\);\s*)?var argsWired\s*=/;
+
+// Returns the rewritten glue and whether it still holds an invoker this rewrite does not recognise.
+export function separateCallArguments(glue) {
+    const text = glue.replace(SHARED, PER_CALL);
+    return { text, missed: text.includes('argsWired') && !SEPARATED.test(text) };
+}

package/src/utils/embindJspiQueue.js

@@ -0,0 +1,25 @@
+// JSPI suspends a call's wasm frames, but its C stack frames stay on the one stack every call of the module shares,
+// and Emscripten 6.0.9 gives a suspended call no stack of its own: a call that resumes after a later one started
+// returns over that one's frames, which the later one still uses. This rewrite runs the module's async (_JSPI)
+// bindings one at a time, as Asyncify runs its async operations: a call made while another is pending enters wasm
+// once that one settles. embind still converts the arguments when the call is made, so a wrong one throws there.
+
+// The release glue spells it on one line, the debug glue across lines.
+const PROMISING = /rtn\s*=\s*WebAssembly\.promising\(rtn\)/g;
+const QUEUED = 'rtn=crossbindJspiQueue(WebAssembly.promising(rtn))';
+const REQUIRE_FUNCTION = /var embind__requireFunction\s*=/;
+// Declared in the module factory, so each instance queues on its own, as each has its own C stack.
+const QUEUE = 'var crossbindJspiQueue=(()=>{var pending=null;return fn=>(...args)=>{'
+    + 'var call=pending?pending.then(()=>fn(...args)):fn(...args);'
+    + 'var settled=pending=call.then(()=>{},()=>{});'
+    + 'settled.then(()=>{if(pending===settled)pending=null});'
+    + 'return call}})();';
+
+// Returns the rewritten glue and whether it holds a promising export this rewrite does not recognise.
+export function queueJspiCalls(glue) {
+    const text = glue.replace(PROMISING, QUEUED);
+    if (text === glue || !REQUIRE_FUNCTION.test(text)) {
+        return { text: glue, missed: glue.includes('WebAssembly.promising(rtn') && !glue.includes(QUEUED) };
+    }
+    return { text: text.replace(REQUIRE_FUNCTION, (declaration) => `${QUEUE}${declaration}`), missed: false };
+}

package/src/utils/execContainer.js

@@ -0,0 +1,49 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import getOsUserAndGroupId from './getOsUserAndGroupId.js';
+
+function samePath(a, b) {
+    const real = (p) => {
+        try {
+            return fs.realpathSync(p);
+        } catch {
+            return path.resolve(p);
+        }
+    };
+    return real(a) === real(b);
+}
+
+// docker exec attaches to a container the user created, so nothing else checks what it mounts. A
+// container without a tool's cache mount keeps that cache inside itself, where the host reads paths
+// that were never written: fail first, with the way to fix it.
+export default function assertExecContainer({ name, mounts, workdir, hint, mountNote }) {
+    let info;
+    try {
+        // stderr is dropped: docker's own "No such container" would land before the message below.
+        info = JSON.parse(execFileSync('docker', ['container', 'inspect', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }))[0];
+    } catch {
+        throw new Error(`crossbind: RUNNER=DOCKER_EXEC needs a container named '${name}', which does not exist.\n${hint}`);
+    }
+    if (!info?.State?.Running) {
+        throw new Error(
+            `crossbind: the container '${name}' exists but is not running. Start it with \`docker start ${name}\`, or recreate it.\n${hint}`,
+        );
+    }
+    for (const [destination, source] of mounts) {
+        const mount = (info.Mounts ?? []).find((m) => m.Destination === destination);
+        if (!mount || !samePath(mount.Source, source)) {
+            const found = mount ? ` - it mounts ${mount.Source} there` : '';
+            throw new Error(
+                `crossbind: the container '${name}' does not mount ${source} at ${destination}${found}. ${mountNote}\n${hint}`,
+            );
+        }
+    }
+    // `docker run --workdir` creates the directory; `docker exec --workdir` does not, and the tool
+    // dies with an OCI "chdir to cwd" error that names nothing the user can act on.
+    try {
+        execFileSync('docker', ['exec', '--user', getOsUserAndGroupId(), name, 'mkdir', '-p', workdir], { stdio: 'ignore' });
+    } catch (e) {
+        throw new Error(`crossbind: could not create the working directory ${workdir} inside '${name}'.\n${hint}`, { cause: e });
+    }
+}

package/src/utils/headerImports.js

@@ -7,9 +7,14 @@ export const ALL_NAMES = '*';
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 // The clause shapes are spelled out, so a match cannot run from one statement into the next.
 const HEADER_IMPORT = /\b(import|export)\s+(type\s+)?((?:[A-Za-z_$][\w$]*\s*,\s*)?(?:\{[^}]*\}|\*(?:\s*as\s+[A-Za-z_$][\w$]*)?)|[A-Za-z_$][\w$]*)\s*from\s*(['"])([^'"\n]+)\4/g;
+// `import('x.h')`, `import 'x.h'` and `require('x.h')` hand the app the whole module. A lazy import may carry a bundler
+// comment (`/* webpackChunkName: "x" */`) or a template literal. A comment ends at its first `*/`, so a run of them
+// matches one way only.
+const WHOLE_MODULE = /\b(?:import\s*\(\s*(?:\/\*(?:[^*]|\*(?!\/))*\*\/\s*)*|import\s+|require\s*\(\s*)(['"`])([^'"`$\n]+)\1/g;
 
+// A comment runs to its first `*/`, or to the end when it never closes, so each is read once.
 function listedNames(list) {
-    return list.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '').split(',')
+    return list.replace(/\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|\/\/[^\n]*/g, '').split(',')
         .map((entry) => entry.trim())
         .filter((entry) => entry && !/^type\s/.test(entry))
         .map((entry) => entry.split(/\s+as\s+/)[0])
@@ -19,13 +24,19 @@ function listedNames(list) {
 // A specifier built at run time is not found.
 export function findHeaderImports(text, headerExtensions) {
     const isHeader = new RegExp(`\\.(${headerExtensions.join('|')})$`);
-    return [...text.matchAll(HEADER_IMPORT)].flatMap(([, , type, clause, , specifier]) => {
+    const listed = [...text.matchAll(HEADER_IMPORT)].flatMap(([, , type, clause, , specifier]) => {
         if (type || !isHeader.test(specifier)) return [];
-        const list = clause.match(/\{([^}]*)\}/);
-        if (clause.replace(list?.[0] ?? '', '').includes('*')) return [{ specifier, names: ALL_NAMES }];
-        const names = listedNames(list?.[1] ?? '');
+        const open = clause.indexOf('{');
+        const close = open === -1 ? -1 : clause.indexOf('}', open);
+        const hasList = close !== -1;
+        if ((hasList ? clause.slice(0, open) + clause.slice(close + 1) : clause).includes('*')) return [{ specifier, names: ALL_NAMES }];
+        const names = listedNames(hasList ? clause.slice(open + 1, close) : '');
         return names.length ? [{ specifier, names }] : [];
     });
+    const whole = [...text.matchAll(WHOLE_MODULE)]
+        .filter(([, , specifier]) => isHeader.test(specifier))
+        .map(([, , specifier]) => ({ specifier, names: ALL_NAMES }));
+    return [...listed, ...whole];
 }
 
 const scanned = new Map();

package/src/utils/hostPlatform.js

@@ -0,0 +1,21 @@
+// What `-p host` builds: the platform whose binaries this machine runs. Node reports glibc and musl
+// Linux alike; as the addon loader decides, a glibc process names its glibc in the report header.
+export default function hostPlatform(platform = process.platform, readReport = processReport) {
+    if (platform !== 'linux') return platform;
+    const header = readReport()?.header;
+    return !header || header.glibcVersionRuntime ? 'linux' : 'linuxmusl';
+}
+
+export const resolveHostPlatform = (platforms, host = hostPlatform()) => platforms.map((platform) => (platform === 'host' ? host : platform));
+
+function processReport() {
+    if (!process.report) return undefined;
+    // Only the header is read; the network section can stall on DNS lookups.
+    const { excludeNetwork } = process.report;
+    process.report.excludeNetwork = true;
+    try {
+        return process.report.getReport();
+    } finally {
+        process.report.excludeNetwork = excludeNetwork;
+    }
+}

package/src/utils/iosToolchain.js

@@ -0,0 +1,6 @@
+// The Xcode every iOS archive is built with, and the deployment target it is built for: port archives
+// and Conan packages link into the same app, so they move together.
+export const IOS_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
+export const XCODE_TOOLCHAIN_BIN = `${IOS_DEVELOPER_DIR}/Toolchains/XcodeDefault.xctoolchain/usr/bin`;
+// Xcode 27 refuses deployment targets below 15.0; React Native's own floor is 15.1.
+export const IOS_DEPLOYMENT_TARGET = '15.1';

package/src/utils/isSourceCmakePackage.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+
+// A cmake package that ships its sources rather than a prebuilt: its own CMakeLists (at the package root, not a
+// generated dist/prebuilt one) is compiled into the consuming build via add_subdirectory.
+export default function isSourceCmakePackage(config) {
+    return config.export?.type === 'cmake'
+        && config.paths.cmake !== config.paths.cliCMakeListsTxt
+        && !config.paths.cmakeDir.endsWith('/prebuilt')
+        && fs.existsSync(config.paths.cmake);
+}

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/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,
+    };
+}