crossbind 2.0.0-beta.68 → 2.0.0-beta.69

package/README.md

@@ -6,7 +6,7 @@
   <h1>crossbind</h1>
 
   <p>
-    <strong>Import C++ and Rust like JavaScript modules.</strong><br>
+    <strong>Build and ship JS apps. Add C++ and Rust as needed.</strong><br>
     Build, package, and run native libraries across browsers, Node.js, edge
     runtimes, iOS, Android, and WASI, or ship them in a desktop or mobile app.
   </p>

package/package.json

@@ -1,62 +1,72 @@
 {
-    "name": "crossbind",
-    "version": "2.0.0-beta.68",
-    "license": "MIT",
-    "homepage": "https://crossbind.dev",
-    "repository": "https://github.com/crossbind/crossbind.git",
-    "description": "Bind C++ to JavaScript without extra code. crossbind supports WebAssembly and React Native for cross-platform compatibility.",
-    "type": "module",
-    "engines": {
-        "node": ">=24"
+  "name": "crossbind",
+  "version": "2.0.0-beta.69",
+  "license": "MIT",
+  "homepage": "https://crossbind.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "description": "Bind C++ to JavaScript without extra code. crossbind supports WebAssembly and React Native for cross-platform compatibility.",
+  "type": "module",
+  "engines": {
+    "node": ">=26"
+  },
+  "bin": {
+    "crossbind": "./src/cli.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./node/dev": "./src/node/dev.mjs",
+    "./app": {
+      "types": "./src/app/index.d.ts",
+      "default": "./src/app/index.js"
     },
-    "bin": {
-        "crossbind": "./src/cli.js"
+    "./app/core": {
+      "types": "./src/app/index.d.ts",
+      "default": "./src/app/index.js"
     },
-    "main": "src/index.js",
-    "exports": {
-        ".": "./src/index.js",
-        "./node/dev": "./src/node/dev.mjs",
-        "./app": {
-            "types": "./src/app/index.d.ts",
-            "default": "./src/app/index.js"
-        },
-        "./*": "./*"
-    },
-    "scripts": {
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "test:coverage": "vitest run --coverage"
-    },
-    "devDependencies": {
-        "@vitest/coverage-v8": "^5.0.1",
-        "vitest": "^5.0.1"
-    },
-    "dependencies": {
-        "@rollup/plugin-commonjs": "^29.0.3",
-        "@rollup/plugin-json": "^6.1.0",
-        "@rollup/plugin-node-resolve": "^16.0.3",
-        "@rollup/plugin-virtual": "^3.0.2",
-        "comlink": "^4.4.2",
-        "commander": "^15.0.0",
-        "glob": "^14.0.3",
-        "log-update": "^8.0.0",
-        "picocolors": "^1.1.1",
-        "pngjs": "^7.0.0",
-        "replace": "^1.2.2",
-        "rollup": "^4.63.4",
-        "spdx-expression-parse": "^5.0.0",
-        "upath": "^3.0.8"
-    },
-    "keywords": [
-        "webassembly",
-        "react-native",
-        "bind",
-        "c++",
-        "emscripten",
-        "embind",
-        "swig",
-        "android",
-        "ios",
-        "mobile"
-    ]
-}
+    "./*": "./*"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.1",
+    "vitest": "^5.0.1"
+  },
+  "dependencies": {
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-virtual": "^3.0.2",
+    "comlink": "^4.4.2",
+    "commander": "^15.0.0",
+    "glob": "^14.0.3",
+    "log-update": "^8.0.0",
+    "picocolors": "^1.1.1",
+    "pngjs": "^7.0.0",
+    "replace": "^1.2.2",
+    "rollup": "^4.63.4",
+    "spdx-expression-parse": "^5.0.0",
+    "upath": "^3.0.8"
+  },
+  "optionalDependencies": {
+    "@crossbind/bridge-tools": "2.0.0-beta.69"
+  },
+  "keywords": [
+    "webassembly",
+    "react-native",
+    "bind",
+    "c++",
+    "emscripten",
+    "embind",
+    "swig",
+    "android",
+    "ios",
+    "mobile"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/actions/addExtension.js

@@ -0,0 +1,191 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { configFileOf, writeExtension } from '../utils/configWriter.js';
+import { isUnderBase } from '../utils/replaceBasePathForDocker.js';
+import { ownPackages } from '../utils/appExtensions.js';
+import resolveAppHostRoot from '../utils/resolveAppHost.js';
+
+// The lockfiles by which a project names the package manager it is installed with.
+const LOCKFILES = [
+    ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm'],
+];
+const MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+// A package as a registry names it, with a version, tag or range after an @; a tarball's file name is none.
+const REGISTRY_SPEC = /^((?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*)(?:@.+)?$/;
+const TARBALL = /\.(tgz|tar|tar\.gz)$/;
+// What a package may be given as on Windows, which runs npm, pnpm and yarn in a shell: nothing the shell reads more into.
+const WINDOWS_SPEC = /^[\w@/\\.~:+=#-]+$/;
+// What a package's crossbind.extension may name: a module of its own, as ./crossbind.extension.js.
+const EXTENSION_ENTRY = /^\.\/(?:[\w-][\w.-]*\/)*[\w-][\w.-]*\.m?js$/;
+
+// Whether a package's exports let another import a module of its by its subpath, as Node resolves one: a package
+// without exports gives every file, and one whose exports name no subpath gives its main module alone.
+function isExported(exports, entry) {
+    if (exports === undefined) return true;
+    if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) return false;
+    if (Object.hasOwn(exports, entry)) return exports[entry] !== null;
+    const pattern = Object.keys(exports).filter((key) => key.startsWith('./') && key.includes('*'))
+        .sort((a, b) => b.length - a.length)
+        .find((key) => {
+            const [head, tail] = key.split('*');
+            return entry.length >= head.length + tail.length && entry.startsWith(head) && entry.endsWith(tail);
+        });
+    return pattern !== undefined && exports[pattern] !== null;
+}
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+// The words module code keeps, which can name no import.
+const RESERVED = new Set(('arguments await break case catch class const continue debugger default delete do else enum eval '
+    + 'export extends false finally for function if implements import in instanceof interface let new null package private '
+    + 'protected public return static super switch this throw true try typeof var void while with yield').split(' '));
+
+const foldersUp = (dir) => (path.dirname(dir) === dir ? [dir] : [dir, ...foldersUp(path.dirname(dir))]);
+
+// The package manager a project is installed with: the one its nearest lockfile names, else the one that runs
+// crossbind, else npm.
+export function packageManagerOf(project, userAgent) {
+    for (const dir of foldersUp(project)) {
+        const lockfile = LOCKFILES.find(([file]) => fs.existsSync(path.join(dir, file)));
+        if (lockfile) return lockfile[1];
+    }
+    const launcher = userAgent?.split('/')[0];
+    return MANAGERS.includes(launcher) ? launcher : 'npm';
+}
+
+// The package a spec names on a registry, or null where it is a path, a tarball or a repository.
+export function registryName(spec) {
+    return TARBALL.test(spec) ? null : (REGISTRY_SPEC.exec(spec)?.[1] ?? null);
+}
+
+// The name a config imports an extension under: its package's, without the scope and an extension- prefix, in
+// camelCase, with Extension after a word module code keeps.
+export function importNameOf(packageName) {
+    const words = packageName.replace(/^@[^/]+\//, '').replace(/^(crossbind-)?extension-/, '').split(/[^a-zA-Z0-9]+/).filter(Boolean);
+    const camel = words.map((word, i) => (i === 0 ? word : `${word[0].toUpperCase()}${word.slice(1)}`)).join('');
+    if (!/^[a-zA-Z]/.test(camel)) return `extension${camel}`;
+    return RESERVED.has(camel) ? `${camel}Extension` : camel;
+}
+
+const dependencyNames = (manifest) => {
+    const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    return new Set(DEPENDENCY_FIELDS.flatMap((field) => Object.keys(pkg[field] ?? {})));
+};
+
+// The folder of an installed package, as Node finds it from the project: in the nearest node_modules that has it.
+const packageDir = (project, name) => foldersUp(project).map((dir) => path.join(dir, 'node_modules', name))
+    .find((dir) => fs.existsSync(path.join(dir, 'package.json')));
+
+const commonFolder = (a, b) => {
+    const [partsA, partsB] = [a.split(path.sep), b.split(path.sep)];
+    const length = partsA.findIndex((part, i) => part !== partsB[i]);
+    return partsA.slice(0, length === -1 ? partsA.length : length).join(path.sep) || path.sep;
+};
+
+// Installs the spec into the project with its package manager, as its owner would at a terminal.
+function install(manager, spec, project, platform, spawn) {
+    const args = [manager === 'npm' ? 'install' : 'add', spec];
+    const command = [manager, ...args].join(' ');
+    console.log(`crossbind: ${command}`);
+    // On Windows npm, pnpm and yarn are .cmd files, which a shell alone runs; WINDOWS_SPEC keeps what it reads out of the
+    // spec.
+    const result = platform === 'win32'
+        ? spawn(command, { cwd: project, stdio: 'inherit', shell: true })
+        : spawn(manager, args, { cwd: project, stdio: 'inherit' });
+    if (result.error) {
+        throw new Error(`crossbind: ${manager} did not start (${result.error.message}): install it, or install ${spec} with the package manager you use and run crossbind add with its name.`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`crossbind: ${command} failed, so crossbind.config.js lists nothing new: install ${spec} yourself, then run crossbind add with its name.`);
+    }
+}
+
+// The spec as a package manager would take it, or why not: a spec that opens with a dash is an option to it.
+function assertSpec(spec, platform) {
+    if (spec.startsWith('-')) throw new Error(`crossbind: crossbind add takes a package, and ${spec} is an option to a package manager.`);
+    if (platform === 'win32' && !WINDOWS_SPEC.test(spec)) {
+        throw new Error(`crossbind: on Windows crossbind add takes a package's name, with a version or tag after an @, or its path, without spaces, quotes or ^&|<>%!() for the shell its package manager runs in to read: install ${spec} yourself, then run crossbind add with its name.`);
+    }
+}
+
+// An extension an app has by having the host is none to add. A project without a host yet has none of them.
+function assertNotOwn(spec) {
+    const name = registryName(spec);
+    let root;
+    try {
+        root = resolveAppHostRoot();
+    } catch {
+        return;
+    }
+    if (ownPackages(root).includes(name)) {
+        throw new Error(`crossbind: an app has ${name} by having @crossbind/core-app-host, which brings it, so there is nothing to add; an extension takes its place with replaces, as extensions.md says.`);
+    }
+}
+
+// The installed package the spec named: the one the install added to package.json, as a spec's own text names no package
+// for every package manager, else the one a registry spec names, which package.json had already.
+function installedName(spec, before, after, manifest) {
+    const added = [...after].filter((name) => !before.has(name));
+    const registry = registryName(spec);
+    const name = added.length === 1 ? added[0] : (added.length === 0 && after.has(registry) && registry);
+    if (!name) {
+        throw new Error(`crossbind: crossbind add cannot tell which package ${spec} is, as ${manifest} gained ${added.length === 0 ? 'none' : 'more than one'}: run crossbind add with its name once this project's package.json lists it.`);
+    }
+    return { name, isAdded: added.length === 1 };
+}
+
+// Installs an extension's package into an app and lists it in crossbind.config.js's extensions; a package that
+// package.json has already, given by its name alone, is listed without installing it again.
+export default function addExtension(spec, {
+    config, env = process.env, platform = process.platform, spawn = spawnSync,
+}) {
+    if (config.target.runtimeEnv !== 'app') {
+        throw new Error("crossbind: an extension builds into an app, which this project is not: set target: { runtimeEnv: 'app' } in crossbind.config.js, as the desktop-app template does.");
+    }
+    assertSpec(spec, platform);
+    assertNotOwn(spec);
+    const { project, base } = config.paths;
+    const manifest = path.join(project, 'package.json');
+    if (!fs.existsSync(manifest)) throw new Error(`crossbind: crossbind add installs into the project's package.json, which ${project} has none of.`);
+    const manager = packageManagerOf(project, env.npm_config_user_agent);
+    const before = dependencyNames(manifest);
+    if (registryName(spec) === spec && before.has(spec)) console.log(`crossbind: package.json has ${spec} already.`);
+    else install(manager, spec, project, platform, spawn);
+    const { name, isAdded } = installedName(spec, before, dependencyNames(manifest), manifest);
+    const dir = packageDir(project, name);
+    if (!dir) throw new Error(`crossbind: ${name} is in package.json, but not installed: run ${manager} install.`);
+    const removal = isAdded ? ` ${manager} ${manager === 'npm' ? 'uninstall' : 'remove'} ${name} removes it.` : '';
+    const own = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const entry = own.crossbind?.extension;
+    if (typeof entry !== 'string') {
+        throw new Error(`crossbind: ${name} is installed, but it is no crossbind extension: its package.json has no crossbind.extension.${removal}`);
+    }
+    if (!EXTENSION_ENTRY.test(entry)) {
+        throw new Error(`crossbind: ${name}'s crossbind.extension, ${JSON.stringify(entry)}, is no module of its own as ./crossbind.extension.js is, so crossbind.config.js lists nothing new.${removal}`);
+    }
+    if (!fs.statSync(path.join(dir, entry), { throwIfNoEntry: false })?.isFile()) {
+        throw new Error(`crossbind: ${name}'s crossbind.extension names ${entry}, which its package has not, so crossbind.config.js lists nothing new.${removal}`);
+    }
+    if (!isExported(own.exports, entry)) {
+        throw new Error(`crossbind: ${name}'s package.json exports no ${entry}, which crossbind.config.js would import, so it lists nothing new: its exports has to give it, as "./crossbind.extension.js": "./crossbind.extension.js" does.${removal}`);
+    }
+    // A build sees paths.base alone, and an extension's root is where its files are, links followed.
+    const real = fs.realpathSync(dir);
+    if (!isUnderBase(real, base)) {
+        // A Windows project's path comes with forward slashes, its real path with backslashes.
+        const home = path.resolve(project);
+        const above = path.relative(home, commonFolder(home, real)).split(path.sep).join('/') || '.';
+        throw new Error(`crossbind: ${name} is in ${real}, outside paths.base, ${base}, which is all a build sees, so crossbind.config.js lists nothing new: set paths: { base: '${above}' } in it, a folder above both, and run crossbind add ${name} again.`);
+    }
+    const specifier = `${name}/${entry.slice(2)}`;
+    const identifier = importNameOf(name);
+    const written = writeExtension(project, specifier, identifier);
+    if (!written) {
+        throw new Error(`crossbind: ${name} is installed, but ${path.basename(configFileOf(project) ?? 'crossbind.config.js')} is no config crossbind can list it in safely: write import ${identifier} from '${specifier}' and extensions: [${identifier}()] into it yourself.`);
+    }
+    const file = path.basename(written.file);
+    console.log(written.isListed
+        ? `crossbind: ${file} lists ${name} already, as ${written.identifier}().`
+        : `crossbind: listed ${name} in ${file} as ${written.identifier}(), which crossbind app build builds in.`);
+    return { name, ...written };
+}

package/src/actions/androidGradle.js

@@ -14,7 +14,9 @@ import { secretFile } from '../utils/secretFile.js';
 const ROLE = 'android-app';
 const PLATFORM = 'linux/amd64';
 const KEYSTORE = '/tmp/crossbind/keystore';
-const GRADLE = ['gradle', '--offline', '--no-watch-fs', '--console=plain', '-q'];
+// An extension's Kotlin compiles inside Gradle's own process: with the container's home /, the Kotlin daemon's client
+// walked files for hours looking for a daemon to use.
+const GRADLE = ['gradle', '--offline', '--no-watch-fs', '--console=plain', '-q', '-Pkotlin.compiler.execution.strategy=in-process'];
 const OUTPUT_LIMIT = 64 * 1024 * 1024;
 const FAILURE_LINES = 40;
 
@@ -74,11 +76,16 @@ function homes() {
     return [[path.join(root, 'gradle'), '/var/cache/crossbind/gradle'], [path.join(root, 'home'), '/var/cache/crossbind/android']];
 }
 
-// A container of crossbind's android-app image, with no network: the project under the build's base, the homes, and
-// the keystore read-only, its passwords passed by name from this environment.
-function containerArgs(signing) {
+// A project whose extensions ask Maven for libraries carries the verification metadata of every file it resolves, and
+// resolves what the image's cache lacks online; any other builds offline against the cache alone.
+const isOnline = (project) => fs.existsSync(path.join(project, 'gradle', 'verification-metadata.xml'));
+const gradleOf = (project) => (isOnline(project) ? GRADLE.filter((arg) => arg !== '--offline') : GRADLE);
+
+// A container of crossbind's android-app image, with no network but for an online project: the project under the
+// build's base, the homes, and the keystore read-only, its passwords passed by name from this environment.
+function containerArgs(signing, isNetworked = false) {
     return [
-        ...DOCKER_RUN_SECURITY_ARGS, '--network', 'none', '--platform', PLATFORM, '--user', getOsUserAndGroupId(),
+        ...DOCKER_RUN_SECURITY_ARGS, ...(isNetworked ? [] : ['--network', 'none']), '--platform', PLATFORM, '--user', getOsUserAndGroupId(),
         '-v', `${state.config.paths.base}:${DOCKER_BASE}`,
         ...homes().flatMap(([host, container]) => {
             fs.mkdirSync(host, { recursive: true });
@@ -113,8 +120,8 @@ export function packageAndroidRelease(project) {
     const env = key ? { ...process.env, ...uploadKeyEnv(key) } : process.env;
     const signing = releaseSigning(env);
     pullDockerImage(ROLE, PLATFORM);
-    docker(['run', '--rm', ...containerArgs(signing), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
-        ...GRADLE, '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`, env);
+    docker(['run', '--rm', ...containerArgs(signing, isOnline(project)), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
+        ...gradleOf(project), '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`, env);
     const outputs = `${project}/app/build/outputs`;
     fs.copyFileSync(`${outputs}/apk/release/app-release.apk`, `${project}.apk`);
     fs.rmSync(`${project}.aab`, { force: true });
@@ -132,25 +139,27 @@ export function packageAndroidRelease(project) {
 }
 
 // During development one container per project, whose Gradle daemon stays warm from one build to the next; it goes with
-// the process.
+// the process, and comes anew when the project comes to need the network, or no longer does.
 let devContainer = null;
 
-function startDevContainer() {
+function startDevContainer(isNetworked) {
     const name = `crossbind-android-app-${getContentHash(state.config.paths.project).slice(0, 12)}`;
     pullDockerImage(ROLE, PLATFORM);
-    // One a crashed session left behind holds the name.
+    // One a crashed session, or the project's need of the network before, left behind holds the name.
     spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' });
-    docker(['run', '--detach', '--rm', '--init', '--name', name, ...containerArgs(null), getDockerImage(ROLE, PLATFORM), 'sleep', 'infinity'],
+    docker(['run', '--detach', '--rm', '--init', '--name', name, ...containerArgs(null, isNetworked), getDockerImage(ROLE, PLATFORM), 'sleep', 'infinity'],
         'starting the development container');
-    process.once('exit', () => spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' }));
-    // A closed terminal ends the session through its exit hooks, as Ctrl-C does.
-    process.once('SIGHUP', () => process.exit(129));
-    return name;
+    if (!devContainer) {
+        process.once('exit', () => spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' }));
+        // A closed terminal ends the session through its exit hooks, as Ctrl-C does.
+        process.once('SIGHUP', () => process.exit(129));
+    }
+    return { name, isNetworked };
 }
 
 // Builds an Android app's Gradle project as a debug APK, signed with the debug key the homes keep, and returns the APK.
 export function buildApk(project) {
-    devContainer ??= startDevContainer();
-    docker(['exec', '-w', inContainer(project), devContainer, ...GRADLE, 'assembleDebug'], `building ${path.basename(project)}`);
+    if (devContainer?.isNetworked !== isOnline(project)) devContainer = startDevContainer(isOnline(project));
+    docker(['exec', '-w', inContainer(project), devContainer.name, ...gradleOf(project), 'assembleDebug'], `building ${path.basename(project)}`);
     return path.join(project, 'app', 'build', 'outputs', 'apk', 'debug', 'app-debug.apk');
 }