@houwert/conductor 0.16.0 → 0.18.0

package/dist/index.js

@@ -30,6 +30,15 @@ const daemon_js_1 = require("./commands/daemon.js");
 const install_js_1 = require("./commands/install.js");
 const device_pool_js_1 = require("./commands/device-pool.js");
 const run_parallel_js_1 = require("./commands/run-parallel.js");
+const run_sequence_js_1 = require("./commands/run-sequence.js");
+const gestures_js_1 = require("./commands/gestures.js");
+const workspace_js_1 = require("./commands/workspace.js");
+const debug_js_1 = require("./commands/debug.js");
+const network_js_1 = require("./commands/network.js");
+const flow_record_js_1 = require("./commands/flow-record.js");
+const profile_js_1 = require("./commands/profile.js");
+const crashes_js_1 = require("./commands/crashes.js");
+const flow_recorder_js_1 = require("./drivers/flow-recorder.js");
 const foreground_app_js_1 = require("./commands/foreground-app.js");
 const list_apps_js_1 = require("./commands/list-apps.js");
 const copy_app_js_1 = require("./commands/copy-app.js");
@@ -42,11 +51,14 @@ const hide_keyboard_js_1 = require("./commands/hide-keyboard.js");
 const scroll_until_visible_js_1 = require("./commands/scroll-until-visible.js");
 const set_location_js_1 = require("./commands/set-location.js");
 const set_orientation_js_1 = require("./commands/set-orientation.js");
+const set_viewport_js_1 = require("./commands/set-viewport.js");
 const start_device_js_1 = require("./commands/start-device.js");
 const stop_device_js_1 = require("./commands/stop-device.js");
 const delete_device_js_1 = require("./commands/delete-device.js");
 const logs_js_1 = require("./commands/logs.js");
 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 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");
@@ -80,6 +92,7 @@ const COMMAND_HELP = {
     'open-link': open_link_js_1.HELP,
     'set-location': set_location_js_1.HELP,
     'set-orientation': set_orientation_js_1.HELP,
+    'set-viewport': set_viewport_js_1.HELP,
     'take-screenshot': screenshot_js_1.HELP,
     'capture-ui': capture_ui_js_1.HELP,
     inspect: inspect_js_1.HELP,
@@ -93,8 +106,19 @@ const COMMAND_HELP = {
     'daemon-status': daemon_js_1.HELP_DAEMON_STATUS,
     'device-pool': device_pool_js_1.HELP,
     'run-parallel': run_parallel_js_1.HELP,
+    'run-sequence': run_sequence_js_1.HELP,
+    gestures: gestures_js_1.HELP,
+    workspace: workspace_js_1.HELP,
+    debug: debug_js_1.HELP,
+    network: network_js_1.HELP,
+    'flow record': flow_record_js_1.HELP,
+    profile: profile_js_1.HELP,
+    crashes: crashes_js_1.HELP,
     logs: logs_js_1.HELP,
     memory: memory_js_1.HELP,
+    metro: metro_js_1.HELP,
+    clipboard: clipboard_js_1.HELP,
+    paste: '  paste                                Trigger OS-level paste (or type clipboard on iOS)',
 };
 const OPTIONS_HELP = `Options:
   --device <id>     Target device ID (also keys the session and daemon)
@@ -133,6 +157,7 @@ async function main() {
             'optional',
             'benchmark',
             'dump',
+            'tappable',
             'objects',
             'heap',
             'leaks',
@@ -173,6 +198,29 @@ async function main() {
             'vs',
             'top',
             'filter',
+            'port',
+            'target',
+            'at',
+            'file',
+            'scale',
+            'center',
+            'degrees',
+            'angle',
+            'limit',
+            'method',
+            'body',
+            'header',
+            'url',
+            'out',
+            'track',
+            'interval',
+            'app',
+            'since',
+            'preset',
+            'width',
+            'height',
+            'user-agent',
+            'color-scheme',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version' },
     });
@@ -207,6 +255,8 @@ async function main() {
         'copy-app',
         'device-pool',
         'run-parallel',
+        'metro',
+        'workspace',
         // `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
@@ -459,6 +509,26 @@ async function main() {
             exitCode = await (0, set_orientation_js_1.setOrientation)(orientation, opts, sessionName);
             break;
         }
+        case 'set-viewport': {
+            exitCode = await (0, set_viewport_js_1.setViewport)({
+                preset: argv['preset'],
+                width: argv['width'] !== undefined
+                    ? Number(argv['width'])
+                    : rest[0] !== undefined
+                        ? Number(rest[0])
+                        : undefined,
+                height: argv['height'] !== undefined
+                    ? Number(argv['height'])
+                    : rest[1] !== undefined
+                        ? Number(rest[1])
+                        : undefined,
+                scale: argv['scale'] !== undefined ? Number(argv['scale']) : undefined,
+                mobile: argv['mobile'],
+                userAgent: argv['user-agent'],
+                colorScheme: argv['color-scheme'],
+            }, opts, sessionName);
+            break;
+        }
         case 'take-screenshot': {
             const outPath = argv['output'];
             const fullPage = Boolean(argv['full-page']);
@@ -471,7 +541,11 @@ async function main() {
             break;
         }
         case 'inspect':
-            exitCode = await (0, inspect_js_1.inspect)(opts, sessionName, { dump: argv['dump'] });
+            exitCode = await (0, inspect_js_1.inspect)(opts, sessionName, {
+                dump: argv['dump'],
+                at: argv['at'],
+                tappableOnly: argv['tappable'],
+            });
             break;
         case 'focused':
             exitCode = await (0, focused_js_1.focused)(opts, sessionName, {
@@ -542,17 +616,231 @@ async function main() {
             exitCode = await (0, device_pool_js_1.devicePool)(action, releaseId, opts);
             break;
         }
+        case 'run-sequence': {
+            const file = argv['file'] ?? rest[0];
+            exitCode = await (0, run_sequence_js_1.runSequence)(file, opts, sessionName);
+            break;
+        }
         case 'run-parallel': {
             const flowsDir = argv['flows-dir'] ?? rest[0] ?? '';
             exitCode = await (0, run_parallel_js_1.runParallel)(flowsDir, opts);
             break;
         }
+        case 'crashes': {
+            const sub = (rest[0] ?? 'list').toLowerCase();
+            if (sub === 'list') {
+                exitCode = await (0, crashes_js_1.crashesList)(opts, sessionName, {
+                    app: argv['app'],
+                    since: argv['since'],
+                });
+            }
+            else if (sub === 'show') {
+                exitCode = await (0, crashes_js_1.crashesShow)(rest[1] ?? '', opts);
+            }
+            else if (sub === 'tail') {
+                exitCode = await (0, crashes_js_1.crashesTail)(opts, sessionName);
+            }
+            else {
+                console.error('Usage: conductor crashes <list|show|tail>');
+                exitCode = 1;
+            }
+            break;
+        }
+        case 'profile': {
+            const sub = (rest[0] ?? '').toLowerCase();
+            const port = argv['port'] !== undefined ? Number(argv['port']) : undefined;
+            const targetIndex = argv['target'] !== undefined ? Number(argv['target']) : undefined;
+            if (sub === 'cpu') {
+                const durationSec = argv['duration'] !== undefined ? Number(argv['duration']) : 10;
+                exitCode = await (0, profile_js_1.profileCpu)(opts, sessionName, {
+                    durationSec,
+                    out: argv['out'],
+                    appId: rest[1],
+                });
+            }
+            else if (sub === 'memory') {
+                const trackSec = argv['track'] !== undefined ? Number(argv['track']) : 10;
+                const intervalMs = argv['interval'] !== undefined ? Number(argv['interval']) : 1000;
+                exitCode = await (0, profile_js_1.profileMemory)(opts, sessionName, {
+                    trackSec,
+                    intervalMs,
+                    appId: rest[1],
+                });
+            }
+            else if (sub === 'react') {
+                const sub2 = (rest[1] ?? '').toLowerCase();
+                const top = argv['top'] !== undefined ? Number(argv['top']) : 20;
+                if (sub2 === 'start') {
+                    exitCode = await (0, profile_js_1.profileReactStart)(opts, sessionName, { port, targetIndex });
+                }
+                else if (sub2 === 'stop') {
+                    exitCode = await (0, profile_js_1.profileReactStop)(opts, sessionName, { port, targetIndex }, top);
+                }
+                else {
+                    console.error('Usage: conductor profile react <start|stop>');
+                    exitCode = 1;
+                }
+            }
+            else {
+                console.error('Usage: conductor profile <cpu|memory|react> [args]');
+                exitCode = 1;
+            }
+            break;
+        }
+        case 'flow': {
+            const sub1 = (rest[0] ?? '').toLowerCase();
+            if (sub1 !== 'record') {
+                console.error('Usage: conductor flow record <start|finish|echo|status>');
+                exitCode = 1;
+                break;
+            }
+            const sub2 = (rest[1] ?? '').toLowerCase();
+            exitCode = await (0, flow_record_js_1.flowRecord)(sub2, rest.slice(2).map(String), opts, sessionName, argv);
+            break;
+        }
+        case 'network': {
+            const sub = (rest[0] ?? '').toLowerCase();
+            const port = argv['port'] !== undefined ? Number(argv['port']) : undefined;
+            const targetIndex = argv['target'] !== undefined ? Number(argv['target']) : undefined;
+            if (sub === 'logs') {
+                const limit = argv['limit'] !== undefined ? Number(argv['limit']) : undefined;
+                exitCode = await (0, network_js_1.networkLogs)(opts, sessionName, { port, targetIndex, limit });
+            }
+            else if (sub === 'request') {
+                const url = rest[1] ?? argv['url'] ?? '';
+                const rawHeaders = argv['header'];
+                const headers = Array.isArray(rawHeaders)
+                    ? rawHeaders
+                    : rawHeaders
+                        ? [rawHeaders]
+                        : [];
+                exitCode = await (0, network_js_1.networkRequest)(url, opts, sessionName, {
+                    port,
+                    targetIndex,
+                    method: argv['method'],
+                    body: argv['body'],
+                    headers,
+                });
+            }
+            else {
+                console.error('Usage: conductor network <logs|request> [args]');
+                exitCode = 1;
+            }
+            break;
+        }
+        case 'debug': {
+            const sub = (rest[0] ?? '').toLowerCase();
+            const debugOpts = {
+                port: argv['port'] !== undefined ? Number(argv['port']) : undefined,
+                targetIndex: argv['target'] !== undefined ? Number(argv['target']) : undefined,
+            };
+            if (sub === 'status') {
+                exitCode = await (0, debug_js_1.debugStatus)(opts, sessionName, debugOpts);
+            }
+            else if (sub === 'evaluate' || sub === 'eval') {
+                const expr = rest.slice(1).join(' ');
+                exitCode = await (0, debug_js_1.debugEvaluate)(expr, opts, sessionName, debugOpts);
+            }
+            else if (sub === 'component-tree') {
+                exitCode = await (0, debug_js_1.debugComponentTree)(opts, sessionName, debugOpts);
+            }
+            else if (sub === 'inspect-element') {
+                const at = rest[1] ?? argv['at'] ?? '';
+                exitCode = await (0, debug_js_1.debugInspectElement)(at, opts, sessionName, debugOpts);
+            }
+            else if (sub === 'log-registry') {
+                exitCode = await (0, debug_js_1.debugLogRegistry)(opts, sessionName);
+            }
+            else if (sub === 'reload') {
+                exitCode = await (0, debug_js_1.debugReload)(opts, sessionName, debugOpts);
+            }
+            else {
+                console.error('Usage: conductor debug <status|evaluate|component-tree|inspect-element|log-registry|reload>');
+                exitCode = 1;
+            }
+            break;
+        }
+        case 'workspace': {
+            const sub = (rest[0] ?? 'info').toLowerCase();
+            exitCode = await (0, workspace_js_1.workspaceCmd)(sub, opts);
+            break;
+        }
+        case 'pinch':
+            exitCode = await (0, gestures_js_1.pinch)(opts, sessionName, {
+                scale: argv['scale'] !== undefined ? Number(argv['scale']) : undefined,
+                center: argv['center'],
+                duration: argv['duration'] !== undefined ? Number(argv['duration']) : undefined,
+                angle: argv['angle'] !== undefined ? Number(argv['angle']) : undefined,
+            });
+            break;
+        case 'rotate-gesture':
+            exitCode = await (0, gestures_js_1.rotateGesture)(opts, sessionName, {
+                degrees: argv['degrees'] !== undefined ? Number(argv['degrees']) : undefined,
+                center: argv['center'],
+                duration: argv['duration'] !== undefined ? Number(argv['duration']) : undefined,
+            });
+            break;
+        case 'gesture': {
+            const file = argv['file'];
+            const rawJson = !file ? rest.join(' ') : undefined;
+            exitCode = await (0, gestures_js_1.gesture)(rawJson, file, opts, sessionName);
+            break;
+        }
+        case 'clipboard': {
+            const sub = (rest[0] ?? '').toLowerCase();
+            if (sub === 'read') {
+                exitCode = await (0, clipboard_js_1.clipboardRead)(opts, sessionName);
+            }
+            else if (sub === 'write') {
+                const text = rest.slice(1).join(' ');
+                exitCode = await (0, clipboard_js_1.clipboardWrite)(text, opts, sessionName);
+            }
+            else {
+                console.error('Usage: conductor clipboard <read|write> [text]');
+                exitCode = 1;
+            }
+            break;
+        }
+        case 'paste':
+            exitCode = await (0, clipboard_js_1.paste)(opts, sessionName);
+            break;
+        case 'metro': {
+            const sub = (rest[0] ?? '').toLowerCase();
+            const port = argv['port'] !== undefined ? Number(argv['port']) : undefined;
+            const targetIndex = argv['target'] !== undefined ? Number(argv['target']) : undefined;
+            const metroSession = argv['device'] ?? 'default';
+            if (sub === 'stop') {
+                exitCode = await (0, metro_js_1.metroStop)(opts, { port });
+            }
+            else if (sub === 'reload') {
+                exitCode = await (0, metro_js_1.metroReload)(opts, metroSession, { port, targetIndex });
+            }
+            else {
+                console.error('Usage: conductor metro <stop|reload> [--port N] [--target N]');
+                exitCode = 1;
+            }
+            break;
+        }
         default:
             // Should be unreachable — unknown commands are caught before device resolution.
             console.error(`Unknown command: ${command}`);
             console.error('Run `conductor --help` for usage.');
             exitCode = 1;
     }
+    // Flow recording — append a YAML step for action commands that succeeded.
+    if (exitCode === 0 && !NO_DEVICE_COMMANDS.has(command) && command !== 'flow') {
+        try {
+            const active = await (0, flow_recorder_js_1.getActiveRecording)(sessionName);
+            if (active) {
+                const step = (0, flow_recorder_js_1.commandToYamlStep)(command, rest.map(String), argv);
+                if (step)
+                    (0, flow_recorder_js_1.appendStep)(active, step);
+            }
+        }
+        catch {
+            // Recording is best-effort — never fail the command for a bookkeeping issue.
+        }
+    }
     process.exit(exitCode);
 }
 main().catch((err) => {

package/dist/runner.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectFirstDevice = detectFirstDevice;
 exports.getDriver = getDriver;
+exports.prewarmDriver = prewarmDriver;
 exports.runDirect = runDirect;
 exports.spawnCommand = spawnCommand;
 exports.runInlineFlow = runInlineFlow;
@@ -194,6 +195,23 @@ async function getDriver(sessionName = 'default') {
     _driverCache.set(sessionName, driver);
     return driver;
 }
+/**
+ * Eagerly start the device daemon (and its XCTest driver) for `deviceId` so
+ * the runner is already warm by the time the first interaction command runs.
+ *
+ * `start-device` is the natural prewarm point: bringing the driver up there
+ * moves the one-off startup cost off the first `tap-on` / `assert-visible`.
+ * Best-effort — failures are swallowed since a real command will surface any
+ * genuine startup error with a proper message.
+ */
+async function prewarmDriver(deviceId) {
+    try {
+        await (0, client_js_1.startDaemon)(deviceId);
+    }
+    catch {
+        /* best-effort: a later command will report a real failure */
+    }
+}
 /**
  * Execute a function with the driver for the given session.
  * Returns a RunResult for consistent error handling across commands.

package/dist/snapshot-store.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SNAPSHOT_STALE_MS = void 0;
+exports.snapshotFilePath = snapshotFilePath;
+exports.isRefQuery = isRefQuery;
+exports.buildStoredSnapshot = buildStoredSnapshot;
+exports.saveSnapshot = saveSnapshot;
+exports.loadSnapshot = loadSnapshot;
+exports.resolveRef = resolveRef;
+/**
+ * Snapshot-scoped ephemeral element refs.
+ *
+ * `capture-ui` assigns each accessible element a short ref (`@e1`, `@e2`, …) and
+ * persists its resolved screen coordinates here, keyed by session. `tap-on @e3`
+ * then taps the cached point directly — no fuzzy text/id matching.
+ *
+ * Refs are deliberately ephemeral: a stale snapshot warns (it does not hard-fail),
+ * and the agent is expected to re-run `capture-ui` and act on fresh refs.
+ */
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const SNAPSHOTS_DIR = path_1.default.join(os_1.default.homedir(), '.conductor', 'snapshots');
+/** A snapshot older than this is considered stale. */
+exports.SNAPSHOT_STALE_MS = 60000;
+function snapshotFilePath(sessionName = 'default') {
+    return path_1.default.join(SNAPSHOTS_DIR, `${sessionName}.json`);
+}
+/** True when `s` looks like an ephemeral element ref (`@e3`). */
+function isRefQuery(s) {
+    return /^@e\d+$/i.test(s.trim());
+}
+/** Build a `StoredSnapshot` from a freshly built a11y snapshot. */
+function buildStoredSnapshot(entries, device) {
+    const refs = {};
+    for (const e of entries) {
+        refs[e.ref] = {
+            ref: e.ref,
+            centerX: e.frame.x + e.frame.w / 2,
+            centerY: e.frame.y + e.frame.h / 2,
+            frame: e.frame,
+            label: e.label,
+            nodeId: e.nodeId,
+        };
+    }
+    return {
+        version: 1,
+        capturedAt: new Date().toISOString(),
+        deviceId: device.deviceId,
+        platform: device.platform,
+        refs,
+    };
+}
+async function saveSnapshot(sessionName, snapshot) {
+    await promises_1.default.mkdir(SNAPSHOTS_DIR, { recursive: true });
+    await promises_1.default.writeFile(snapshotFilePath(sessionName), JSON.stringify(snapshot, null, 2));
+}
+async function loadSnapshot(sessionName) {
+    try {
+        const data = await promises_1.default.readFile(snapshotFilePath(sessionName), 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve an `@eN` ref against the session's last `capture-ui` snapshot.
+ * Throws when there is no snapshot or the ref is unknown. `staleReason` is
+ * advisory — callers warn but still act, since refs are explicitly ephemeral.
+ */
+function resolveRef(snapshot, ref, ctx) {
+    if (!snapshot) {
+        throw new Error(`no snapshot for this session — run \`conductor capture-ui\` before using ${ref}`);
+    }
+    const norm = ref.trim().toLowerCase();
+    const key = Object.keys(snapshot.refs).find((k) => k.toLowerCase() === norm);
+    if (!key) {
+        const avail = Object.keys(snapshot.refs);
+        const shown = avail.slice(0, 8).join(', ');
+        throw new Error(`${ref} is not in the last snapshot ` +
+            `(${avail.length} ref${avail.length === 1 ? '' : 's'}: ${shown}${avail.length > 8 ? ', …' : ''})`);
+    }
+    let staleReason = null;
+    const ageMs = Date.now() - new Date(snapshot.capturedAt).getTime();
+    if (ageMs > exports.SNAPSHOT_STALE_MS) {
+        staleReason = `snapshot is ${Math.round(ageMs / 1000)}s old`;
+    }
+    else if (ctx?.deviceId && snapshot.deviceId && ctx.deviceId !== snapshot.deviceId) {
+        staleReason = `snapshot was captured on a different device (${snapshot.deviceId})`;
+    }
+    return { entry: snapshot.refs[key], staleReason };
+}

package/package.json

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

package/proto/conductor_android.proto

@@ -12,6 +12,8 @@ service ConductorDriver {
 
   rpc tap(TapRequest) returns (TapResponse) {}
 
+  rpc gesturePath(GesturePathRequest) returns (GesturePathResponse) {}
+
   rpc inputText(InputTextRequest) returns (InputTextResponse) {}
 
   rpc eraseAllText(EraseAllTextRequest) returns (EraseAllTextResponse) {}
@@ -76,6 +78,33 @@ message TapRequest {
 
 message TapResponse {}
 
+// One step in a finger's path.
+//   x, y      pixel coordinates on the device's natural orientation.
+//   dt_ms     delay in milliseconds since the previous step. For the first
+//             step in a path, this is the initial offset before the touch
+//             goes down.
+message GestureStep {
+  double x = 1;
+  double y = 2;
+  uint32 dt_ms = 3;
+}
+
+// A single finger's traced path. Must have at least one step. The first step
+// is the down position; subsequent steps are moves; the finger lifts after
+// the last step.
+message GestureFingerPath {
+  repeated GestureStep steps = 1;
+}
+
+// Multi-finger gesture request. paths.size() == 1 is a single-finger gesture;
+// paths.size() >= 2 dispatches a true multi-touch gesture via
+// UiAutomation.dispatchGesture (API 24+).
+message GesturePathRequest {
+  repeated GestureFingerPath paths = 1;
+}
+
+message GesturePathResponse {}
+
 message InputTextRequest {
   string text = 1;
 }