feat: bundle adb platform-tools into packaged app

ADB runtime logic now works as follows:
- App window shows first, then ADB initializes asynchronously in the background
- If an ADB server is already listening on 127.0.0.1:5037, the app reuses it and does not start its own server
- If no server is running, the app starts ADB with the bundled binary and then initializes device tracking

This change adds:
- CI step to download platform-tools before packaging
- electron-builder extraResources to embed platform-tools into the app resources directory
- runtime lookup for packaged/dev/downloaded platform-tools locations
- prepare-platform-tools script and tracked placeholder directory
- clearer ADB startup error reporting and adbkit module compatibility fallback

Author: 刘威

.github/workflows/build.yml

@@ -90,6 +90,9 @@ jobs:
           npm_config_fund: false
           npm_config_loglevel: warn
 
+      - name: Prepare bundled platform-tools
+        run: npm run prepare:platform-tools
+
       # Rebuild native modules after cache restore
       - name: Rebuild native modules
         if: steps.npm-cache.outputs.cache-hit == 'true'

.gitignore

@@ -4,6 +4,10 @@ node_modules/
 # Build output
 dist/
 out/
+bundled-tools/*
+!bundled-tools/platform-tools/
+bundled-tools/platform-tools/*
+!bundled-tools/platform-tools/.gitkeep
 
 # Electron
 *.log

bundled-tools/platform-tools/.gitkeep

@@ -0,0 +1 @@
+

electron-builder.yml

@@ -6,6 +6,11 @@ files:
   - src/**/*
   - assets/**/*
   - package.json
+extraResources:
+  - from: bundled-tools/platform-tools
+    to: platform-tools
+    filter:
+      - '**/*'
 win:
   target:
     - target: zip

package.json

@@ -5,6 +5,7 @@
   "main": "src/main/index.js",
   "scripts": {
     "start": "electron .",
+    "prepare:platform-tools": "node scripts/prepare-platform-tools.js",
     "build": "electron-builder",
     "build:win": "electron-builder --win",
     "build:mac": "electron-builder --mac",

scripts/prepare-platform-tools.js

@@ -0,0 +1,20 @@
+const path = require('path');
+const { downloadPlatformTools } = require('../src/main/adb/download');
+
+async function main() {
+  const targetDir = path.resolve(__dirname, '../bundled-tools/platform-tools');
+
+  console.log(`[CI] Preparing platform-tools in ${targetDir}`);
+
+  const adbPath = await downloadPlatformTools((status, progress) => {
+    const suffix = typeof progress === 'number' ? ` ${progress}%` : '';
+    console.log(`[CI] platform-tools ${status}${suffix}`);
+  }, { targetDir });
+
+  console.log(`[CI] ADB prepared at ${adbPath}`);
+}
+
+main().catch((err) => {
+  console.error('[CI] Failed to prepare platform-tools:', err);
+  process.exit(1);
+});

src/main/adb/device.js

@@ -4,7 +4,7 @@ const net = require('net');
 const { spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
-const { getBundledAdbPath, hasBundledAdb } = require('./download');
+const { getBundledAdbPath } = require('./download');
 
 const ADB_SERVER_PORT = 5037;
 const HEALTH_CHECK_INTERVAL = 5000;
@@ -79,9 +79,12 @@ class DeviceManager extends EventEmitter {
 
     if (!isRunning) {
       console.log('[ADB] ADB server not running, starting...');
-      const started = await this._startAdbServer();
-      if (!started) {
-        this.emit('server:error', { message: 'Failed to start ADB server' });
+      const startResult = await this._startAdbServer();
+      if (!startResult.ok) {
+        this.emit('server:error', {
+          message: startResult.message || 'Failed to start ADB server',
+          help: startResult.help || 'Please install Android Platform Tools or start ADB manually.'
+        });
         return;
       }
     } else {
@@ -90,7 +93,22 @@ class DeviceManager extends EventEmitter {
 
     // Initialize adbkit client
     try {
-      const adbkit = require('@devicefarmer/adbkit').default || require('@devicefarmer/adbkit');
+      // Prefer adbkit from package.json; keep compatibility with devicefarmer fork if present.
+      let adbkit;
+      try {
+        adbkit = require('adbkit');
+      } catch (errPrimary) {
+        const missingPrimary = errPrimary && errPrimary.code === 'MODULE_NOT_FOUND';
+        if (!missingPrimary) throw errPrimary;
+        try {
+          const fallback = require('@devicefarmer/adbkit');
+          adbkit = fallback.default || fallback;
+        } catch (errFallback) {
+          throw new Error(
+            `Unable to load ADB library. Tried "adbkit" and "@devicefarmer/adbkit". ${errPrimary.message}`
+          );
+        }
+      }
       this.client = adbkit.createClient();
 
       // Start device tracking
@@ -144,36 +162,68 @@ class DeviceManager extends EventEmitter {
 
       let stdout = '';
       let stderr = '';
+      let settled = false;
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        resolve(result);
+      };
 
       proc.stdout.on('data', (data) => { stdout += data.toString(); });
       proc.stderr.on('data', (data) => { stderr += data.toString(); });
 
-      proc.on('close', (code) => {
+      proc.on('close', async (code) => {
         if (code === 0) {
           console.log('[ADB] Server started successfully');
-          resolve(true);
+          finish({ ok: true });
         } else {
-          console.error(`[ADB] Server start failed with code ${code}: ${stderr}`);
-          resolve(false);
+          // Some adb variants return non-zero while server is actually up.
+          const running = await this._checkServerRunning();
+          if (running) {
+            console.warn(`[ADB] start-server exited with code ${code}, but server is reachable`);
+            finish({ ok: true });
+            return;
+          }
+
+          const details = (stderr || stdout || '').trim();
+          const message = details
+            ? `Failed to start ADB server (${details})`
+            : `Failed to start ADB server (exit code ${code})`;
+          console.error(`[ADB] ${message}`);
+          finish({
+            ok: false,
+            message,
+            help: 'Run "adb start-server" to verify ADB works, or install Android Platform Tools.'
+          });
         }
       });
 
       proc.on('error', (err) => {
         console.error(`[ADB] Failed to spawn adb: ${err.message}`);
-        this.emit('adb:error', {
-          message: 'ADB not found. Please install Android Platform Tools.',
-          help: 'Run "adb install-platform-tools" or install Android SDK.'
+        const isMissingAdb = err.code === 'ENOENT';
+        finish({
+          ok: false,
+          message: isMissingAdb
+            ? 'ADB binary not found. Please install Android Platform Tools.'
+            : `Failed to launch ADB: ${err.message}`,
+          help: isMissingAdb
+            ? 'Use "Auto Download" in the app or install Android Platform Tools manually.'
+            : 'Please verify adb executable is accessible and retry.'
         });
-        resolve(false);
       });
 
       // Timeout after 10 seconds
-      setTimeout(() => {
+      const timeout = setTimeout(() => {
         if (!proc.killed) {
           proc.kill();
           console.log('[ADB] Server start timed out');
-          resolve(false);
         }
+        finish({
+          ok: false,
+          message: 'Failed to start ADB server (timeout)',
+          help: 'Please check whether adb can start from terminal via "adb start-server".'
+        });
       }, 10000);
     });
   }

src/main/adb/download.js

@@ -11,22 +11,55 @@ const PLATFORM_TOOLS_URLS = {
   linux: 'https://dl.google.com/android/repository/platform-tools-latest-linux.zip'
 };
 
-// Get platform tools directory
-function getPlatformToolsDir() {
+function getAdbExecutableName() {
+  return process.platform === 'win32' ? 'adb.exe' : 'adb';
+}
+
+function getDownloadedPlatformToolsDir() {
   return path.join(os.homedir(), '.adb-proxy-browser', 'platform-tools');
 }
 
+function getDevBundledPlatformToolsDir() {
+  return path.resolve(__dirname, '../../../bundled-tools/platform-tools');
+}
+
+function getPackagedPlatformToolsDir() {
+  if (!process.resourcesPath) {
+    return null;
+  }
+  return path.join(process.resourcesPath, 'platform-tools');
+}
+
+function getPlatformToolsDirCandidates() {
+  const candidates = [];
+  const packagedDir = getPackagedPlatformToolsDir();
+  const devBundledDir = getDevBundledPlatformToolsDir();
+  const downloadedDir = getDownloadedPlatformToolsDir();
+
+  if (packagedDir) candidates.push(packagedDir);
+  candidates.push(devBundledDir);
+  candidates.push(downloadedDir);
+
+  return candidates;
+}
+
+function getExistingPlatformToolsDir() {
+  return getPlatformToolsDirCandidates().find((dir) => fs.existsSync(path.join(dir, getAdbExecutableName()))) || null;
+}
+
+// Backward-compatible name used by the rest of the app.
+function getPlatformToolsDir() {
+  return getExistingPlatformToolsDir() || getDownloadedPlatformToolsDir();
+}
+
 // Get adb path
 function getBundledAdbPath() {
-  const dir = getPlatformToolsDir();
-  const adbName = process.platform === 'win32' ? 'adb.exe' : 'adb';
-  return path.join(dir, adbName);
+  return path.join(getPlatformToolsDir(), getAdbExecutableName());
 }
 
 // Check if bundled adb exists
 function hasBundledAdb() {
-  const adbPath = getBundledAdbPath();
-  return fs.existsSync(adbPath);
+  return !!getExistingPlatformToolsDir();
 }
 
 // Download file
@@ -35,10 +68,9 @@ function downloadFile(url, dest) {
     console.log(`[ADB] Downloading from ${url}`);
     const file = fs.createWriteStream(dest);
 
-    const request = (url) => {
-      https.get(url, (response) => {
+    const request = (nextUrl) => {
+      https.get(nextUrl, (response) => {
         if (response.statusCode === 302 || response.statusCode === 301) {
-          // Follow redirect
           request(response.headers.location);
           return;
         }
@@ -53,7 +85,7 @@ function downloadFile(url, dest) {
 
         response.on('data', (chunk) => {
           downloaded += chunk.length;
-          const percent = Math.round((downloaded / totalSize) * 100);
+          const percent = totalSize ? Math.round((downloaded / totalSize) * 100) : 0;
           process.stdout.write(`\r[ADB] Downloading: ${percent}%`);
         });
 
@@ -79,20 +111,18 @@ async function extractZip(zipPath, destDir) {
   return new Promise((resolve, reject) => {
     console.log(`[ADB] Extracting ${zipPath} to ${destDir}`);
 
-    // Create dest directory
     if (!fs.existsSync(destDir)) {
       fs.mkdirSync(destDir, { recursive: true });
     }
 
     let cmd;
     if (process.platform === 'win32') {
-      // Use PowerShell to extract
       cmd = `powershell -Command "Expand-Archive -Path '${zipPath}' -DestinationPath '${path.dirname(destDir)}' -Force"`;
     } else {
       cmd = `unzip -o "${zipPath}" -d "${path.dirname(destDir)}"`;
     }
 
-    exec(cmd, (error, stdout, stderr) => {
+    exec(cmd, (error) => {
       if (error) {
         console.error(`[ADB] Extract error: ${error.message}`);
         reject(error);
@@ -104,39 +134,50 @@ async function extractZip(zipPath, destDir) {
   });
 }
 
+function ensureAdbExecutable(targetDir) {
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  const adbPath = path.join(targetDir, getAdbExecutableName());
+  if (fs.existsSync(adbPath)) {
+    fs.chmodSync(adbPath, '755');
+  }
+}
+
+function ensureAdbExists(targetDir) {
+  const adbPath = path.join(targetDir, getAdbExecutableName());
+  if (!fs.existsSync(adbPath)) {
+    throw new Error(`ADB binary not found after extraction: ${adbPath}`);
+  }
+  return adbPath;
+}
+
 // Download and setup platform tools
-async function downloadPlatformTools(onProgress) {
+async function downloadPlatformTools(onProgress, options = {}) {
   const url = PLATFORM_TOOLS_URLS[process.platform];
   if (!url) {
     throw new Error(`Unsupported platform: ${process.platform}`);
   }
 
-  const platformToolsDir = getPlatformToolsDir();
-  const zipPath = path.join(os.tmpdir(), 'platform-tools.zip');
+  const platformToolsDir = options.targetDir || getDownloadedPlatformToolsDir();
+  const zipPath = options.zipPath || path.join(os.tmpdir(), `platform-tools-${process.platform}.zip`);
 
   try {
     if (onProgress) onProgress('downloading', 0);
 
-    // Download
     await downloadFile(url, zipPath);
     if (onProgress) onProgress('extracting', 50);
 
-    // Extract
     await extractZip(zipPath, platformToolsDir);
+    ensureAdbExecutable(platformToolsDir);
+    const adbPath = ensureAdbExists(platformToolsDir);
     if (onProgress) onProgress('complete', 100);
 
-    // Make executable on Unix
-    if (process.platform !== 'win32') {
-      const adbPath = getBundledAdbPath();
-      fs.chmodSync(adbPath, '755');
-    }
-
-    // Cleanup
     fs.unlinkSync(zipPath);
 
-    return getBundledAdbPath();
+    return adbPath;
   } catch (err) {
-    // Cleanup on error
     try {
       if (fs.existsSync(zipPath)) fs.unlinkSync(zipPath);
     } catch (e) {}
@@ -146,6 +187,9 @@ async function downloadPlatformTools(onProgress) {
 
 module.exports = {
   getPlatformToolsDir,
+  getDownloadedPlatformToolsDir,
+  getDevBundledPlatformToolsDir,
+  getPackagedPlatformToolsDir,
   getBundledAdbPath,
   hasBundledAdb,
   downloadPlatformTools