crossbind 2.0.0-beta.63 → 2.0.0-beta.65

package/AGENTS.md

@@ -4,7 +4,8 @@
 
 ## What lives here
 
-- `src/bin.js` — `crossbind` CLI entry; commander commands, target filtering and top-level orchestration.
+- `src/cli.js` — `crossbind` CLI entry: `login`, `logout`, `usage`, `account`, `config` and `--version` run from `src/program.js` without loading a project (only `config list -t all|project` loads it); every other command goes to `src/bin.js`.
+- `src/bin.js` — the commands that need a project; commander commands, target filtering and top-level orchestration.
 - `src/index.js` — public API barrel re-exported as the `crossbind` npm package (`createLib`, `buildWasm`, `state`, `getData`, `isSourceNewer`, …).
 - `src/actions/` — the actual build steps. **Most edits land here.**
 - `src/state/` — config loading + target matrix.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "crossbind",
-    "version": "2.0.0-beta.63",
+    "version": "2.0.0-beta.65",
     "license": "MIT",
     "homepage": "https://crossbind.dev",
     "repository": "https://github.com/crossbind/crossbind.git",
@@ -10,7 +10,7 @@
         "node": ">=24"
     },
     "bin": {
-        "crossbind": "./src/bin.js"
+        "crossbind": "./src/cli.js"
     },
     "main": "src/index.js",
     "exports": {

package/src/actions/androidDevice.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { ANDROID_ABIS } from './gradleProject.js';
+import { EXEC_MAX_BUFFER } from './run.js';
+
+const ACTIVITY = 'dev.crossbind.app.CrossbindActivity';
+
+// The adb that reaches the device: the one on PATH, else the platform tools of ANDROID_HOME's SDK or Android Studio's.
+// crossbind installs none.
+function adbPath() {
+    const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT
+        || path.join(os.homedir(), process.platform === 'darwin' ? 'Library/Android/sdk' : 'Android/Sdk');
+    const found = [...(process.env.PATH ?? '').split(path.delimiter).map((dir) => path.join(dir, 'adb')), path.join(sdk, 'platform-tools', 'adb')]
+        .find((file) => fs.statSync(file, { throwIfNoEntry: false })?.isFile());
+    if (!found) {
+        throw new Error('crossbind: an Android app runs on a device through adb, which is not on PATH nor in an Android SDK. Install Android\'s platform tools: `brew install --cask android-platform-tools` on macOS, `sudo apt install adb` on Debian and Ubuntu, or Android Studio.');
+    }
+    return found;
+}
+
+function tool(program, args, options = {}) {
+    const result = spawnSync(program, args, { encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER, ...options });
+    if (result.status !== 0) {
+        throw new Error(`crossbind: ${path.basename(program)} ${args.join(' ')} failed: ${`${result.stdout ?? ''}${result.stderr ?? ''}`.trim() || result.error?.message}`);
+    }
+    return result.stdout;
+}
+
+const adb = (args) => tool(adbPath(), args);
+// adb shell hands the device's shell one line, which splits it again.
+const quoted = (text) => `'${String(text).replace(/'/g, "'\\''")}'`;
+
+// The device an app runs on in development and in tests: the one ANDROID_SERIAL names, else the only one attached, and
+// the ABI of it the app builds for. crossbind starts no emulator.
+export function attachedDevice() {
+    const serials = adb(['devices']).split('\n').slice(1).map((line) => line.trim().split('\t'))
+        .filter(([, status]) => status === 'device').map(([serial]) => serial);
+    const serial = process.env.ANDROID_SERIAL || (serials.length === 1 ? serials[0] : null);
+    if (!serial) {
+        throw new Error(serials.length === 0
+            ? 'crossbind: no Android device is attached. Start an emulator, in Android Studio\'s Device Manager or with `emulator -avd <name>`, or connect a phone with USB debugging on.'
+            : `crossbind: ${serials.length} Android devices are attached (${serials.join(', ')}). Set ANDROID_SERIAL to the one the app runs on.`);
+    }
+    const abis = adb(['-s', serial, 'shell', 'getprop', 'ro.product.cpu.abilist']).trim().split(',');
+    const abi = abis.find((one) => ANDROID_ABIS.includes(one));
+    if (!abi) throw new Error(`crossbind: the Android device ${serial} runs ${abis.join(', ')}, and apps build for ${ANDROID_ABIS.join(' and ')}.`);
+    return { serial, abi };
+}
+
+// Installs an APK on the attached device and opens it, with `env` as the activity's extras; a dev server's page on this
+// machine reaches the device through adb reverse. The process returned carries the app's log, its page's console among
+// it, and ends with the app; close() ends the app.
+export default function openOnDevice(apk, { env = {}, stdio = 'pipe' } = {}) {
+    const { serial } = attachedDevice();
+    const id = JSON.parse(fs.readFileSync(path.join(path.dirname(apk), 'output-metadata.json'), 'utf8')).applicationId;
+    try {
+        adb(['-s', serial, 'install', '-r', '-d', apk]);
+    } catch (error) {
+        if (!error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE')) throw error;
+        // As the one Google Play installs: only an uninstall replaces it, which takes its data, so the developer runs it.
+        throw new Error(`crossbind: ${id} on ${serial} is signed with another key than this build, so it cannot be updated; \`adb -s ${serial} uninstall ${id}\` removes it, with its data, and the next run installs this one.`, { cause: error });
+    }
+    const devPort = env.CROSSBIND_APP_URL && new URL(env.CROSSBIND_APP_URL).port;
+    if (devPort) adb(['-s', serial, 'reverse', `tcp:${devPort}`, `tcp:${devPort}`]);
+    const extras = Object.entries(env).flatMap(([key, value]) => ['--es', key, quoted(value)]);
+    adb(['-s', serial, 'shell', 'am', 'start', '-S', '-W', '-n', `${id}/${ACTIVITY}`, ...extras]);
+    const pid = spawnSync(adbPath(), ['-s', serial, 'shell', 'pidof', id], { encoding: 'utf8' }).stdout?.trim();
+    if (!pid) throw new Error(`crossbind: ${id} stopped as it started on ${serial}; its log is in \`adb logcat\`.`);
+    // The log of the app's process alone, without the divider logcat starts with, until the process ends. The pattern
+    // that ends logcat names it first, so it matches not the shell whose command line holds it too.
+    const logcat = `logcat -v raw --pid=${pid} -s Crossbind:V`;
+    const child = spawn(adbPath(), ['-s', serial, 'shell',
+        `${logcat} | grep -v '^--------- ' & while [ -d /proc/${pid} ]; do sleep 1; done; pkill -f '^${logcat}'`], { stdio });
+    return { child, close: () => spawnSync(adbPath(), ['-s', serial, 'shell', 'am', 'force-stop', id]) };
+}

package/src/actions/androidGradle.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import state from '../state/index.js';
+import getOsUserAndGroupId from '../utils/getOsUserAndGroupId.js';
+import pullDockerImage, { getDockerImage } from '../utils/pullDockerImage.js';
+import { DOCKER_BASE, isUnderBase } from '../utils/replaceBasePathForDocker.js';
+import { DOCKER_RUN_SECURITY_ARGS } from '../utils/dockerSecurity.js';
+import { getContentHash } from '../utils/hash.js';
+
+const ROLE = 'android-app';
+const PLATFORM = 'linux/amd64';
+const KEYSTORE = '/tmp/crossbind/keystore';
+const GRADLE = ['gradle', '--offline', '--no-watch-fs', '--console=plain', '-q'];
+const OUTPUT_LIMIT = 64 * 1024 * 1024;
+const FAILURE_LINES = 40;
+
+// The upload key a release is signed with, named by the environment alone so that no secret reaches a file.
+export const SIGNING = {
+    keystore: 'CROSSBIND_ANDROID_KEYSTORE',
+    alias: 'CROSSBIND_ANDROID_KEY_ALIAS',
+    password: 'CROSSBIND_ANDROID_KEYSTORE_PASSWORD',
+    keyPassword: 'CROSSBIND_ANDROID_KEY_PASSWORD',
+};
+
+const listed = (names) => `${names.join(' and ')} ${names.length > 1 ? 'are' : 'is'}`;
+
+// The keystore of the upload key, or null for none: a release is then signed with the debug key.
+export function releaseSigning(env = process.env) {
+    if (!env[SIGNING.keystore]) {
+        const stray = [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]);
+        if (stray.length) throw new Error(`crossbind: ${listed(stray)} set without ${SIGNING.keystore}, the keystore of the upload key.`);
+        return null;
+    }
+    const missing = [SIGNING.alias, SIGNING.password].filter((name) => !env[name]);
+    if (missing.length) throw new Error(`crossbind: ${SIGNING.keystore} is set, but ${listed(missing)} not.`);
+    const file = path.resolve(env[SIGNING.keystore]);
+    if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`crossbind: ${SIGNING.keystore} names ${file}, which is no file.`);
+    return { file, names: [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]) };
+}
+
+// Gradle's caches and the Android tools' home outlive a container; the second keeps the debug key, which a new one would
+// replace, so that a later build still installs over the last.
+function homes() {
+    const root = path.join(os.homedir(), '.crossbind', 'android');
+    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) {
+    return [
+        ...DOCKER_RUN_SECURITY_ARGS, '--network', 'none', '--platform', PLATFORM, '--user', getOsUserAndGroupId(),
+        '-v', `${state.config.paths.base}:${DOCKER_BASE}`,
+        ...homes().flatMap(([host, container]) => {
+            fs.mkdirSync(host, { recursive: true });
+            return ['-v', `${host}:${container}`];
+        }),
+        ...(signing ? ['-v', `${signing.file}:${KEYSTORE}:ro`, '-e', `${SIGNING.keystore}=${KEYSTORE}`, ...signing.names.flatMap((name) => ['-e', name])] : []),
+    ];
+}
+
+function docker(args, what) {
+    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT });
+    if (result.error) throw new Error(`crossbind: cannot run docker for ${what}: ${result.error.message}`, { cause: result.error });
+    if (result.status !== 0) {
+        const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim().split('\n').slice(-FAILURE_LINES).join('\n');
+        throw new Error(`crossbind: ${what} failed in the android-app image with exit code ${result.status}:\n${output}`);
+    }
+}
+
+// The container sees the project's base alone, under its own POSIX path whatever the host's separators.
+function inContainer(project) {
+    const dir = path.resolve(project);
+    if (!isUnderBase(dir, state.config.paths.base)) {
+        throw new Error(`crossbind: the Android project ${dir} is outside ${state.config.paths.base}, the project's base and all the android-app container sees. Build the app into a directory under it.`);
+    }
+    return path.posix.join(DOCKER_BASE, ...path.relative(state.config.paths.base, dir).split(path.sep));
+}
+
+// An Android app as the files it ships: its release APK, and with an upload key also the bundle Google Play takes, beside
+// the Gradle project as <project>.apk and <project>.aab.
+export function packageAndroidRelease(project) {
+    const signing = releaseSigning();
+    pullDockerImage(ROLE, PLATFORM);
+    docker(['run', '--rm', ...containerArgs(signing), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
+        ...GRADLE, '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`);
+    const outputs = `${project}/app/build/outputs`;
+    fs.copyFileSync(`${outputs}/apk/release/app-release.apk`, `${project}.apk`);
+    fs.rmSync(`${project}.aab`, { force: true });
+    if (signing) {
+        fs.copyFileSync(`${outputs}/bundle/release/app-release.aab`, `${project}.aab`);
+    } else {
+        console.warn(`crossbind: ${path.basename(project)}.apk is signed with this machine's debug key: it installs for testing, and Google Play takes no app signed so. Set ${SIGNING.keystore}, ${SIGNING.alias} and ${SIGNING.password} to sign it with your upload key and make the bundle too.`);
+    }
+}
+
+// During development one container per project, whose Gradle daemon stays warm from one build to the next; it goes with
+// the process.
+let devContainer = null;
+
+function startDevContainer() {
+    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.
+    spawnSync('docker', ['rm', '--force', name], { stdio: 'ignore' });
+    docker(['run', '--detach', '--rm', '--init', '--name', name, ...containerArgs(null), 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;
+}
+
+// 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)}`);
+    return path.join(project, 'app', 'build', 'outputs', 'apk', 'debug', 'app-debug.apk');
+}