@houwert/conductor 0.30.0 → 0.32.0

package/dist/drivers/ios.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -16,6 +49,7 @@ const promises_1 = __importDefault(require("fs/promises"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const devicectl = __importStar(require("./devicectl.js"));
 /**
  * How long a captured view hierarchy may be reused. Bounds the staleness of a
  * cached snapshot when the screen changes without a driver-issued command
@@ -24,11 +58,18 @@ const child_process_1 = require("child_process");
  */
 const HIERARCHY_CACHE_TTL_MS = 750;
 class IOSDriver {
-    constructor(port = 1075, host = '127.0.0.1', deviceId, platform = 'ios') {
+    constructor(port = 1075, host = '127.0.0.1', deviceId, platform = 'ios', 
+    /**
+     * Physical devices route app lifecycle through devicectl instead of simctl,
+     * and can't offer the simulator-only conveniences (clipboard, location,
+     * TCC pre-approval, video capture).
+     */
+    isPhysical = false) {
         this.port = port;
         this.host = host;
         this.deviceId = deviceId;
         this.platform = platform;
+        this.isPhysical = isPhysical;
         this._recordingProcess = null;
         /**
          * Short-lived cache of the most recent view hierarchy, keyed by request
@@ -38,6 +79,12 @@ class IOSDriver {
          */
         this.hierarchyCache = null;
     }
+    /** Reject a simulator-only operation with a message that names the alternative. */
+    unsupportedOnDevice(operation, alternative) {
+        throw new Error(`${operation} is not supported on physical ${this.platform === 'tvos' ? 'tvOS' : 'iOS'} devices` +
+            (alternative ? ` — ${alternative}` : '') +
+            '.');
+    }
     request(method, path, body) {
         return new Promise((resolve, reject) => {
             const bodyBuf = body !== undefined ? Buffer.from(JSON.stringify(body), 'utf-8') : undefined;
@@ -193,7 +240,18 @@ class IOSDriver {
         for (const [key, value] of Object.entries(args ?? {})) {
             argPairs.push(`-${key}`, value);
         }
-        if (inject) {
+        if (this.isPhysical && (inject || argPairs.length > 0)) {
+            // devicectl is the device-side equivalent of `simctl launch`: it takes
+            // both launch arguments and an environment dictionary.
+            const deviceId = this.requireDeviceId();
+            await devicectl.launchApp(deviceId, bundleId, argPairs, inject
+                ? {
+                    DYLD_INSERT_LIBRARIES: inject.dylibPath,
+                    CONDUCTOR_INPROC_PORT: String(inject.inprocPort),
+                }
+                : undefined);
+        }
+        else if (inject) {
             // Injection requires simctl launch with SIMCTL_CHILD_ env — the XCTest
             // /launchApp path only activates and can't set environment.
             const deviceId = this.requireDeviceId();
@@ -220,6 +278,13 @@ class IOSDriver {
     }
     async clearAppState(bundleId) {
         const deviceId = this.requireDeviceId();
+        if (this.isPhysical) {
+            // No get_app_container on device, so there's no bundle to reinstall from;
+            // the caller has to supply the .app again via install-app.
+            await devicectl.uninstallApp(deviceId, bundleId);
+            this.invalidateHierarchyCache();
+            return;
+        }
         // Terminate first to prevent app from saving state after clear
         await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
         // Capture the .app bundle path before uninstalling — uninstall deletes the UUID directory
@@ -240,26 +305,40 @@ class IOSDriver {
     }
     async uninstallApp(bundleId) {
         const deviceId = this.requireDeviceId();
-        await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
-        await this.simctl(['uninstall', deviceId, bundleId]);
+        if (this.isPhysical) {
+            await devicectl.uninstallApp(deviceId, bundleId);
+        }
+        else {
+            await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
+            await this.simctl(['uninstall', deviceId, bundleId]);
+        }
         this.invalidateHierarchyCache();
     }
     async clearKeychain() {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('clear-keychain');
         const deviceId = this.requireDeviceId();
         await this.simctl(['keychain', deviceId, 'reset']);
     }
     async openLink(url) {
+        if (this.isPhysical) {
+            this.unsupportedOnDevice('open-link', 'devicectl has no openurl equivalent');
+        }
         const deviceId = this.requireDeviceId();
         await this.simctl(['openurl', deviceId, url]);
         this.invalidateHierarchyCache();
     }
     /** Read the simulator's clipboard. Uses `xcrun simctl pbpaste <udid>`. */
     async clipboardRead() {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('Reading the clipboard');
         const deviceId = this.requireDeviceId();
         return this.simctlCapture(['pbpaste', deviceId]);
     }
     /** Write to the simulator's clipboard. Uses `xcrun simctl pbcopy <udid>` over stdin. */
     async clipboardWrite(text) {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('Writing the clipboard');
         const deviceId = this.requireDeviceId();
         await new Promise((resolve, reject) => {
             const proc = (0, child_process_1.spawn)('xcrun', ['simctl', 'pbcopy', deviceId], {
@@ -275,6 +354,8 @@ class IOSDriver {
         });
     }
     async setLocation(latitude, longitude) {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('set-location');
         const deviceId = this.requireDeviceId();
         await this.simctl(['location', deviceId, 'set', `${latitude},${longitude}`]);
     }
@@ -339,6 +420,12 @@ class IOSDriver {
             mediaLibrary: 'media-library',
             siri: 'siri',
         };
+        // On device there's no TCC pre-approval path, so the runner's interruption
+        // monitor is the only thing that can answer permission dialogs.
+        if (this.isPhysical) {
+            await this.post('setPermissions', { permissions: expanded });
+            return;
+        }
         const deviceId = this.requireDeviceId();
         if (allValue !== undefined) {
             // Best-effort bulk grant/revoke. 'all' covers TCC-managed permissions but
@@ -370,6 +457,8 @@ class IOSDriver {
         await this.post('setPermissions', { permissions: expanded });
     }
     async addMedia(filePath) {
+        if (this.isPhysical)
+            this.unsupportedOnDevice('add-media');
         const deviceId = this.requireDeviceId();
         await this.simctl(['addmedia', deviceId, filePath]);
     }
@@ -380,6 +469,9 @@ class IOSDriver {
         throw new Error('getAirplaneMode is not supported on iOS simulators');
     }
     async startRecording(outputPath) {
+        if (this.isPhysical) {
+            this.unsupportedOnDevice('Screen recording', 'capture stills with `conductor screenshot`');
+        }
         const deviceId = this.requireDeviceId();
         if (this._recordingProcess)
             await this.stopRecording();

package/dist/index.js

@@ -229,6 +229,7 @@ async function main() {
             'report',
             'timeline',
             'baselines',
+            'reset',
         ],
         string: [
             'device',
@@ -1219,8 +1220,16 @@ async function main() {
             else if (sub === 'reload') {
                 exitCode = await (0, metro_js_1.metroReload)(opts, metroSession, { port, targetIndex });
             }
+            else if (sub === 'use') {
+                exitCode = await (0, metro_js_1.metroUse)(opts, metroSession, {
+                    location: rest[1],
+                    appId: rest[2],
+                    reset: argv['reset'],
+                });
+            }
             else {
-                console.error('Usage: conductor metro <stop|reload> [--port N] [--target N]');
+                console.error('Usage: conductor metro <stop|reload|use> [--port N] [--target N]\n' +
+                    '       conductor metro use <port|host:port> [<appId>] [--reset]');
                 exitCode = 1;
             }
             break;

package/dist/runner.js

@@ -151,12 +151,16 @@ async function getDriver(sessionName = 'default') {
     (0, verbose_js_1.log)(`getDriver: platform=${platform} deviceId=${deviceId} port=${port || '(deferred)'}`);
     let driver;
     if (platform === 'ios') {
-        if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
+        // Physical devices serve the driver from their own loopback, so the CLI
+        // has to reach them over the network instead of the host's.
+        const host = await (0, bootstrap_js_1.resolveDriverHost)(deviceId);
+        if (!(await (0, bootstrap_js_1.isPortOpen)(port, host))) {
             (0, verbose_js_1.log)(`Driver not running — starting daemon for ${deviceId}...`);
             await (0, client_js_1.startDaemon)(deviceId);
-            await waitForPort(port);
+            await waitForPort(port, undefined, undefined, host);
         }
-        const iosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId, 'ios');
+        const isPhysical = (await (0, bootstrap_js_1.detectDeviceKind)(deviceId)) === 'physical';
+        const iosDriver = new ios_js_1.IOSDriver(port, host, deviceId, 'ios', isPhysical);
         if (!(await iosDriver.isAlive())) {
             throw new Error(`iOS XCTest driver on port ${port} is not responding.\n` +
                 `Run: conductor daemon-start --device ${deviceId}`);
@@ -164,12 +168,16 @@ async function getDriver(sessionName = 'default') {
         driver = iosDriver;
     }
     else if (platform === 'tvos') {
-        if (!(await (0, bootstrap_js_1.isPortOpen)(port))) {
+        // Physical devices serve the driver from their own loopback, so the CLI
+        // has to reach them over the network instead of the host's.
+        const host = await (0, bootstrap_js_1.resolveDriverHost)(deviceId);
+        if (!(await (0, bootstrap_js_1.isPortOpen)(port, host))) {
             (0, verbose_js_1.log)(`tvOS driver not running — starting daemon for ${deviceId}...`);
             await (0, client_js_1.startDaemon)(deviceId);
-            await waitForPort(port);
+            await waitForPort(port, undefined, undefined, host);
         }
-        const tvosDriver = new ios_js_1.IOSDriver(port, '127.0.0.1', deviceId, 'tvos');
+        const isPhysical = (await (0, bootstrap_js_1.detectDeviceKind)(deviceId)) === 'physical';
+        const tvosDriver = new ios_js_1.IOSDriver(port, host, deviceId, 'tvos', isPhysical);
         if (!(await tvosDriver.isAlive())) {
             throw new Error(`tvOS XCTest driver on port ${port} is not responding.\n` +
                 `Run: conductor daemon-start --device ${deviceId}`);
@@ -403,10 +411,10 @@ async function spawnCommand(cmd, args, options) {
     });
 }
 /** Poll until a TCP port is open, or throw after timeout. */
-async function waitForPort(port, timeoutMs = 180000, pollMs = 500) {
+async function waitForPort(port, timeoutMs = 180000, pollMs = 500, host = '127.0.0.1') {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await (0, bootstrap_js_1.isPortOpen)(port))
+        if (await (0, bootstrap_js_1.isPortOpen)(port, host))
             return;
         await new Promise((r) => setTimeout(r, pollMs));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

package/skills/conductor-device-interact/SKILL.md

@@ -41,7 +41,7 @@ conductor assert-visible "Dashboard"
 | `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega / roku. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`, `Remote Page Up/Down` on tvOS and Android TV, and `Remote Guide` on tvOS) for tvOS / Android TV / vega / roku. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
@@ -127,6 +127,16 @@ relaunch without the flag. (See `conductor-device-setup`.)
 
 - `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega|roku>` scopes by platform.
 - Vega (Amazon Fire TV) is D-pad driven: navigate with `press-key "Remote Dpad …"`; coordinate `tap-on` also works. `open-link`, `set-location`, gestures, and clipboard are unsupported. See `conductor-device-setup`.
+- Apple TV (tvOS) is focus-driven and has **no touch surface automation**: XCTest
+  refuses remote swipe gestures ("Swipe events are only implemented for iOS,
+  visionOS, and watchOS"), so `swipe`/`scroll` are unavailable. Navigate with
+  `press-key "Remote Dpad Up/Down/Left/Right"` and `"Remote Dpad Center"`; for
+  long lists use `press-key "Remote Page Up"` / `"Remote Page Down"` (tvOS 14.3+;
+  also mapped on Android TV), which move a screenful at a time when the app
+  honours them. `"Remote Guide"` (14.3+) and
+  `"Remote TV Provider"` / `"Remote One Two Three"` / `"Remote Four Colors"`
+  (18.1+) are also available. `--duration <seconds>` holds a button for
+  accelerated scrolling.
 - Roku is D-pad only — there is no touch. `tap-on <selector>` resolves the element but presses `Select`, which activates whatever currently holds **focus**, so navigate focus onto the target with `press-key "Remote Dpad …"` first and use `tap-on` to confirm. `scroll`/`swipe` become repeated D-pad presses in the direction the content moves. `open-link` needs an app id (it becomes a channel launch parameter). Only sideloaded dev-mode channels are inspectable. See `conductor-device-setup`.
 - Add `--json` for machine-readable output; failed assertions exit non-zero.
 - Run a per-session daemon for many commands (see `conductor-device-setup`).

package/skills/conductor-device-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-setup
-description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, Roku devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD or a Roku device, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, physical iOS/tvOS devices, Vega (Amazon Fire TV) virtual devices, Roku devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD or a Roku device, driving a physical iPhone/iPad/Apple TV, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
 ---
 
 # Conductor — device & app setup
@@ -102,6 +102,33 @@ Unsupported on Roku: `install-app`/`uninstall-app` (sideload via the device's de
 web server at `http://<device-ip>`), `list-apps`, `clear-state`, gestures,
 screen recording, clipboard, `set-location`, memory/CPU profiling, and device logs.
 
+### Physical iOS / tvOS devices
+
+Real iPhones, iPads, and Apple TVs work alongside simulators. They're discovered
+through `devicectl`, show up in `list-devices` with status `connected`, and are
+addressed by their CoreDevice identifier (`--device <uuid>`).
+
+Requirements:
+
+- The device is **paired** with this Mac and on the **same network** — conductor
+  reaches the driver over the LAN, not the host's loopback.
+- **Developer Mode** is enabled on the device.
+- A signing team: conductor builds and signs the XCTest driver locally on first
+  use (a few minutes; cached per team in `~/.conductor/<platform>-driver-device/`).
+  Set `CONDUCTOR_TEAM_ID=<team>` when the Mac has more than one development team
+  — conductor refuses to guess rather than sign with the wrong one.
+
+Everything driven through the XCTest driver behaves the same as on a simulator:
+`inspect`, `capture-ui`, `tap-on`, `press-key`, `swipe`, `launch-app`,
+`terminate-app`, `install-app`, `uninstall-app`, flows.
+
+Simulator-only — these fail with an explicit message on a physical device:
+`set-location`, `open-link`, clipboard read/write, `clear-keychain`, `add-media`,
+screen recording and the live video stream, and OS log collection (`conductor
+logs` still gets **Metro** logs, which is the useful source for React Native).
+`clear-state` uninstalls on device without reinstalling — reinstall with
+`install-app` afterwards.
+
 ## App lifecycle
 
 | Command                                               | Purpose                                                                |

package/skills/conductor-metro-debugger/SKILL.md

@@ -54,6 +54,21 @@ running indefinitely.
 |---|---|
 | `conductor metro reload [--port N] [--target N]` | Reload the JS bundle without restarting native |
 | `conductor metro stop [--port N]` | Stop the Metro bundler on a port (default 8081) |
+| `conductor metro use <port\|host:port> [<appId>]` | Point the app at a specific Metro (iOS/tvOS simulators) |
+| `conductor metro use --reset [<appId>]` | Drop that override, back to the compiled-in port |
+
+An app asks for the Metro port compiled into React-Core from `RCT_METRO_PORT` at
+pod-install time, so a build can end up asking for a port nothing is serving —
+typically a git worktree whose Metro runs elsewhere, or a pod install from a
+shell that lacked the env var. Symptom: the app never loads a bundle (or keeps
+running a stale one) while `conductor metro reload` works fine against the port
+you expect. `metro use` overrides it via the `RCT_jsLocation` preference, so no
+recompile is needed and the setting survives reinstalls. **Relaunch the app**
+afterwards — it is read when the bridge starts. The app id defaults to the
+current session's.
+
+Android has no such preference; map the port with
+`adb -s <serial> reverse tcp:8081 tcp:<metro-port>` instead.
 
 ## Tips