@mcesystems/adb-kit 1.0.68 → 1.0.69

package/README.md

@@ -1,191 +1,200 @@
 # @mcesystems/adb-kit
 
-ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations.
+## 1. Description
 
-## Features
+**What it does:** ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations: listing devices, reading device properties, installing/uninstalling apps, checking and waiting for USB debugging, and port forwarding.
 
-- **Device Operations**: Get device properties, install/uninstall apps
-- **USB Debugging Detection**: Check and wait for USB debugging enabled
-- **Port Forwarding**: Forward local ports to device services
-- **Cross-platform**: Works on Windows, macOS, and Linux
+**When it's used:** Use this package when your application needs to communicate with Android devices over ADB—for example device management tools, test runners, or installers that target Android hardware.
 
-## Installation
+## 2. Install
 
 ```bash
 npm install @mcesystems/adb-kit
 ```
 
-## Requirements
+**Requirements:** Node.js 18+, Android device with USB debugging enabled, and ADB binaries (see Resources).
 
-- Node.js 18+
-- Android device with USB debugging enabled
-- ADB binaries (see Platform Setup)
+## 3. Resources
 
-### Platform Setup
+This package needs ADB binaries to run. You can obtain them in one of these ways:
 
-#### Using the Export Script (Recommended for Distribution)
+**Option A – Export script (recommended for distribution)**  
+Bundle ADB for your app using the provided script:
 
-Use the export script to bundle ADB binaries for your application:
 ```bash
-# Using npx (after installing the package)
 npx export-adb-resources /path/to/your-app/resources/adb-kit
 
-# Or export for all platforms at once
+# All platforms
 npx export-adb-resources /path/to/your-app/resources/adb-kit --all
-
-# Or run the script directly
-npx tsx node_modules/@mcesystems/adb-kit/scripts/export-resources.ts /path/to/your-app/resources
 ```
 
-See [scripts/README.md](./scripts/README.md) for detailed prerequisites and instructions.
-
-#### Windows & macOS (Development)
+See [scripts/README.md](./scripts/README.md) for arguments, options, output layout, and prerequisites.
 
-Set the `AdbBinPath` environment variable to the ADB binary location, or ensure `adb` is in your system PATH.
+**Option B – Development**  
+- **Windows / macOS:** Set `AdbBinPath` to your ADB binary directory, or have `adb` on system PATH.  
+- **Linux:** Install via package manager (e.g. `sudo apt install adb`).
 
-#### Linux
-
-Install ADB via your package manager:
-```bash
-sudo apt install adb  # Debian/Ubuntu
-sudo dnf install android-tools  # Fedora
-```
+The package resolves ADB in this order: `AdbBinPath` env, then bundled resources under `dist/resources/bin/<platform>/`, then system PATH.
 
-## Usage
+## 4. Examples
 
-### Basic Device Operations
+**Create a device kit and read properties**
 
 ```typescript
 import { AdbDeviceKit } from '@mcesystems/adb-kit';
 
-// Create a device kit for a specific device
 const device = new AdbDeviceKit('device-serial-number', 1);
-
-// Get device properties
 const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
-console.log(`Device: ${manufacturer} ${model}`);
-
-// Get all properties
 const allProps = await device.getAllDeviceProperties();
-
-// List connected devices
 const devices = await device.listDevices();
 ```
 
-### App Management
+**Install/uninstall and check app**
 
 ```typescript
-const device = new AdbDeviceKit('device-serial-number', 1);
-
-// Install an APK
 await device.installApp('/path/to/app.apk');
-
-// Check if app is installed
 const isInstalled = await device.isAppInstalled('com.example.app');
-
-// Uninstall an app
 await device.uninstallApp('com.example.app');
 ```
 
-### USB Debugging
+**USB debugging**
 
 ```typescript
-const device = new AdbDeviceKit('device-serial-number', 1);
-
-// Check if USB debugging is enabled
 const hasDebugging = await device.hasUsbDebugging();
-
-// Wait for USB debugging to be enabled (with timeout)
-await device.waitForUsbDebugging(30000); // 30 seconds
+await device.waitForUsbDebugging(30000); // 30s timeout
 ```
 
-### Port Forwarding
+**Port forwarding**
 
 ```typescript
-const device = new AdbDeviceKit('device-serial-number', 1);
-
-// Forward a local port to a device service
 const localPort = await device.startPortForward('tcp:8080');
-console.log(`Forwarded to local port: ${localPort}`);
 ```
 
-### Access ADB Client
+**Low-level clients**
 
 ```typescript
-const device = new AdbDeviceKit('device-serial-number', 1);
-
-// Get the underlying adbkit client for advanced operations
 const client = await device.getClient();
-
-// Get the device client for direct device operations
 const deviceClient = await device.getDeviceClient();
 ```
 
-## API Reference
+**USB debugging robustness example**
+
+Interactive example that runs the same flow 5 times to verify `waitForUsbDebugging` handling: start without USB debugging (device not found), short 5s timeout (user lets it pass), then wait up to 30s while the user enables USB debugging, show device recognized, then user disables USB debugging and repeats.
+
+```bash
+# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
+pnpm example:usb-debugging
+```
+
+See [examples/usb-debugging-robustness.ts](./examples/usb-debugging-robustness.ts) for the script.
+
+For more scenarios and step-by-step explanations, see [Example.md](./Example.md).
+
+## 5. API
 
 ### AdbDeviceKit
 
-**Constructor:**
-- `new AdbDeviceKit(deviceId: string, port: number)`: Create a device kit
+**Constructor**
+
+- **Input:** `deviceId: string`, `port: number`
+- **Output:** new `AdbDeviceKit` instance bound to that device and logical port.
+
+**listDevices()**
 
-**Device Info:**
-- `getDeviceId()`: Get the device serial number
-- `getPort()`: Get the logical port number
-- `getDeviceProperties(properties: DeviceProperty[])`: Get specific device properties
-- `getAllDeviceProperties()`: Get all device properties
+- **Input:** none
+- **Output:** `Promise<AdbDevice[]>` — list of connected devices (`AdbDevice`: `{ id: string; type: AdbDeviceType }`).
 
-**Device State:**
-- `hasUsbDebugging()`: Check if USB debugging is enabled
-- `waitForUsbDebugging(timeout?)`: Wait for USB debugging
+**getDeviceProperties(properties)**
 
-**App Management:**
-- `installApp(apkPath: string)`: Install an APK
-- `uninstallApp(packageName: string)`: Uninstall an app
-- `isAppInstalled(packageName: string)`: Check if app is installed
+- **Input:** `properties: DeviceProperty[]` — e.g. `['Manufacturer', 'Model']`
+- **Output:** `Promise<string[]>` — values in the same order as `properties`; failed props are `""`.
 
-**Port Forwarding:**
-- `startPortForward(serviceName: string)`: Forward to a device service
+**getAllDeviceProperties()**
 
-**Advanced:**
-- `getClient()`: Get the adbkit client
-- `getDeviceClient()`: Get the device client
-- `listDevices()`: List all connected devices
+- **Input:** none
+- **Output:** `Promise<Record<string, string>>` — all device properties from `getprop`.
+
+**installApp(appPath)**
+
+- **Input:** `appPath: string` — path to APK
+- **Output:** `Promise<void>` — resolves when install finishes; rejects on failure.
+
+**uninstallApp(packageName)**
+
+- **Input:** `packageName: string` — e.g. `'com.example.app'`
+- **Output:** `Promise<void>` — resolves when uninstall finishes; rejects on failure.
+
+**isAppInstalled(packageName)**
+
+- **Input:** `packageName: string`
+- **Output:** `Promise<boolean>` — whether the package is installed.
+
+**hasUsbDebugging()**
+
+- **Input:** none
+- **Output:** `Promise<boolean>` — whether this device appears in the ADB device list.
+
+**waitForUsbDebugging(timeout?, numberOfAllowedAttempts?)**
+
+- **Input:** `timeout?: number` (default `120000` ms), `numberOfAllowedAttempts?: number` (default `5`, accepted for backward compatibility; give-up is determined by timeout and tracker end only)
+- **Output:** `Promise<boolean>` — `true` when device is present and ready, `false` when tracking ends without device; rejects on timeout, device removal, or connection error.
+
+**startPortForward(serviceName)**
+
+- **Input:** `serviceName: string` — e.g. `'tcp:8080'`
+- **Output:** `Promise<number | null>` — local port number used for forwarding, or `null` if forwarding failed. Reuses same port on repeated calls.
+
+**getClient()**
+
+- **Input:** none
+- **Output:** `Promise<AdbClient>` — underlying adbkit client.
+
+**getDeviceClient()**
+
+- **Input:** none
+- **Output:** `Promise<DeviceClient>` — adbkit device client for this device.
+
+**getDeviceId()**
+
+- **Input:** none
+- **Output:** `string` — device serial (last segment after `\` on Windows).
+
+**getPort()**
+
+- **Input:** none
+- **Output:** `number` — logical port passed to the constructor.
 
 ### DeviceProperty
 
-Available device properties:
-- `Manufacturer`, `Name`, `Model`, `Brand`, `Device`
-- `Android Version`, `Platform`, `CPU`, `CPU.abi2`
-- `Description`, `Fingerprint`
-- `GSM Flexversion`, `GSM IMEI`
-- `Locale Language`, `Locale Region`
-- `Wifi Channels`, `Board Platform`, `Product Board`
-- `Display ID`, `Version Incremental`, `Version SDK`
-- `Version Codename`, `Version Release`
-- `Build Date`, `Build Type`, `Build User`
+Supported property names for `getDeviceProperties()`:  
+`Manufacturer`, `Name`, `Model`, `Brand`, `Device`, `Android Version`, `Platform`, `CPU`, `CPU.abi2`, `Description`, `Fingerprint`, `GSM Flexversion`, `GSM IMEI`, `Locale Language`, `Locale Region`, `Wifi Channels`, `Board Platform`, `Product Board`, `Display ID`, `Version Incremental`, `Version SDK`, `Version Codename`, `Version Release`, `Build Date`, `Build Type`, `Build User`.
 
-## Development
+## 6. Flow
 
-```bash
-# Build the package
-npm run build
+Example flow: wait for device, read identity, install an app, then forward a port.
+
+```typescript
+import { AdbDeviceKit } from '@mcesystems/adb-kit';
 
-# Run tests
-npm test
+const deviceId = 'ABC123'; // from your device discovery
+const device = new AdbDeviceKit(deviceId, 1);
 
-# Clean build artifacts
-npm run clean
-```
+// 1. Wait for USB debugging (e.g. after user enables it)
+await device.waitForUsbDebugging(60000);
 
-### Setting Up ADB for Development
+// 2. Identify device
+const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
+console.log(`Device: ${manufacturer} ${model}`);
 
-For development, you can either:
-1. Use the export script to download ADB to a local path
-2. Install ADB via Homebrew (`brew install android-platform-tools`) or your system package manager
-3. Set `AdbBinPath` environment variable to your ADB installation
+// 3. Install app
+await device.installApp('./build/app.apk');
 
-## License
+// 4. Forward a device service to a local port
+const localPort = await device.startPortForward('tcp:8080');
+console.log(`Service reachable at localhost:${localPort}`);
+```
 
-ISC
+## 7. TODO
 
-ADB Platform Tools are licensed under the Apache License 2.0.
+- [ ] Optional: Re-authorize handling when ADB reports vendor keys not set (revoke and re-authorize device).
+- [ ] Optional: Add Example.md with more detailed scenarios and explanations.

package/dist/index.js

@@ -29847,7 +29847,7 @@ var require_adb = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     var client_1 = __importDefault(require_client2());
     var util_1 = __importDefault(require_util3());
-    var Adb = class {
+    var Adb2 = class {
       static createClient(options = {}) {
         const opts = {
           bin: options.bin,
@@ -29864,8 +29864,8 @@ var require_adb = __commonJS({
         return new client_1.default(opts);
       }
     };
-    Adb.util = util_1.default;
-    exports2.default = Adb;
+    Adb2.util = util_1.default;
+    exports2.default = Adb2;
   }
 });
 
@@ -30213,7 +30213,8 @@ var require_dist = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AdbDeviceKit: () => AdbDeviceKit
+  AdbDeviceKit: () => AdbDeviceKit,
+  readAll: () => readAll
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -31284,6 +31285,23 @@ function ensureAdbPathFromResources() {
     logInfo(`Using ADB from resources: ${adbPath}`);
   }
 }
+function isConnectionErrorMessage(err) {
+  const msg = err.message ?? "";
+  const code = err.code ?? "";
+  const name = err.name ?? "";
+  return msg.includes("ECONNRESET") || msg.includes("EPIPE") || msg.includes("Premature end of stream") || code === "ECONNRESET" || code === "EPIPE" || name === "PrematureEOFError";
+}
+var connectionErrorHandlerInstalled = false;
+function installConnectionErrorHandler() {
+  if (connectionErrorHandlerInstalled) return;
+  connectionErrorHandlerInstalled = true;
+  process.on("unhandledRejection", (reason) => {
+    if (reason instanceof Error && isConnectionErrorMessage(reason)) {
+      logDetail(`Suppressed expected ADB connection error: ${reason.message}`);
+      return;
+    }
+  });
+}
 var deviceProps = {
   Manufacturer: "ro.product.manufacturer",
   Name: "ro.product.name",
@@ -31318,9 +31336,8 @@ var AdbDeviceKit = class {
     setLogLevel(process.env.LOG_LEVEL ?? "none");
     logNamespace(`adb:${deviceId}`);
     ensureAdbPathFromResources();
-    this.client = adbkit.default.createClient({
-      bin: process.env.ADB_PATH ?? getAdbBinaryPath() ?? "."
-    });
+    installConnectionErrorHandler();
+    this.client = this.connect();
     this.deviceId = deviceId.split("\\").pop() ?? deviceId;
     logInfo(`Device ID: ${this.deviceId}`);
     this.device = this.client.getDevice(this.deviceId);
@@ -31329,6 +31346,18 @@ var AdbDeviceKit = class {
   device;
   deviceId;
   devicePort = null;
+  connect() {
+    const adbBin = process.env.ADB_PATH ?? getAdbBinaryPath() ?? "adb";
+    const client = adbkit.default.createClient({ bin: adbBin });
+    const errorHandler = (err) => {
+      logError(`ADB client connection error (e.g. device disconnected): ${err.message}`);
+      client.removeListener("error", errorHandler);
+      this.client = this.connect();
+      this.device = this.client.getDevice(this.deviceId);
+    };
+    client.on("error", errorHandler);
+    return client;
+  }
   async listDevices() {
     const devices = await this.client.listDevices();
     return devices;
@@ -31381,39 +31410,84 @@ var AdbDeviceKit = class {
     const devices = await this.listDevices();
     return !!devices.find((device) => device.id === this.deviceId);
   }
-  async waitForUsbDebugging(timeout2 = 12e4, numberOfAllowedAttempts = 5) {
+  /**
+   * Creates an isolated ADB client for tracking operations.
+   * This client is separate from the main client so connection errors
+   * during tracking don't affect other operations.
+   */
+  createTrackingClient() {
+    const adbBin = process.env.ADB_PATH ?? getAdbBinaryPath() ?? "adb";
+    return adbkit.default.createClient({ bin: adbBin });
+  }
+  async waitForUsbDebugging(timeout2 = 12e4, _numberOfAllowedAttempts = 5) {
     if (await this.hasUsbDebugging()) {
       logDetail("USB debugging is already enabled");
       return true;
     }
-    let count = numberOfAllowedAttempts;
-    const tracker = await this.client.trackDevices();
+    const trackingClient = this.createTrackingClient();
+    const tracker = await trackingClient.trackDevices();
+    let settled = false;
     return new Promise((resolve, reject) => {
       const timeoutId = setTimeout(() => {
         logError("Timeout waiting for USB debugging");
-        reject(new Error("Timeout waiting for USB debugging"));
+        settle({ type: "reject", err: new Error("Timeout waiting for USB debugging") });
       }, timeout2);
-      tracker.on("remove", (_) => {
+      const cleanupTrackingClient = () => {
+        try {
+          tracker.end();
+        } catch {
+        }
+        trackingClient.on("error", () => {
+        });
+      };
+      const settle = (result) => {
+        if (settled) return;
+        settled = true;
         clearTimeout(timeoutId);
+        cleanupTrackingClient();
+        if (result.type === "resolve") {
+          resolve(result.value);
+        } else {
+          logError(result.err.message);
+          reject(result.err);
+        }
+      };
+      trackingClient.on("error", (err) => {
+        if (isConnectionErrorMessage(err)) {
+          logDetail(`Tracking client connection closed: ${err.message}`);
+          settle({ type: "resolve", value: false });
+        } else {
+          logError(`Tracking client error: ${err.message}`);
+          settle({ type: "reject", err });
+        }
+      });
+      tracker.on("error", (err) => {
+        if (isConnectionErrorMessage(err)) {
+          logDetail(`Tracker connection closed: ${err.message}`);
+          settle({ type: "resolve", value: false });
+        } else {
+          logError(`Tracker error: ${err.message}`);
+          settle({ type: "reject", err });
+        }
+      });
+      tracker.on("end", () => {
+        logDetail("Device tracking ended");
+        settle({ type: "resolve", value: false });
+      });
+      tracker.on("remove", (_) => {
         logError("Device removed from tracker");
+        settle({ type: "reject", err: new Error("Device removed while waiting for USB debugging") });
       });
       tracker.on("add", (device) => {
         if (device.type === "device") {
           logDetail("Device added to tracker");
-          clearTimeout(timeoutId);
-          resolve(true);
+          settle({ type: "resolve", value: true });
         }
       });
       tracker.on("change", (device) => {
-        count--;
-        if (device.type === "device" && count > 0) {
-          clearTimeout(timeoutId);
+        if (device.type === "device") {
           logDetail("Device changed in tracker");
-          resolve(true);
-        } else if (count === 0) {
-          logDetail("No device found in tracker");
-          this.client.kill();
-          resolve(false);
+          settle({ type: "resolve", value: true });
         }
       });
     });
@@ -31439,8 +31513,13 @@ var AdbDeviceKit = class {
     return this.device;
   }
 };
+
+// src/index.ts
+var import_adbkit = __toESM(require_dist());
+var readAll = import_adbkit.default.util.readAll;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AdbDeviceKit
+  AdbDeviceKit,
+  readAll
 });
 //# sourceMappingURL=index.js.map