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

package/src/utils/rustMt.js

@@ -4,6 +4,9 @@ import path from 'node:path';
 // One argv per flag: runCargo joins these with cargo's 0x1F separator, so a flag must not
 // contain a space of its own.
 const MT_RUSTFLAGS = ['-Ctarget-feature=+atomics,+bulk-memory,+mutable-globals'];
+// A musl std links Rust's own static libunwind under crt-static, its default; the addon's C++ already
+// unwinds through libgcc_s, and one module must not carry two unwinders.
+const MUSL_RUSTFLAGS = ['-Ctarget-feature=-crt-static'];
 
 // mt (shared-memory) wasm needs every Rust object built with the atomics/bulk-memory features,
 // std included - and rustup ships only a featureless std. The nightly-only -Zbuild-std rebuild
@@ -66,6 +69,7 @@ export function cargoBuildInvocation({
         rustflags: [
             ...(wasmSysroot ? ['--sysroot', wasmSysroot] : []),
             ...(isMt ? MT_RUSTFLAGS : []),
+            ...(target.platform === 'linuxmusl' ? MUSL_RUSTFLAGS : []),
         ],
         panic: target.platform === 'wasm' ? 'abort' : undefined,
         // Only the nightly build-std rebuild needs unstable flags; where a sysroot answers, stable

package/src/utils/scopedEmbind.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+
+// Every package's loader bundles its own embind runtime, which keeps its state, and the functions its addon calls by
+// name, on globalThis and Module. Shadowing both gives each bundle a scope of its own with the real global as its
+// prototype, which the loader hands to its addon: addons of several packages then run in one process.
+export default function scopedEmbind(embindFile) {
+    const realPath = (file) => {
+        try {
+            return fs.realpathSync(file);
+        } catch (e) {
+            return file;
+        }
+    };
+    const embind = realPath(embindFile);
+    return {
+        name: 'crossbind-scoped-embind',
+        transform(code, id) {
+            if (realPath(id) !== embind) return null;
+            return `const globalThis = Object.create(global);\nconst Module = (globalThis.Module = {});\n${code}\nexport { globalThis as crossbindScope };\n`;
+        },
+    };
+}

package/src/utils/selectRunner.js

@@ -0,0 +1,81 @@
+import { cloudCredentials, cloudUrl } from './cloudAccount.js';
+import logger from './logger.js';
+import systemKeys, { assertRunner } from './systemKeys.js';
+
+const RUNNER_VARIABLE = 'CROSSBIND_RUNNER';
+const SYSTEM_CONFIG = '~/.crossbind.json';
+const SHARED = { key: 'REMOTE_URL', url: 'CROSSBIND_REMOTE_URL', token: 'CROSSBIND_TOKEN' };
+
+export const remoteVariables = (role) => {
+    const suffix = `_${role.toUpperCase()}`;
+    return { key: `${SHARED.key}${suffix}`, url: `${SHARED.url}${suffix}`, token: `${SHARED.token}${suffix}` };
+};
+
+// Unchecked, so commands that run no step still work with an invalid RUNNER, `crossbind config set` among them.
+function runnerSetting(system, env) {
+    if (env[RUNNER_VARIABLE]) return { runner: env[RUNNER_VARIABLE], name: RUNNER_VARIABLE };
+    return { runner: system?.RUNNER ?? systemKeys.RUNNER.default, name: `RUNNER in ${SYSTEM_CONFIG}` };
+}
+
+export function chosenRunner(system, env = process.env) {
+    const { runner, name } = runnerSetting(system, env);
+    return assertRunner(runner, name);
+}
+
+export const isLocalRunner = (system, env = process.env) => runnerSetting(system, env).runner === 'LOCAL';
+
+// A variable wins over the same key in the system config, and an image's own address over the shared one.
+// A token goes only to the address it is paired with, so a shared token never reaches the runner of one image.
+function remoteAddress(role, system, env) {
+    for (const names of [remoteVariables(role), SHARED]) {
+        const url = env[names.url] || system?.[names.key];
+        if (url) {
+            const from = env[names.url] ? `$${names.url}` : `${names.key} in ${SYSTEM_CONFIG}`;
+            if (!['http:', 'https:'].includes(URL.parse(url)?.protocol)) {
+                throw new Error(`crossbind: ${from} is ${JSON.stringify(url)}, not an http or https address.`);
+            }
+            return {
+                url, from, token: env[names.token], tokenVariable: names.token,
+            };
+        }
+    }
+    return null;
+}
+
+const announced = new Set();
+
+// Each image says once which runner its steps go to and which settings sent them there.
+function announce(role, remote, env) {
+    const key = `${role} ${remote.url}`;
+    if (announced.has(key)) return;
+    announced.add(key);
+    const chosenBy = env[RUNNER_VARIABLE] ? `$${RUNNER_VARIABLE}` : SYSTEM_CONFIG;
+    const shown = remote.url.replace(/\/\/[^/]*@/, '//');
+    logger.info(`crossbind: ${role} steps run on the runner at ${shown} (RUNNER=REMOTE from ${chosenBy}, address from ${remote.from}).`);
+}
+
+// A runner address named anywhere, for any image, keeps every image off the cloud: the sources go only where the
+// user sends them.
+const namesOwnRunner = (system, env) => Object.keys(systemKeys).some((key) => key.startsWith(SHARED.key) && system?.[key])
+    || Object.keys(env).some((name) => name.startsWith(SHARED.url) && env[name]);
+
+// The sign-in of `crossbind login` carries its own token; a token set for runners never reaches the cloud.
+function cloudAddress(role, system, env) {
+    const url = cloudUrl(system, env);
+    const signedIn = cloudCredentials(url);
+    if (!signedIn) return null;
+    return {
+        url: `${url}/runner/${role}`, from: `crossbind login as ${signedIn.login}`, token: signedIn.token, tokenVariable: null,
+    };
+}
+
+// Under REMOTE, an image runs on its own address, else the shared one; a machine that names no runner address at all
+// runs on crossbind cloud once signed in. Without any it gets no runner: its steps stop instead of running in the
+// local Docker, where the build would only seem to run on a runner.
+export function runnerFor(role, system, env = process.env) {
+    const runner = chosenRunner(system, env);
+    if (runner !== 'REMOTE') return { runner };
+    const remote = remoteAddress(role, system, env) ?? (namesOwnRunner(system, env) ? null : cloudAddress(role, system, env));
+    if (remote) announce(role, remote, env);
+    return { runner, remote };
+}

package/src/utils/sourceFingerprint.js

@@ -6,12 +6,13 @@ import { getContentHash } from './hash.js';
 // version, with provenance and licence metadata already claiming the new one.
 export const SOURCE_FINGERPRINT_FILE = 'crossbind-source.fingerprint';
 
-export function getSourceFingerprint(config) {
+export function getSourceFingerprint(config, target) {
     const nativeVersion = config?.package?.nativeVersion || null;
     const sha256 = config?.build?.sha256 || null;
-    // Packages that build from local sources pin neither; they keep the existence-only behaviour.
+    // Local-source packages pin neither; buildLib checks their native source inventory instead.
     if (!nativeVersion && !sha256) return null;
-    return getContentHash(JSON.stringify({ nativeVersion, sha256 }));
+    const sourceReplacements = target ? config?.build?.sourceReplaceList?.(target, config.allDependencyPaths?.[target.path] ?? {}) : undefined;
+    return getContentHash(JSON.stringify({ nativeVersion, sha256, ...(sourceReplacements?.length ? { sourceReplacements } : {}) }));
 }
 
 export function isSourceFingerprintStale(libdir, fingerprint) {

package/src/utils/swigInterface.js

@@ -1,4 +1,5 @@
 import upath from 'upath';
+import { ALL_NAMES } from './headerImports.js';
 
 // Libraries whose headers are not self-contained (spatialite expects sqlite3.h first) list the
 // prerequisites in export.headerPrelude of the package that ships the header: its output or project
@@ -15,6 +16,29 @@ export function findIgnoredDeclarations(headerFile, configs, headerPath) {
     return findHeaderOption('ignoredDeclarations', headerFile, configs, headerPath);
 }
 
+// SWIG preprocessor lines a package puts right before one of its public headers, in export.swigPreamble: GDAL hides
+// its C SRS API behind `#ifndef SWIG` for its own bindings, and picks VSIStatBufL's typedef by whether VSI_STAT64_T is
+// defined, which a macro defined as itself answers while each platform's compiler still resolves the name.
+export function findSwigPreamble(headerFile, configs, headerPath) {
+    return findHeaderOption('swigPreamble', headerFile, configs, headerPath);
+}
+
+// Includes SWIG reads inlined into one of a package's headers, in export.swigInlineIncludes. SWIG reads no #include, and
+// libgeotiff fills its key and code enums from .inc files included inside the enum bodies, where the file markers
+// -includeall wraps around an included file do not parse.
+export function findSwigInlineIncludes(headerFile, configs, headerPath) {
+    return findHeaderOption('swigInlineIncludes', headerFile, configs, headerPath);
+}
+
+const INCLUDE_LINE = /^[ \t]*#[ \t]*include[ \t]*"([^"]+)"[^\n]*$/gm;
+
+export function inlineIncludes(headerText, names, readInclude) {
+    const included = new Set([...headerText.matchAll(INCLUDE_LINE)].map(([, name]) => name));
+    const missing = names.filter((name) => !included.has(name));
+    if (missing.length) throw new Error(`crossbind: swigInlineIncludes lists ${missing.join(', ')}, which the header does not include.`);
+    return headerText.replace(INCLUDE_LINE, (line, name) => (names.includes(name) ? readInclude(name) : line));
+}
+
 function findHeaderOption(option, headerFile, configs, headerPath) {
     const file = upath.normalize(headerFile);
     let owner = null;
@@ -39,31 +63,59 @@ export function interfaceIncludes(headerPath, prelude = []) {
 
 // The prelude and the completing includes reach only the compiled wrapper and swigMacros only SWIG's parse: SWIG still
 // wraps just the imported header. The ignored declarations follow the macros, so the retry without macros keeps them.
-export function buildInterfaceContent({ moduleName, headerPath, prelude = [], completing = [], swigMacros = [], ignored = [] }) {
+export function buildInterfaceContent({
+    moduleName, headerPath, prelude = [], completing = [], swigMacros = [], ignored = [], constants = [], preamble = [], functions = ALL_NAMES,
+    extras = [],
+}) {
     const includes = [...new Set([...interfaceIncludes(headerPath, prelude), ...completing])]
         .map((header) => `#include "${header}"`)
         .join('\n');
     const macros = swigMacros.length ? `${swigMacros.join('\n')}\n\n` : '';
     const ignores = ignored.length ? `${ignored.map((name) => `%ignore ${name};`).join('\n')}\n\n` : '';
+    // The marker keeps a preamble that starts with #define apart from the macro block the retry drops.
+    const preambleBlock = preamble.length ? `// package preamble\n${preamble.join('\n')}\n\n` : '';
+    const extraBlock = extras.length ? `${extras.join('\n')}\n\n` : '';
+    // Named constants are asked for ahead of the macros, which may define one. Every constant is asked for after them:
+    // SWIG binds an interface's own #define lines, and the prelude only carries other headers' values for the parse.
+    const everyConstant = constants === ALL_NAMES;
     const module = moduleName.replace(/\W/g, '_');
     return `#ifndef _${module}_I
 #define _${module}_I
 
 %module ${module}
 
-%{
+${extraBlock}%{
 ${includes}
 %}
 
-%feature("shared_ptr");
+${everyConstant ? '' : constantRequests(constants)}%feature("shared_ptr");
 %feature("polymorphic_shared_ptr");
 
-${macros}${ignores}%include "${headerPath}"
+${macros}${functionRequests(functions)}${ignores}${preambleBlock}${everyConstant ? constantRequests(constants) : ''}%include "${headerPath}"
 
 #endif
 `;
 }
 
+// SWIG binds a constant only on request, so a header's thousands of macros cost nothing until the app imports one.
+function constantRequests(constants) {
+    if (constants === ALL_NAMES) return '%feature("embind:constant");\n\n';
+    return constants.length ? `${constants.map((name) => `%feature("embind:constant") ${name};`).join('\n')}\n\n` : '';
+}
+
+// SWIG ignores every global function, then wraps the listed names again: class members, enums and constants stay. The
+// package's own ignores come after, since SWIG applies the later of two renames of a name.
+function functionRequests(functions) {
+    if (functions === ALL_NAMES) return '';
+    const names = [...new Set(functions)].sort();
+    return `%rename($ignore, %$isfunction, %$isglobal) "";\n${names.map((name) => `%rename("%s") ${name};\n`).join('')}\n`;
+}
+
+// Editor declarations need the whole header even when the compiled bridge selects functions by import.
+export function interfaceWithAllFunctions(content) {
+    return content.replace(/%rename\(\$ignore, %\$isfunction, %\$isglobal\) "";\n(?:%rename\("%s"\) [A-Za-z_]\w*;\n)*\n/g, '');
+}
+
 export function withoutSwigMacros(content) {
     return content.replace(/(%feature\("polymorphic_shared_ptr"\);\n\n)(?:#define [^\n]*\n)+\n/, '$1');
 }
@@ -111,7 +163,7 @@ const tokenize = (text) => text.match(TOKEN) ?? [];
 const identifiers = (text) => tokenize(text).filter((token) => IDENTIFIER.test(token));
 // Lines are spliced before comments go, as in the compiler, and a comment marker inside a literal is text.
 const LITERAL_OR_COMMENT = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
-const stripComments = (text) => text
+export const stripComments = (text) => text
     .replace(/\\\r?\n/g, ' ')
     .replace(LITERAL_OR_COMMENT, (match) => (match.startsWith('/') ? ' ' : match));
 
@@ -154,7 +206,7 @@ function headerReferences(headerText) {
 // SWIG parses only the imported header, so export, linkage and attribute macros from its #includes read as syntax
 // errors. Those come from the compiler's macro table, with the flags and versions its #if lines test; type and value
 // macros stay undefined so every platform's compiler resolves them.
-export function selectSwigMacros({ headerText, macros, predefined }) {
+export function selectSwigMacros({ headerText, macros, predefined, constants = [] }) {
     const memoize = (classify) => {
         const results = new Map();
         const check = (name) => {
@@ -190,6 +242,14 @@ export function selectSwigMacros({ headerText, macros, predefined }) {
     };
     declarations.forEach((name) => forward(name, isSyntax));
     conditions.forEach((name) => forward(name, isConstant));
+    // An imported constant reaches SWIG with the macros its value uses, so SWIG can type it: SWIG reads no #include, and
+    // drops a constant whose value uses a macro it has not seen.
+    const isObjectConstant = (name) => !macros.get(name).params && isConstant(name);
+    const imported = constants === ALL_NAMES ? [...defined] : constants;
+    imported.forEach((name) => {
+        if (!defined.has(name)) forward(name, isObjectConstant);
+        else identifiers(macros.get(name)?.body ?? '').forEach((token) => forward(token, isObjectConstant));
+    });
 
     const visible = new Set([
         ...tokenize(stripComments(headerText)),
@@ -318,6 +378,26 @@ function walkScopes(text, visit) {
     });
 }
 
+// Whether the token at `index` sits inside the parentheses of the declaration it belongs to: a prototype's parameter.
+function isInsideParentheses(tokens, index) {
+    let depth = 0;
+    for (let at = index - 1; at >= 0 && ![';', '{', '}'].includes(tokens[at]); at -= 1) {
+        if (tokens[at] === '(') depth += 1;
+        else if (tokens[at] === ')') depth -= 1;
+    }
+    return depth > 0;
+}
+
+// Whether a variable `name` is declared outside every class, namespace and block, as `extern int name;` is.
+export function declaresAtFileScope(text, name) {
+    let found = false;
+    walkScopes(text, (token, index, tokens, scopes) => {
+        if (token === name && scopes.every((scope) => scope.kind === 'extern') && [';', '=', '[', ','].includes(tokens[index + 1])
+            && !isInsideParentheses(tokens, index)) found = true;
+    });
+    return found;
+}
+
 // Classes, structs and enums by qualified name, including the names C typedefs give them, each mapped to the first header
 // defining it. Preprocessor branches are all read.
 export function indexTypeDefinitions(files) {

package/src/utils/systemKeys.js

@@ -4,12 +4,36 @@ const systemKeys = {
         default: '',
     },
     RUNNER: {
-        description: 'The execution environment for running the application.',
-        options: ['DOCKER_RUN', 'DOCKER_EXEC', 'LOCAL'],
+        description: 'Where toolchain steps run: DOCKER_RUN, DOCKER_EXEC, LOCAL, or REMOTE on the runners REMOTE_URL and REMOTE_URL_<IMAGE> name; a machine that names none builds on crossbind cloud once signed in with crossbind login. The CROSSBIND_RUNNER environment variable overrides it.',
+        options: ['DOCKER_RUN', 'DOCKER_EXEC', 'LOCAL', 'REMOTE'],
         default: 'DOCKER_RUN',
     },
+    REMOTE_URL: {
+        description: 'Under RUNNER=REMOTE, the runner of every image without an address of its own. Its token comes from the CROSSBIND_TOKEN environment variable. The CROSSBIND_REMOTE_URL environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_WEB: {
+        description: 'Under RUNNER=REMOTE, the runner of the web image: wasm builds, wasi builds and the bridge steps of every platform but android. Token: CROSSBIND_TOKEN_WEB. The CROSSBIND_REMOTE_URL_WEB environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_ANDROID: {
+        description: 'Under RUNNER=REMOTE, the runner of the android image. Token: CROSSBIND_TOKEN_ANDROID. The CROSSBIND_REMOTE_URL_ANDROID environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_LINUX: {
+        description: 'Under RUNNER=REMOTE, the runner of the linux image (linux and linuxmusl builds). Token: CROSSBIND_TOKEN_LINUX. The CROSSBIND_REMOTE_URL_LINUX environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_WINDOWS: {
+        description: 'Under RUNNER=REMOTE, the runner of the windows image (win32 builds). Token: CROSSBIND_TOKEN_WINDOWS. The CROSSBIND_REMOTE_URL_WINDOWS environment variable overrides it.',
+        default: '',
+    },
+    CLOUD_URL: {
+        description: 'The crossbind cloud that crossbind login, logout and usage talk to. The CROSSBIND_CLOUD_URL environment variable overrides it.',
+        default: 'https://api.crossbind.dev',
+    },
     WASI_SDK_PATH: {
-        description: 'Path to an extracted wasi-sdk (>= 34, wasm32-wasip3 sysroot) used by platform:\'wasi\' builds. The CROSSBIND_WASI_SDK_PATH environment variable overrides it.',
+        description: 'Path to an extracted wasi-sdk (>= 34, wasm32-wasip3 sysroot) that platform:\'wasi\' builds use under RUNNER=LOCAL; the other runners use the sdk in the image. The CROSSBIND_WASI_SDK_PATH environment variable overrides it.',
         default: '',
     },
     DOCKER_REGISTRY_MIRROR: {
@@ -24,6 +48,22 @@ const systemKeys = {
         description: 'Image reference used for android builds instead of the pinned one. A reference without the release digest disables the reproducibility guarantee. The CROSSBIND_IMAGE_ANDROID environment variable overrides it.',
         default: '',
     },
+    DOCKER_IMAGE_LINUX: {
+        description: 'Image reference used for linux (Node.js addon) builds instead of the pinned one. A reference without the release digest disables the reproducibility guarantee. The CROSSBIND_IMAGE_LINUX environment variable overrides it.',
+        default: '',
+    },
+    DOCKER_IMAGE_WINDOWS: {
+        description: 'Image reference used for win32 (Node.js addon) builds instead of the pinned one. A reference without the release digest disables the reproducibility guarantee. The CROSSBIND_IMAGE_WINDOWS environment variable overrides it.',
+        default: '',
+    },
 };
 
 export default systemKeys;
+
+// Read as LOCAL, a runner crossbind does not know would run recipes and build scripts on the host.
+export function assertRunner(runner, name = 'RUNNER') {
+    if (!systemKeys.RUNNER.options.includes(runner)) {
+        throw new Error(`crossbind: the runner ${runner} is invalid; ${name} is one of ${systemKeys.RUNNER.options.join(', ')}.`);
+    }
+    return runner;
+}

package/src/utils/targets.js

@@ -1,7 +1,7 @@
 // Single source for the build-target matrix and its naming; state/ copies (and then
 // decorates) these entries, and consumer runtimes read them without touching CLI state.
 
-export const TARGETS = [
+const BASE_TARGETS = [
     {
         platform: 'wasm', arch: 'wasm32', runtime: 'st', buildType: 'release', runtimeEnv: 'browser',
     },
@@ -63,10 +63,10 @@ export const TARGETS = [
         platform: 'wasm', arch: 'wasm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
     },
     {
-        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'release',
+        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'release', runtimeEnv: 'wasi',
     },
     {
-        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'debug',
+        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'debug', runtimeEnv: 'wasi',
     },
     {
         platform: 'android', arch: 'arm64-v8a', runtime: 'mt', buildType: 'release',
@@ -92,12 +92,113 @@ export const TARGETS = [
     {
         platform: 'ios', arch: 'iphonesimulator', runtime: 'mt', buildType: 'debug',
     },
+    {
+        platform: 'darwin', arch: 'arm64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'darwin', arch: 'arm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'darwin', arch: 'x64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'darwin', arch: 'x64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linux', arch: 'arm64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linux', arch: 'arm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linux', arch: 'x64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linux', arch: 'x64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'arm64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'arm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'x64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'x64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'win32', arch: 'arm64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'win32', arch: 'arm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'win32', arch: 'x64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'win32', arch: 'x64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+];
+
+// A native executable links the same archives as the Node-API addon of its platform and arch.
+export const TARGETS = [
+    ...BASE_TARGETS,
+    ...BASE_TARGETS
+        .filter((target) => target.runtimeEnv === 'node' && target.platform !== 'wasm')
+        .map((target) => ({ ...target, runtimeEnv: 'native' })),
 ];
 
+// Built only when named with -p: a plain `crossbind build` keeps producing what it did before
+// native Node.js addons existed.
+export const OPT_IN_PLATFORMS = ['darwin', 'linux', 'linuxmusl', 'win32'];
+
+// Built on the host itself: Apple's linker and SDKs exist in no toolchain image.
+export const HOST_BUILT_PLATFORMS = ['ios', 'darwin'];
+
+// The runtime environment names the binary a build makes; android and ios have none, since
+// React Native links them.
+export const runtimeEnvsOf = (platform) => [
+    ...new Set(TARGETS.filter((target) => target.platform === platform && target.runtimeEnv).map((target) => target.runtimeEnv)),
+];
+
+export const RUNTIME_ENVS = [...new Set(TARGETS.map((target) => target.runtimeEnv).filter(Boolean))];
+
+// A build makes only the binaries it is asked for: -e first, then the config's target.runtimeEnv.
+// Bundler plugins ask through getTargetParams instead.
+export function selectRuntimeEnvs(cliRuntimeEnvs, configRuntimeEnv) {
+    if (cliRuntimeEnvs?.length) return cliRuntimeEnvs;
+    return configRuntimeEnv ? [configRuntimeEnv] : [];
+}
+
 export function targetPathOf(target) {
     return `${target.platform}-${target.arch}-${target.runtime}-${target.buildType}`;
 }
 
+// The release build of a target, whose prebuilts a debug build of it falls back to.
+export const releaseTargetOf = (target) => ({ ...target, buildType: 'release', path: target.releasePath });
+
+// Every platform/arch addon of one build type sits next to a single loader, which fills in
+// {platform} and {arch} from the running process. The loader is CommonJS whatever the package
+// "type" says, since it needs __dirname and process.dlopen.
+export function nodeAddonNamesOf(target, projectName) {
+    const suffix = target.buildType === 'debug' ? '.debug' : '';
+    const addonPattern = `${projectName}.{platform}-{arch}${suffix}.node`;
+    return {
+        addonPattern,
+        addonName: addonPattern.replace('{platform}', target.platform).replace('{arch}', target.arch),
+        jsName: `${projectName}.native${suffix}.cjs`,
+    };
+}
+
+// One executable per platform, arch and build type, named like the addons it replaces.
+export function nativeCommandNamesOf(target, projectName) {
+    const suffix = target.buildType === 'debug' ? '.debug' : '';
+    const extension = target.platform === 'win32' ? '.exe' : '';
+    return { commandName: `${projectName}.${target.platform}-${target.arch}${suffix}${extension}` };
+}
+
 export function filterTargetSpecs(targetSpecs, target) {
     return targetSpecs?.filter(t => (
         (!t.platform || t.platform === target.platform)

package/src/utils/toolchainNotices.js

@@ -0,0 +1,5 @@
+// Where a build keeps the notices of the runtime a toolchain image linked into its binaries,
+// relative to the build directory; crossbind licenses reads them from there.
+export default function toolchainNoticesDir(platform) {
+    return `toolchain-licenses/${platform}`;
+}

package/src/utils/wasiToolchain.js

@@ -1,5 +1,7 @@
 // Toolchain surface for platform:'wasi' (wasm32-wasip3, wasi-sdk >= 34; run under `wasmtime`).
 
+import { isLocalRunner } from './selectRunner.js';
+
 export const WASI_TARGET_TRIPLE = 'wasm32-wasip3';
 // The sdk's clang still defaults to wasip1, so every compile/link carries --target explicitly.
 export const WASI_TARGET_FLAGS = [`--target=${WASI_TARGET_TRIPLE}`];
@@ -31,6 +33,7 @@ export const WASI_LINK_LIBS = [
     '-lunwind',
     '-lsetjmp',
     ...WASI_EMULATION_LIBS,
+    '-Wl,--wrap=lseek',
 ];
 
 export function wasiCFlags() {
@@ -41,7 +44,17 @@ export function wasiCxxFlags() {
     return [...WASI_TARGET_FLAGS, ...WASI_COMPILE_DEFINES, '-fwasm-exceptions', ...WASI_EH_CFLAGS];
 }
 
-// Env override first, then persistent ~/.crossbind.json; null when unset.
+// The host sdk of a RUNNER=LOCAL build: env override first, then persistent ~/.crossbind.json; null when
+// unset, and under the other runners, whose builds use the sdk in the image.
 export function resolveWasiSdkPath(system, env = process.env) {
+    if (!isLocalRunner(system, env)) return null;
     return env.CROSSBIND_WASI_SDK_PATH || system?.WASI_SDK_PATH || null;
 }
+
+// Recipes read the wasi-sdk location from the environment (lazily, in getBuildParams), so it names
+// the sdk the build uses: the host's under RUNNER=LOCAL, none (the image's) under the other runners.
+export function exportWasiSdkPath(system, env = process.env) {
+    const sdk = resolveWasiSdkPath(system, env);
+    if (sdk) env.CROSSBIND_WASI_SDK_PATH = sdk;
+    else delete env.CROSSBIND_WASI_SDK_PATH;
+}

package/src/utils/windowsToolchain.js

@@ -0,0 +1,18 @@
+// The windows image's llvm-mingw and its CMake toolchain files, one per target triple: port archives and
+// Conan packages link into the same addon, so they move together.
+const LLVM_MINGW = '/opt/llvm-mingw';
+const WINDOWS_TOOLCHAIN = '/opt/crossbind/windows';
+const WINDOWS_TRIPLES = { x64: 'x86_64-w64-mingw32', arm64: 'aarch64-w64-mingw32' };
+
+export const windowsTriple = (target) => WINDOWS_TRIPLES[target.arch];
+export const windowsToolchainFile = (target) => `${WINDOWS_TOOLCHAIN}/${windowsTriple(target)}.cmake`;
+export const windowsTool = (target, name) => `${LLVM_MINGW}/bin/${windowsTriple(target)}-${name}`;
+
+// The compilers, archive and resource 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 target's, so pkg-config reads none.
+export const windowsBuildEnv = (target) => ({
+    ...Object.fromEntries(Object.entries({
+        CC: 'clang', CXX: 'clang++', AR: 'ar', RANLIB: 'ranlib', NM: 'nm', STRIP: 'strip', RC: 'windres', WINDRES: 'windres',
+    }).map(([variable, tool]) => [variable, windowsTool(target, tool)])),
+    PKG_CONFIG_LIBDIR: '',
+});

package/vitest.config.js

@@ -12,6 +12,17 @@ export default defineConfig({
     test: {
         include: ['test/**/*.test.js'],
         environment: 'node',
+        // A developer's own runner settings must not decide where the tested steps run, and neither must their
+        // crossbind login: no one signs in to a cloud at this address.
+        env: {
+            CROSSBIND_RUNNER: '',
+            CROSSBIND_REMOTE_URL: '',
+            CROSSBIND_REMOTE_URL_WEB: '',
+            CROSSBIND_REMOTE_URL_ANDROID: '',
+            CROSSBIND_REMOTE_URL_LINUX: '',
+            CROSSBIND_REMOTE_URL_WINDOWS: '',
+            CROSSBIND_CLOUD_URL: 'http://127.0.0.1:9',
+        },
         coverage: {
             provider: 'v8',
             reporter: ['text', 'html'],

package/src/utils/cppFieldBindings.js

@@ -1,23 +0,0 @@
-// SWIG's -embind backend emits functions and constructors but no member variables, so
-// public fields never reach JS from the generated bridge alone. This post-pass injects
-// embind .property lines for the value-semantics fields parseCppSurface captured - the
-// same post-processing precedent as bridgeAsyncGuard.
-
-export function buildFieldPropertyLines(cls) {
-    return (cls.fields ?? []).map((f) => `.property("${f.name}", &${cls.name}::${f.name})`);
-}
-
-export function injectFieldBindings(bridgeContent, model) {
-    let out = bridgeContent;
-    for (const cls of model.classes ?? []) {
-        const lines = buildFieldPropertyLines(cls)
-            .filter((line) => !out.includes(line));
-        if (!lines.length) continue;
-        // Lazy template match still lands on the right opener: the first `>(\s*"Name")`
-        // closes the template list even when it contains nested arguments like base<T>.
-        const opener = new RegExp(`(emscripten::class_<[\\s\\S]*?>\\s*\\(\\s*"${cls.name}"\\s*\\))`);
-        if (!opener.test(out)) continue;
-        out = out.replace(opener, `$1\n    ${lines.join('\n    ')}`);
-    }
-    return out;
-}