@houwert/conductor 0.15.0 → 0.17.0

package/dist/drivers/ios.js

@@ -16,6 +16,13 @@ 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");
+/**
+ * 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
+ * (timer-driven UI, async animation). Mirrors the equivalent cache TTL in the
+ * agent-device runner.
+ */
+const HIERARCHY_CACHE_TTL_MS = 750;
 class IOSDriver {
     constructor(port = 1075, host = '127.0.0.1', deviceId, platform = 'ios') {
         this.port = port;
@@ -23,6 +30,13 @@ class IOSDriver {
         this.deviceId = deviceId;
         this.platform = platform;
         this._recordingProcess = null;
+        /**
+         * Short-lived cache of the most recent view hierarchy, keyed by request
+         * params. Only served when the caller explicitly opts in (e.g. the first
+         * probe of a wait loop) and dropped by any UI-mutating command, so polling
+         * loops and post-action reads always see a fresh tree.
+         */
+        this.hierarchyCache = null;
     }
     request(method, path, body) {
         return new Promise((resolve, reject) => {
@@ -71,6 +85,10 @@ class IOSDriver {
             throw new Error('IOSDriver: deviceId is required for this operation');
         return this.deviceId;
     }
+    /** Drop the cached view hierarchy — call after any command that mutates the UI. */
+    invalidateHierarchyCache() {
+        this.hierarchyCache = null;
+    }
     simctl(args) {
         const _id = this.requireDeviceId();
         return new Promise((resolve, reject) => {
@@ -111,9 +129,10 @@ class IOSDriver {
     }
     async tap(x, y, duration) {
         await this.post('touch', { x, y, ...(duration !== undefined ? { duration } : {}) });
+        this.invalidateHierarchyCache();
     }
     async swipe(startX, startY, endX, endY, duration, appIds) {
-        await this.post('swipeV2', {
+        await this.post('swipe', {
             startX,
             startY,
             endX,
@@ -121,15 +140,29 @@ class IOSDriver {
             duration,
             ...(appIds ? { appIds } : {}),
         });
+        this.invalidateHierarchyCache();
+    }
+    /**
+     * Multi-finger gesture playback. `paths` is one entry per finger; each entry's
+     * `steps` are the (x, y, dt) frames making up that finger's path. The driver
+     * synthesizes a multi-finger XCSynthesizedEventRecord when paths.length > 1.
+     * `dt` is the delay in seconds since the previous step (or the initial offset
+     * for the first step).
+     */
+    async gesturePath(paths) {
+        await this.post('gesturePath', { paths });
     }
     async inputText(text, appIds = []) {
         await this.post('inputText', { text, appIds });
+        this.invalidateHierarchyCache();
     }
     async pressKey(key) {
         await this.post('pressKey', { key });
+        this.invalidateHierarchyCache();
     }
     async pressButton(button) {
         await this.post('pressButton', { button });
+        this.invalidateHierarchyCache();
     }
     async launchApp(bundleId, args) {
         if (args && Object.keys(args).length > 0) {
@@ -145,9 +178,11 @@ class IOSDriver {
         else {
             await this.post('launchApp', { bundleId });
         }
+        this.invalidateHierarchyCache();
     }
     async terminateApp(appId) {
         await this.post('terminateApp', { appId });
+        this.invalidateHierarchyCache();
     }
     async clearAppState(bundleId) {
         const deviceId = this.requireDeviceId();
@@ -167,11 +202,13 @@ class IOSDriver {
         finally {
             await promises_1.default.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
         }
+        this.invalidateHierarchyCache();
     }
     async uninstallApp(bundleId) {
         const deviceId = this.requireDeviceId();
         await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
         await this.simctl(['uninstall', deviceId, bundleId]);
+        this.invalidateHierarchyCache();
     }
     async clearKeychain() {
         const deviceId = this.requireDeviceId();
@@ -180,6 +217,28 @@ class IOSDriver {
     async openLink(url) {
         const deviceId = this.requireDeviceId();
         await this.simctl(['openurl', deviceId, url]);
+        this.invalidateHierarchyCache();
+    }
+    /** Read the simulator's clipboard. Uses `xcrun simctl pbpaste <udid>`. */
+    async clipboardRead() {
+        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) {
+        const deviceId = this.requireDeviceId();
+        await new Promise((resolve, reject) => {
+            const proc = (0, child_process_1.spawn)('xcrun', ['simctl', 'pbcopy', deviceId], {
+                stdio: ['pipe', 'ignore', 'pipe'],
+            });
+            let stderr = '';
+            proc.stderr?.on('data', (c) => {
+                stderr += c.toString();
+            });
+            proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`xcrun simctl pbcopy failed: ${stderr.trim()}`)));
+            proc.on('error', reject);
+            proc.stdin?.end(text);
+        });
     }
     async setLocation(latitude, longitude) {
         const deviceId = this.requireDeviceId();
@@ -187,6 +246,7 @@ class IOSDriver {
     }
     async setOrientation(orientation) {
         await this.post('setOrientation', { orientation });
+        this.invalidateHierarchyCache();
     }
     async setPermissions(appId, permissions) {
         // All iOS permissions the XCTest runner's interruption monitor can handle.
@@ -298,7 +358,14 @@ class IOSDriver {
             this._recordingProcess = null;
         }
     }
-    async viewHierarchy(excludeKeyboardElements = false, appIds = []) {
+    async viewHierarchy(excludeKeyboardElements = false, appIds = [], opts = {}) {
+        const key = `${excludeKeyboardElements}:${appIds.join(',')}`;
+        if (opts.cache &&
+            this.hierarchyCache &&
+            this.hierarchyCache.key === key &&
+            Date.now() - this.hierarchyCache.at < HIERARCHY_CACHE_TTL_MS) {
+            return this.hierarchyCache.value;
+        }
         const { status, data } = await this.request('POST', '/viewHierarchy', {
             appIds,
             excludeKeyboardElements,
@@ -306,9 +373,27 @@ class IOSDriver {
         if (status < 200 || status >= 300) {
             throw new Error(`iOS driver viewHierarchy failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
         }
+        const value = JSON.parse(data.toString('utf-8'));
+        this.hierarchyCache = { key, value, at: Date.now() };
+        return value;
+    }
+    /**
+     * Resolve a single element directly via the runner instead of dumping and
+     * matching the whole view hierarchy. Returns `matchCount` so callers can
+     * fall back to the snapshot path when the result is ambiguous (>1) or empty.
+     */
+    async queryElement(selectorKey, selectorValue, appIds = []) {
+        const { status, data } = await this.request('POST', '/queryElement', {
+            selectorKey,
+            selectorValue,
+            appIds,
+        });
+        if (status < 200 || status >= 300) {
+            throw new Error(`iOS driver queryElement failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
+        }
         return JSON.parse(data.toString('utf-8'));
     }
-    async screenshot() {
+    async screenshot(_opts = {}) {
         const { status, data } = await this.request('GET', '/screenshot');
         if (status < 200 || status >= 300) {
             throw new Error(`iOS driver screenshot failed (HTTP ${status})`);

package/dist/drivers/metro-cdp.js

@@ -0,0 +1,291 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetroCdpClient = void 0;
+exports.resolveDebuggerUrl = resolveDebuggerUrl;
+exports.cdpCall = cdpCall;
+/**
+ * One-shot CDP client to Metro's debugger endpoint.
+ *
+ * Sibling to `MetroLogSource` in log-sources/metro.ts: that class stays connected
+ * to stream `Runtime.consoleAPICalled`; this one opens a short-lived socket for
+ * request/response calls (`Page.reload`, `Runtime.evaluate`, etc.).
+ *
+ * Reuses `fetchTargets()` / target selection from `log-sources/metro.ts` and
+ * `metro-discovery.ts` — do not duplicate discovery logic here.
+ */
+const ws_1 = __importDefault(require("ws"));
+const metro_js_1 = require("./log-sources/metro.js");
+const metro_discovery_js_1 = require("./log-sources/metro-discovery.js");
+/**
+ * Resolve a Metro target's `webSocketDebuggerUrl` honoring deviceId / targetIndex.
+ * Throws with a clear message if Metro is unreachable or no target matches.
+ */
+async function resolveDebuggerUrl(opts) {
+    const port = opts.port ?? 8081;
+    const host = opts.host ?? 'localhost';
+    const targets = await (0, metro_js_1.fetchTargets)(port, host);
+    const withWs = targets.filter((t) => t.webSocketDebuggerUrl);
+    if (withWs.length === 0) {
+        throw new Error(`Metro on ${host}:${port} returned no debugger targets. Is an app running on a device/simulator?`);
+    }
+    if (opts.targetIndex !== undefined) {
+        if (opts.targetIndex < 0 || opts.targetIndex >= withWs.length) {
+            throw new Error(`--target ${opts.targetIndex} is out of range (have ${withWs.length}).`);
+        }
+        return withWs[opts.targetIndex].webSocketDebuggerUrl;
+    }
+    if (opts.deviceId && opts.platform) {
+        const displayName = await (0, metro_discovery_js_1.getDeviceDisplayName)(opts.platform, opts.deviceId);
+        if (displayName) {
+            const target = (0, metro_discovery_js_1.selectTargetForDevice)(withWs, displayName);
+            if (target)
+                return target.webSocketDebuggerUrl;
+        }
+    }
+    // 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;
+}
+/**
+ * Open a short-lived CDP socket, send a single method, return the result.
+ * Closes the socket whether the call succeeds or throws.
+ */
+async function cdpCall(method, params, opts) {
+    const wsUrl = await resolveDebuggerUrl(opts);
+    return cdpCallOnUrl(wsUrl, method, params, opts.timeoutMs ?? 10000);
+}
+async function cdpCallOnUrl(wsUrl, method, params, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const ws = new ws_1.default(wsUrl);
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            ws.terminate();
+            reject(new Error(`CDP ${method} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        function finish(err, value) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            ws.removeAllListeners();
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        }
+        const req = { id: 1, method };
+        if (params)
+            req.params = params;
+        ws.on('open', () => {
+            ws.send(JSON.stringify(req));
+        });
+        ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg.id !== req.id)
+                    return;
+                if (msg.error) {
+                    finish(new Error(`CDP ${method}: ${msg.error.message}`));
+                }
+                else {
+                    finish(null, msg.result);
+                }
+            }
+            catch (err) {
+                finish(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        ws.on('error', (err) => finish(err));
+        ws.on('close', () => {
+            if (!settled)
+                finish(new Error(`CDP socket closed before ${method} completed`));
+        });
+    });
+}
+/**
+ * Stateful CDP client. Open once, issue many calls. Used by the debugger
+ * commands that need session-scoped state (loaded scripts, enabled domains).
+ */
+class MetroCdpClient {
+    constructor() {
+        this.ws = null;
+        this.nextId = 1;
+        this.pending = new Map();
+        this.events = new Map();
+        this.enabledDomains = new Set();
+        this.loadedScripts = new Map();
+        this.bindings = new Set();
+        this.callbackPending = new Map();
+    }
+    async connect(opts) {
+        const wsUrl = await resolveDebuggerUrl(opts);
+        await new Promise((resolve, reject) => {
+            const ws = new ws_1.default(wsUrl);
+            ws.on('open', () => {
+                this.ws = ws;
+                resolve();
+            });
+            ws.on('message', (data) => this.handleMessage(data.toString()));
+            ws.on('error', (err) => {
+                if (!this.ws)
+                    reject(err);
+            });
+            ws.on('close', () => {
+                this.ws = null;
+            });
+        });
+    }
+    handleMessage(raw) {
+        try {
+            const msg = JSON.parse(raw);
+            if (typeof msg.id === 'number') {
+                const slot = this.pending.get(msg.id);
+                if (slot) {
+                    this.pending.delete(msg.id);
+                    if (msg.error)
+                        slot.reject(new Error(msg.error.message));
+                    else
+                        slot.resolve(msg.result);
+                }
+                return;
+            }
+            if (msg.method) {
+                if (msg.method === 'Debugger.scriptParsed') {
+                    const p = msg.params;
+                    if (p?.scriptId)
+                        this.loadedScripts.set(p.scriptId, { url: p.url });
+                }
+                const handlers = this.events.get(msg.method);
+                if (handlers)
+                    for (const h of handlers)
+                        h(msg.params);
+            }
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    on(method, handler) {
+        const arr = this.events.get(method) ?? [];
+        arr.push(handler);
+        this.events.set(method, arr);
+    }
+    async send(method, params) {
+        if (!this.ws)
+            throw new Error('CDP client not connected');
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject,
+            });
+            this.ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    async enableDomain(domain) {
+        if (this.enabledDomains.has(domain))
+            return;
+        await this.send(`${domain}.enable`);
+        this.enabledDomains.add(domain);
+    }
+    /**
+     * Install a `Runtime.addBinding` callback. The injected JS calls
+     * `globalThis.__conductor_callback(JSON.stringify({ requestId, ... }))` and
+     * this method routes the payload back to the awaiter keyed on `requestId`.
+     *
+     * Returns a function that, given a requestId, returns a promise resolving
+     * to the next payload tagged with that requestId. Useful for async fiber
+     * walkers that can't return synchronously from `Runtime.evaluate`.
+     */
+    async installCallbackBinding(bindingName = '__conductor_callback') {
+        await this.enableDomain('Runtime');
+        if (!this.bindings.has(bindingName)) {
+            await this.send('Runtime.addBinding', { name: bindingName });
+            this.bindings.add(bindingName);
+            this.on('Runtime.bindingCalled', (params) => {
+                const p = params;
+                if (p.name !== bindingName)
+                    return;
+                try {
+                    const parsed = JSON.parse(p.payload);
+                    if (parsed.requestId && this.callbackPending.has(parsed.requestId)) {
+                        const slot = this.callbackPending.get(parsed.requestId);
+                        this.callbackPending.delete(parsed.requestId);
+                        slot.resolve(parsed);
+                    }
+                }
+                catch {
+                    // ignore malformed payloads
+                }
+            });
+        }
+        return (requestId, timeoutMs = 5000) => new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.callbackPending.delete(requestId);
+                reject(new Error(`callback ${requestId} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.callbackPending.set(requestId, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject,
+            });
+        });
+    }
+    /**
+     * Evaluate a JS expression in the app's runtime. Returns the value or throws
+     * a thrown JS exception's description. Awaits promises by default.
+     */
+    async evaluate(expression, returnByValue = true) {
+        await this.enableDomain('Runtime');
+        const result = await this.send('Runtime.evaluate', {
+            expression,
+            returnByValue,
+            awaitPromise: true,
+            generatePreview: false,
+        });
+        if (result.exceptionDetails) {
+            const msg = result.exceptionDetails.exception?.description ??
+                result.exceptionDetails.text ??
+                'evaluation threw';
+            throw new Error(msg);
+        }
+        return (result.result.value ?? result.result.description);
+    }
+    getEnabledDomains() {
+        return new Set(this.enabledDomains);
+    }
+    getLoadedScripts() {
+        return this.loadedScripts;
+    }
+    isConnected() {
+        return this.ws !== null;
+    }
+    close() {
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch {
+                // ignore
+            }
+            this.ws = null;
+        }
+        this.pending.clear();
+        this.events.clear();
+    }
+}
+exports.MetroCdpClient = MetroCdpClient;