@houwert/conductor 0.21.0 → 0.22.0

package/dist/commands/web-targets.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.webTargets = webTargets;
+/**
+ * List the CDP page targets exposed by an external browser (e.g. an Electron app
+ * launched with `--remote-debugging-port`). Each target is a controllable page —
+ * for the Lightning emulator, one per tile plus its control/remote chrome.
+ *
+ * Reads the DevTools HTTP endpoint (`/json/list`) directly, so it needs no
+ * Playwright browser and works before any daemon session exists. Use the printed
+ * target IDs with `--cdp-url` / `--cdp-target` to bind a session to a tile.
+ */
+const http_1 = __importDefault(require("http"));
+const output_js_1 = require("../output.js");
+/** Derive the `http://host:port` base from a CDP URL (which may be ws:// or include a path). */
+function httpBase(cdpUrl) {
+    const u = new URL(cdpUrl);
+    const proto = u.protocol === 'https:' || u.protocol === 'wss:' ? 'https:' : 'http:';
+    return `${proto}//${u.host}`;
+}
+function fetchTargets(cdpUrl) {
+    const url = `${httpBase(cdpUrl)}/json/list`;
+    return new Promise((resolve, reject) => {
+        const req = http_1.default.get(url, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                if ((res.statusCode ?? 0) >= 300) {
+                    reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString('utf-8')));
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+        req.setTimeout(5000, () => req.destroy(new Error(`Timed out fetching ${url}`)));
+        req.on('error', reject);
+    });
+}
+async function webTargets(cdpUrl, opts) {
+    if (!cdpUrl) {
+        console.error('web-targets requires --cdp-url <url> (e.g. --cdp-url http://127.0.0.1:9222).\n' +
+            'Launch the browser/Electron app with --remote-debugging-port to expose it.');
+        return 1;
+    }
+    let targets;
+    try {
+        targets = await fetchTargets(cdpUrl);
+    }
+    catch (err) {
+        console.error(`Could not reach CDP endpoint at ${cdpUrl}: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    // Only type="page" targets are controllable as Playwright Pages.
+    const pages = targets.filter((t) => t.type === 'page');
+    if (opts.json) {
+        (0, output_js_1.printData)(pages.map((t) => ({ id: t.id, title: t.title, url: t.url })), opts);
+        return 0;
+    }
+    if (pages.length === 0) {
+        console.log('No page targets found. Is the app loaded and started with --remote-debugging-port?');
+        return 0;
+    }
+    console.log(`Found ${pages.length} page target(s) at ${cdpUrl}:\n`);
+    pages.forEach((t, i) => {
+        console.log(`  [${i}] ${t.title || '(untitled)'}`);
+        console.log(`      url:    ${t.url}`);
+        console.log(`      target: ${t.id}`);
+        console.log(`      bind:   conductor --device web:chromium:t${i} --cdp-url ${cdpUrl} --cdp-target ${t.id} inspect`);
+        console.log('');
+    });
+    console.log('Bind a session to a target once (any command), then drop the --cdp-* flags on later\n' +
+        'commands for that --device — the attachment is remembered per session.');
+    return 0;
+}
+exports.HELP = '  web-targets --cdp-url <url>          List controllable CDP page targets (one per Electron webview/tile)';

package/dist/drivers/log-sources/metro-discovery.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMetroPort = isMetroPort;
 exports.discoverMetroPortForDevice = discoverMetroPortForDevice;
 exports.getDeviceDisplayName = getDeviceDisplayName;
+exports.deviceNameMatches = deviceNameMatches;
 exports.selectTargetForDevice = selectTargetForDevice;
 exports.targetsForDevice = targetsForDevice;
 /**
@@ -200,6 +201,16 @@ async function getDeviceDisplayName(platform, deviceId) {
     }
     return null;
 }
+/**
+ * Whether a Metro target's `deviceName` refers to the same device as `displayName`.
+ * Tolerant of the suffixes Metro appends to the bare model name — e.g. Android's
+ * `ro.product.model` is `Chromecast` while Metro reports `Chromecast - 14 - API 34`.
+ */
+function deviceNameMatches(targetDeviceName, displayName) {
+    if (!targetDeviceName)
+        return false;
+    return targetDeviceName === displayName || targetDeviceName.startsWith(`${displayName} `);
+}
 /**
  * Filter Metro /json targets to those belonging to this device (by display
  * name), preferring the fusebox runtime if present. Returns undefined when
@@ -208,7 +219,7 @@ async function getDeviceDisplayName(platform, deviceId) {
  */
 function selectTargetForDevice(targets, displayName) {
     const withWs = targets.filter((t) => t.webSocketDebuggerUrl);
-    const matches = withWs.filter((t) => t.deviceName === displayName);
+    const matches = withWs.filter((t) => deviceNameMatches(t.deviceName, displayName));
     if (matches.length === 0)
         return undefined;
     const fusebox = matches.find((t) => t.reactNative?.capabilities?.prefersFuseboxFrontend);
@@ -216,5 +227,5 @@ function selectTargetForDevice(targets, displayName) {
 }
 /** Convenience: all /json targets belonging to this device. */
 function targetsForDevice(targets, displayName) {
-    return targets.filter((t) => t.webSocketDebuggerUrl && t.deviceName === displayName);
+    return targets.filter((t) => t.webSocketDebuggerUrl && deviceNameMatches(t.deviceName, displayName));
 }

package/dist/drivers/metro-cdp.js

@@ -40,12 +40,20 @@ function selectDebuggerUrl(targets, opts, displayName) {
         }
         return withWs[opts.targetIndex].webSocketDebuggerUrl;
     }
-    if (displayName) {
-        const target = (0, metro_discovery_js_1.selectTargetForDevice)(withWs, displayName);
+    // Device-scoped: must resolve to that device's own target. Never silently
+    // fall back to another device — that reloads the wrong app and reports success.
+    if (opts.deviceId) {
+        const target = displayName ? (0, metro_discovery_js_1.selectTargetForDevice)(withWs, displayName) : undefined;
         if (target)
             return target.webSocketDebuggerUrl;
+        const available = withWs
+            .map((t, i) => `  [${i}] ${t.deviceName ?? t.title ?? '(unnamed)'}`)
+            .join('\n');
+        throw new Error(`No Metro debugger target for device ${opts.deviceId}` +
+            (displayName ? ` (${displayName})` : '') +
+            `.\nAvailable targets:\n${available}\nPass --target <index> to pick one explicitly.`);
     }
-    // Prefer the Hermes/React target by title, otherwise first.
+    // No device requested: prefer the Hermes/React target by title, otherwise first.
     const target = withWs.find((t) => t.title && /hermes|react/i.test(t.title)) ?? withWs[0];
     return target.webSocketDebuggerUrl;
 }

package/dist/index.js

@@ -61,6 +61,8 @@ const memory_js_1 = require("./commands/memory.js");
 const metro_js_1 = require("./commands/metro.js");
 const clipboard_js_1 = require("./commands/clipboard.js");
 const options_js_1 = require("./commands/options.js");
+const web_targets_js_1 = require("./commands/web-targets.js");
+const session_js_2 = require("./session.js");
 const device_picker_js_1 = require("./device-picker.js");
 const update_check_js_1 = require("./update-check.js");
 const pkg_root_js_1 = require("./pkg-root.js");
@@ -123,11 +125,15 @@ const COMMAND_HELP = {
     clipboard: clipboard_js_1.HELP,
     paste: '  paste                                Trigger OS-level paste (or type clipboard on iOS)',
     'list-options': options_js_1.HELP,
+    'web-targets': web_targets_js_1.HELP,
 };
 const OPTIONS_HELP = `Options:
   --device <id>     Target device ID (also keys the session and daemon)
   --device-name <n> Target a booted device by name (resolved to ID from booted devices)
   --platform <p>    Filter to devices of this platform (ios, android, tvos, web)
+  --cdp-url <url>   Attach the web driver to an existing browser over CDP (e.g. an
+                    Electron app started with --remote-debugging-port). Remembered per session.
+  --cdp-target <id> Pick which CDP page target to control (see \`conductor web-targets\`)
   --json            Output as machine-readable JSON
   --options         List valid values for a command's enumerated parameters and exit
   --verbose, -v     Log daemon calls, fallbacks, and raw output
@@ -230,6 +236,8 @@ async function main() {
             'height',
             'user-agent',
             'color-scheme',
+            'cdp-url',
+            'cdp-target',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version', o: 'output', y: 'yes' },
     });
@@ -274,6 +282,7 @@ async function main() {
         'metro',
         'workspace',
         'list-options',
+        'web-targets',
         // `logs --list` and `logs --source metro` only query Metro on localhost — no device needed
         // `logs` always needs a device session — Metro discovery is device-scoped.
         // `daemon-stop --all` stops every daemon — no device needed
@@ -309,8 +318,38 @@ async function main() {
                 explicitDevice ?? (await (0, device_picker_js_1.pickDevice)(argv['platform'])) ?? 'default';
         }
     }
+    // CDP attach settings (web only): --cdp-url/--cdp-target map to the env the daemon
+    // reads. Passing them once persists them to the session so later commands for the
+    // same --device don't need the flags; absent flags hydrate from the saved session.
+    const isWebSession = sessionName === 'web' || sessionName.startsWith('web:');
+    if (isWebSession && !NO_DEVICE_COMMANDS.has(command)) {
+        const cdpUrlFlag = argv['cdp-url'];
+        const cdpTargetFlag = argv['cdp-target'];
+        if (cdpUrlFlag || cdpTargetFlag) {
+            if (cdpUrlFlag)
+                process.env.CONDUCTOR_CDP_URL = cdpUrlFlag;
+            if (cdpTargetFlag)
+                process.env.CONDUCTOR_CDP_TARGET_ID = cdpTargetFlag;
+            await (0, session_js_2.updateSession)({
+                cdpUrl: process.env.CONDUCTOR_CDP_URL,
+                cdpTargetId: process.env.CONDUCTOR_CDP_TARGET_ID,
+            }, sessionName);
+        }
+        else {
+            const saved = await (0, session_js_2.getSession)(sessionName);
+            if (saved.cdpUrl && !process.env.CONDUCTOR_CDP_URL) {
+                process.env.CONDUCTOR_CDP_URL = saved.cdpUrl;
+            }
+            if (saved.cdpTargetId && !process.env.CONDUCTOR_CDP_TARGET_ID) {
+                process.env.CONDUCTOR_CDP_TARGET_ID = saved.cdpTargetId;
+            }
+        }
+    }
     let exitCode = 0;
     switch (command) {
+        case 'web-targets':
+            exitCode = await (0, web_targets_js_1.webTargets)(argv['cdp-url'], opts);
+            break;
         case 'start-device':
             exitCode = await (0, start_device_js_1.startDevice)(argv['platform'], opts, {
                 osVersion: argv['os-version'],

package/package.json

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

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, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, installing or launching an app, setting up the web driver, 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, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, 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
@@ -19,27 +19,44 @@ conductor list-apps          # installed app ids / package names
 
 ## Devices
 
-| Command | Purpose |
-|---|---|
-| `conductor start-device --platform <ios\|android\|tvos\|web>` | Boot a simulator/emulator or start the web driver |
-| `conductor start-device --os-version <n> --device-type <name>` | Pick OS version + device type (creates if needed) |
-| `conductor stop-device [<name-or-id>] [--all]` | Shut down device(s) |
-| `conductor delete-device <name-or-id> [--all]` | Delete simulator(s)/AVD(s)/web session(s) |
-| `conductor set-location --lat <n> --lng <n>` | Set GPS coordinates |
-| `conductor set-orientation <portrait\|landscape>` | Set orientation |
-| `conductor set-viewport [<w> <h>] [--preset mobile\|tablet\|desktop]` | Resize web viewport (web only) |
-| `conductor install-web [--check] [browser]` | Install a Playwright browser (chromium/firefox/webkit); `--check` = status |
+| Command                                                               | Purpose                                                                    |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `conductor start-device --platform <ios\|android\|tvos\|web>`         | Boot a simulator/emulator or start the web driver                          |
+| `conductor start-device --os-version <n> --device-type <name>`        | Pick OS version + device type (creates if needed)                          |
+| `conductor stop-device [<name-or-id>] [--all]`                        | Shut down device(s)                                                        |
+| `conductor delete-device <name-or-id> [--all]`                        | Delete simulator(s)/AVD(s)/web session(s)                                  |
+| `conductor set-location --lat <n> --lng <n>`                          | Set GPS coordinates                                                        |
+| `conductor set-orientation <portrait\|landscape>`                     | Set orientation                                                            |
+| `conductor set-viewport [<w> <h>] [--preset mobile\|tablet\|desktop]` | Resize web viewport (web only)                                             |
+| `conductor install-web [--check] [browser]`                           | Install a Playwright browser (chromium/firefox/webkit); `--check` = status |
+
+### Attach to an existing browser (CDP)
+
+Instead of launching its own browser, the web driver can attach to one that's
+already running and exposes CDP over a remote-debugging port — e.g. an Electron
+app started with `--remote-debugging-port`, where each window / webview is a
+separate page target you can drive independently.
+
+| Command                                                                            | Purpose                                                                                                          |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `conductor web-targets --cdp-url <url>`                                            | List the controllable page targets the browser exposes (id, url, title) + a paste-ready bind command for each    |
+| `conductor --device web:<browser>:<label> --cdp-url <url> --cdp-target <id> <cmd>` | Bind a session to one target; the attachment persists so later commands for that `--device` don't need the flags |
+
+Use a distinct fully-qualified `--device web:chromium:<label>` per target (a bare
+`web` gets an auto-generated sub-id instead). Each target is its own session, so
+several webviews can be driven concurrently. Only `type=page` targets are
+controllable. See [Web testing → Attaching to an existing browser](../../../docs/web.md).
 
 ## App lifecycle
 
-| Command | Purpose |
-|---|---|
-| `conductor install-app <path>` | Install .app / .ipa / .apk |
-| `conductor launch-app <appId>` | Launch app (saved to session); `--no-stop-app`, `--argument key=value` |
-| `conductor stop-app [<appId>]` | Stop app |
-| `conductor uninstall-app <appId>` | Uninstall app |
-| `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators |
-| `conductor download-app <appId> --output <path>` | Download installed app binary |
+| Command                                               | Purpose                                                                |
+| ----------------------------------------------------- | ---------------------------------------------------------------------- |
+| `conductor install-app <path>`                        | Install .app / .ipa / .apk                                             |
+| `conductor launch-app <appId>`                        | Launch app (saved to session); `--no-stop-app`, `--argument key=value` |
+| `conductor stop-app [<appId>]`                        | Stop app                                                               |
+| `conductor uninstall-app <appId>`                     | Uninstall app                                                          |
+| `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators                           |
+| `conductor download-app <appId> --output <path>`      | Download installed app binary                                          |
 
 ### ⚠️ Destructive flags — ask the user first
 
@@ -54,15 +71,15 @@ you genuinely need one, ask the human first.
 A **session** remembers the last device + app so you don't re-specify them.
 Parallel agents each get their own `--session <name>` so they don't collide.
 
-| Command | Purpose |
-|---|---|
-| `conductor session [--clear] [--list]` | Show, clear, or list sessions |
-| `conductor daemon-start` | Start the per-session background daemon (keeps the driver warm — do this for any multi-step session) |
-| `conductor daemon-status` | Show daemon status |
-| `conductor daemon-stop [--all]` | Stop this session's daemon (`--all` = every session) |
-| `conductor device-pool --list` | List devices + pool status |
-| `conductor device-pool --acquire` | Claim a free device (prints id) |
-| `conductor device-pool --release <id>` | Release a device back to the pool |
+| Command                                | Purpose                                                                                              |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `conductor session [--clear] [--list]` | Show, clear, or list sessions                                                                        |
+| `conductor daemon-start`               | Start the per-session background daemon (keeps the driver warm — do this for any multi-step session) |
+| `conductor daemon-status`              | Show daemon status                                                                                   |
+| `conductor daemon-stop [--all]`        | Stop this session's daemon (`--all` = every session)                                                 |
+| `conductor device-pool --list`         | List devices + pool status                                                                           |
+| `conductor device-pool --acquire`      | Claim a free device (prints id)                                                                      |
+| `conductor device-pool --release <id>` | Release a device back to the pool                                                                    |
 
 Don't leave a daemon running when you're done — `daemon-stop` it.