@mcesystems/apple-kit 1.0.61 → 1.0.63

package/README.md

@@ -1,16 +1,16 @@
 # @mcesystems/apple-kit
 
-iOS device management toolkit using libimobiledevice command-line tools. Provides device detection, app installation/uninstallation, port forwarding, activation, and device property access.
+iOS device management toolkit using libimobiledevice and go-ios command-line tools. We use both because they each provide capabilities that the other does not. The package provides app installation/uninstallation, port forwarding, activation, and device property access.
 
 ## Features
 
-- **Device Detection**: Monitor iOS device connections via USB plug-and-play
 - **App Management**: Install and uninstall iOS applications (.ipa files)
-- **Launch Apps**: Start applications on the device
 - **Port Forwarding**: Forward local ports to device ports (for debugging, etc.)
-- **Device Activation**: Check and manage device activation state
+- **Device Activation**: Activate devices and skip setup steps
 - **Trust/Pairing**: Handle device trust and pairing
 - **Device Info**: Access device properties (name, model, iOS version, UDID, etc.)
+- **Profile Management**: List and remove configuration profiles
+- **Device Wipe**: Erase device data (factory reset)
 - **Cross-platform**: Works on Windows, macOS, and Linux
 
 ## Installation
@@ -24,17 +24,20 @@ npm install @mcesystems/apple-kit
 - Node.js 18+
 - iOS device connected via USB
 - Device must be trusted/paired with the computer
+- libimobiledevice tools (idevice\*)
+- go-ios `ios` CLI binary
 
 ### Platform-specific Requirements
 
 #### Windows
 - libimobiledevice binaries - use the export script (see below)
+- go-ios `ios.exe` (see Resources section below)
 - iTunes installed OR Apple Mobile Device Support
 
 #### macOS
 **Option 1: Use bundled binaries (recommended for distribution)**
 
-Use the export script to bundle binaries for your application:
+Use the export script to bundle libimobiledevice for your application:
 ```bash
 # Using npx (after installing the package)
 npx export-apple-resources /path/to/your-app/resources/apple-kit
@@ -53,42 +56,35 @@ See [scripts/README.md](./scripts/README.md) for detailed prerequisites and inst
 - libimobiledevice-utils: `sudo apt install libimobiledevice-utils`
 - Tools are auto-detected from `/usr/bin` or `/usr/local/bin`
 
-### Binary Resolution Order
+### Resources and Binary Resolution
 
-The package looks for idevice tools in this order:
-1. `IDeviceBinPath` environment variable (for custom paths)
-2. Bundled resources in your app's `resources/bin/{platform}/` directory
-3. Homebrew paths on macOS (`/opt/homebrew/bin`, `/usr/local/bin`)
-4. System PATH (for global installations)
+Set a resources directory once so both toolchains can be located:
 
-## Usage
+```typescript
+import path from "node:path";
+import { AppleDeviceKit } from "@mcesystems/apple-kit";
 
-### Device Monitoring
+AppleDeviceKit.setResourcesDir(path.join(process.cwd(), "resources"));
+```
 
-```typescript
-import { DevicesMonitor } from '@mcesystems/apple-kit';
+If you do not set a resources directory, make sure both toolchains are on your PATH.
 
-const monitor = new DevicesMonitor({
-  logicalPortMap: {
-    "Port_#0005.Hub_#0002": 1,
-    "Port_#0006.Hub_#0002": 2
-  }
-});
+The package looks for tools in this order:
+1. `resourcesDir/ios/bin/{platform}/` (go-ios `ios` and libimobiledevice tools)
+2. Homebrew paths on macOS (`/opt/homebrew/bin`, `/usr/local/bin`)
+3. System PATH (for global installations)
 
-const events = await monitor.startTracking();
+## Usage
 
-events.on('added', async (deviceKit) => {
-  console.log(`iOS device connected: ${deviceKit.getDeviceId()}`);
-  const info = await deviceKit.getDeviceInfo();
-  console.log(`  ${info.deviceName} - iOS ${info.productVersion}`);
-});
+### List Devices (go-ios)
 
-events.on('removed', (deviceId, port) => {
-  console.log(`iOS device disconnected: ${deviceId}`);
-});
+```typescript
+import { createIosCli } from "@mcesystems/apple-kit";
 
-// Later: stop monitoring
-await monitor.stopTracking();
+// Example: <resourcesDir>/ios/bin/{platform}/ios(.exe)
+const cli = createIosCli("path/to/ios");
+const list = await cli.listDevices();
+console.log(list.udids);
 ```
 
 ### Install/Uninstall Agent
@@ -98,17 +94,11 @@ import { AppleDeviceKit } from '@mcesystems/apple-kit';
 
 const device = new AppleDeviceKit('device-udid', 1);
 
-// Install an agent/app locally
-await device.installApp('/path/to/agent.ipa');
-
-// Install via MDM (ignores ipaPath, uses appId or url)
+// Install app locally, then (if MDM is configured) take over management
 await device.installApp('/path/to/agent.ipa', {
-  installViaMdm: true,
-  mdm: {
-    appId: 'com.example.agent',
-    url: 'https://example.com/agent.ipa',
-    waitForInstalled: true
-  }
+  appId: 'com.example.agent',
+  url: 'https://example.com/agent.ipa',
+  waitForInstalled: true
 });
 
 // Check if installed
@@ -126,12 +116,12 @@ await device.uninstallApp('com.example.agent');
 ```typescript
 const device = new AppleDeviceKit('device-udid', 1);
 
-const info = await device.getDeviceInfo();
-console.log(`Device: ${info.deviceName}`);
-console.log(`Model: ${info.productType}`);
-console.log(`iOS: ${info.productVersion} (${info.buildVersion})`);
-console.log(`Serial: ${info.serialNumber}`);
-console.log(`UDID: ${info.udid}`);
+const info = await device.info();
+console.log(`Device: ${info.DeviceName}`);
+console.log(`Model: ${info.ProductType}`);
+console.log(`iOS: ${info.ProductVersion} (${info.BuildVersion})`);
+console.log(`Serial: ${info.SerialNumber}`);
+console.log(`UDID: ${info.UniqueDeviceID}`);
 ```
 
 ### Trust/Pairing
@@ -142,44 +132,27 @@ const device = new AppleDeviceKit('device-udid', 1);
 // Check if device is trusted
 const isPaired = await device.isPaired();
 
-// Initiate pairing (user must accept on device)
-await device.pair();
-
-// Wait for user to accept trust dialog
-await device.waitForPairing(60000); // 60 second timeout
+// Trust the device (initiates pairing and waits for user acceptance)
+await device.trustDevice(60000);
 
 // Unpair device
 await device.unpair();
 ```
 
-### Launch Application
-
-```typescript
-const device = new AppleDeviceKit('device-udid', 1);
-
-// Launch an app
-await device.launchApp('com.example.myapp');
-
-// Launch with arguments
-await device.launchApp('com.example.myapp', ['--debug', '--port=8080']);
-```
-
 ### Port Forwarding
 
 ```typescript
 const device = new AppleDeviceKit('device-udid', 1);
 
-// Forward local port 8080 to device port 8080
-const forward = device.startPortForward(8080, 8080);
+// Forward device port 8080 to a local port (auto-allocated)
+const forward = await device.startPortForwardAsync(8080);
+console.log(`Local port: ${forward.localPort}`);
 
 // Use the forwarded connection...
 // connect to localhost:8080 to reach device:8080
 
 // Stop forwarding when done
-forward.stop();
-
-// Or use async version that waits for ready
-const forwardAsync = await device.startPortForwardAsync(8080, 8080);
+device.closePortForward();
 ```
 
 ### Activation
@@ -192,107 +165,86 @@ const state = await device.getActivationState();
 console.log(`Activated: ${state.isActivated}`);
 console.log(`State: ${state.activationState}`);
 
-// Activate device (requires valid activation record)
-await device.activate({
-  resourcesDir: process.env.APPLE_KIT_RESOURCES_DIR,
-});
-
-// Deactivate device
-await device.deactivate();
+// Activate device (uses go-ios and MDM client)
+const cleanup = await device.activate();
+if (cleanup) {
+  await cleanup(); // removes WiFi profile when done
+}
 ```
 
-When `resourcesDir` is set, the activation flow reads MDM credentials from
-`@clientLocal.json` inside that folder, plist templates from `resourcesDir/plist`,
-and the iOS CLI binary from `resourcesDir/ios/bin/{platform}`.
-If `resourcesDir/mdm/enrollment_{udid}.mobileconfig` or
-`resourcesDir/mdm/enrollment.mobileconfig` exists, it is installed instead of
-calling the MDM API (offline enrollment).
-
-### Running Without iTunes (usbmuxd)
+The activation flow can install a WiFi profile based on environment variables:
+`WIFI_SSID`, `WIFI_PASSWORD`, `WIFI_ENCRYPTION`, `WIFI_HIDDEN`, `WIFI_ENTERPRISE`,
+`WIFI_USERNAME`, and `WIFI_EAP_TYPE`.
 
-On Windows, iTunes provides the Apple Mobile Device Service for USB communication. If you don't have iTunes installed, you can run the bundled `usbmuxd`:
+### Profiles
 
 ```typescript
-import { startUsbmuxd, stopUsbmuxd, ensureUsbmuxd } from '@mcesystems/apple-kit';
+const device = new AppleDeviceKit('device-udid', 1);
 
-// Start usbmuxd daemon (required if iTunes is not installed)
-const daemon = startUsbmuxd();
+// List profiles
+const profiles = await device.listProfiles();
+console.log(profiles.profiles);
 
-// Or ensure it's running (starts if not already running)
-ensureUsbmuxd();
+// Remove a profile by identifier
+await device.removeProfile("com.example.profile");
+```
 
-// Now you can use device operations...
-const devices = await AppleDeviceKit.listDevices();
+### Wipe Device
 
-// When done, stop the daemon
-stopUsbmuxd();
-// or
-daemon.stop();
-```
+```typescript
+const device = new AppleDeviceKit('device-udid', 1);
 
-**Note:** The usbmuxd daemon must be running before connecting devices. Start it before plugging in your iOS device.
+// WARNING: this erases all data
+await device.wipe();
+```
 
 ## API Reference
 
 ### AppleDeviceKit
 
 **Static methods:**
-- `listDevices()`: Get all connected iOS devices
+- `setResourcesDir(dir)`: Configure resources location
 
 **Device Info:**
-- `getDeviceInfo()`: Get device properties
+- `info()`: Get device properties
 - `getDeviceId()`: Get the device UDID
-- `getPort()`: Get the logical port number
+- `getLogicalPort()`: Get the logical port number
+- `getDevicePort()`: Get current local forwarded port (or null)
 
 **App Management:**
-- `installApp(ipaPath, options?)`: Install an IPA file or via MDM
+- `installApp(ipaPath, options)`: Install IPA and take over via MDM if configured
 - `uninstallApp(bundleId)`: Uninstall an app by bundle ID
 - `isAppInstalled(bundleId)`: Check if app is installed
 - `listApps()`: List all installed user apps
-- `launchApp(bundleId, args?)`: Launch an application
 
 **Trust/Pairing:**
 - `isPaired()`: Check if device is paired/trusted
 - `pair()`: Initiate pairing (user must accept on device)
+- `trustDevice(timeout?, onWaiting?)`: Pair and wait for user acceptance
 - `unpair()`: Remove pairing/trust
-- `waitForPairing(timeout?)`: Wait for device to be paired
+- `waitForPairing(timeout?, pollInterval?)`: Wait for device to be paired
 
 **Port Forwarding:**
-- `startPortForward(localPort, devicePort)`: Start port forwarding
-- `startPortForwardAsync(localPort, devicePort)`: Start and wait for ready
+- `startPortForwardAsync(devicePort, startupTimeout?)`: Start and wait for ready
+- `closePortForward()`: Stop forwarding
+
+**Profiles:**
+- `listProfiles()`: List installed profiles
+- `removeProfile(identifier)`: Remove profile by identifier
 
 **Activation:**
 - `getActivationState()`: Get activation state
-- `activate()`: Activate the device
-- `deactivate()`: Deactivate the device
-
-### DevicesMonitor
+- `activate()`: Activate the device (returns cleanup function)
 
-- `startTracking()`: Start monitoring for iOS device connections
-- `stopTracking()`: Stop monitoring
-- `getKits()`: Get all currently tracked devices
-- `getKit(udid)`: Get a specific device kit by UDID
+**Device Wipe:**
+- `wipe()`: Erase device data
 
-### usbmuxd Functions
-
-- `startUsbmuxd(foreground?)`: Start the usbmuxd daemon
-- `stopUsbmuxd()`: Stop the daemon
-- `isUsbmuxdRunning()`: Check if daemon is running
-- `ensureUsbmuxd()`: Start if not already running
-
-To use a custom resources folder, pass it as the second parameter:
-`startUsbmuxd(false, { resourcesDir: "..." })`.
+**Lifecycle:**
+- `dispose()`: Clean up resources and port forwards
 
 ### Types
 
 ```typescript
-interface PortForwardHandle {
-  stop: () => void;
-  localPort: number;
-  devicePort: number;
-  process: ChildProcess;
-}
-
 interface ActivationState {
   isActivated: boolean;
   activationState: string;