@ebowwa/ios-devices 1.0.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ebowwa/ios-devices",
+  "version": "1.0.0",
+  "description": "iOS device control library wrapping xcrun devicectl, libimobiledevice, and simctl",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --sourcemap --external shell-quote",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build && bun run build:types"
+  },
+  "keywords": [
+    "ios",
+    "iphone",
+    "ipad",
+    "device",
+    "devicectl",
+    "simctl",
+    "libimobiledevice",
+    "xcode"
+  ],
+  "author": "ebowwa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ebowwa/codespaces"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "shell-quote": "^1.8.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/device-ctl.ts

@@ -0,0 +1,547 @@
+/**
+ * DeviceCtl - Wrapper for xcrun devicectl (iOS 17+)
+ * Primary interface for modern iOS device control
+ */
+
+import {
+  execDeviceCtl,
+  exec,
+  buildDeviceArg,
+  type ExecOptions,
+} from './utils.js';
+import {
+  type IOSDevice,
+  type DeviceDetails,
+  type ProcessInfo,
+  type InstalledApp,
+  type FileInfo,
+  type DisplayInfo,
+  type CommandResult,
+  type ProcessSignal,
+  type DarwinNotification,
+} from './types.js';
+
+export interface DeviceCtlOptions {
+  timeout?: number;
+}
+
+export class DeviceCtl {
+  private options: DeviceCtlOptions;
+
+  constructor(options: DeviceCtlOptions = {}) {
+    this.options = { timeout: 60000, ...options };
+  }
+
+  private execOpts(): ExecOptions {
+    return { timeout: this.options.timeout };
+  }
+
+  // ==========================================================================
+  // Device Listing & Management
+  // ==========================================================================
+
+  /**
+   * List all connected devices
+   */
+  async listDevices(): Promise<IOSDevice[]> {
+    const result = await execDeviceCtl(['list', 'devices'], this.execOpts());
+
+    if (!result.success || !result.json) {
+      return this.parseDevicesFromText(result.stdout);
+    }
+
+    const data = result.json as { devices?: Array<Record<string, unknown>> };
+    return (data.devices || []).map(this.parseDeviceFromJson);
+  }
+
+  private parseDeviceFromJson(device: Record<string, unknown>): IOSDevice {
+    return {
+      identifier: device.udid as string || device.identifier as string,
+      name: device.name as string || device.deviceName as string || 'Unknown',
+      model: device.model as string || '',
+      modelCode: device.modelCode as string || '',
+      productType: device.productType as string || '',
+      osVersion: device.osVersion as string || device.productVersion as string || '',
+      osBuildVersion: device.buildVersion as string || '',
+      architecture: device.architecture as string || 'arm64e',
+      platform: this.detectPlatform(device.productType as string),
+      connectionType: this.detectConnectionType(device),
+      isTrusted: device.trusted as boolean ?? true,
+      isAvailable: device.available as boolean ?? true,
+    };
+  }
+
+  private parseDevicesFromText(text: string): IOSDevice[] {
+    const lines = text.split('\n');
+    const devices: IOSDevice[] = [];
+
+    for (const line of lines) {
+      // Parse format: "Device Name (iOS 18.1) [UDID]"
+      const match = line.match(/^(.+?)\s*\((.+?)\)\s*\[([A-F0-9-]+)\]/i);
+      if (match) {
+        devices.push({
+          identifier: match[3],
+          name: match[1].trim(),
+          model: '',
+          modelCode: '',
+          productType: '',
+          osVersion: match[2],
+          osBuildVersion: '',
+          architecture: 'arm64e',
+          platform: 'iOS',
+          connectionType: 'USB',
+          isTrusted: true,
+          isAvailable: true,
+        });
+      }
+    }
+
+    return devices;
+  }
+
+  private detectPlatform(productType?: string): 'iOS' | 'iPadOS' | 'tvOS' | 'watchOS' | 'visionOS' {
+    if (!productType) return 'iOS';
+    if (productType.includes('iPad')) return 'iPadOS';
+    if (productType.includes('AppleTV') || productType.includes('TV')) return 'tvOS';
+    if (productType.includes('Watch')) return 'watchOS';
+    if (productType.includes('Vision') || productType.includes('Reality')) return 'visionOS';
+    return 'iOS';
+  }
+
+  private detectConnectionType(device: Record<string, unknown>): 'USB' | 'Network' | 'Wireless' {
+    if (device.connectionType) return device.connectionType as 'USB' | 'Network' | 'Wireless';
+    if (device.networkDevice === true) return 'Network';
+    if (device.wirelessEnabled === true) return 'Wireless';
+    return 'USB';
+  }
+
+  /**
+   * Get detailed device information
+   */
+  async getDeviceInfo(deviceId: string): Promise<DeviceDetails | null> {
+    const result = await execDeviceCtl(
+      ['device', 'info', 'details', ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+
+    if (!result.success) return null;
+
+    if (result.json) {
+      const d = result.json as Record<string, unknown>;
+      return {
+        udid: d.udid as string || deviceId,
+        name: d.name as string || d.deviceName as string || '',
+        model: d.model as string || '',
+        productType: d.productType as string || '',
+        productVersion: d.productVersion as string || d.osVersion as string || '',
+        buildVersion: d.buildVersion as string || '',
+        serialNumber: d.serialNumber as string,
+        cpuArchitecture: d.architecture as string || 'arm64e',
+        deviceName: d.deviceName as string || d.name as string || '',
+        timeZone: d.timeZone as string,
+        locale: d.locale as string,
+      };
+    }
+
+    return this.parseDeviceDetailsFromText(result.stdout);
+  }
+
+  private parseDeviceDetailsFromText(text: string): DeviceDetails | null {
+    const lines = text.split('\n');
+    const info: Record<string, string> = {};
+
+    for (const line of lines) {
+      const match = line.match(/^([^:]+):\s*(.+)$/);
+      if (match) {
+        info[match[1].trim().toLowerCase().replace(/\s+/g, '_')] = match[2].trim();
+      }
+    }
+
+    return {
+      udid: info.udid || info.identifier || '',
+      name: info.name || info.device_name || '',
+      model: info.model || '',
+      productType: info.product_type || '',
+      productVersion: info.product_version || info.os_version || '',
+      buildVersion: info.build_version || '',
+      serialNumber: info.serial_number,
+      cpuArchitecture: info.architecture || info.cpu_architecture || 'arm64e',
+      deviceName: info.device_name || info.name || '',
+    };
+  }
+
+  /**
+   * Get device lock state
+   */
+  async getLockState(deviceId: string): Promise<'locked' | 'unlocked'> {
+    const result = await execDeviceCtl(
+      ['device', 'info', 'lockState', ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+
+    if (result.stdout.toLowerCase().includes('unlocked')) return 'unlocked';
+    return 'locked';
+  }
+
+  /**
+   * Get display information
+   */
+  async getDisplays(deviceId: string): Promise<DisplayInfo[]> {
+    const result = await execDeviceCtl(
+      ['device', 'info', 'displays', ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+
+    if (!result.success || !result.json) return [];
+
+    const displays = (result.json as { displays?: unknown[] }).displays || [];
+    return displays.map((d: unknown) => {
+      const display = d as Record<string, unknown>;
+      return {
+        id: display.id as number || 0,
+        width: display.width as number || display.resolutionWidth as number || 0,
+        height: display.height as number || display.resolutionHeight as number || 0,
+        scale: display.scale as number || 1,
+        refreshRate: display.refreshRate as number,
+        colorSpace: display.colorSpace as string,
+      };
+    });
+  }
+
+  // ==========================================================================
+  // Pairing
+  // ==========================================================================
+
+  /**
+   * Pair with a device
+   */
+  async pair(deviceId: string): Promise<CommandResult> {
+    return execDeviceCtl(['manage', 'pair', ...buildDeviceArg(deviceId)], this.execOpts());
+  }
+
+  /**
+   * Unpair from a device
+   */
+  async unpair(deviceId: string): Promise<CommandResult> {
+    return execDeviceCtl(['manage', 'unpair', ...buildDeviceArg(deviceId)], this.execOpts());
+  }
+
+  // ==========================================================================
+  // Device Control
+  // ==========================================================================
+
+  /**
+   * Reboot a device
+   */
+  async reboot(deviceId: string): Promise<CommandResult> {
+    return execDeviceCtl(['device', 'reboot', ...buildDeviceArg(deviceId)], this.execOpts());
+  }
+
+  /**
+   * Set device orientation
+   */
+  async setOrientation(deviceId: string, orientation: 'portrait' | 'landscape' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right'): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'orientation', '--orientation', orientation, ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+  }
+
+  // ==========================================================================
+  // Process Management
+  // ==========================================================================
+
+  /**
+   * List running processes
+   */
+  async listProcesses(deviceId: string): Promise<ProcessInfo[]> {
+    const result = await execDeviceCtl(
+      ['device', 'info', 'processes', ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+
+    if (!result.success) return [];
+
+    return this.parseProcessesFromText(result.stdout);
+  }
+
+  private parseProcessesFromText(text: string): ProcessInfo[] {
+    const lines = text.split('\n');
+    const processes: ProcessInfo[] = [];
+
+    for (const line of lines) {
+      // Try to parse PID and process name
+      const match = line.match(/^\s*(\d+)\s+(.+?)\s*$/);
+      if (match) {
+        processes.push({
+          pid: parseInt(match[1], 10),
+          name: match[2].trim(),
+        });
+      }
+    }
+
+    return processes;
+  }
+
+  /**
+   * Launch an app
+   */
+  async launchApp(deviceId: string, bundleId: string, options: { arguments?: string[]; environment?: Record<string, string> } = {}): Promise<CommandResult> {
+    const args = ['device', 'process', 'launch', ...buildDeviceArg(deviceId), bundleId];
+
+    if (options.arguments?.length) {
+      args.push('--arguments', ...options.arguments);
+    }
+
+    if (options.environment) {
+      for (const [key, value] of Object.entries(options.environment)) {
+        args.push('--environment', `${key}=${value}`);
+      }
+    }
+
+    return execDeviceCtl(args, this.execOpts());
+  }
+
+  /**
+   * Terminate a process
+   */
+  async terminateProcess(deviceId: string, processNameOrPid: string | number): Promise<CommandResult> {
+    const args = ['device', 'process', 'terminate', ...buildDeviceArg(deviceId)];
+
+    if (typeof processNameOrPid === 'number') {
+      args.push('--pid', String(processNameOrPid));
+    } else {
+      args.push('--name', processNameOrPid);
+    }
+
+    return execDeviceCtl(args, this.execOpts());
+  }
+
+  /**
+   * Send signal to a process
+   */
+  async signalProcess(deviceId: string, pid: number, signal: ProcessSignal): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'process', 'signal', '--pid', String(pid), '--signal', signal, ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Suspend a process
+   */
+  async suspendProcess(deviceId: string, pid: number): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'process', 'suspend', '--pid', String(pid), ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Resume a process
+   */
+  async resumeProcess(deviceId: string, pid: number): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'process', 'resume', '--pid', String(pid), ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Send memory warning to a process
+   */
+  async sendMemoryWarning(deviceId: string, pid: number): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'process', 'sendMemoryWarning', '--pid', String(pid), ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Respring the device (restart SpringBoard)
+   */
+  async respring(deviceId: string): Promise<CommandResult> {
+    // Find SpringBoard PID and send SIGHUP
+    const processes = await this.listProcesses(deviceId);
+    const springBoard = processes.find((p) => p.name === 'SpringBoard' || p.name.includes('SpringBoard'));
+
+    if (!springBoard) {
+      return { success: false, stdout: '', stderr: 'SpringBoard process not found', exitCode: 1 };
+    }
+
+    return this.signalProcess(deviceId, springBoard.pid, 'SIGHUP');
+  }
+
+  // ==========================================================================
+  // App Management
+  // ==========================================================================
+
+  /**
+   * List installed apps
+   */
+  async listApps(deviceId: string): Promise<InstalledApp[]> {
+    const result = await execDeviceCtl(
+      ['device', 'info', 'apps', ...buildDeviceArg(deviceId)],
+      this.execOpts()
+    );
+
+    if (!result.success) return [];
+
+    return this.parseAppsFromText(result.stdout);
+  }
+
+  private parseAppsFromText(text: string): InstalledApp[] {
+    const lines = text.split('\n');
+    const apps: InstalledApp[] = [];
+
+    for (const line of lines) {
+      // Try parsing bundle identifier and name
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('[') && trimmed.includes('.')) {
+        const parts = trimmed.split(/\s+/);
+        if (parts.length >= 1) {
+          apps.push({
+            bundleIdentifier: parts[0],
+            bundleName: parts[1] || parts[0].split('.').pop() || '',
+            bundleVersion: '',
+            installPath: '',
+            platform: 'iOS',
+            type: 'User',
+          });
+        }
+      }
+    }
+
+    return apps;
+  }
+
+  /**
+   * Install an app
+   */
+  async installApp(deviceId: string, appPath: string): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'install', 'app', ...buildDeviceArg(deviceId), appPath],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Uninstall an app
+   */
+  async uninstallApp(deviceId: string, bundleId: string): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'uninstall', ...buildDeviceArg(deviceId), bundleId],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Get app icon
+   */
+  async getAppIcon(deviceId: string, bundleId: string, outputPath?: string): Promise<CommandResult> {
+    const args = ['device', 'info', 'appIcon', ...buildDeviceArg(deviceId), bundleId];
+    if (outputPath) {
+      args.push('--output', outputPath);
+    }
+    return execDeviceCtl(args, this.execOpts());
+  }
+
+  // ==========================================================================
+  // File System
+  // ==========================================================================
+
+  /**
+   * List files in a directory
+   */
+  async listFiles(deviceId: string, path: string): Promise<FileInfo[]> {
+    const result = await execDeviceCtl(
+      ['device', 'info', 'files', ...buildDeviceArg(deviceId), '--path', path],
+      this.execOpts()
+    );
+
+    if (!result.success) return [];
+
+    return this.parseFilesFromText(result.stdout);
+  }
+
+  private parseFilesFromText(text: string): FileInfo[] {
+    const lines = text.split('\n');
+    const files: FileInfo[] = [];
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      const isDirectory = trimmed.endsWith('/');
+      const name = isDirectory ? trimmed.slice(0, -1) : trimmed;
+
+      if (name && name !== '.' && name !== '..') {
+        files.push({
+          path: name,
+          name: name.split('/').pop() || name,
+          isDirectory,
+        });
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Copy file to device
+   */
+  async copyToDevice(deviceId: string, source: string, destination: string): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'copy', 'to-device', ...buildDeviceArg(deviceId), '--source', source, '--destination', destination],
+      this.execOpts()
+    );
+  }
+
+  /**
+   * Copy file from device
+   */
+  async copyFromDevice(deviceId: string, source: string, destination: string): Promise<CommandResult> {
+    return execDeviceCtl(
+      ['device', 'copy', 'from-device', ...buildDeviceArg(deviceId), '--source', source, '--destination', destination],
+      this.execOpts()
+    );
+  }
+
+  // ==========================================================================
+  // Notifications
+  // ==========================================================================
+
+  /**
+   * Post a Darwin notification
+   */
+  async postNotification(deviceId: string, name: string, userInfo?: Record<string, unknown>): Promise<CommandResult> {
+    const args = ['device', 'notification', 'post', ...buildDeviceArg(deviceId), '--name', name];
+
+    if (userInfo) {
+      args.push('--user-info', JSON.stringify(userInfo));
+    }
+
+    return execDeviceCtl(args, this.execOpts());
+  }
+
+  // ==========================================================================
+  // Diagnostics
+  // ==========================================================================
+
+  /**
+   * Collect diagnostics
+   */
+  async collectDiagnostics(options: { devices?: string; archiveDestination?: string } = {}): Promise<CommandResult> {
+    const args = ['diagnose'];
+
+    if (options.devices) {
+      args.push('--devices', options.devices);
+    }
+
+    if (options.archiveDestination) {
+      args.push('--archive-destination', options.archiveDestination);
+    }
+
+    return execDeviceCtl(args, { ...this.execOpts(), timeout: 300000 }); // 5 min timeout
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @ebowwa/ios-devices
+ * iOS device control library wrapping xcrun devicectl, libimobiledevice, and simctl
+ */
+
+export { IOSDevices, DeviceCtl, LibIMobileDevice, SimCtl, checkAvailableTools } from './unified-api.js';
+
+export * from './types.js';