@houwert/conductor 0.13.1 → 0.15.0

package/dist/commands/run-parallel.js

@@ -21,6 +21,7 @@ exports.HELP = `  run-parallel --flows-dir <path>     Run flows in parallel acro
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
+const sdk_js_1 = require("../android/sdk.js");
 const output_js_1 = require("../output.js");
 async function runParallel(flowsDir, opts = {}) {
     if (!flowsDir) {
@@ -107,7 +108,7 @@ async function runShard(deviceId, flowFile) {
 async function discoverAllDevices() {
     const devices = [];
     try {
-        const out = await spawnCapture('adb', ['devices']);
+        const out = await spawnCapture((0, sdk_js_1.resolveAndroidTool)('adb'), ['devices']);
         for (const line of out.split('\n').slice(1)) {
             const id = line.trim().split(/\s+/)[0];
             if (id && !line.includes('offline') && id !== '')

package/dist/commands/start-device.js

@@ -4,17 +4,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
+exports.pickAndroidArch = pickAndroidArch;
+exports.parseInstalledSystemImages = parseInstalledSystemImages;
+exports.pickSystemImage = pickSystemImage;
+exports.buildAvdmanagerCreateArgs = buildAvdmanagerCreateArgs;
 exports.startDevice = startDevice;
 exports.HELP = `  start-device
     --platform <ios|android|tvos|web> Boot a simulator/emulator, or start the web driver (Playwright)
     --os-version <n>                  iOS/tvOS version (e.g. 18) or Android API level (e.g. 33)
-    --avd <name>                      Android AVD name (default: first available)
+    --avd <name>                      Android AVD name (default: first available; created if missing + --device-type)
     --name <name>                     Set a custom name on the device after creation (iOS/tvOS/web)
-    --device-type <name>              iOS/tvOS device type (e.g. "iPhone 16 Pro", "Apple TV 4K"); creates if needed
+    --device-type <name>              iOS/tvOS device type (e.g. "iPhone 16 Pro", "Apple TV 4K") or
+                                      Android device profile (e.g. "pixel_7"); creates if needed
+    --system-image <id>               Android only: override auto-picked system image
+                                      (e.g. "system-images;android-34;google_apis;arm64-v8a")
     --browser <chromium|firefox|webkit> Web only: which Playwright browser to launch (default: chromium)`;
 const fs_1 = __importDefault(require("fs"));
 const child_process_1 = require("child_process");
 const runner_js_1 = require("../runner.js");
+const sdk_js_1 = require("../android/sdk.js");
 const client_js_1 = require("../daemon/client.js");
 const protocol_js_1 = require("../daemon/protocol.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
@@ -389,8 +397,13 @@ async function startTvOS(osVersion, opts, name, deviceType) {
     return 0;
 }
 // ── Android ───────────────────────────────────────────────────────────────────
+// TODO: Replace bare command names with the resolver from `android-sdk-path-resolver-68477d`
+// once it lands on main. For now we rely on `emulator`/`adb`/`avdmanager`/`sdkmanager`
+// being on PATH.
 async function listAVDs() {
-    const result = await (0, runner_js_1.spawnCommand)('emulator', ['-list-avds']);
+    const result = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('emulator'), ['-list-avds'], {
+        env: (0, sdk_js_1.androidSpawnEnv)(),
+    });
     if (!result.success)
         throw new Error(`emulator -list-avds failed: ${result.stderr}`);
     return result.stdout
@@ -398,11 +411,146 @@ async function listAVDs() {
         .map((l) => l.trim())
         .filter(Boolean);
 }
+/** Pick the Android system-image arch tag based on the host CPU. */
+function pickAndroidArch(arch = process.arch) {
+    return arch === 'arm64' ? 'arm64-v8a' : 'x86_64';
+}
+/**
+ * Parse `sdkmanager --list_installed` (or --list) output, returning installed
+ * system-image package paths like "system-images;android-34;google_apis;arm64-v8a".
+ */
+function parseInstalledSystemImages(stdout) {
+    const images = [];
+    for (const rawLine of stdout.split('\n')) {
+        const line = rawLine.trim();
+        if (!line.startsWith('system-images;'))
+            continue;
+        // Format is "<path> | <version> | <description> | <location>" with leading whitespace
+        const path = line.split(/[|\s]+/)[0];
+        if (path && !images.includes(path))
+            images.push(path);
+    }
+    return images;
+}
+/**
+ * Pick the best installed system image matching the requested API level and arch.
+ * Prefers `google_apis` over `default` (no Play store dependency on Apple Silicon
+ * where Play images often lack arm64). Returns undefined if no match.
+ */
+function pickSystemImage(installed, apiLevel, arch) {
+    const filtered = installed.filter((img) => {
+        const parts = img.split(';');
+        // parts: ["system-images", "android-<api>", "<variant>", "<arch>"]
+        if (parts.length < 4)
+            return false;
+        if (parts[3] !== arch)
+            return false;
+        if (apiLevel && parts[1] !== `android-${apiLevel}`)
+            return false;
+        return true;
+    });
+    if (filtered.length === 0)
+        return undefined;
+    // Variant preference: google_apis > google_apis_playstore > default > others
+    const rank = (img) => {
+        const variant = img.split(';')[2];
+        if (variant === 'google_apis')
+            return 0;
+        if (variant === 'google_apis_playstore')
+            return 1;
+        if (variant === 'default')
+            return 2;
+        return 3;
+    };
+    filtered.sort((a, b) => {
+        const r = rank(a) - rank(b);
+        if (r !== 0)
+            return r;
+        // Then prefer higher API level
+        const ai = parseInt(a.split(';')[1].replace('android-', ''), 10) || 0;
+        const bi = parseInt(b.split(';')[1].replace('android-', ''), 10) || 0;
+        return bi - ai;
+    });
+    return filtered[0];
+}
+/** Build the avdmanager argv for AVD creation — pure, exported for tests. */
+function buildAvdmanagerCreateArgs(avdName, systemImage, deviceProfile) {
+    return ['create', 'avd', '-n', avdName, '-k', systemImage, '-d', deviceProfile];
+}
+async function listInstalledSystemImages() {
+    const result = await (0, runner_js_1.spawnCommand)('sdkmanager', ['--list_installed']);
+    if (!result.success) {
+        throw new Error(`sdkmanager --list_installed failed: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    return parseInstalledSystemImages(result.stdout);
+}
+/** Run avdmanager create avd, piping "no\n" so it skips the custom hardware prompt. */
+async function spawnAvdmanagerCreate(args) {
+    await new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)('avdmanager', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stderr = '';
+        proc.stdout.on('data', () => {
+            /* discard */
+        });
+        proc.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on('error', (err) => reject(err));
+        proc.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`avdmanager exited ${code}: ${stderr.trim()}`));
+        });
+        proc.stdin.end('no\n');
+    });
+}
+async function createAndroidAVD(avdName, deviceProfile, apiLevel, systemImageOverride) {
+    const arch = pickAndroidArch();
+    let systemImage;
+    if (systemImageOverride) {
+        systemImage = systemImageOverride;
+    }
+    else {
+        let installed;
+        try {
+            installed = await listInstalledSystemImages();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Could not list installed Android system images (${msg}). ` +
+                `Ensure the Android SDK command-line tools are installed and on PATH.`);
+        }
+        const picked = pickSystemImage(installed, apiLevel, arch);
+        if (!picked) {
+            const apiHint = apiLevel ?? '34';
+            throw new Error(`No installed Android system image matches arch=${arch}` +
+                (apiLevel ? `, api=${apiLevel}` : '') +
+                `.\nInstall one with:\n  sdkmanager "system-images;android-${apiHint};google_apis;${arch}"`);
+        }
+        systemImage = picked;
+    }
+    const args = buildAvdmanagerCreateArgs(avdName, systemImage, deviceProfile);
+    try {
+        await spawnAvdmanagerCreate(args);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Failed to create AVD "${avdName}": ${msg}`);
+    }
+    // Validate the AVD now appears in emulator -list-avds
+    const avds = await listAVDs();
+    if (!avds.includes(avdName)) {
+        throw new Error(`AVD "${avdName}" was not registered after creation (not in emulator -list-avds).`);
+    }
+}
 async function waitForAndroidBoot(avdName) {
     const deadline = Date.now() + ANDROID_BOOT_TIMEOUT_MS;
     const connectedBefore = new Set();
     // Snapshot currently connected devices so we can identify the new one
-    const before = await (0, runner_js_1.spawnCommand)('adb', ['devices']);
+    const before = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['devices'], {
+        env: (0, sdk_js_1.androidSpawnEnv)(),
+    });
     for (const line of before.stdout.split('\n').slice(1)) {
         const id = line.trim().split(/\s+/)[0];
         if (id)
@@ -410,7 +558,9 @@ async function waitForAndroidBoot(avdName) {
     }
     while (Date.now() < deadline) {
         await (0, utils_js_1.sleep)(POLL_MS);
-        const result = await (0, runner_js_1.spawnCommand)('adb', ['devices']);
+        const result = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['devices'], {
+            env: (0, sdk_js_1.androidSpawnEnv)(),
+        });
         if (!result.success)
             continue;
         for (const line of result.stdout.split('\n').slice(1)) {
@@ -419,13 +569,7 @@ async function waitForAndroidBoot(avdName) {
             const status = parts[1];
             if (id && status === 'device' && !connectedBefore.has(id)) {
                 // Check boot completed
-                const boot = await (0, runner_js_1.spawnCommand)('adb', [
-                    '-s',
-                    id,
-                    'shell',
-                    'getprop',
-                    'sys.boot_completed',
-                ]);
+                const boot = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', id, 'shell', 'getprop', 'sys.boot_completed'], { env: (0, sdk_js_1.androidSpawnEnv)() });
                 if (boot.stdout.trim() === '1')
                     return id;
             }
@@ -433,7 +577,7 @@ async function waitForAndroidBoot(avdName) {
     }
     throw new Error(`Android emulator (${avdName}) did not appear within ${ANDROID_BOOT_TIMEOUT_MS / 1000}s`);
 }
-async function startAndroid(avdName, opts) {
+async function startAndroid(avdName, opts, deviceType, osVersion, systemImage) {
     let avds;
     try {
         avds = await listAVDs();
@@ -442,20 +586,38 @@ async function startAndroid(avdName, opts) {
         (0, output_js_1.printError)(`Failed to list AVDs: ${e instanceof Error ? e.message : String(e)}`, opts);
         return 1;
     }
-    if (avds.length === 0) {
-        (0, output_js_1.printError)('No Android AVDs found. Create one in Android Studio → Device Manager.', opts);
+    let target = avdName ?? avds[0];
+    // If the requested AVD doesn't exist (or none exist) and a device profile was
+    // provided, create the AVD before booting.
+    const needsCreate = (avds.length === 0 || (avdName !== undefined && !avds.includes(avdName))) &&
+        deviceType !== undefined;
+    if (needsCreate) {
+        if (!avdName) {
+            (0, output_js_1.printError)('--avd <name> is required when creating an AVD with --device-type.', opts);
+            return 1;
+        }
+        console.log(`No AVD "${avdName}" found. Creating one with device profile "${deviceType}"...`);
+        try {
+            await createAndroidAVD(avdName, deviceType, osVersion, systemImage);
+        }
+        catch (e) {
+            (0, output_js_1.printError)(e instanceof Error ? e.message : String(e), opts);
+            return 1;
+        }
+        target = avdName;
+    }
+    else if (avds.length === 0) {
+        (0, output_js_1.printError)('No Android AVDs found. Pass --device-type <profile> --avd <name> to create one, ' +
+            'or create one in Android Studio → Device Manager.', opts);
         return 1;
     }
-    const target = avdName ?? avds[0];
-    if (!avds.includes(target)) {
-        (0, output_js_1.printError)(`AVD "${target}" not found. Available: ${avds.join(', ')}`, opts);
+    else if (!avds.includes(target)) {
+        (0, output_js_1.printError)(`AVD "${target}" not found. Available: ${avds.join(', ')}. ` +
+            `Pass --device-type to create it.`, opts);
         return 1;
     }
     console.log(`Launching emulator: ${target}...`);
-    const proc = (0, child_process_1.spawn)('emulator', ['-avd', target, '-netdelay', 'none', '-netspeed', 'full'], {
-        detached: true,
-        stdio: 'ignore',
-    });
+    const proc = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('emulator'), ['-avd', target, '-netdelay', 'none', '-netspeed', 'full'], { detached: true, stdio: 'ignore', env: (0, sdk_js_1.androidSpawnEnv)() });
     proc.unref();
     let deviceId;
     try {
@@ -526,7 +688,7 @@ async function startDevice(platform, opts, flags) {
         case 'tvos':
             return startTvOS(flags.osVersion, opts, flags.name, flags.deviceType);
         case 'android':
-            return startAndroid(flags.avd, opts);
+            return startAndroid(flags.avd, opts, flags.deviceType, flags.osVersion, flags.systemImage);
         case 'web':
             return startWebDriver(opts, flags.browser, flags.name);
         default:

package/dist/commands/stop-device.js

@@ -6,6 +6,7 @@ exports.HELP = `  stop-device [<name-or-id>]
     --platform <ios|tvos|android|web> Scope to a single platform
     --all                             Stop all booted simulators / running emulators / web sessions`;
 const runner_js_1 = require("../runner.js");
+const sdk_js_1 = require("../android/sdk.js");
 const output_js_1 = require("../output.js");
 const client_js_1 = require("../daemon/client.js");
 const list_devices_js_1 = require("./list-devices.js");
@@ -18,7 +19,7 @@ async function shutdownSimulator(udid) {
 }
 // ── Android ──────────────────────────────────────────────────────────────────
 async function killEmulator(serial) {
-    const result = await (0, runner_js_1.spawnCommand)('adb', ['-s', serial, 'emu', 'kill']);
+    const result = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', serial, 'emu', 'kill']);
     if (!result.success) {
         throw new Error(`Failed to kill emulator ${serial}: ${result.stderr.trim()}`);
     }

package/dist/daemon/server.js

@@ -19,6 +19,7 @@ const url_1 = __importDefault(require("url"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const protocol_js_1 = require("./protocol.js");
+const sdk_js_1 = require("../android/sdk.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const android_js_1 = require("../drivers/android.js");
 const web_server_js_1 = require("./web-server.js");
@@ -129,6 +130,7 @@ async function ensureDriverRunning() {
 }
 // ── Daemon main ──────────────────────────────────────────────────────────────
 async function main() {
+    (0, sdk_js_1.ensureAndroidEnv)();
     // Ensure per-session daemon directory exists
     fs_1.default.mkdirSync(path_1.default.dirname(PID_FILE), { recursive: true });
     fs_1.default.writeFileSync(PID_FILE, String(process.pid));

package/dist/daemon/web-server.js

@@ -868,6 +868,44 @@ async function handleRequest(req, res, dlog) {
                 }
                 return;
             }
+            case '/heapSnapshot': {
+                // V8 heap snapshot via CDP. The snapshot streams as JSON chunks via
+                // `HeapProfiler.addHeapSnapshotChunk` events; we concatenate them and
+                // return the assembled JSON. Snapshots are large (10-100+ MB on real
+                // pages) — fine over localhost HTTP.
+                const p = await getPage(dlog);
+                const session = await p.context().newCDPSession(p);
+                const chunks = [];
+                const onChunk = (e) => {
+                    chunks.push(e.chunk);
+                };
+                try {
+                    await session.send('HeapProfiler.enable').catch(() => { });
+                    // Optional: collect garbage before snapshotting so transient
+                    // allocations don't muddy diff comparisons. Triggered via ?gc=1.
+                    if (parsedUrl.query['gc']) {
+                        await session.send('HeapProfiler.collectGarbage').catch(() => { });
+                    }
+                    session.on('HeapProfiler.addHeapSnapshotChunk', onChunk);
+                    await session.send('HeapProfiler.takeHeapSnapshot', {
+                        reportProgress: false,
+                        captureNumericValue: false,
+                        exposeInternals: false,
+                    });
+                    // Each chunk is already JSON text; concatenation yields the full snapshot JSON.
+                    const body = chunks.join('');
+                    res.writeHead(200, {
+                        'Content-Type': 'application/json',
+                        'Content-Length': Buffer.byteLength(body),
+                    });
+                    res.end(body);
+                }
+                finally {
+                    session.off('HeapProfiler.addHeapSnapshotChunk', onChunk);
+                    await session.detach().catch(() => { });
+                }
+                return;
+            }
             case '/consoleLogs': {
                 const since = parsedUrl.query['since'] ?? '';
                 const entries = since

package/dist/drivers/android.js

@@ -50,6 +50,7 @@ const protoLoader = __importStar(require("@grpc/proto-loader"));
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const sdk_js_1 = require("../android/sdk.js");
 // __dirname is available in CommonJS — points to dist/drivers/
 const PROTO_PATH = path_1.default.join(__dirname, '../../proto/conductor_android.proto');
 let _packageDef = null;
@@ -148,7 +149,9 @@ class AndroidDriver {
     // ── ADB-shell operations (not in gRPC proto) ─────────────────────────────
     adb(args) {
         return new Promise((resolve, reject) => {
-            const proc = (0, child_process_1.spawn)('adb', ['-s', this.deviceId, ...args], { stdio: 'ignore' });
+            const proc = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', this.deviceId, ...args], {
+                stdio: 'ignore',
+            });
             proc.on('close', (code) => {
                 if (code === 0)
                     resolve();
@@ -182,7 +185,7 @@ class AndroidDriver {
     }
     adbOutput(args) {
         return new Promise((resolve, reject) => {
-            const proc = (0, child_process_1.spawn)('adb', ['-s', this.deviceId, ...args], {
+            const proc = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', this.deviceId, ...args], {
                 stdio: ['ignore', 'pipe', 'pipe'],
             });
             let stdout = '';
@@ -200,7 +203,9 @@ class AndroidDriver {
     }
     async getForegroundApp() {
         const output = await this.adbOutput(['shell', 'dumpsys', 'activity', 'activities']);
-        const match = output.match(/mResumedActivity.*?([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)\//);
+        // API 28- prints `mResumedActivity:`; API 29+ uses `ResumedActivity:` /
+        // `topResumedActivity=`. Accept all three so this works across versions.
+        const match = output.match(/(?:m|top)?ResumedActivity[=:].*?([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)\//);
         if (!match)
             throw new Error('Could not determine foreground app');
         return match[1];
@@ -326,7 +331,7 @@ class AndroidDriver {
         if (this._recordingProcess)
             await this.stopRecording();
         this._recordingOutputPath = outputPath;
-        this._recordingProcess = (0, child_process_1.spawn)('adb', ['-s', this.deviceId, 'shell', 'screenrecord', '/sdcard/conductor_recording.mp4'], { stdio: 'ignore' });
+        this._recordingProcess = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', this.deviceId, 'shell', 'screenrecord', '/sdcard/conductor_recording.mp4'], { stdio: 'ignore' });
     }
     async stopRecording() {
         if (this._recordingProcess) {

package/dist/drivers/bootstrap.js

@@ -42,6 +42,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const verbose_js_1 = require("../verbose.js");
 const utils_js_1 = require("../utils.js");
+const sdk_js_1 = require("../android/sdk.js");
 /** Cache: deviceId → platform */
 const _platformCache = new Map();
 async function detectPlatform(deviceId) {
@@ -353,8 +354,24 @@ async function installDriver(deviceId) {
         throw new Error(`Conductor driver APKs not found at ${path_1.default.join(driversDir, 'android')}.\n` +
             `Run 'make package-cli' from the repo root to build and bundle the drivers.`);
     }
-    await spawnAndWait('adb', ['-s', deviceId, 'install', '-r', '-t', '-g', appApk]);
-    await spawnAndWait('adb', ['-s', deviceId, 'install', '-r', '-t', '-g', serverApk]);
+    await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
+        '-s',
+        deviceId,
+        'install',
+        '-r',
+        '-t',
+        '-g',
+        appApk,
+    ]);
+    await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
+        '-s',
+        deviceId,
+        'install',
+        '-r',
+        '-t',
+        '-g',
+        serverApk,
+    ]);
     (0, verbose_js_1.log)(`installDriver: done`);
 }
 // ── iOS bootstrap ─────────────────────────────────────────────────────────────
@@ -598,9 +615,15 @@ async function startAndroidDriver(deviceId, port = ANDROID_BASE_PORT) {
     }
     (0, verbose_js_1.log)(`Starting Android driver for device ${deviceId} on port ${port}`);
     // Step 1: ADB port forward
-    await spawnAndWait('adb', ['-s', deviceId, 'forward', `tcp:${port}`, `tcp:${port}`]);
+    await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
+        '-s',
+        deviceId,
+        'forward',
+        `tcp:${port}`,
+        `tcp:${port}`,
+    ]);
     // Step 2: Get device API level to decide instrumentation flags
-    const apiResult = await spawnCapture('adb', [
+    const apiResult = await spawnCapture((0, sdk_js_1.resolveAndroidTool)('adb'), [
         '-s',
         deviceId,
         'shell',
@@ -628,7 +651,7 @@ async function startAndroidDriver(deviceId, port = ANDROID_BASE_PORT) {
         String(port),
         CONDUCTOR_TEST_RUNNER,
     ];
-    const proc = (0, child_process_1.spawn)('adb', instrArgs, {
+    const proc = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('adb'), instrArgs, {
         detached: true,
         stdio: ['ignore', 'ignore', 'ignore'],
     });
@@ -647,7 +670,7 @@ async function startAndroidDriver(deviceId, port = ANDROID_BASE_PORT) {
         `Try running: conductor install --device ${deviceId}`);
 }
 async function stopAndroidDriver(deviceId, port = ANDROID_BASE_PORT) {
-    await spawnAndWait('adb', [
+    await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
         '-s',
         deviceId,
         'shell',
@@ -655,7 +678,13 @@ async function stopAndroidDriver(deviceId, port = ANDROID_BASE_PORT) {
         'force-stop',
         'dev.houwert.conductor',
     ]).catch(() => { });
-    await spawnAndWait('adb', ['-s', deviceId, 'forward', '--remove', `tcp:${port}`]).catch(() => { });
+    await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
+        '-s',
+        deviceId,
+        'forward',
+        '--remove',
+        `tcp:${port}`,
+    ]).catch(() => { });
 }
 // ── Web bootstrap ────────────────────────────────────────────────────────────
 /**
@@ -783,8 +812,18 @@ async function uninstallDriver(deviceId, platform) {
         await spawnAndWait('xcrun', ['simctl', 'uninstall', deviceId, TVOS_RUNNER_BUNDLE_ID]).catch(() => { });
     }
     else {
-        await spawnAndWait('adb', ['-s', deviceId, 'uninstall', 'dev.houwert.conductor']).catch(() => { });
-        await spawnAndWait('adb', ['-s', deviceId, 'uninstall', 'dev.houwert.conductor.test']).catch(() => { });
+        await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
+            '-s',
+            deviceId,
+            'uninstall',
+            'dev.houwert.conductor',
+        ]).catch(() => { });
+        await spawnAndWait((0, sdk_js_1.resolveAndroidTool)('adb'), [
+            '-s',
+            deviceId,
+            'uninstall',
+            'dev.houwert.conductor.test',
+        ]).catch(() => { });
     }
 }
 // ── Helpers ───────────────────────────────────────────────────────────────────

package/dist/drivers/log-sources/android.js

@@ -5,6 +5,7 @@ exports.AndroidLogSource = void 0;
  * Android log source — streams logs from an Android device/emulator via `adb logcat`.
  */
 const child_process_1 = require("child_process");
+const sdk_js_1 = require("../../android/sdk.js");
 function mapPriority(priority) {
     // Android log priorities: 2=V, 3=D, 4=I, 5=W, 6=E, 7=F
     const p = typeof priority === 'string' ? priority.toUpperCase() : String(priority);
@@ -44,10 +45,7 @@ class AndroidLogSource {
         let pid;
         if (this.appId) {
             try {
-                pid = (0, child_process_1.execSync)(`adb -s ${this.deviceId} shell pidof ${this.appId}`, {
-                    encoding: 'utf-8',
-                    timeout: 5000,
-                }).trim();
+                pid = (0, child_process_1.execFileSync)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', this.deviceId, 'shell', 'pidof', this.appId], { encoding: 'utf-8', timeout: 5000 }).trim();
             }
             catch {
                 // App may not be running yet — proceed without PID filter
@@ -55,7 +53,9 @@ class AndroidLogSource {
         }
         // Clear existing logcat buffer so we start fresh
         try {
-            (0, child_process_1.execSync)(`adb -s ${this.deviceId} logcat -c`, { timeout: 5000 });
+            (0, child_process_1.execFileSync)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', this.deviceId, 'logcat', '-c'], {
+                timeout: 5000,
+            });
         }
         catch {
             // Ignore clear failures
@@ -71,7 +71,7 @@ class AndroidLogSource {
         if (pid) {
             args.push('--pid', pid);
         }
-        this.proc = (0, child_process_1.spawn)('adb', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        this.proc = (0, child_process_1.spawn)((0, sdk_js_1.resolveAndroidTool)('adb'), args, { stdio: ['ignore', 'pipe', 'pipe'] });
         let stderrChunks = '';
         this.proc.stderr.on('data', (chunk) => {
             stderrChunks += chunk.toString('utf-8');

package/dist/drivers/log-sources/metro-discovery.js

@@ -24,6 +24,7 @@ exports.targetsForDevice = targetsForDevice;
  */
 const child_process_1 = require("child_process");
 const metro_js_1 = require("./metro.js");
+const sdk_js_1 = require("../../android/sdk.js");
 /** Metro dev-server port ranges we consider. */
 const METRO_PORT_RANGES = [
     [8080, 8099], // Metro default range
@@ -58,7 +59,12 @@ async function discoverMetroPortForDevice(platform, deviceId) {
 }
 async function discoverMetroPortAndroid(deviceId) {
     try {
-        const output = await spawnCapture('adb', ['-s', deviceId, 'reverse', '--list']);
+        const output = await spawnCapture((0, sdk_js_1.resolveAndroidTool)('adb'), [
+            '-s',
+            deviceId,
+            'reverse',
+            '--list',
+        ]);
         // Lines look like: host-13 tcp:8082 tcp:8082
         for (const line of output.split('\n')) {
             const match = line.match(/tcp:(\d+)\s+tcp:(\d+)/);
@@ -172,7 +178,7 @@ async function getDeviceDisplayName(platform, deviceId) {
     }
     if (platform === 'android') {
         try {
-            const output = await spawnCapture('adb', [
+            const output = await spawnCapture((0, sdk_js_1.resolveAndroidTool)('adb'), [
                 '-s',
                 deviceId,
                 'shell',

package/dist/drivers/web.js

@@ -18,7 +18,7 @@ class WebDriver {
         this.host = host;
         this.deviceId = deviceId;
     }
-    request(method, path, body) {
+    request(method, path, body, timeoutMs = 30000) {
         return new Promise((resolve, reject) => {
             const bodyBuf = body !== undefined ? Buffer.from(JSON.stringify(body), 'utf-8') : undefined;
             const options = {
@@ -38,7 +38,7 @@ class WebDriver {
                 res.on('end', () => resolve({ status: res.statusCode ?? 0, data: Buffer.concat(chunks) }));
                 res.on('error', reject);
             });
-            req.setTimeout(30000, () => {
+            req.setTimeout(timeoutMs, () => {
                 req.destroy(new Error(`Web driver request timed out: ${method} ${path}`));
             });
             req.on('error', reject);
@@ -139,6 +139,20 @@ class WebDriver {
     async memory() {
         return this.get('memory');
     }
+    /**
+     * Take a V8 heap snapshot via CDP. Returns the raw JSON text (large; tens
+     * of MB on a real page). Caller can write it to a `.heapsnapshot` file for
+     * Chrome DevTools and/or parse it for class statistics.
+     */
+    async heapSnapshot(opts = {}) {
+        // 5-minute timeout — large pages can take 30-60s to snapshot + transfer.
+        const qs = opts.gc ? '?gc=1' : '';
+        const { status, data } = await this.request('GET', `/heapSnapshot${qs}`, undefined, 5 * 60000);
+        if (status < 200 || status >= 300) {
+            throw new Error(`Web driver heapSnapshot failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
+        }
+        return data.toString('utf-8');
+    }
     async eraseAllText(count = 50) {
         await this.post('eraseText', { count });
     }