@webority/mobile-tools 0.0.0-stage → 0.1.0

package/LICENSE.txt

@@ -0,0 +1,9 @@
+Copyright (c) Webority Technologies. All rights reserved.
+
+This software and its NuGet packages are the proprietary and confidential property
+of Webority Technologies. They are published publicly only for the convenience of
+Webority's own projects and internal consumption.
+
+No license or right to use, copy, modify, merge, publish, distribute, sublicense,
+or create derivative works is granted to any third party. Unauthorized use,
+reproduction, or distribution is prohibited.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @webority/mobile-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The dev-time CLI for Webority React Native apps. It covers four jobs: compiling the environment config into the native projects, catching a stale `node_modules` before a 20-minute build, building and launching on one device, and rendering per-environment launcher icons. It behaves the same on Windows (Git Bash, PowerShell, cmd) and macOS (zsh).
+
+It is a devDependency. App code never imports it, and it adds nothing to the app bundle.
+
+```bash
+npm install --save-dev --save-exact @webority/mobile-tools
+```
+
+Node 24. Run every command from the app's root folder, where `appsettings.json` and `package.json` live.
+
+## Commands
+
+### `prebuild`
+
+```bash
+npx mobile-tools prebuild --env <Development|Staging|Production> [--platform android|ios]
+npx mobile-tools prebuild --same-env [--platform android|ios]
+```
+
+- Merges `appsettings.json` with `appsettings.<Env>.json` into `appsettings.Compiled.json`.
+- Stamps `COMMIT` (the short git sha, with `-dirty` when the app folder has changes other than the files prebuild writes) and `BUILD_TIME` (UTC, ISO 8601).
+- Fails, naming the key, when the merged settings lack `APP_NAME`, `APP_ID`, `ENVIRONMENT`, `BASE_URL`, `VERSION_DISPLAY` or `VERSION_INTERNAL`.
+- Fails when `ENVIRONMENT` differs from the `--env` given, when `VERSION_INTERNAL` is not a positive whole number, or when an `APP_ID_SUFFIX` disagrees with the environment.
+- **Android** (`android/gradle.properties`): sets `APP_NAME`, `APP_ID`, `VERSION_DISPLAY` and `VERSION_INTERNAL`. Every other line, comment and line ending stays as it was.
+  - With flavors, `APP_ID` is the base id. Each flavor's `applicationIdSuffix` adds the suffix.
+  - Without flavors, `APP_ID` is the suffixed id.
+- **iOS**:
+  - Sets `CFBundleDisplayName` in `ios/<name>/Info.plist`.
+  - In `project.pbxproj`, sets `PRODUCT_BUNDLE_IDENTIFIER` (suffixed), `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION`. It also sets `ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon-<Env>` when that icon set exists.
+  - When another environment's icon set exists but this one's does not, prebuild fails, so a build never ships the wrong icon.
+  - Copies `<firebasePlistDir>/GoogleService-Info.<Env>.plist` to `ios/<name>/GoogleService-Info.plist`. Without that file for the environment, it removes the copy.
+- Without `--platform`, it stamps every platform folder the app has.
+- `--same-env` recompiles the environment last compiled, which refreshes the build stamp.
+- Running it twice gives the same native files as running it once. A file whose content did not change is not rewritten.
+
+| Environment | App id suffix | Android flavor |
+|---|---|---|
+| Development | `.development` | `development` |
+| Staging | `.staging` | `staging` |
+| Production | none | `production` |
+
+### `sync`
+
+```bash
+npx mobile-tools sync --check
+npx mobile-tools sync
+npx mobile-tools sync --stamp
+npx mobile-tools hooks install
+```
+
+- `sync --check` hashes the lockfile (`package-lock.json` or `pnpm-lock.yaml`), the dependency fields of `package.json` and every file under `patches/`. It compares that hash with the stamp in `node_modules/.webority-install.json`.
+  - On macOS it also compares `ios/Podfile.lock` with `ios/Pods/Manifest.lock` when both exist.
+  - On a mismatch it prints the fix command and exits 1, well inside a second.
+- `sync` installs from the lockfile and writes the stamp: `npm ci`, or `pnpm install --frozen-lockfile` when the app has `pnpm-lock.yaml`.
+  - When a package with an `android/` folder was added, removed or changed version, and the app has been built before, it runs `gradlew generateCodegenArtifactsFromSchema`. It then deletes `android/app/.cxx` and `android/app/build/generated/autolinking`.
+  - On macOS it runs `pod install` (through `bundle exec` when the app has a `Gemfile`) when the Pods are missing or stale.
+- `sync --stamp` only records that `node_modules` matches the lockfile now. Run it from the app's `postinstall`, so a plain `npm ci` or `pnpm install` also leaves an accurate stamp.
+- `hooks install` writes git `post-merge` and `post-checkout` hooks that run `sync --check` after every pull and branch switch.
+  - It honours `core.hooksPath`, and an app in a subfolder of the repo gets its own block.
+  - A hook it did not write is kept as `<hook>.chained` and still runs first, with its exit status passed through.
+
+### `run`
+
+```bash
+npx mobile-tools run --env <Environment> [--platform android|ios] [--device <serial|name>]
+```
+
+**Android** (the default):
+
+1. Runs `sync --check` and stops on a stale tree.
+2. Lists `adb` devices. A device that answers on several serials (MuMu shows one instance as `127.0.0.1:16416`, `127.0.0.1:7555` and `emulator-5556`) is shown once.
+3. Picks the device:
+   - the one named by `--device` (any of its serials, or its model name);
+   - otherwise the only device;
+   - otherwise asks, on a terminal. Without a terminal it fails with the list.
+4. Reads the device's ABI and runs `prebuild`.
+5. Builds `:app:assemble<Flavor>Debug` (or `:app:assembleDebug` without flavors) with `-PreactNativeArchitectures=<abi>`, so only one ABI compiles.
+6. Installs with `adb -s <serial> install -r` on that device only.
+7. Reuses a Metro already serving this app. Otherwise it starts one detached and prints the path of its log; when another project holds 8081, the new Metro takes the next free port.
+8. Sets `adb reverse tcp:8081` (and, for Development, the local API port). It then launches `<applicationId>/<namespace>.MainActivity`.
+
+**iOS** (macOS only):
+
+1. Picks a booted simulator or a connected iPhone (`xcrun simctl`, `xcrun devicectl`).
+2. Runs `prebuild`.
+3. Builds with `xcodebuild -workspace ios/<name>.xcworkspace -scheme <name> -configuration Debug -destination id=<udid> -derivedDataPath ios/build ONLY_ACTIVE_ARCH=YES`.
+4. Installs and launches the app.
+5. Metro must be on 8081, where the iOS app looks.
+
+The build log goes to `node_modules/.cache/mobile-tools/`. On a failure only the root error is printed, with the log path. That root error is Metro's `Unable to resolve module` when present, otherwise Gradle's first "What went wrong" block or the compiler's `error:` lines.
+
+Every program is started by absolute path with an argument list, never through a shell string:
+
+- `android/gradlew` on macOS. `android\gradlew.bat` on Windows, through `cmd.exe` named by path, because Node will not start a `.bat` file any other way.
+- `adb` from `ANDROID_HOME/platform-tools`, falling back to `PATH`.
+- `/usr/bin/xcrun` and `/usr/bin/xcodebuild`.
+
+`NoDefaultCurrentDirectoryInExePath` is removed from every child's environment. On any other OS an iOS command stops with one line.
+
+### `icons`
+
+```bash
+npx mobile-tools icons [--source <png|svg>]
+```
+
+Renders every environment's launcher icons from one square source: an SVG, or a PNG of at least 1024 px.
+
+- **Android**, per flavor, into `android/app/src/<flavor>/res`:
+  - `ic_launcher` and `ic_launcher_round` in `mipmap-mdpi` through `mipmap-xxxhdpi`;
+  - the adaptive `ic_launcher_foreground`, with `mipmap-anydpi-v26` XML;
+  - `ic_launcher_background`, taken from the source's corner colour.
+  - Launcher icons of the same name in another format (`.webp`) are removed, because Android rejects the duplicate.
+  - Skipped when `flavors` is `false`.
+- **iOS**: `ios/<name>/Images.xcassets/AppIcon-<Env>.appiconset`, a single 1024 px universal icon with no alpha channel. Xcode derives the other sizes. Prebuild selects the set.
+- Production is clean. Staging carries an orange `STAGING` ribbon across the bottom-right corner, and Development a green `DEV` one. The ribbon is SVG text in a generic sans-serif, with no font file.
+- The same source gives the same bytes on the same machine.
+
+## `mobile-tools.config.json`
+
+Optional, at the app root. Every key is optional. An unknown key or a wrong type fails, naming the key.
+
+```json
+{
+  "iosProjectName": "FieldApp",
+  "flavors": true,
+  "localApiPort": 62430,
+  "iconSource": "assets/app-icon.svg",
+  "firebasePlistDir": "ios/firebase"
+}
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `iosProjectName` | the single `ios/*.xcodeproj` | Xcode project, scheme and workspace name |
+| `flavors` | `true` | Android product flavors `development`, `staging`, `production` in dimension `environment` |
+| `localApiPort` | the port of `appsettings.Development.json`'s `BASE_URL` when it is `localhost` | port `run` reverses for a Development build |
+| `iconSource` | none | source image for `icons` when `--source` is not given |
+| `firebasePlistDir` | `ios/firebase` | folder holding `GoogleService-Info.<Env>.plist` |
+
+## Typical `package.json` scripts
+
+```json
+{
+  "scripts": {
+    "android": "mobile-tools run --env Development",
+    "android:staging": "mobile-tools run --env Staging",
+    "ios": "mobile-tools run --env Development --platform ios",
+    "prebuild": "mobile-tools prebuild --same-env",
+    "sync": "mobile-tools sync",
+    "postinstall": "mobile-tools sync --stamp"
+  }
+}
+```
+
+`postinstall` keeps the stamp accurate after any install. After a pull, `npx mobile-tools sync` is still the one command to run: it also resets native codegen when a native package moved, which a plain install does not.

package/lib/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { parseEnvironment } from './config.js';
+import { installHooks } from './hooks.js';
+import { icons } from './icons.js';
+import { CliError, fail, say, warn } from './output.js';
+import { prebuild } from './prebuild.js';
+import { run } from './run.js';
+import { checkSync, sync, writeStamp } from './sync.js';
+const USAGE = `mobile-tools <command> [options]   (run from the app's root folder)
+
+  prebuild --env <Development|Staging|Production> [--platform android|ios]
+  prebuild --same-env [--platform android|ios]
+      Compile appsettings into appsettings.Compiled.json and stamp the native projects.
+
+  sync [--check | --stamp]
+      --check: exit 1 with the fix command when node_modules (or ios/Pods) is stale.
+      --stamp: record that node_modules matches the lockfile now (run it from postinstall).
+      Without either: install from the lockfile, stamp, and reset native codegen when needed.
+
+  hooks install
+      Add git post-merge and post-checkout hooks that run sync --check.
+
+  run --env <Environment> [--platform android|ios] [--device <serial|name>]
+      Build for one device's ABI, install it there, reuse or start Metro, and launch.
+
+  icons [--source <png|svg>]
+      Render per-environment launcher icons for Android flavors and iOS AppIcon-<Env> sets.`;
+const parse = (args, options, allowPositionals = false) => {
+    try {
+        const { values, positionals } = parseArgs({ args, options, allowPositionals, strict: true });
+        return { values: values, positionals };
+    }
+    catch (error) {
+        return fail(`${error.message}\n\n${USAGE}`, 2);
+    }
+};
+const envOption = (value) => typeof value === 'string' ? parseEnvironment(value) : undefined;
+const platformOption = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value !== 'android' && value !== 'ios') {
+        return fail(`--platform must be android or ios, not ${String(value)}`, 2);
+    }
+    return value;
+};
+const main = async (argv) => {
+    const [command, ...rest] = argv;
+    const appRoot = process.cwd();
+    switch (command) {
+        case 'prebuild': {
+            const { values } = parse(rest, {
+                env: { type: 'string' },
+                'same-env': { type: 'boolean' },
+                platform: { type: 'string' }
+            });
+            prebuild({
+                appRoot,
+                env: envOption(values.env),
+                sameEnv: values['same-env'] === true,
+                platform: platformOption(values.platform)
+            });
+            return;
+        }
+        case 'sync': {
+            const { values } = parse(rest, { check: { type: 'boolean' }, stamp: { type: 'boolean' } });
+            if (values.check && values.stamp) {
+                fail('use --check or --stamp, not both', 2);
+            }
+            if (values.stamp) {
+                writeStamp(appRoot);
+                say('sync --stamp: recorded node_modules as matching the lockfile');
+                return;
+            }
+            if (values.check) {
+                const problems = checkSync(appRoot, process.platform);
+                if (problems.length > 0) {
+                    fail(problems.join('\n'));
+                }
+                say('sync --check: node_modules matches the lockfile');
+                return;
+            }
+            sync(appRoot, process.platform);
+            return;
+        }
+        case 'hooks': {
+            const { positionals } = parse(rest, {}, true);
+            if (positionals[0] !== 'install' || positionals.length !== 1) {
+                fail(`usage: mobile-tools hooks install\n\n${USAGE}`, 2);
+            }
+            installHooks(appRoot);
+            return;
+        }
+        case 'run': {
+            const { values } = parse(rest, {
+                env: { type: 'string' },
+                platform: { type: 'string' },
+                device: { type: 'string' }
+            });
+            const env = envOption(values.env) ?? fail('run needs --env <Development|Staging|Production>', 2);
+            await run({
+                appRoot,
+                env,
+                platform: platformOption(values.platform) ?? 'android',
+                device: typeof values.device === 'string' ? values.device : undefined
+            });
+            return;
+        }
+        case 'icons': {
+            const { values } = parse(rest, { source: { type: 'string' } });
+            await icons({
+                appRoot,
+                source: typeof values.source === 'string' ? values.source : undefined
+            });
+            return;
+        }
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            say(USAGE);
+            return;
+        default:
+            fail(`unknown command "${command}"\n\n${USAGE}`, 2);
+    }
+};
+main(process.argv.slice(2)).catch((error) => {
+    if (error instanceof CliError) {
+        warn(`mobile-tools: ${error.message}`);
+        process.exit(error.exitCode);
+    }
+    warn(error instanceof Error ? (error.stack ?? error.message) : String(error));
+    process.exit(1);
+});

package/lib/config.js

@@ -0,0 +1,188 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fail } from './output.js';
+export const ENVIRONMENTS = ['Development', 'Staging', 'Production'];
+/** The only app id suffixes the fleet allows; Production carries none. */
+const SUFFIX = {
+    Development: '.development',
+    Staging: '.staging',
+    Production: ''
+};
+export const CONFIG_FILE = 'mobile-tools.config.json';
+export const COMPILED_FILE = 'appsettings.Compiled.json';
+/** The keys every app's merged appsettings must carry before a build. */
+export const REQUIRED_SETTINGS = [
+    'APP_NAME',
+    'APP_ID',
+    'ENVIRONMENT',
+    'BASE_URL',
+    'VERSION_DISPLAY',
+    'VERSION_INTERNAL'
+];
+export const parseEnvironment = (value) => {
+    const match = ENVIRONMENTS.find((env) => env.toLowerCase() === value.toLowerCase());
+    return match ?? fail(`unknown environment "${value}": use ${ENVIRONMENTS.join(', ')}`, 2);
+};
+export const envSuffix = (env) => SUFFIX[env];
+/** Android flavor names are the environment in lower case: development, staging, production. */
+export const flavorOf = (env) => env.toLowerCase();
+/** The id the app installs under: the base id plus the environment's suffix. */
+export const applicationId = (baseId, env) => `${baseId}${envSuffix(env)}`;
+/**
+ * The APP_ID written to gradle.properties. With flavors the flavor's applicationIdSuffix adds
+ * the suffix, so Gradle gets the base; without flavors nothing else would add it.
+ */
+export const gradleAppId = (baseId, env, flavors) => flavors ? baseId : applicationId(baseId, env);
+/** The debug assemble task for an environment. */
+export const assembleTask = (env, flavors) => {
+    if (!flavors) {
+        return 'assembleDebug';
+    }
+    const flavor = flavorOf(env);
+    return `assemble${flavor[0].toUpperCase()}${flavor.slice(1)}Debug`;
+};
+/** Where Gradle puts that task's APKs. */
+export const apkDir = (appRoot, env, flavors) => flavors
+    ? path.join(appRoot, 'android', 'app', 'build', 'outputs', 'apk', flavorOf(env), 'debug')
+    : path.join(appRoot, 'android', 'app', 'build', 'outputs', 'apk', 'debug');
+const readJson = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return fail(`cannot read ${file}: ${error.message}`);
+    }
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const CONFIG_KEYS = {
+    iosProjectName: 'string',
+    flavors: 'boolean',
+    localApiPort: 'port',
+    iconSource: 'string',
+    firebasePlistDir: 'string'
+};
+/** Validates mobile-tools.config.json; every unknown key or wrong type fails, naming the key. */
+export const parseToolsConfig = (raw, source = CONFIG_FILE) => {
+    if (!isRecord(raw)) {
+        return fail(`${source} must hold a JSON object`);
+    }
+    for (const [key, value] of Object.entries(raw)) {
+        const kind = Object.hasOwn(CONFIG_KEYS, key) ? CONFIG_KEYS[key] : undefined;
+        if (!kind) {
+            return fail(`${source}: unknown key "${key}" (known: ${Object.keys(CONFIG_KEYS).join(', ')})`);
+        }
+        const ok = kind === 'port'
+            ? Number.isInteger(value) && value > 0 && value < 65536
+            : kind === 'string'
+                ? typeof value === 'string' && value.trim() !== ''
+                : typeof value === kind;
+        if (!ok) {
+            const expected = {
+                port: 'a port number',
+                string: 'a non-empty string',
+                boolean: 'true or false'
+            };
+            fail(`${source}: "${key}" must be ${expected[kind]}`);
+        }
+    }
+    return {
+        iosProjectName: raw.iosProjectName,
+        flavors: raw.flavors ?? true,
+        localApiPort: raw.localApiPort,
+        iconSource: raw.iconSource,
+        firebasePlistDir: raw.firebasePlistDir ?? path.join('ios', 'firebase')
+    };
+};
+export const loadToolsConfig = (appRoot) => {
+    const file = path.join(appRoot, CONFIG_FILE);
+    return parseToolsConfig(existsSync(file) ? readJson(file) : {});
+};
+/** The configured iOS project name, or the one `*.xcodeproj` under ios/; undefined when the app has no ios/. */
+export const resolveIosProjectName = (appRoot, config) => {
+    if (config.iosProjectName) {
+        return config.iosProjectName;
+    }
+    const iosDir = path.join(appRoot, 'ios');
+    if (!existsSync(iosDir)) {
+        return undefined;
+    }
+    const projects = readdirSync(iosDir).filter((name) => name.endsWith('.xcodeproj'));
+    if (projects.length !== 1) {
+        return fail(`found ${projects.length} .xcodeproj folders in ios/: set "iosProjectName" in ${CONFIG_FILE}`);
+    }
+    return projects[0].slice(0, -'.xcodeproj'.length);
+};
+/** Base settings overlaid by one environment's file, then validated. Pure apart from the inputs. */
+export const mergeAppSettings = (base, overlay, env) => {
+    if (!isRecord(base)) {
+        return fail('appsettings.json must hold a JSON object');
+    }
+    if (!isRecord(overlay)) {
+        return fail(`appsettings.${env}.json must hold a JSON object`);
+    }
+    const merged = { ...base, ...overlay };
+    const missing = REQUIRED_SETTINGS.filter((key) => merged[key] === undefined || merged[key] === null || merged[key] === '');
+    if (missing.length > 0) {
+        fail(`appsettings (${env}) is missing required key(s): ${missing.join(', ')}`);
+    }
+    if (merged.ENVIRONMENT !== env) {
+        fail(`appsettings.${env}.json sets ENVIRONMENT to ${JSON.stringify(merged.ENVIRONMENT)}; it must be "${env}"`);
+    }
+    if (merged.APP_ID_SUFFIX !== undefined && merged.APP_ID_SUFFIX !== envSuffix(env)) {
+        fail(`appsettings (${env}) sets APP_ID_SUFFIX to ${JSON.stringify(merged.APP_ID_SUFFIX)}; ` +
+            `${env} builds always use ${JSON.stringify(envSuffix(env))}. Remove the key or correct it.`);
+    }
+    if (!/^[1-9][0-9]*$/.test(String(merged.VERSION_INTERNAL))) {
+        fail(`VERSION_INTERNAL must be a positive whole number, not ${JSON.stringify(merged.VERSION_INTERNAL)}`);
+    }
+    if (!/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/.test(String(merged.APP_ID))) {
+        fail(`APP_ID ${JSON.stringify(merged.APP_ID)} is not a reverse-domain id such as com.example.app`);
+    }
+    return merged;
+};
+export const loadAppSettings = (appRoot, env) => {
+    const baseFile = path.join(appRoot, 'appsettings.json');
+    const envFile = path.join(appRoot, `appsettings.${env}.json`);
+    if (!existsSync(baseFile)) {
+        fail(`no appsettings.json in ${appRoot}: run mobile-tools from the app's root folder`);
+    }
+    if (!existsSync(envFile)) {
+        fail(`appsettings.${env}.json not found: every buildable environment declares its own file`);
+    }
+    return mergeAppSettings(readJson(baseFile), readJson(envFile), env);
+};
+/** The ENVIRONMENT of the last compile, for --same-env. */
+export const lastCompiledEnvironment = (appRoot) => {
+    const file = path.join(appRoot, COMPILED_FILE);
+    if (!existsSync(file)) {
+        return fail(`--same-env: no ${COMPILED_FILE} yet; pass --env <Environment> once`);
+    }
+    const compiled = readJson(file);
+    if (!isRecord(compiled) || typeof compiled.ENVIRONMENT !== 'string') {
+        return fail(`--same-env: ${COMPILED_FILE} has no ENVIRONMENT`);
+    }
+    return parseEnvironment(compiled.ENVIRONMENT);
+};
+/**
+ * The local API port `run` reverses for Development: the configured port, else the port of a
+ * localhost BASE_URL, else none (the API is remote and needs no tunnel).
+ */
+export const localApiPort = (devBaseUrl, config) => {
+    if (config.localApiPort !== undefined) {
+        return config.localApiPort;
+    }
+    let url;
+    try {
+        url = new URL(devBaseUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {
+        return undefined;
+    }
+    if (url.port !== '') {
+        return Number(url.port);
+    }
+    return url.protocol === 'https:' ? 443 : 80;
+};

package/lib/devices.js

@@ -0,0 +1,95 @@
+import { createInterface } from 'node:readline/promises';
+import { capture } from './exec.js';
+import { fail } from './output.js';
+/** Parses `adb devices`. */
+export const parseAdbDevices = (text) => text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('List of devices') && !line.startsWith('*'))
+    .map((line) => {
+    const [serial, state = ''] = line.split(/\s+/);
+    return { serial, state };
+});
+/** A USB serial first, then emulator-NNNN, then host:port. */
+const serialRank = (serial) => {
+    if (serial.startsWith('emulator-')) {
+        return 1;
+    }
+    return serial.includes(':') ? 2 : 0;
+};
+/**
+ * Collapses serials that reach one device. Some emulators (MuMu) answer on several serials at
+ * once (127.0.0.1:16416, 127.0.0.1:7555, emulator-5556); they report the same ro.serialno and
+ * android_id. Two separate emulators can share ro.serialno, so android_id is part of the key.
+ */
+export const dedupeDevices = (probes) => {
+    const groups = new Map();
+    for (const probe of probes) {
+        const key = probe.serialNo === '' ? `serial:${probe.serial}` : `${probe.serialNo}|${probe.androidId}`;
+        groups.set(key, [...(groups.get(key) ?? []), probe]);
+    }
+    return [...groups.values()]
+        .map((group) => {
+        const serials = group
+            .map((probe) => probe.serial)
+            .sort((a, b) => serialRank(a) - serialRank(b) || a.localeCompare(b));
+        const chosen = group.find((probe) => probe.serial === serials[0]);
+        return { serial: serials[0], serials, model: chosen.model, abi: chosen.abi };
+    })
+        .sort((a, b) => a.serial.localeCompare(b.serial));
+};
+const PROBE_SCRIPT = 'getprop ro.serialno; getprop ro.product.model; getprop ro.product.cpu.abi; settings get secure android_id';
+export const probeDevice = (adb, serial, cwd) => {
+    const result = capture({ file: adb, args: ['-s', serial, 'shell', PROBE_SCRIPT] }, cwd);
+    if (result.status !== 0) {
+        return fail(`adb could not read ${serial}: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    const [serialNo = '', model = '', abi = '', androidId = ''] = result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim());
+    return { serial, serialNo, model, abi, androidId };
+};
+export const listAndroidDevices = (adb, cwd) => {
+    const result = capture({ file: adb, args: ['devices'] }, cwd);
+    if (result.status !== 0) {
+        return fail(`adb devices failed: ${result.stderr.trim()}`);
+    }
+    const entries = parseAdbDevices(result.stdout);
+    const unusable = entries.filter((entry) => entry.state !== 'device');
+    const ready = entries.filter((entry) => entry.state === 'device');
+    if (ready.length === 0) {
+        const detail = unusable.map((entry) => `${entry.serial} is ${entry.state}`).join('; ');
+        return fail(`no Android device ready${detail ? ` (${detail})` : ''}. Connect a phone with USB debugging, start an emulator, or adb connect host:port.`);
+    }
+    return dedupeDevices(ready.map((entry) => probeDevice(adb, entry.serial, cwd)));
+};
+export const describeDevice = (device) => `${device.model || 'unknown model'} (${device.serial}, ${device.abi})`;
+/** Matches --device against any serial of a device or its model name (case-insensitive). */
+export const findDevice = (devices, requested) => devices.find((device) => device.serials.includes(requested)) ??
+    devices.find((device) => device.model.toLowerCase() === requested.toLowerCase());
+/**
+ * The device to use: the --device match, the only device, or the user's pick on a terminal.
+ * Without a terminal several devices are an error listing them, never a guess.
+ */
+export const pickDevice = async (devices, requested, describe, interactive) => {
+    const list = devices.map((device, i) => `  ${i + 1}. ${describe(device)}`).join('\n');
+    if (requested) {
+        return (findDevice(devices, requested) ??
+            fail(`no device matches --device ${requested}. Connected:\n${list}`));
+    }
+    if (devices.length === 1) {
+        return devices[0];
+    }
+    if (!interactive) {
+        return fail(`several devices are connected; pass --device <serial|name>:\n${list}`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`Several devices are connected:\n${list}\nRun on which? [1-${devices.length}] `);
+        const index = Number(answer.trim()) - 1;
+        return devices[index] ?? fail(`no device numbered ${answer.trim()}`);
+    }
+    finally {
+        rl.close();
+    }
+};

package/lib/exec.js

@@ -0,0 +1,73 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import path from 'node:path';
+import { fail } from './output.js';
+import { childEnv } from './platform.js';
+/** Run to completion and capture the output. A program that cannot start reports status -1. */
+export const capture = (inv, cwd) => {
+    const result = spawnSync(inv.file, inv.args, {
+        cwd,
+        env: childEnv(process.env),
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        windowsHide: true,
+        windowsVerbatimArguments: inv.windowsVerbatimArguments
+    });
+    return {
+        status: result.error ? -1 : (result.status ?? -1),
+        stdout: result.stdout ?? '',
+        stderr: result.error ? result.error.message : (result.stderr ?? '')
+    };
+};
+/** Run with the terminal attached (installs, pod install, codegen) and fail on a non-zero exit. */
+export const runInherit = (inv, cwd, what) => {
+    const result = spawnSync(inv.file, inv.args, {
+        cwd,
+        env: childEnv(process.env),
+        stdio: 'inherit',
+        windowsHide: true,
+        windowsVerbatimArguments: inv.windowsVerbatimArguments
+    });
+    if (result.error) {
+        fail(`${what} could not start: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        fail(`${what} failed (exit ${result.status ?? 'signal'})`);
+    }
+};
+/** Run with stdout and stderr written to a log file; resolves to the exit status. */
+export const runToLog = (inv, cwd, logFile) => {
+    mkdirSync(path.dirname(logFile), { recursive: true });
+    const fd = openSync(logFile, 'w');
+    return new Promise((resolve) => {
+        const child = spawn(inv.file, inv.args, {
+            cwd,
+            env: childEnv(process.env),
+            stdio: ['ignore', fd, fd],
+            windowsHide: true,
+            windowsVerbatimArguments: inv.windowsVerbatimArguments
+        });
+        child.on('error', () => {
+            closeSync(fd);
+            resolve(-1);
+        });
+        child.on('close', (code) => {
+            closeSync(fd);
+            resolve(code ?? -1);
+        });
+    });
+};
+/** Start a long-lived process detached from this one, its output in a log file. */
+export const startDetached = (inv, cwd, logFile) => {
+    mkdirSync(path.dirname(logFile), { recursive: true });
+    const fd = openSync(logFile, 'a');
+    const child = spawn(inv.file, inv.args, {
+        cwd,
+        env: childEnv(process.env),
+        detached: true,
+        stdio: ['ignore', fd, fd],
+        windowsHide: true
+    });
+    child.unref();
+    closeSync(fd);
+};