dsh-apk-vm 0.3.13 → 0.4.0

package/lib/android.js

@@ -50,6 +50,8 @@ import { promises as fsp } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { inflateRawSync } from 'node:zlib';
+import { inspectCertificate } from './x509.js';
+import { extractApkBundle, cleanupBundle } from './apk-bundle.js';
 
 const IS_WIN = process.platform === 'win32';
 const EXE = IS_WIN ? '.exe' : '';
@@ -470,6 +472,17 @@ export class AndroidVm {
       typeof opts.gpuMode === 'string' && opts.gpuMode.trim()
         ? opts.gpuMode.trim()
         : DEFAULT_OPTIONS.gpuMode;
+    // Headless Linux servers usually have no usable EGL/GL display for the
+    // emulator's host GPU mode; fall back to the software renderer so CI and
+    // remote validation can still boot (slowly).
+    if (
+      process.platform === 'linux' &&
+      !process.env.DISPLAY &&
+      !process.env.WAYLAND_DISPLAY &&
+      this.gpuMode === 'host'
+    ) {
+      this.gpuMode = 'swiftshader_indirect';
+    }
     this.accel = opts.accel === 'on' || opts.accel === 'off' ? opts.accel : 'auto';
     this.requireAccel = opts.requireAccel !== false;
     this.accelCheckTimeoutMs = asPositiveInt(opts.accelCheckTimeoutMs, DEFAULT_OPTIONS.accelCheckTimeoutMs);
@@ -503,6 +516,7 @@ export class AndroidVm {
     this._serialActive = null;
     this._child = null; // spawned emulator process, if any
     this._spawnedByUs = false;
+    this._suppressAutoAttach = false;
     this._bootStartAt = null;
     this._sawNotBooted = false;
     this._bootProbe = { serial: null, at: 0, booted: false };
@@ -558,6 +572,7 @@ export class AndroidVm {
    */
   async start() {
     if (this._disposed) throw new Error('AndroidVm has been disposed');
+    this._suppressAutoAttach = false;
     // Serialize with a start that a stop() may have interrupted: the stale run aborts
     // via _waitEpoch, then this call performs a clean attach/boot.
     while (this._starting) {
@@ -575,11 +590,15 @@ export class AndroidVm {
     return this._starting;
   }
 
-  /** Stop the attached VM: graceful emulator shutdown when possible, then adb detach. */
+  /**
+   * Stop the attached VM: kill only an emulator this process spawned; for any
+   * pre-existing (auto-attached or explicitly attached) device, detach instead.
+   */
   async stop() {
     this._waitEpoch += 1; // abort an in-flight boot wait
     this._bootWait = null; // let a subsequent start() begin a fresh wait
     this._pushLog('[vm] stop requested');
+    this._suppressAutoAttach = true;
     if (this._external) {
       // Never kill or disconnect a user's physical/remote device; just detach.
       this._serialActive = null;
@@ -589,8 +608,12 @@ export class AndroidVm {
     }
     const serial = this._serialActive || this.serial;
     const child = this._child;
+    // Critical safety rule: only stop an emulator that this process spawned.
+    // An auto-attached pre-existing emulator (for example on a shared Linux
+    // host) must never receive `adb emu kill` or `adb disconnect`.
+    const spawnedHere = this._spawnedByUs === true || Boolean(child);
 
-    if (serial) {
+    if (serial && spawnedHere) {
       try {
         const result = await this._adb(['-s', serial, 'emu', 'kill'], { timeoutMs: 10000 });
         if (result && result.code === 0) this._pushLog(`[vm] sent emulator kill to ${serial}`);
@@ -612,6 +635,8 @@ export class AndroidVm {
       if (stillConnected && isNetworkSerial(serial)) {
         await this._adb(['disconnect', serial], { timeoutMs: 10000 }).catch(() => {});
       }
+    } else if (serial) {
+      this._pushLog(`[vm] leaving pre-existing device ${serial} running (not spawned by this process)`);
     }
 
     if (child && child.exitCode === null) {
@@ -758,7 +783,7 @@ export class AndroidVm {
           if (depth + 1 <= this.maxApkDepth) stack.push({ dir: fullPath, depth: depth + 1 });
           continue;
         }
-        if (!entry.isFile() || !/\.apk$/i.test(name)) continue;
+        if (!entry.isFile() || !/\.(?:apk|apks|xapk)$/i.test(name)) continue;
         const key = IS_WIN ? fullPath.toLowerCase() : fullPath;
         if (seen.has(key)) continue;
         seen.add(key);
@@ -769,6 +794,7 @@ export class AndroidVm {
             name,
             size: stat.size,
             mtime: new Date(stat.mtimeMs).toISOString(),
+            kind: path.extname(name).slice(1).toLowerCase(),
           });
         } catch {
           /* file vanished mid-scan */
@@ -826,62 +852,75 @@ export class AndroidVm {
   }
 
   /**
-   * Install an APK with `adb install -r` (retries with -t for test-only packages),
+   * Install a plain APK or an APKS/XAPK bundle with `adb install-multiple`,
    * then resolve its metadata and best-effort launch it so the panel shows the app.
-   * Returns { packageName, label, launchActivity }.
+   * Returns { packageName, label, launchActivity, bundle? }.
    */
   async installApk(apkPath) {
-    const file = await this._assertApkFile(apkPath);
+    const file = await this._assertPackageFile(apkPath);
     const serial = await this._requireSerial();
     const stat = await fsp.stat(file);
-    const metadata = await this.inspectApk(file);
-
-    this._pushLog(
-      `[vm] installing ${path.basename(file)} (${stat.size} bytes) on ${serial} ` +
-        `[${metadata.packageName}]`,
-    );
-    const startedAt = Date.now();
-    let result = await this._adb(['-s', serial, 'install', '-r', file], {
-      timeoutMs: this.installTimeoutMs,
-      maxBytes: 8 * 1024 * 1024,
-    });
-    let output = `${result.stdout.toString('utf8')}\n${result.stderr}`;
-    if (/INSTALL_FAILED_TEST_ONLY/i.test(output)) {
-      this._pushLog('[vm] package is test-only; retrying with adb install -r -t');
-      result = await this._adb(['-s', serial, 'install', '-r', '-t', file], {
+    const bundle = await extractApkBundle(file);
+    try {
+      const metadata = await this.inspectApk(bundle.basePath);
+      this._pushLog(
+        `[vm] installing ${path.basename(file)} (${stat.size} bytes, ${bundle.kind}, ` +
+          `${bundle.apkPaths.length} apk) on ${serial} [${metadata.packageName}]`,
+      );
+      const startedAt = Date.now();
+      const installArgs =
+        bundle.apkPaths.length > 1
+          ? ['install-multiple', '-r', ...bundle.apkPaths]
+          : ['install', '-r', bundle.basePath];
+      let result = await this._adb(['-s', serial, ...installArgs], {
         timeoutMs: this.installTimeoutMs,
         maxBytes: 8 * 1024 * 1024,
       });
-      output = `${result.stdout.toString('utf8')}\n${result.stderr}`;
-    }
-
-    if (result.timedOut) {
-      throw new Error(`adb install timed out after ${this.installTimeoutMs}ms`);
-    }
-    const failure = /Failure\s*\[([^\]]+)\]\s*:?\s*([^\r\n]*)/i.exec(output);
-    if (failure) {
-      throw new Error(
-        `adb install failed: ${failure[1]}${failure[2] && failure[2].trim() ? `: ${failure[2].trim()}` : ''}`,
-      );
-    }
-    if (result.code !== 0 || !/Success/i.test(output)) {
-      throw new Error(
-        `adb install did not report success (exit ${result.code}): ${output.trim().slice(0, 400)}`,
-      );
-    }
-    this._pushLog(`[vm] installed ${metadata.packageName} in ${Date.now() - startedAt}ms`);
+      let output = `${result.stdout.toString('utf8')}\n${result.stderr}`;
+      if (/INSTALL_FAILED_TEST_ONLY/i.test(output)) {
+        this._pushLog('[vm] package is test-only; retrying with -t');
+        const retryArgs =
+          bundle.apkPaths.length > 1
+            ? ['install-multiple', '-r', '-t', ...bundle.apkPaths]
+            : ['install', '-r', '-t', bundle.basePath];
+        result = await this._adb(['-s', serial, ...retryArgs], {
+          timeoutMs: this.installTimeoutMs,
+          maxBytes: 8 * 1024 * 1024,
+        });
+        output = `${result.stdout.toString('utf8')}\n${result.stderr}`;
+      }
+      if (result.timedOut) {
+        throw new Error(`adb install timed out after ${this.installTimeoutMs}ms`);
+      }
+      const failure = /Failure\s*\[([^\]]+)\]\s*:?\s*([^\r\n]*)/i.exec(output);
+      if (failure) {
+        throw new Error(
+          `adb install failed: ${failure[1]}${failure[2] && failure[2].trim() ? `: ${failure[2].trim()}` : ''}`,
+        );
+      }
+      if (result.code !== 0 || !/Success/i.test(output)) {
+        throw new Error(
+          `adb install did not report success (exit ${result.code}): ${output.trim().slice(0, 400)}`,
+        );
+      }
+      this._pushLog(`[vm] installed ${metadata.packageName} in ${Date.now() - startedAt}ms`);
 
-    if (metadata.launchActivity) {
-      try {
-        await this.launchPackage(metadata.packageName, metadata.launchActivity);
-        this._pushLog(`[vm] launched ${metadata.packageName}/${metadata.launchActivity}`);
-      } catch (error) {
-        this._pushLog(`[vm] install succeeded but launch failed: ${error.message}`);
+      if (metadata.launchActivity) {
+        try {
+          await this.launchPackage(metadata.packageName, metadata.launchActivity);
+          this._pushLog(`[vm] launched ${metadata.packageName}/${metadata.launchActivity}`);
+        } catch (error) {
+          this._pushLog(`[vm] install succeeded but launch failed: ${error.message}`);
+        }
+      } else {
+        this._pushLog(`[vm] ${metadata.packageName} exposes no launchable activity; not launched`);
       }
-    } else {
-      this._pushLog(`[vm] ${metadata.packageName} exposes no launchable activity; not launched`);
+      return bundle.kind === 'apk'
+        ? metadata
+        : { ...metadata, bundle: { kind: bundle.kind, apkCount: bundle.apkPaths.length } };
+    } finally {
+      await cleanupBundle(bundle);
     }
-    return metadata;
   }
 
   /** Launch a package/activity via `adb shell am start -n` (monkey fallback without activity). */
@@ -1368,18 +1407,128 @@ export class AndroidVm {
     return { ok: true, rotation, orientation: String(orientation) };
   }
 
+  /** Configure or clear the guest's global HTTP proxy. */
+  async setProxy(options = {}) {
+    const opts = options && typeof options === 'object' ? options : {};
+    const enabled = opts.enabled !== false;
+    const serial = this._debugSerial();
+    const run = (command) =>
+      this._adbText(['-s', serial, 'shell', command], { timeoutMs: 20000, maxBytes: 64 * 1024 }).then((text) =>
+        text.trim(),
+      );
+    if (!enabled) {
+      await run('settings delete global http_proxy 2>/dev/null || true');
+      await run('settings delete global global_http_proxy_host 2>/dev/null || true');
+      await run('settings delete global global_http_proxy_port 2>/dev/null || true');
+      await run('settings delete global global_http_proxy_exclusion_list 2>/dev/null || true');
+      const current = await run('settings get global http_proxy');
+      this._pushLog('[vm] HTTP proxy cleared');
+      return { ok: true, proxy: null, host: null, port: null, current: current || null };
+    }
+    const host = String(opts.host || '').trim();
+    const port = Number(opts.port);
+    if (!/^[A-Za-z0-9._:-]{1,253}$/.test(host)) throw new Error(`invalid proxy host: ${JSON.stringify(opts.host)}`);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`invalid proxy port: ${opts.port}`);
+    const proxy = `${host}:${port}`;
+    await run(`settings put global http_proxy ${proxy}`);
+    await run(`settings put global global_http_proxy_host ${host}`);
+    await run(`settings put global global_http_proxy_port ${port}`);
+    if (typeof opts.bypass === 'string' && opts.bypass.trim()) {
+      await run(`settings put global global_http_proxy_exclusion_list ${opts.bypass.trim()}`);
+    }
+    const current = await run('settings get global http_proxy');
+    this._pushLog(`[vm] HTTP proxy set to ${proxy}`);
+    return { ok: true, proxy, host, port, current: current || null };
+  }
+
+  /** Read the guest's current global HTTP proxy settings. */
+  async getProxy() {
+    const serial = this._debugSerial();
+    const text = await this._adbText(['-s', serial, 'shell', 'settings get global http_proxy'], {
+      timeoutMs: 15000,
+      maxBytes: 64 * 1024,
+    });
+    const proxy = String(text).trim();
+    return { ok: true, proxy: proxy && proxy !== 'null' && proxy !== ':0' ? proxy : null };
+  }
+
+  /**
+   * Install a PEM/DER CA certificate into the rooted guest's user CA store and,
+   * when the system partition is writable, into the system store as well.
+   * Returns the Android-compatible subject hash filename.
+   */
+  async installCaCertificate(localPath) {
+    const file = path.resolve(String(localPath || ''));
+    if (!file) throw new Error('installCaCertificate requires a local certificate path');
+    if (!/\.(pem|crt|cer|der)$/i.test(file)) throw new Error('certificate must be .pem, .crt, .cer or .der');
+    if (!existsSync(file)) throw new Error(`certificate not found: ${file}`);
+    const input = await fsp.readFile(file);
+    const cert = inspectCertificate(input);
+    await this.ensureRoot();
+    const serial = this._debugSerial();
+    const remote = `/data/local/tmp/dsh-ca-${cert.fileName}`;
+    const push = await this._adb(['-s', serial, 'push', file, remote], {
+      timeoutMs: 60000,
+      maxBytes: 64 * 1024,
+    });
+    if (push.code !== 0 || push.timedOut) {
+      throw new Error(`failed to push certificate: ${push.stderr.toString('utf8').slice(0, 300)}`);
+    }
+    const userDir = '/data/misc/user/0/cacerts-added';
+    const installUser = await this._adb(
+      [
+        '-s',
+        serial,
+        'shell',
+        `mkdir -p ${userDir} && cp ${remote} ${userDir}/${cert.fileName} && ` +
+          `chmod 644 ${userDir}/${cert.fileName} && chown system:system ${userDir}/${cert.fileName} && ` +
+          `(restorecon ${userDir}/${cert.fileName} 2>/dev/null || true) && ls -l ${userDir}/${cert.fileName}`,
+      ],
+      { timeoutMs: 20000, maxBytes: 64 * 1024 },
+    );
+    if (installUser.code !== 0) {
+      throw new Error(`failed to install user CA: ${installUser.stderr.toString('utf8').slice(0, 300)}`);
+    }
+    let systemCa = false;
+    const remount = await this._adb(
+      ['-s', serial, 'shell', 'mount -o rw,remount / 2>/dev/null || true; cp ' + remote + ' /system/etc/security/cacerts/' + cert.fileName + ' 2>/dev/null'],
+      { timeoutMs: 20000, maxBytes: 64 * 1024 },
+    );
+    if (remount.code === 0) {
+      const verify = await this._adb(['-s', serial, 'shell', `test -f /system/etc/security/cacerts/${cert.fileName} && echo yes`], {
+        timeoutMs: 10000,
+        maxBytes: 16 * 1024,
+      });
+      systemCa = /yes/.test(verify.stdout.toString('utf8'));
+    }
+    await this._adb(['-s', serial, 'shell', 'rm', '-f', remote], { timeoutMs: 10000, maxBytes: 16 * 1024 }).catch(() => {});
+    this._pushLog(`[vm] installed CA ${cert.hash}.0 (user=${true}, system=${systemCa})`);
+    return {
+      ok: true,
+      hash: cert.hash,
+      fileName: cert.fileName,
+      subject: cert.subject,
+      installedPath: `${userDir}/${cert.fileName}`,
+      systemCa,
+      note: systemCa
+        ? 'user and system CA stores updated; restart the target app'
+        : 'user CA store updated; apps targeting API 24+ may still require a system CA or a network-security-config override',
+    };
+  }
+
   /** Dump the current UIAutomator hierarchy XML (for agent/UI inspection). */
   async uiDump() {
     await this.ensureRoot();
     const serial = this._debugSerial();
     const remote = '/data/local/tmp/dsh-window.xml';
     const result = await this._adb(
-      ['-s', serial, 'shell', `uiautomator dump ${remote} >/dev/null 2>&1; cat ${remote}`],
+      ['-s', serial, 'shell', `uiautomator dump ${remote} 2>&1; cat ${remote} 2>/dev/null`],
       { timeoutMs: 45000, maxBytes: 1024 * 1024 },
     );
     let xml = result.stdout.toString('utf8').trim();
     if (!/<hierarchy[\s>]/.test(xml)) {
-      throw new Error(`uiautomator dump failed: ${result.stderr.toString('utf8').slice(0, 300) || 'empty hierarchy'}`);
+      const detail = `${result.stderr.toString('utf8')}\n${xml}`.trim().slice(0, 500);
+      throw new Error(`uiautomator dump failed: ${detail || 'empty hierarchy'}`);
     }
     const nodes = (xml.match(/<node\b/g) || []).length;
     if (xml.length > 500000) xml = xml.slice(0, 500000);
@@ -1510,6 +1659,7 @@ export class AndroidVm {
 
     this.serial = target;
     this._serialActive = target;
+    this._suppressAutoAttach = false;
     this._pushLog(`[vm] connecting to ${target}`);
 
     try {
@@ -1670,6 +1820,7 @@ export class AndroidVm {
     this._managedPort = managed.port;
     this._external = true;
     this._externalSerial = target;
+    this._suppressAutoAttach = false;
     this.avdName = '';
     this.serial = target;
     this.port = null;
@@ -1687,6 +1838,7 @@ export class AndroidVm {
     this._serialActive = null;
     this._external = false;
     this._externalSerial = null;
+    this._suppressAutoAttach = false;
     this.avdName = this._managedAvdName;
     this.serial = this._managedSerial;
     this.port = this._managedPort;
@@ -1878,7 +2030,7 @@ export class AndroidVm {
       return { args: [], bootKind: 'cold', accelAvailable, snapshotAvailable, fatal: message };
     }
     const bootKind = snapshotAvailable ? 'snapshot' : 'cold';
-    const args = ['-avd', this.avdName, '-no-window', '-no-audio', '-no-boot-anim'];
+    const args = ['-avd', this.avdName, '-no-window', '-no-audio', '-no-boot-anim', '-no-metrics'];
     if (snapshotAvailable) {
       args.push('-snapshot', this.snapshotName);
     } else if (!this.quickBoot) {
@@ -2107,6 +2259,9 @@ export class AndroidVm {
   }
 
   async _refresh() {
+    // After stop(), keep reporting `stopped` instead of immediately auto-attaching
+    // a pre-existing device again on the next status poll. start() clears this.
+    if (this._suppressAutoAttach && this._state === 'stopped') return;
     const devices = await this._listDevices();
 
     if (this._lastProbeError) {
@@ -2348,15 +2503,24 @@ export class AndroidVm {
   }
 
   async _assertApkFile(apkPath) {
-    if (typeof apkPath !== 'string' || apkPath.trim() === '') {
-      throw new Error('an APK path is required');
+    const file = await this._assertPackageFile(apkPath);
+    if (!/\.apk$/i.test(file)) throw new Error(`not an .apk file: ${file}`);
+    return file;
+  }
+
+  async _assertPackageFile(packagePath) {
+    if (typeof packagePath !== 'string' || packagePath.trim() === '') {
+      throw new Error('an APK/APKS/XAPK path is required');
+    }
+    const file = path.resolve(packagePath);
+    if (!/\.(?:apk|apks|xapk)$/i.test(file)) {
+      throw new Error(`package must be .apk, .apks or .xapk (AAB must be converted first): ${file}`);
     }
-    const file = path.resolve(apkPath);
     let stat;
     try {
       stat = await fsp.stat(file);
     } catch {
-      throw new Error(`APK not found: ${file}`);
+      throw new Error(`package not found: ${file}`);
     }
     if (!stat.isFile()) throw new Error(`not a regular file: ${file}`);
     return file;

package/lib/apk-bundle.js

@@ -0,0 +1,165 @@
+/**
+ * APK bundle support: plain .apk, Android App Bundle archives (.apks) and
+ * XAPK packages. Uses only Node built-ins; split APKs are extracted to a temp
+ * directory and installed with `adb install-multiple`.
+ */
+import { inflateRawSync } from 'node:zlib';
+import { promises as fsp } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+function readUInt64(buffer, offset) {
+  const low = buffer.readUInt32LE(offset);
+  const high = buffer.readUInt32LE(offset + 4);
+  return high * 0x100000000 + low;
+}
+
+/** List entries in an APK/ZIP/APKS/XAPK archive from its central directory. */
+export function listZipEntries(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 22) throw new Error('not a ZIP archive');
+  let eocd = -1;
+  const min = Math.max(0, buffer.length - 65557);
+  for (let i = buffer.length - 22; i >= min; i -= 1) {
+    if (buffer.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0) throw new Error('not a ZIP archive: end-of-central-directory not found');
+  const total = buffer.readUInt16LE(eocd + 10);
+  let offset = buffer.readUInt32LE(eocd + 16);
+  const entries = [];
+  for (let index = 0; index < total; index += 1) {
+    if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== 0x02014b50) {
+      throw new Error('corrupt ZIP central directory');
+    }
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const uncompressedSize = buffer.readUInt32LE(offset + 24);
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    const localOffset = buffer.readUInt32LE(offset + 42);
+    const name = buffer.toString('utf8', offset + 46, offset + 46 + nameLength).replace(/\\/g, '/');
+    if (name && !name.endsWith('/')) {
+      entries.push({
+        name,
+        method,
+        compressedSize,
+        uncompressedSize,
+        localOffset,
+        dataOffset: -1,
+      });
+    }
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+  for (const entry of entries) {
+    if (entry.localOffset + 30 > buffer.length || buffer.readUInt32LE(entry.localOffset) !== 0x04034b50) {
+      throw new Error(`corrupt ZIP local header for ${entry.name}`);
+    }
+    const nameLength = buffer.readUInt16LE(entry.localOffset + 26);
+    const extraLength = buffer.readUInt16LE(entry.localOffset + 28);
+    entry.dataOffset = entry.localOffset + 30 + nameLength + extraLength;
+    if (entry.dataOffset + entry.compressedSize > buffer.length) throw new Error(`truncated ZIP entry ${entry.name}`);
+  }
+  return entries;
+}
+
+function readZipEntry(buffer, entry) {
+  const data = buffer.subarray(entry.dataOffset, entry.dataOffset + entry.compressedSize);
+  if (entry.method === 0) return Buffer.from(data);
+  if (entry.method === 8) return inflateRawSync(data);
+  throw new Error(`unsupported ZIP compression method ${entry.method} for ${entry.name}`);
+}
+
+function safeEntryPath(name) {
+  const normalized = String(name || '')
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .split('/')
+    .filter((part) => part && part !== '.' && part !== '..')
+    .join('/');
+  if (!normalized || normalized.includes('\0')) throw new Error(`unsafe ZIP entry name: ${JSON.stringify(name)}`);
+  return normalized;
+}
+
+function isApkEntry(name) {
+  return /\.apk$/i.test(name);
+}
+
+function bundleKind(filePath) {
+  const ext = path.extname(String(filePath || '')).toLowerCase();
+  if (ext === '.apk') return 'apk';
+  if (ext === '.apks') return 'apks';
+  if (ext === '.xapk') return 'xapk';
+  if (ext === '.aab') return 'aab';
+  return 'unknown';
+}
+
+function chooseBase(apks) {
+  const byName = apks.find((entry) => /(^|\/)(splits\/)?base-master\.apk$/i.test(entry.name));
+  if (byName) return byName;
+  const plainBase = apks.find((entry) => /(^|\/)(base|universal|app)\.apk$/i.test(entry.name));
+  if (plainBase) return plainBase;
+  return [...apks].sort((a, b) => b.uncompressedSize - a.uncompressedSize)[0] || null;
+}
+
+/**
+ * Extract a bundle to a temp directory.
+ * Returns { kind, basePath, apkPaths, extractedDir, entries }.
+ */
+export async function extractApkBundle(filePath, options = {}) {
+  const source = path.resolve(String(filePath || ''));
+  const kind = bundleKind(source);
+  if (kind === 'unknown') throw new Error(`unsupported package extension: ${path.extname(source) || '(none)'}`);
+  if (kind === 'aab') {
+    throw new Error(
+      'AAB files are App Bundles and cannot be installed directly; build device APKs first ' +
+        '(e.g. `bundletool build-apks --bundle app.aab --output app.apks`) and upload the .apks file',
+    );
+  }
+  if (kind === 'apk') return { kind, basePath: source, apkPaths: [source], extractedDir: null, entries: [] };
+  const buffer = await fsp.readFile(source);
+  const entries = listZipEntries(buffer);
+  const apks = entries.filter((entry) => isApkEntry(entry.name));
+  if (!apks.length) throw new Error(`${kind.toUpperCase()} archive contains no .apk entries`);
+  const base = chooseBase(apks);
+  if (!base) throw new Error(`${kind.toUpperCase()} archive has no candidate base APK`);
+  // Install the base plus all split/config APKs. In .apks archives the
+  // standalone variant is intentionally ignored: it is a complete fallback, not
+  // a split that belongs next to base-master.
+  let selected = apks;
+  if (kind === 'apks') {
+    selected = apks.filter((entry) => !/^standalones\//i.test(entry.name));
+    if (!selected.some((entry) => entry.name === base.name)) selected.push(base);
+  }
+  const dir =
+    options.dir ||
+    path.join(os.tmpdir(), `dsh-apk-bundle-${Date.now()}-${randomUUID().slice(0, 8)}`);
+  await fsp.mkdir(dir, { recursive: true });
+  const apkPaths = [];
+  let basePath = null;
+  for (const entry of selected) {
+    const relative = safeEntryPath(entry.name);
+    const target = path.join(dir, relative);
+    if (!target.startsWith(dir + path.sep)) throw new Error(`unsafe bundle path: ${entry.name}`);
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    await fsp.writeFile(target, readZipEntry(buffer, entry));
+    apkPaths.push(target);
+    if (entry.name === base.name) basePath = target;
+  }
+  if (!basePath) basePath = apkPaths[0];
+  return {
+    kind,
+    basePath,
+    apkPaths,
+    extractedDir: dir,
+    entries: selected.map((entry) => entry.name),
+  };
+}
+
+export async function cleanupBundle(bundle) {
+  if (!bundle || !bundle.extractedDir) return;
+  await fsp.rm(bundle.extractedDir, { recursive: true, force: true }).catch(() => {});
+}