@mcesystems/apple-kit 1.0.0 → 1.0.1

package/dist/index.js

@@ -1,10 +1,9 @@
-// src/logic/appleDeviceKit.ts
-import { spawn } from "node:child_process";
-
 // src/utils/debug.ts
 import createDebug from "debug";
 var debug = createDebug("apple-kit");
 var debugTask = createDebug("apple-kit:task");
+var debugWarning = createDebug("apple-kit:warning");
+var debugError = createDebug("apple-kit:error");
 function logInfo(message) {
   debug(message);
 }
@@ -12,73 +11,13 @@ function logTask(message) {
   debugTask(message);
 }
 
-// src/utils/exec.ts
+// src/logic/actions/device.ts
 import { exec as execCallback } from "node:child_process";
-import { promisify } from "node:util";
-
-// src/utils/idevicePath.ts
 import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname(__filename);
-function getResourcesBinPath() {
-  const packageRoot = dirname(dirname(__dirname));
-  const platform = process.platform;
-  let platformDir;
-  switch (platform) {
-    case "win32":
-      platformDir = "windows";
-      break;
-    case "darwin":
-      platformDir = "darwin";
-      break;
-    case "linux":
-      platformDir = "linux";
-      break;
-    default:
-      throw new Error(`Unsupported platform: ${platform}`);
-  }
-  return join(packageRoot, "resources", "bin", platformDir);
-}
-function getIDeviceToolPath(toolName) {
-  const binPath = getResourcesBinPath();
-  const ext = process.platform === "win32" ? ".exe" : "";
-  const toolPath = join(binPath, `${toolName}${ext}`);
-  if (existsSync(toolPath)) {
-    return toolPath;
-  }
-  return null;
-}
-function getIDeviceBinPath() {
-  return getResourcesBinPath();
-}
-
-// src/utils/exec.ts
-var execAsync = promisify(execCallback);
-async function execIDevice(command, options = {}) {
-  const binPath = getIDeviceBinPath();
-  const env = {
-    ...process.env,
-    PATH: `${binPath};${process.env.PATH}`
-  };
-  const result = await execAsync(command, {
-    ...options,
-    env,
-    windowsHide: true,
-    encoding: "utf8"
-  });
-  return {
-    stdout: result.stdout.toString(),
-    stderr: result.stderr.toString()
-  };
-}
-async function runIDeviceTool(toolPath, args = [], options = {}) {
-  const command = `"${toolPath}" ${args.map((a) => `"${a}"`).join(" ")}`;
-  return execIDevice(command, options);
-}
+import { join } from "node:path";
+import { promisify } from "node:util";
 
-// src/logic/appleDeviceKit.ts
+// src/logic/dataParser.ts
 function parsePlistOutput(output) {
   const result = {};
   const lines = output.split("\n");
@@ -125,6 +64,413 @@ function parseAppList(output) {
   }
   return apps;
 }
+
+// src/logic/actions/device.ts
+var execAsync = promisify(execCallback);
+async function getDeviceInfo(udid) {
+  logTask(`Getting device info for ${udid}`);
+  const result = await runIDeviceTool("ideviceinfo", ["-u", udid]);
+  if (!result) {
+    throw new Error("Failed to get device info");
+  }
+  const props = parsePlistOutput(result.stdout);
+  return {
+    deviceName: props.DeviceName || "",
+    productType: props.ProductType || "",
+    productVersion: props.ProductVersion || "",
+    buildVersion: props.BuildVersion || "",
+    serialNumber: props.SerialNumber || "",
+    udid: props.UniqueDeviceID || udid,
+    wifiAddress: props.WiFiAddress || "",
+    bluetoothAddress: props.BluetoothAddress || "",
+    phoneNumber: props.PhoneNumber || "",
+    cpuArchitecture: props.CPUArchitecture || "",
+    hardwareModel: props.HardwareModel || "",
+    modelNumber: props.ModelNumber || "",
+    regionInfo: props.RegionInfo || "",
+    timeZone: props.TimeZone || "",
+    uniqueChipID: props.UniqueChipID || "",
+    isPaired: true
+    // If we can get info, device is paired
+  };
+}
+async function listDevices() {
+  try {
+    const result = await runIDeviceTool("idevice_id", ["-l"]);
+    if (!result) {
+      return [];
+    }
+    return parseDeviceList(result.stdout);
+  } catch {
+    return [];
+  }
+}
+async function runIDeviceTool(toolName, args = [], options = {}) {
+  const command = `"${toolName}" ${args.map((a) => `"${a}"`).join(" ")}`;
+  return execIDevice(command, options);
+}
+async function execIDevice(command, options = {}) {
+  const binPath = getIDeviceBinPath();
+  const env = {
+    ...process.env,
+    PATH: `${binPath};${process.env.PATH}`
+  };
+  const result = await execAsync(command, {
+    ...options,
+    env,
+    windowsHide: true,
+    encoding: "utf8"
+  });
+  return {
+    stdout: result.stdout.toString(),
+    stderr: result.stderr.toString()
+  };
+}
+function getResourcesBinPath() {
+  const binPath = process.env.IDeviceBinPath;
+  if (!binPath) {
+    throw new Error("IDeviceBinPath is not set");
+  }
+  return binPath;
+}
+function getIDeviceBinPath() {
+  return getResourcesBinPath();
+}
+
+// src/logic/actions/activation.ts
+async function getActivationState(udid) {
+  logTask(`Getting activation state for device ${udid}`);
+  try {
+    const result = await runIDeviceTool("ideviceinfo", ["-u", udid, "-k", "ActivationState"]);
+    if (!result) {
+      return {
+        isActivated: false,
+        activationState: "Unknown"
+      };
+    }
+    const { stdout } = result;
+    const state = stdout.trim();
+    return {
+      isActivated: state === "Activated",
+      activationState: state
+    };
+  } catch {
+    return {
+      isActivated: false,
+      activationState: "Unknown"
+    };
+  }
+}
+async function activate(udid) {
+  logTask(`Activating device ${udid}`);
+  try {
+    const result = await runIDeviceTool("ideviceactivation", ["-u", udid, "activate"]);
+    if (!result) {
+      return false;
+    }
+    return result.stdout.toLowerCase().includes("success") || result.stdout.toLowerCase().includes("activated");
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    throw new Error(`Activation failed: ${errorMsg}`);
+  }
+}
+
+// src/logic/actions/pair.ts
+async function isPaired(udid) {
+  logTask(`Checking pairing status for ${udid}`);
+  try {
+    const result = await runIDeviceTool("idevicepair", [
+      "-u",
+      udid,
+      "validate"
+    ]);
+    if (!result) {
+      return false;
+    }
+    return result.stdout.toLowerCase().includes("success");
+  } catch {
+    return false;
+  }
+}
+async function trustDevice(udid, timeout = 6e4, onWaitingForTrust) {
+  logTask(`Trusting device ${udid}`);
+  if (await isPaired(udid)) {
+    logInfo(`Device ${udid} is already trusted`);
+    return true;
+  }
+  logInfo(`Initiating pairing for device ${udid}`);
+  const pairResult = await pair(udid);
+  if (pairResult) {
+    logInfo(`Device ${udid} paired successfully`);
+    return true;
+  }
+  logInfo("Please accept the trust dialog on the device...");
+  onWaitingForTrust?.();
+  try {
+    await waitForPairing(udid, timeout, 1e3);
+    logInfo(`Device ${udid} is now trusted`);
+    return true;
+  } catch {
+    logInfo(`Timeout waiting for trust acceptance on device ${udid}`);
+    return false;
+  }
+}
+async function waitForPairing(udid, timeout = 12e4, pollInterval = 1e3) {
+  logTask(`Waiting for pairing on device ${udid}`);
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    if (await isPaired(udid)) {
+      logInfo(`Device ${udid} is now paired`);
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+  throw new Error(`Timeout waiting for device pairing after ${timeout}ms`);
+}
+async function pair(udid) {
+  logTask(`Initiating pairing for device ${udid}`);
+  try {
+    const result = await runIDeviceTool("idevicepair", ["-u", udid, "pair"]);
+    if (!result) {
+      return false;
+    }
+    return result.stdout.toLowerCase().includes("success");
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    if (errorMsg.includes("Please accept the trust dialog")) {
+      return false;
+    }
+    throw error;
+  }
+}
+async function unpair(udid) {
+  logTask(`Un-pairing device ${udid}`);
+  try {
+    const result = await runIDeviceTool("idevicepair", [
+      "-u",
+      udid,
+      "unpair"
+    ]);
+    if (!result) {
+      return false;
+    }
+    return result.stdout.toLowerCase().includes("success");
+  } catch {
+    return false;
+  }
+}
+
+// src/logic/actions/install.ts
+async function installApp(ipaPath, udid) {
+  logTask(`Installing app ${ipaPath} on device ${udid}`);
+  if (!await isPaired(udid)) {
+    await waitForPairing(udid, 1e4);
+  }
+  await runIDeviceTool("ideviceinstaller", ["-u", udid, "-i", ipaPath]);
+}
+async function uninstallApp(bundleId, udid) {
+  logTask(`Uninstalling app ${bundleId} from device ${udid}`);
+  if (!await isPaired(udid)) {
+    await waitForPairing(udid, 1e4);
+  }
+  await runIDeviceTool("ideviceinstaller", ["-u", udid, "-U", bundleId]);
+}
+async function listApps(udid) {
+  logTask(`Listing apps on device ${udid}`);
+  if (!await isPaired(udid)) {
+    await waitForPairing(udid, 1e4);
+  }
+  try {
+    const result = await runIDeviceTool("ideviceinstaller", ["-u", udid, "-l"]);
+    if (!result) {
+      return [];
+    }
+    const { stdout } = result;
+    return parseAppList(stdout);
+  } catch {
+    return [];
+  }
+}
+async function isAppInstalled(bundleId, udid) {
+  logTask(`Checking if app ${bundleId} is installed on device ${udid}`);
+  const apps = await listApps(udid);
+  return apps.some((app) => app.bundleId === bundleId);
+}
+async function wakeDevice(udid) {
+  try {
+    logInfo("Attempting to wake device screen...");
+    await runIDeviceTool("ideviceinfo", ["-u", udid, "-k", "DeviceName"]);
+    try {
+      await runIDeviceTool("ideviceinfo", ["-u", udid, "-k", "ActivationState"]);
+    } catch {
+    }
+    try {
+      await runIDeviceTool("idevicepair", ["-u", udid, "validate"]);
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1e3));
+    logInfo("Device wake attempt completed");
+  } catch (error) {
+    logInfo(
+      `Device wake attempt failed (non-critical): ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+async function launchApp(bundleId, args, udid) {
+  logTask(`Launching app ${bundleId} on device ${udid}`);
+  if (!await isPaired(udid)) {
+    await waitForPairing(udid, 1e4);
+  }
+  await wakeDevice(udid);
+  try {
+    logInfo(`Attempting to launch ${bundleId} using idevicedebug...`);
+    const result = await runIDeviceTool("idevicedebug", ["-u", udid, "run", bundleId, ...args]);
+    const output = (result?.stdout ?? "") + (result?.stderr ?? "");
+    if (output.trim()) {
+      logInfo(`idevicedebug output: ${output.substring(0, 200)}`);
+    }
+    if (output.toLowerCase().includes("could not start") && output.toLowerCase().includes("debugserver")) {
+      logInfo("idevicedebug requires debugserver, falling back to pymobiledevice3...");
+      throw new Error("debugserver_not_available");
+    }
+    logInfo(`App ${bundleId} launched successfully using idevicedebug`);
+    await new Promise((resolve) => setTimeout(resolve, 1e3));
+    return;
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    if (errorMsg.includes("debugserver_not_available") || errorMsg.toLowerCase().includes("could not start") || errorMsg.toLowerCase().includes("debugserver")) {
+      logInfo("idevicedebug failed, trying pymobiledevice3 for iOS 17+...");
+      await launchAppWithPymobiledevice3(bundleId, args, udid);
+      return;
+    }
+    throw error;
+  }
+}
+async function launchAppWithPymobiledevice3(bundleId, args, udid) {
+  logTask(`Launching app ${bundleId} using pymobiledevice3`);
+  const { exec } = await import("node:child_process");
+  const { promisify: promisify2 } = await import("node:util");
+  const execAsync2 = promisify2(exec);
+  try {
+    let cmdArgs = [
+      "-m",
+      "pymobiledevice3",
+      "developer",
+      "dvt",
+      "launch",
+      "--udid",
+      udid,
+      "--kill-existing",
+      // Kill existing instance to bring app to foreground
+      bundleId,
+      ...args
+    ];
+    let command = `python ${cmdArgs.map((a) => `"${a}"`).join(" ")}`;
+    logInfo(`Executing: ${command}`);
+    const result = await execAsync2(command, {
+      windowsHide: true,
+      encoding: "utf8",
+      timeout: 3e4
+      // 30 second timeout
+    });
+    const output = result.stdout.toString() + result.stderr.toString();
+    if (output.trim()) {
+      logInfo(`pymobiledevice3 output: ${output.substring(0, 200)}`);
+    }
+    if (output.toLowerCase().includes("developer mode") && output.toLowerCase().includes("not enabled")) {
+      throw new Error(
+        "Developer Mode is not enabled on the device.\nPlease enable it: Settings \u2192 Privacy & Security \u2192 Developer Mode \u2192 Enable"
+      );
+    }
+    if (output.toLowerCase().includes("tunneld") && (output.toLowerCase().includes("unable to connect") || output.toLowerCase().includes("invalidserviceerror"))) {
+      logInfo("Tunnel required, retrying with tunnel option...");
+      cmdArgs = [
+        "-m",
+        "pymobiledevice3",
+        "developer",
+        "dvt",
+        "launch",
+        "--udid",
+        udid,
+        "--tunnel",
+        udid,
+        // Use UDID for tunnel
+        "--kill-existing",
+        bundleId,
+        ...args
+      ];
+      command = `python ${cmdArgs.map((a) => `"${a}"`).join(" ")}`;
+      logInfo(`Retrying with tunnel: ${command}`);
+      try {
+        const retryResult = await execAsync2(command, {
+          windowsHide: true,
+          encoding: "utf8",
+          timeout: 3e4
+        });
+        const retryOutput = retryResult.stdout.toString() + retryResult.stderr.toString();
+        if (retryOutput.trim()) {
+          logInfo(`pymobiledevice3 retry output: ${retryOutput.substring(0, 200)}`);
+        }
+        if (retryOutput.toLowerCase().includes("tunneld") && retryOutput.toLowerCase().includes("unable to connect")) {
+          throw new Error(
+            "Tunnel connection failed. For iOS 17+, you may need to start tunneld:\n  python -m pymobiledevice3 remote tunneld\nOr ensure Developer Mode is enabled and device is unlocked."
+          );
+        }
+        logInfo(`App ${bundleId} launched successfully using pymobiledevice3 with tunnel`);
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return;
+      } catch {
+        throw new Error(
+          "Tunnel connection failed. For iOS 17+, you may need to start tunneld:\n  python -m pymobiledevice3 remote tunneld\nOr ensure Developer Mode is enabled and device is unlocked."
+        );
+      }
+    }
+    if (output.toLowerCase().includes("not found") || output.toLowerCase().includes("command not found") || output.toLowerCase().includes("cannot find")) {
+      throw new Error(
+        "pymobiledevice3 is not installed.\nInstall it with: python -m pip install --user pymobiledevice3"
+      );
+    }
+    if (output.toLowerCase().includes("error") && !output.toLowerCase().includes("warning")) {
+      logInfo(`Warning: pymobiledevice3 reported errors: ${output.substring(0, 300)}`);
+    }
+    logInfo(`App ${bundleId} launched successfully using pymobiledevice3`);
+    await new Promise((resolve) => setTimeout(resolve, 1e3));
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    if (errorMsg.includes("not found") || errorMsg.includes("command not found") || errorMsg.includes("cannot find") || errorMsg.includes("No module named")) {
+      throw new Error(
+        "pymobiledevice3 is not installed or Python is not available.\nInstall it with: python -m pip install --user pymobiledevice3\nFor iOS 17+, Developer Mode must also be enabled on the device."
+      );
+    }
+    throw error;
+  }
+}
+
+// src/logic/actions/proxy.ts
+async function startPortForward(localPort, devicePort, udid) {
+  logTask(`Starting port forward ${localPort} -> ${devicePort} for device ${udid}`);
+  const result = await runIDeviceTool("iproxy", [
+    localPort.toString(),
+    devicePort.toString(),
+    "-u",
+    udid
+  ]);
+  return {
+    localPort,
+    devicePort,
+    ...result
+  };
+}
+async function startPortForwardAsync(localPort, devicePort, udid, _timeout = 5e3) {
+  const result = await startPortForward(localPort, devicePort, udid);
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  if (result.stdout.includes("error") || result.stderr.includes("error")) {
+    throw new Error("Port forwarding failed to start");
+  }
+  return result;
+}
+
+// src/logic/appleDeviceKit.ts
 var AppleDeviceKit = class {
   constructor(udid, port) {
     this.port = port;
@@ -132,314 +478,127 @@ var AppleDeviceKit = class {
     logInfo(`AppleDeviceKit initialized for device: ${this.deviceId}`);
   }
   deviceId;
-  // ==================== Device Info ====================
   /**
    * Get detailed device information
    */
   async getDeviceInfo() {
-    logTask(`Getting device info for ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("ideviceinfo");
-    if (!toolPath) {
-      throw new Error("ideviceinfo tool not found");
-    }
-    const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId]);
-    const props = parsePlistOutput(stdout);
-    return {
-      deviceName: props.DeviceName || "",
-      productType: props.ProductType || "",
-      productVersion: props.ProductVersion || "",
-      buildVersion: props.BuildVersion || "",
-      serialNumber: props.SerialNumber || "",
-      udid: props.UniqueDeviceID || this.deviceId,
-      wifiAddress: props.WiFiAddress || "",
-      bluetoothAddress: props.BluetoothAddress || "",
-      phoneNumber: props.PhoneNumber || "",
-      cpuArchitecture: props.CPUArchitecture || "",
-      hardwareModel: props.HardwareModel || "",
-      modelNumber: props.ModelNumber || "",
-      regionInfo: props.RegionInfo || "",
-      timeZone: props.TimeZone || "",
-      uniqueChipID: props.UniqueChipID || "",
-      isPaired: true
-      // If we can get info, device is paired
-    };
+    return getDeviceInfo(this.deviceId);
   }
-  // ==================== Trust/Pairing ====================
   /**
    * Check if device is paired/trusted with this computer
    */
   async isPaired() {
-    logTask(`Checking pairing status for ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("idevicepair");
-    if (!toolPath) {
-      throw new Error("idevicepair tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "validate"]);
-      return stdout.toLowerCase().includes("success");
-    } catch {
-      return false;
-    }
+    return isPaired(this.deviceId);
   }
   /**
    * Wait for device to be paired
    * Polls the pairing status until successful or timeout
-   * 
+   *
    * @param timeout Timeout in milliseconds (default: 120000)
    * @param pollInterval Poll interval in milliseconds (default: 1000)
    */
   async waitForPairing(timeout = 12e4, pollInterval = 1e3) {
-    logTask(`Waiting for pairing on device ${this.deviceId}`);
-    const startTime = Date.now();
-    while (Date.now() - startTime < timeout) {
-      if (await this.isPaired()) {
-        logInfo(`Device ${this.deviceId} is now paired`);
-        return true;
-      }
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
-    }
-    throw new Error(`Timeout waiting for device pairing after ${timeout}ms`);
+    return waitForPairing(this.deviceId, timeout, pollInterval);
   }
   /**
    * Attempt to pair/trust the device
    * User must accept the trust dialog on the device
    */
   async pair() {
-    logTask(`Initiating pairing for device ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("idevicepair");
-    if (!toolPath) {
-      throw new Error("idevicepair tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "pair"]);
-      return stdout.toLowerCase().includes("success");
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      if (errorMsg.includes("Please accept the trust dialog")) {
-        return false;
-      }
-      throw error;
-    }
+    return pair(this.deviceId);
+  }
+  /**
+   * Trust/pair the device - initiates pairing and waits for user to accept
+   *
+   * This is the recommended method for establishing trust with a device.
+   * It will:
+   * 1. Check if already paired
+   * 2. If not, initiate pairing (shows "Trust This Computer?" on device)
+   * 3. Wait for user to accept the trust dialog
+   *
+   * @param timeout Timeout in milliseconds to wait for user acceptance (default: 60000)
+   * @param onWaitingForTrust Callback when waiting for user to accept trust dialog
+   * @returns true if device is now trusted
+   */
+  async trustDevice(timeout = 6e4, onWaitingForTrust) {
+    return trustDevice(this.deviceId, timeout, onWaitingForTrust);
   }
   /**
    * Unpair/untrust the device
    */
   async unpair() {
-    logTask(`Unpairing device ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("idevicepair");
-    if (!toolPath) {
-      throw new Error("idevicepair tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "unpair"]);
-      return stdout.toLowerCase().includes("success");
-    } catch {
-      return false;
-    }
+    return unpair(this.deviceId);
   }
-  // ==================== App Installation ====================
   /**
    * Install an IPA file on the device (install agent)
-   * 
+   *
    * @param ipaPath Path to the IPA file
    */
   async installApp(ipaPath) {
-    logTask(`Installing app ${ipaPath} on device ${this.deviceId}`);
-    if (!await this.isPaired()) {
-      await this.waitForPairing(1e4);
-    }
-    const toolPath = getIDeviceToolPath("ideviceinstaller");
-    if (!toolPath) {
-      throw new Error("ideviceinstaller tool not found");
-    }
-    await runIDeviceTool(toolPath, ["-u", this.deviceId, "-i", ipaPath]);
+    installApp(ipaPath, this.deviceId);
   }
   /**
    * Uninstall an app by bundle ID (uninstall agent)
-   * 
+   *
    * @param bundleId Application bundle identifier
    */
   async uninstallApp(bundleId) {
-    logTask(`Uninstalling app ${bundleId} from device ${this.deviceId}`);
-    if (!await this.isPaired()) {
-      await this.waitForPairing(1e4);
-    }
-    const toolPath = getIDeviceToolPath("ideviceinstaller");
-    if (!toolPath) {
-      throw new Error("ideviceinstaller tool not found");
-    }
-    await runIDeviceTool(toolPath, ["-u", this.deviceId, "-U", bundleId]);
+    uninstallApp(bundleId, this.deviceId);
   }
   /**
    * Check if an app is installed on the device
-   * 
+   *
    * @param bundleId Application bundle identifier
    */
   async isAppInstalled(bundleId) {
-    logTask(`Checking if app ${bundleId} is installed on device ${this.deviceId}`);
-    const apps = await this.listApps();
-    return apps.some((app) => app.bundleId === bundleId);
+    return isAppInstalled(bundleId, this.deviceId);
   }
   /**
    * List all installed user applications
    */
   async listApps() {
-    logTask(`Listing apps on device ${this.deviceId}`);
-    if (!await this.isPaired()) {
-      await this.waitForPairing(1e4);
-    }
-    const toolPath = getIDeviceToolPath("ideviceinstaller");
-    if (!toolPath) {
-      throw new Error("ideviceinstaller tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "-l"]);
-      return parseAppList(stdout);
-    } catch {
-      return [];
-    }
+    return listApps(this.deviceId);
   }
-  // ==================== Launch Application ====================
   /**
    * Launch an application on the device
-   * 
-   * @param bundleId Application bundle identifier to launch
-   * @param args Optional arguments to pass to the app
+   *
+   * @param bundleId Application bundle identifier
+   * @param args Application arguments
    */
   async launchApp(bundleId, args = []) {
-    logTask(`Launching app ${bundleId} on device ${this.deviceId}`);
-    if (!await this.isPaired()) {
-      await this.waitForPairing(1e4);
-    }
-    const toolPath = getIDeviceToolPath("idevicedebug");
-    if (!toolPath) {
-      throw new Error("idevicedebug tool not found");
-    }
-    const toolArgs = ["-u", this.deviceId, "run", bundleId, ...args];
-    await runIDeviceTool(toolPath, toolArgs);
-  }
-  // ==================== Port Forwarding ====================
-  /**
-   * Start port forwarding from local port to device port
-   * 
-   * @param localPort Local port to listen on
-   * @param devicePort Device port to forward to
-   * @returns Handle to stop the port forwarding
-   */
-  startPortForward(localPort, devicePort) {
-    logTask(`Starting port forward ${localPort} -> ${devicePort} for device ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("iproxy");
-    if (!toolPath) {
-      throw new Error("iproxy tool not found");
-    }
-    const binPath = getIDeviceBinPath();
-    const env = {
-      ...process.env,
-      PATH: `${binPath};${process.env.PATH}`
-    };
-    const proc = spawn(toolPath, [
-      localPort.toString(),
-      devicePort.toString(),
-      "-u",
-      this.deviceId
-    ], {
-      env,
-      windowsHide: true,
-      stdio: "pipe"
-    });
-    proc.on("error", (err) => {
-      logInfo(`Port forward error: ${err.message}`);
-    });
-    return {
-      stop: () => {
-        proc.kill();
-      },
-      localPort,
-      devicePort,
-      process: proc
-    };
+    return launchApp(bundleId, args, this.deviceId);
   }
   /**
-   * Start port forwarding and wait for it to be ready
-   * 
+   * Start port forwarding and wait for it to be ready.
+   * we need port forwarding to be able to connect to the device from the computer
+   * and communicate with it using the local port.
+   *
    * @param localPort Local port to listen on
    * @param devicePort Device port to forward to
    * @param _timeout Timeout in milliseconds (reserved for future use)
    */
   async startPortForwardAsync(localPort, devicePort, _timeout = 5e3) {
-    const handle = this.startPortForward(localPort, devicePort);
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    if (handle.process.killed || handle.process.exitCode !== null) {
-      throw new Error("Port forwarding failed to start");
-    }
-    return handle;
+    return startPortForwardAsync(localPort, devicePort, this.deviceId);
   }
-  // ==================== Activation ====================
   /**
    * Get the activation state of the device
    */
   async getActivationState() {
-    logTask(`Getting activation state for device ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("ideviceinfo");
-    if (!toolPath) {
-      throw new Error("ideviceinfo tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "-k", "ActivationState"]);
-      const state = stdout.trim();
-      return {
-        isActivated: state === "Activated",
-        activationState: state
-      };
-    } catch {
-      return {
-        isActivated: false,
-        activationState: "Unknown"
-      };
-    }
+    return getActivationState(this.deviceId);
   }
   /**
-   * Activate the device
+   * Activate the device (register in apple servers), an activated device belongs to someone (a user/company).
+   * A device that is on hello screen cannot pass the wifi step unless it is activated.
+   * the activate save us the need of the device to be connected to the internet to do the activation
+   * and register in apple servers.
+   *
    * Note: This requires a valid activation record or Apple server access
+   *
+   * precondition: the device must be paired and trusted
    */
   async activate() {
-    logTask(`Activating device ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("ideviceactivation");
-    if (!toolPath) {
-      throw new Error("ideviceactivation tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "activate"]);
-      return stdout.toLowerCase().includes("success") || stdout.toLowerCase().includes("activated");
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      throw new Error(`Activation failed: ${errorMsg}`);
-    }
-  }
-  /**
-   * Deactivate the device
-   */
-  async deactivate() {
-    logTask(`Deactivating device ${this.deviceId}`);
-    const toolPath = getIDeviceToolPath("ideviceactivation");
-    if (!toolPath) {
-      throw new Error("ideviceactivation tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-u", this.deviceId, "deactivate"]);
-      return stdout.toLowerCase().includes("success");
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Get activation state as string
-   */
-  async getActivationStateString() {
-    const state = await this.getActivationState();
-    return state.activationState;
+    return activate(this.deviceId);
   }
-  // ==================== Device Identifiers ====================
   /**
    * Get the device UDID
    */
@@ -452,22 +611,6 @@ var AppleDeviceKit = class {
   getPort() {
     return this.port;
   }
-  // ==================== Static Methods ====================
-  /**
-   * Static method to list all connected iOS devices
-   */
-  static async listDevices() {
-    const toolPath = getIDeviceToolPath("idevice_id");
-    if (!toolPath) {
-      throw new Error("idevice_id tool not found");
-    }
-    try {
-      const { stdout } = await runIDeviceTool(toolPath, ["-l"]);
-      return parseDeviceList(stdout);
-    } catch {
-      return [];
-    }
-  }
 };
 
 // src/logic/devicesMonitor.ts
@@ -483,7 +626,7 @@ var DevicesMonitor = class {
   eventEmitter;
   /**
    * Start tracking iOS device connections
-   * 
+   *
    * @returns EventEmitter that emits:
    *   - 'added': (deviceKit: AppleDeviceKit) when a device is connected
    *   - 'removed': (deviceId: string, port: number) when a device is disconnected
@@ -493,9 +636,7 @@ var DevicesMonitor = class {
     const listenerConfig = {
       logicalPortMap: this.config.logicalPortMap,
       // Filter for Apple devices only
-      listenOnlyDevices: [
-        { vid: APPLE_VID.toString(16).toUpperCase().padStart(4, "0"), pid: "" }
-      ]
+      listenOnlyDevices: [{ vid: APPLE_VID.toString(16).toUpperCase().padStart(4, "0"), pid: "" }]
     };
     usbDeviceListener.startListening(listenerConfig);
     this.eventEmitter = new EventEmitter();
@@ -553,7 +694,7 @@ var DevicesMonitor = class {
    * Find connected iOS device and emit event
    */
   async findAndEmitDevice(usbDevice) {
-    const iOSDevices = await AppleDeviceKit.listDevices();
+    const iOSDevices = await listDevices();
     if (iOSDevices.length === 0) {
       setTimeout(() => this.findAndEmitDevice(usbDevice), 500);
       return;
@@ -576,7 +717,7 @@ var DevicesMonitor = class {
    */
   async identifyConnectedDevices() {
     logInfo("Identifying already connected iOS devices");
-    const iOSDevices = await AppleDeviceKit.listDevices();
+    const iOSDevices = await listDevices();
     const usbDevices = usbDeviceListener.listDevices().filter((d) => d.vid === APPLE_VID);
     for (let i = 0; i < iOSDevices.length; i++) {
       const iDevice = iOSDevices[i];
@@ -593,88 +734,8 @@ var DevicesMonitor = class {
     }
   }
 };
-
-// src/utils/usbmuxd.ts
-import { spawn as spawn2 } from "node:child_process";
-var usbmuxdProcess = null;
-function startUsbmuxd(foreground = false) {
-  if (usbmuxdProcess && !usbmuxdProcess.killed) {
-    logInfo("usbmuxd is already running");
-    return {
-      stop: () => stopUsbmuxd(),
-      isRunning: () => !usbmuxdProcess?.killed,
-      process: usbmuxdProcess
-    };
-  }
-  const toolPath = getIDeviceToolPath("usbmuxd");
-  if (!toolPath) {
-    throw new Error("usbmuxd executable not found");
-  }
-  const binPath = getIDeviceBinPath();
-  const env = {
-    ...process.env,
-    PATH: `${binPath};${process.env.PATH}`
-  };
-  const args = [];
-  if (foreground) {
-    args.push("-f");
-  }
-  args.push("-v");
-  logInfo(`Starting usbmuxd: ${toolPath}`);
-  usbmuxdProcess = spawn2(toolPath, args, {
-    env,
-    windowsHide: true,
-    stdio: "pipe",
-    detached: !foreground
-  });
-  usbmuxdProcess.stdout?.on("data", (data) => {
-    logInfo(`usbmuxd: ${data.toString().trim()}`);
-  });
-  usbmuxdProcess.stderr?.on("data", (data) => {
-    logInfo(`usbmuxd error: ${data.toString().trim()}`);
-  });
-  usbmuxdProcess.on("error", (err) => {
-    logInfo(`usbmuxd failed to start: ${err.message}`);
-  });
-  usbmuxdProcess.on("exit", (code) => {
-    logInfo(`usbmuxd exited with code ${code}`);
-    usbmuxdProcess = null;
-  });
-  if (!foreground) {
-    usbmuxdProcess.unref();
-  }
-  return {
-    stop: () => stopUsbmuxd(),
-    isRunning: () => usbmuxdProcess !== null && !usbmuxdProcess.killed,
-    process: usbmuxdProcess
-  };
-}
-function stopUsbmuxd() {
-  if (usbmuxdProcess && !usbmuxdProcess.killed) {
-    logInfo("Stopping usbmuxd");
-    usbmuxdProcess.kill();
-    usbmuxdProcess = null;
-  }
-}
-function isUsbmuxdRunning() {
-  return usbmuxdProcess !== null && !usbmuxdProcess.killed;
-}
-function ensureUsbmuxd() {
-  if (isUsbmuxdRunning()) {
-    return {
-      stop: () => stopUsbmuxd(),
-      isRunning: () => isUsbmuxdRunning(),
-      process: usbmuxdProcess
-    };
-  }
-  return startUsbmuxd();
-}
 export {
   AppleDeviceKit,
-  DevicesMonitor,
-  ensureUsbmuxd,
-  isUsbmuxdRunning,
-  startUsbmuxd,
-  stopUsbmuxd
+  DevicesMonitor
 };
 //# sourceMappingURL=index.js.map