@houwert/conductor 0.31.0 → 0.32.1

package/dist/commands/metro.js

@@ -3,12 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.metroStop = metroStop;
 exports.metroReload = metroReload;
+exports.normalizeMetroLocation = normalizeMetroLocation;
+exports.metroUse = metroUse;
 exports.HELP = `  metro stop [--port N]                Stop the Metro bundler process on a port (default 8081)
-  metro reload [--port N] [--target N]  Reload the JS bundle without restarting native`;
+  metro reload [--port N] [--target N]  Reload the JS bundle without restarting native
+  metro use <port|host:port> [<appId>]  Point an RN app at a Metro other than its compiled-in one
+  metro use --reset [<appId>]           Drop the override, back to the compiled-in port`;
 const child_process_1 = require("child_process");
 const output_js_1 = require("../output.js");
 const metro_cdp_js_1 = require("../drivers/metro-cdp.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const runner_js_1 = require("../runner.js");
+const session_js_1 = require("../session.js");
 async function pidsOnPort(port) {
     return new Promise((resolve) => {
         const proc = (0, child_process_1.spawn)('lsof', ['-ti', `tcp:${port}`], {
@@ -109,3 +115,133 @@ async function metroReload(opts, sessionName, metroOpts) {
         }
     }
 }
+/**
+ * NSUserDefaults key RCTBundleURLProvider reads before falling back to the
+ * RCT_METRO_PORT baked into React-Core at pod-install time. Writing it is the
+ * only way to move a build onto another port without recompiling.
+ */
+const JS_LOCATION_KEY = 'RCT_jsLocation';
+/**
+ * `8102` → `localhost:8102`. Also tolerates a pasted `http://host:port/`.
+ *
+ * Takes a number too: minimist turns a bare port argument into one.
+ */
+function normalizeMetroLocation(raw) {
+    const trimmed = String(raw)
+        .trim()
+        .replace(/^https?:\/\//, '')
+        .replace(/\/+$/, '');
+    const match = trimmed.match(/^(?:([A-Za-z0-9._-]+):)?(\d+)$/);
+    if (!match) {
+        throw new Error(`invalid location "${raw}" — expected <port> or <host:port>`);
+    }
+    const [, host = 'localhost', rawPort] = match;
+    const port = Number(rawPort);
+    if (port < 1 || port > 65535) {
+        throw new Error(`invalid port "${rawPort}" in "${raw}" — expected 1-65535`);
+    }
+    return `${host}:${port}`;
+}
+async function isPackagerRunning(location) {
+    try {
+        const res = await fetch(`http://${location}/status`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return res.ok && (await res.text()).includes('packager-status:running');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Point a React Native app at a specific Metro by writing RCTBundleURLProvider's
+ * `RCT_jsLocation` default into the app's preferences on a simulator.
+ *
+ * The port an app asks for is compiled into React-Core from `RCT_METRO_PORT` at
+ * pod-install time, so a build made against the wrong port (a git worktree with
+ * its own Metro, a pod install from a shell missing the env var) keeps asking
+ * for the old one until it is recompiled. This override survives reinstalls and
+ * needs no rebuild.
+ */
+async function metroUse(opts, sessionName, useOpts) {
+    const deviceId = sessionName && sessionName !== 'default' ? sessionName : await (0, runner_js_1.detectFirstDevice)();
+    if (!deviceId) {
+        (0, output_js_1.printError)('metro use: no device found. Pass --device <id> or boot a simulator.', opts);
+        return 1;
+    }
+    const platform = await (0, bootstrap_js_1.detectPlatform)(deviceId).catch(() => undefined);
+    if (platform !== 'ios' && platform !== 'tvos') {
+        (0, output_js_1.printError)(`metro use: only iOS/tvOS simulators are supported (device is ${platform ?? 'unknown'}).\n` +
+            'On Android, map the port instead: adb -s <serial> reverse tcp:8081 tcp:<metro-port>', opts);
+        return 1;
+    }
+    const kind = await (0, bootstrap_js_1.detectDeviceKind)(deviceId).catch(() => undefined);
+    if (kind === 'physical') {
+        (0, output_js_1.printError)('metro use: physical devices read their packager host from the bundled ip.txt, ' +
+            'not from simulator defaults. Set it from the in-app dev menu instead.', opts);
+        return 1;
+    }
+    const appId = useOpts.appId ?? (await (0, session_js_1.getSession)(sessionName)).appId;
+    if (!appId) {
+        (0, output_js_1.printError)('metro use: no appId given and no active session. Run launch-app first.', opts);
+        return 1;
+    }
+    if (useOpts.reset) {
+        // `defaults delete` exits non-zero when the key was never written, which is
+        // the same end state the caller asked for.
+        await (0, runner_js_1.spawnCommand)('xcrun', [
+            'simctl',
+            'spawn',
+            deviceId,
+            'defaults',
+            'delete',
+            appId,
+            JS_LOCATION_KEY,
+        ]);
+        if (opts.json)
+            (0, output_js_1.printData)({ appId, deviceId, location: null, reset: true }, opts);
+        else
+            (0, output_js_1.printSuccess)(`Cleared Metro override for "${appId}" — relaunch the app to apply`, opts);
+        return 0;
+    }
+    if (!useOpts.location) {
+        (0, output_js_1.printError)('Usage: conductor metro use <port|host:port> [<appId>] | metro use --reset', opts);
+        return 1;
+    }
+    let location;
+    try {
+        location = normalizeMetroLocation(useOpts.location);
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`metro use: ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+    const running = await isPackagerRunning(location);
+    const result = await (0, runner_js_1.spawnCommand)('xcrun', [
+        'simctl',
+        'spawn',
+        deviceId,
+        'defaults',
+        'write',
+        appId,
+        JS_LOCATION_KEY,
+        location,
+    ]);
+    if (!result.success) {
+        (0, output_js_1.printError)(`metro use: could not write ${JS_LOCATION_KEY} for "${appId}"\n${result.stderr}`, opts);
+        return 1;
+    }
+    if (!running) {
+        // RCTBundleURLProvider drops a stored location when nothing answers there,
+        // so the app would silently fall back to its compiled-in port.
+        process.stderr.write(`warning: no packager answered at ${location}; the app falls back to its ` +
+            'compiled-in port until Metro is up there.\n');
+    }
+    if (opts.json) {
+        (0, output_js_1.printData)({ appId, deviceId, location, packagerRunning: running, reset: false }, opts);
+    }
+    else {
+        (0, output_js_1.printSuccess)(`"${appId}" → ${location} — relaunch the app to apply`, opts);
+    }
+    return 0;
+}

package/dist/commands/start-device.js

@@ -35,6 +35,22 @@ const output_js_1 = require("../output.js");
 const utils_js_1 = require("../utils.js");
 const cli_js_1 = require("../drivers/vega/cli.js");
 const discovery_js_1 = require("../drivers/roku/discovery.js");
+/**
+ * Show the simulator window. Xcode 27 replaced Simulator.app with DeviceHub.app,
+ * so fall back to the hub when Simulator.app is absent.
+ */
+function openSimulatorUI() {
+    const tryOpen = (args, next) => {
+        const p = (0, child_process_1.spawn)('open', args, { detached: true, stdio: 'ignore' });
+        p.on('error', () => next?.());
+        p.on('exit', (code) => {
+            if (code !== 0)
+                next?.();
+        });
+        p.unref();
+    };
+    tryOpen(['-a', 'Simulator'], () => tryOpen(['-b', 'com.apple.dt.Devices']));
+}
 const IOS_BOOT_TIMEOUT_MS = 120000;
 const ANDROID_BOOT_TIMEOUT_MS = 120000;
 const POLL_MS = 1000;
@@ -252,8 +268,7 @@ async function startIOS(osVersion, opts, name, deviceType) {
             return 1;
         }
     }
-    // Open the Simulator.app so the window appears
-    (0, child_process_1.spawn)('open', ['-a', 'Simulator'], { detached: true, stdio: 'ignore' }).unref();
+    openSimulatorUI();
     const displayName = name ?? device.name;
     // Prewarm the driver so the first interaction command is not the
     // one that pays the XCTest runner startup cost.
@@ -416,8 +431,7 @@ async function startTvOS(osVersion, opts, name, deviceType) {
             return 1;
         }
     }
-    // Open the Simulator.app so the window appears
-    (0, child_process_1.spawn)('open', ['-a', 'Simulator'], { detached: true, stdio: 'ignore' }).unref();
+    openSimulatorUI();
     const displayName = name ?? device.name;
     // Prewarm the driver so the first interaction command is not the
     // one that pays the XCTest runner startup cost.

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/package.json

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

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