@ebowwa/ios-devices 1.0.0

package/src/unified-api.ts

@@ -0,0 +1,578 @@
+/**
+ * Unified API - Single interface for iOS device control
+ * Automatically selects best available tool (devicectl > libimobiledevice)
+ */
+
+import { DeviceCtl } from './device-ctl.js';
+import { LibIMobileDevice } from './lib-imobiledevice.js';
+import { SimCtl } from './sim-ctl.js';
+import { checkAvailableTools, type ExecOptions } from './utils.js';
+import {
+  type IOSDevice,
+  type DeviceDetails,
+  type ProcessInfo,
+  type InstalledApp,
+  type FileInfo,
+  type LogEntry,
+  type LogFilter,
+  type CommandResult,
+  type SimulatorDevice,
+  type Location,
+} from './types.js';
+
+export interface IOSDevicesOptions {
+  timeout?: number;
+  preferDeviceCtl?: boolean; // Default true for iOS 17+
+}
+
+export class IOSDevices {
+  private deviceCtl: DeviceCtl | null = null;
+  private libIMobile: LibIMobileDevice | null = null;
+  private simCtl: SimCtl;
+  private availableTools: {
+    devicectl: boolean;
+    simctl: boolean;
+    libimobiledevice: boolean;
+  } | null = null;
+
+  constructor(private options: IOSDevicesOptions = {}) {
+    this.simCtl = new SimCtl(options);
+  }
+
+  /**
+   * Initialize and check available tools
+   */
+  async initialize(): Promise<void> {
+    this.availableTools = await checkAvailableTools();
+
+    if (this.availableTools.devicectl && this.options.preferDeviceCtl !== false) {
+      this.deviceCtl = new DeviceCtl(this.options);
+    }
+
+    if (this.availableTools.libimobiledevice) {
+      this.libIMobile = new LibIMobileDevice(this.options);
+    }
+  }
+
+  /**
+   * Get available tools status
+   */
+  getToolsStatus(): { devicectl: boolean; simctl: boolean; libimobiledevice: boolean } | null {
+    return this.availableTools;
+  }
+
+  // ==========================================================================
+  // Device Management (Physical Devices)
+  // ==========================================================================
+
+  /**
+   * List all connected devices
+   */
+  async listDevices(): Promise<IOSDevice[]> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      // DeviceCtl.listDevices() returns IOSDevice[] directly
+      return await this.deviceCtl.listDevices();
+    }
+
+    if (this.libIMobile) {
+      const result = await this.libIMobile.listDevices();
+      if (result.success) {
+        return this.parseDeviceListLegacy(result.stdout);
+      }
+    }
+
+    return [];
+  }
+
+  /**
+   * Get device details
+   */
+  async getDeviceDetails(deviceId: string): Promise<DeviceDetails | null> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      const details = await this.deviceCtl.getDeviceInfo(deviceId);
+      if (details) {
+        return details;
+      }
+    }
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId, ...this.options });
+      const result = await libIMobile.getDeviceInfo();
+      if (result.success) {
+        return this.parseDeviceDetailsLegacy(result.stdout);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Reboot device
+   */
+  async rebootDevice(deviceId: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      return this.deviceCtl.reboot(deviceId);
+    }
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.restart();
+    }
+
+    return { success: false, stdout: '', stderr: 'No device control tools available', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // Process Management
+  // ==========================================================================
+
+  /**
+   * List processes on device
+   */
+  async listProcesses(deviceId: string): Promise<ProcessInfo[]> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      return this.deviceCtl.listProcesses(deviceId);
+    }
+
+    return [];
+  }
+
+  /**
+   * Launch app
+   */
+  async launchApp(deviceId: string, bundleId: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      return this.deviceCtl.launchApp(deviceId, bundleId);
+    }
+
+    return { success: false, stdout: '', stderr: 'devicectl required for launch', exitCode: 1 };
+  }
+
+  /**
+   * Terminate app/process
+   */
+  async terminateProcess(deviceId: string, pidOrName: number | string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      if (typeof pidOrName === 'number') {
+        return this.deviceCtl.terminateProcess(deviceId, pidOrName);
+      } else {
+        // Find PID first
+        const processes = await this.listProcesses(deviceId);
+        const proc = processes.find((p) => p.name === pidOrName || p.bundleIdentifier === pidOrName);
+        if (proc) {
+          return this.deviceCtl.terminateProcess(deviceId, proc.pid);
+        }
+        return { success: false, stdout: '', stderr: 'Process not found', exitCode: 1 };
+      }
+    }
+
+    return { success: false, stdout: '', stderr: 'devicectl required', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // App Management
+  // ==========================================================================
+
+  /**
+   * List installed apps
+   */
+  async listApps(deviceId: string): Promise<InstalledApp[]> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      return this.deviceCtl.listApps(deviceId);
+    }
+
+    return [];
+  }
+
+  /**
+   * Install app
+   */
+  async installApp(deviceId: string, appPath: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      return this.deviceCtl.installApp(deviceId, appPath);
+    }
+
+    return { success: false, stdout: '', stderr: 'devicectl required', exitCode: 1 };
+  }
+
+  /**
+   * Uninstall app
+   */
+  async uninstallApp(deviceId: string, bundleId: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.deviceCtl) {
+      return this.deviceCtl.uninstallApp(deviceId, bundleId);
+    }
+
+    return { success: false, stdout: '', stderr: 'devicectl required', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // Logging
+  // ==========================================================================
+
+  /**
+   * Stream syslog
+   */
+  async streamSyslog(deviceId: string, filter?: LogFilter): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.streamSyslog(filter);
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required for syslog', exitCode: 1 };
+  }
+
+  /**
+   * Get syslog archive
+   */
+  async getSyslogArchive(deviceId: string, outputPath: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.getSyslogArchive(outputPath);
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // Screenshot
+  // ==========================================================================
+
+  /**
+   * Take screenshot
+   */
+  async takeScreenshot(deviceId: string, outputPath?: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.takeScreenshot(outputPath);
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // Location
+  // ==========================================================================
+
+  /**
+   * Set simulated location
+   */
+  async setLocation(deviceId: string, latitude: number, longitude: number): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.setLocation(latitude, longitude);
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required', exitCode: 1 };
+  }
+
+  /**
+   * Reset location
+   */
+  async resetLocation(deviceId: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.resetLocation();
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // Backup
+  // ==========================================================================
+
+  /**
+   * Create backup
+   */
+  async createBackup(deviceId: string, directory: string, encrypt?: boolean, password?: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.createBackup(directory, encrypt, password);
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required', exitCode: 1 };
+  }
+
+  /**
+   * Restore backup
+   */
+  async restoreBackup(deviceId: string, directory: string, password?: string): Promise<CommandResult> {
+    if (!this.availableTools) await this.initialize();
+
+    if (this.libIMobile) {
+      const libIMobile = new LibIMobileDevice({ udid: deviceId });
+      return libIMobile.restoreBackup(directory, password);
+    }
+
+    return { success: false, stdout: '', stderr: 'libimobiledevice required', exitCode: 1 };
+  }
+
+  // ==========================================================================
+  // Simulator (direct access)
+  // ==========================================================================
+
+  /**
+   * Get SimCtl instance for simulator control
+   */
+  getSimulator(): SimCtl {
+    return this.simCtl;
+  }
+
+  /**
+   * List simulators
+   */
+  async listSimulators(): Promise<SimulatorDevice[]> {
+    const result = await this.simCtl.list({ devices: true, available: true });
+    if (result.success) {
+      return this.parseSimulatorList(result.stdout);
+    }
+    return [];
+  }
+
+  /**
+   * Boot simulator
+   */
+  async bootSimulator(udid: string): Promise<CommandResult> {
+    return this.simCtl.boot(udid);
+  }
+
+  /**
+   * Shutdown simulator
+   */
+  async shutdownSimulator(udid: string): Promise<CommandResult> {
+    return this.simCtl.shutdown(udid);
+  }
+
+  // ==========================================================================
+  // Parsing Helpers
+  // ==========================================================================
+
+  private parseDeviceList(json: unknown): IOSDevice[] {
+    // Parse devicectl JSON output
+    const devices: IOSDevice[] = [];
+    try {
+      const data = json as { devices?: Array<{
+        identifier?: string;
+        name?: string;
+        modelCode?: string;
+        productType?: string;
+        osVersion?: string;
+        osBuildVersion?: string;
+        architecture?: string;
+        platform?: string;
+        connectionProperties?: { connectionType?: string };
+      }> };
+
+      if (data?.devices) {
+        for (const d of data.devices) {
+          devices.push({
+            identifier: d.identifier || '',
+            name: d.name || '',
+            model: d.modelCode || '',
+            modelCode: d.modelCode || '',
+            productType: d.productType || '',
+            osVersion: d.osVersion || '',
+            osBuildVersion: d.osBuildVersion || '',
+            architecture: d.architecture || '',
+            platform: (d.platform as IOSDevice['platform']) || 'iOS',
+            connectionType: d.connectionProperties?.connectionType === 'Wired' ? 'USB' : 'Network',
+            isTrusted: true,
+            isAvailable: true,
+          });
+        }
+      }
+    } catch {
+      // Parse error
+    }
+    return devices;
+  }
+
+  private parseDeviceListLegacy(text: string): IOSDevice[] {
+    // Parse idevice_id -l output
+    const devices: IOSDevice[] = [];
+    const lines = text.split('\n');
+    for (const line of lines) {
+      const match = line.match(/^([A-F0-9-]+)\s+(.+)$/);
+      if (match) {
+      devices.push({
+        identifier: match[1],
+        name: match[2].trim(),
+        model: '',
+        modelCode: '',
+        productType: '',
+        osVersion: '',
+        osBuildVersion: '',
+        architecture: '',
+        platform: 'iOS',
+        connectionType: 'USB',
+        isTrusted: true,
+        isAvailable: true,
+      });
+    }
+  }
+    return devices;
+  }
+
+  private parseDeviceDetails(json: unknown): DeviceDetails | null {
+    try {
+      const d = json as {
+        identifier?: string;
+        name?: string;
+        modelCode?: string;
+        productType?: string;
+        productVersion?: string;
+        buildVersion?: string;
+        serialNumber?: string;
+        architecture?: string;
+      };
+
+      return {
+        udid: d.identifier || '',
+        name: d.name || '',
+        model: d.modelCode || '',
+        productType: d.productType || '',
+        productVersion: d.productVersion || '',
+        buildVersion: d.buildVersion || '',
+        serialNumber: d.serialNumber,
+        cpuArchitecture: d.architecture || '',
+        deviceName: d.name || '',
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private parseDeviceDetailsLegacy(text: string): DeviceDetails | null {
+    // Parse ideviceinfo output
+    const details: Partial<DeviceDetails> = {};
+    const lines = text.split('\n');
+    for (const line of lines) {
+      const match = line.match(/^(.+?):\s*(.+)$/);
+      if (match) {
+        const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+        const value = match[2].trim();
+        if (key === 'unique_device_id') details.udid = value;
+        if (key === 'device_name') details.name = value;
+        if (key === 'model_name') details.model = value;
+        if (key === 'product_type') details.productType = value;
+        if (key === 'product_version') details.productVersion = value;
+        if (key === 'build_version') details.buildVersion = value;
+        if (key === 'serial_number') details.serialNumber = value;
+        if (key === 'cpu_architecture') details.cpuArchitecture = value;
+      }
+    }
+    return details as DeviceDetails;
+  }
+
+  private parseProcessList(json: unknown): ProcessInfo[] {
+    const processes: ProcessInfo[] = [];
+    try {
+      const data = json as { processes?: Array<{
+        pid?: number;
+        name?: string;
+        user?: string;
+        bundleIdentifier?: string;
+      }> };
+
+      if (data?.processes) {
+        for (const p of data.processes) {
+          processes.push({
+            pid: p.pid || 0,
+            name: p.name || '',
+            user: p.user,
+            bundleIdentifier: p.bundleIdentifier,
+          });
+        }
+      }
+    } catch {
+      // Parse error
+    }
+    return processes;
+  }
+
+  private parseAppList(json: unknown): InstalledApp[] {
+    const apps: InstalledApp[] = [];
+    try {
+      const data = json as { apps?: Array<{
+        bundleIdentifier?: string;
+        bundleName?: string;
+        bundleVersion?: string;
+        installPath?: string;
+        platform?: string;
+        type?: string;
+      }> };
+
+      if (data?.apps) {
+        for (const a of data.apps) {
+          apps.push({
+            bundleIdentifier: a.bundleIdentifier || '',
+            bundleName: a.bundleName || '',
+            bundleVersion: a.bundleVersion || '',
+            installPath: a.installPath || '',
+            platform: (a.platform as InstalledApp['platform']) || 'iOS',
+            type: (a.type as InstalledApp['type']) || 'User',
+          });
+        }
+      }
+    } catch {
+      // Parse error
+    }
+    return apps;
+  }
+
+  private parseSimulatorList(text: string): SimulatorDevice[] {
+    const simulators: SimulatorDevice[] = [];
+    const lines = text.split('\n');
+    for (const line of lines) {
+      const match = line.match(/([A-F0-9-]+)\s+\((.+?)\)\s+\((.+?)\)/);
+      if (match) {
+        simulators.push({
+          udid: match[1],
+          name: match[2],
+          state: line.includes('Booted') ? 'Booted' : 'Shutdown',
+          runtime: match[3],
+          deviceType: '',
+          availability: 'available',
+        });
+      }
+    }
+    return simulators;
+  }
+}
+
+// Re-export classes for direct access
+export { DeviceCtl } from './device-ctl.js';
+export { LibIMobileDevice } from './lib-imobiledevice.js';
+export { SimCtl } from './sim-ctl.js';
+export { checkAvailableTools } from './utils.js';