verikun 0.4.1 → 0.5.0

package/README.md

@@ -1,13 +1,14 @@
 # verikun
 
-Drive a connected Android device/emulator (and, later, iOS simulators) the way
+Drive a connected Android device/emulator or iOS simulator the way
 Puppeteer drives a browser — **tap, type, swipe, screenshot**, and most
 importantly **inspect the UI hierarchy by semantic identifiers** so an AI agent
 can act and then *verify* what happened.
 
-It is a thin, deterministic, zero-runtime-dependency wrapper over `adb` (and
-`xcrun simctl` for iOS) that turns the raw `uiautomator` dump into a compact,
-token-efficient list of meaningful elements addressable by `resource-id`,
+It is a thin, deterministic, zero-runtime-dependency wrapper over `adb` (Android)
+and `idb` + `xcrun simctl` (iOS) that turns the raw `uiautomator` dump (Android)
+or `idb ui describe-all` accessibility tree (iOS) into a compact, token-efficient
+list of meaningful elements addressable by `resource-id` / accessibility id,
 visible text, accessibility label, or class.
 
 ```
@@ -78,7 +79,7 @@ vk screenshot                   # -> ./.verikun/screen.png
 | `swipe --from x,y --to x,y [--duration ms]` | Explicit swipe between two points. |
 | `screenshot [--out path] [--more] [--max px] [--full] [--json]` | Save a PNG (default `./.verikun/screen.png`); prints the path. [Downscaled](#screenshots) to a 700px longest edge by default to save tokens; `--more` bumps detail, `--max px` sets an exact cap, `--full` keeps the original. |
 | `launch <app> [--clear] [--no-restart]` / `stop <app>` | App lifecycle by package id (Android) / bundle id (iOS). `launch` **restarts by default** — it force-stops the app first (a no-op if it isn't running) so a rerun starts fresh instead of resurfacing a still-running instance's current screen; `--no-restart` skips that. `--clear` also wipes the app's local data (login/session, prefs, cache) for a fresh-install start. |
-| `clear <app>` | Wipe the app's locally stored data — login/session, preferences, caches — resetting it to a just-installed state (Android `pm clear`, which also force-stops the app). iOS not supported yet. |
+| `clear <app>` | Wipe the app's locally stored data — login/session, preferences, caches — resetting it to a just-installed state (Android `pm clear`, which also force-stops the app). iOS unsupported: there is no per-app data reset. |
 
 ### Batch
 | Command | Description |
@@ -319,9 +320,10 @@ Failure-evidence captures in test-run reports stay full-resolution for debugging
 ## How it works
 
 ```
-cli.ts ──> drivers/ ──> adb / xcrun        (platform I/O)
+cli.ts ──> drivers/ ──> adb (Android) / idb + simctl (iOS)   (platform I/O)
    │           └─ produces normalized Element[]
    ├─ ui/android-parse.ts   uiautomator XML -> Element[]
+   ├─ ui/ios-parse.ts       idb describe-all JSON -> Element[]
    ├─ ui/selector.ts        @id / text: / desc: / class: matching
    └─ ui/format.ts          compact / tree / json rendering
 ```
@@ -332,30 +334,39 @@ selector, formatting, and command layers operate only on the normalized
 
 - **Android** (`drivers/adb.ts`): `uiautomator dump` for the hierarchy,
   `screencap -p` for screenshots, `input tap/text/swipe/keyevent`, `wm size`.
-- **iOS** (`drivers/simctl.ts`): `screenshot`, `launch`, `stop` work today via
-  `xcrun simctl`. Full interaction and hierarchy inspection are planned via
-  WebDriverAgent — see [iOS roadmap](#ios-roadmap) below.
+- **iOS** (`drivers/ios.ts`): `idb ui describe-all` for the hierarchy,
+  `idb ui tap/text/swipe/key/button` for interaction, `idb describe` for screen
+  size; simulator `screenshot`/`launch`/`stop`/`log` stay on `xcrun simctl` (no
+  idb needed for those). See [iOS setup](#ios-setup) below.
 
 Run artifacts (screenshots, dumps) are written under `./.verikun/` (gitignored).
 
-## iOS roadmap
+## iOS setup
 
-Today `vk --ios` supports **screenshots, launch, and stop** via `xcrun simctl`.
-Tapping, swiping, typing, and `vk ui` hierarchy inspection are not yet wired up.
+`vk --ios` reaches feature parity with Android — `ui`/`find`, `tap`, `text`/`type`,
+`swipe`, `key`, `assert`, `wait`, `screenshot`, `launch`/`stop`, plus `vk batch`,
+`vk ai`, and the JUnit/HTML reports — on both simulators and physical devices.
 
-The planned backend is **[WebDriverAgent](https://github.com/appium/WebDriverAgent)**
-(WDA) — an open-source XCTest HTTP server maintained by the Appium team. It
-requires no Python and works on both simulators and physical devices. Once WDA
-is running, `vk` will drive it over HTTP and the command layer stays unchanged.
+Everything interactive is powered by **[`idb`](https://github.com/facebook/idb)**
+(Facebook's iOS Development Bridge), a CLI shelled one-shot exactly like `adb`, so
+verikun stays zero-runtime-dependency and one-process-per-command. Install it once:
 
-**One-time setup (when this lands):**
-1. Clone WebDriverAgent and open it in Xcode
-2. Set your Apple developer signing team
-3. Build & run on the target device or simulator
-4. `vk --ios tap`, `vk --ios ui`, etc. will work automatically
+```sh
+brew tap facebook/fb && brew install idb-companion   # the companion daemon
+pip install fb-idb                                    # the idb CLI (needs Python 3.6+)
+```
 
-Until then, running any unsupported iOS command prints an explanation and exits
-with code 3.
+Then boot a simulator (Simulator.app, or `xcrun simctl boot <name>`) and check
+your setup with `vk doctor --ios`. `vk --ios tap`, `vk --ios ui`, etc. then work.
+
+**Caveats (documented limitations, not bugs):**
+- `clear` is unsupported — iOS has no per-app data reset (uninstall + reinstall is
+  the manual equivalent, but it removes the app too). Exits 3 with an explanation.
+- `current` returns `(unknown)` — iOS exposes no reliable foreground-app query.
+- `swipe` duration is not honored (idb has no millisecond duration knob).
+- `log` capture is simulator-only (via `log show`); for a physical device use
+  Console.app or `idb log` directly.
+- `--tree` renders flat — idb's accessibility list has no nesting depth.
 
 ## Using it from an AI agent
 

package/dist/cli.js

@@ -149,10 +149,10 @@ function cmdDevices(ctx) {
     }
     try {
         // Only include booted simulators; always include physical devices (they carry a note)
-        allDevices.push(...new drivers_1.SimctlDriver().listDevices().filter((d) => d.state === 'booted' || d.note));
+        allDevices.push(...new drivers_1.IdbDriver().listDevices().filter((d) => d.state === 'booted' || d.note));
     }
     catch (e) {
-        (0, output_1.err)(`devices: simctl backend unavailable (${e.message})`);
+        (0, output_1.err)(`devices: iOS backend unavailable (${e.message})`);
     }
     if ((0, args_1.flagBool)(ctx.flags, 'json')) {
         (0, output_1.json)(allDevices);
@@ -171,18 +171,50 @@ function cmdDevices(ctx) {
 }
 function cmdDoctor(ctx) {
     if (ctx.platform === 'ios') {
-        const r = (0, exec_1.runText)('xcrun', ['simctl', 'list', 'devices', 'booted']);
-        (0, output_1.out)('xcrun: present');
-        (0, output_1.out)(r.stdout.trim() || '(no booted simulators)');
-        (0, output_1.out)('note: iOS screenshots + launch/stop work via simctl; tap/text/swipe/hierarchy need idb.');
-        return 0;
+        try {
+            const r = (0, exec_1.runText)('xcrun', ['simctl', 'list', 'devices', 'booted']);
+            (0, output_1.out)('xcrun: present');
+            (0, output_1.out)(r.stdout.trim() || '(no booted simulators)');
+        }
+        catch (e) {
+            // Not necessarily missing: runText also throws on a spawn timeout or other exec
+            // failure, so surface the real reason rather than always claiming "NOT FOUND".
+            (0, output_1.err)(`xcrun: ${e.message}`);
+            (0, output_1.err)('  (if the Xcode command-line tools are not installed: `xcode-select --install`)');
+            return 3;
+        }
+        // idb (+ its companion) powers everything interactive: ui/tap/text/swipe/key/logs.
+        const idb = process.env.IDB || 'idb';
+        let idbOk = true;
+        try {
+            (0, exec_1.runText)(idb, ['--help']); // idb has no --version; --help confirms the binary runs
+            (0, output_1.out)('idb: present');
+        }
+        catch (e) {
+            (0, output_1.err)(`idb: ${e.message}`);
+            (0, output_1.err)('  needed for ui/tap/text/swipe/key/logs — install: `brew install idb-companion` then `pip install fb-idb`');
+            idbOk = false;
+        }
+        try {
+            (0, exec_1.runText)('idb_companion', ['--help']);
+            (0, output_1.out)('idb_companion: present');
+        }
+        catch (e) {
+            (0, output_1.err)(`idb_companion: ${e.message}`);
+            (0, output_1.err)('  install: `brew install idb-companion`');
+            idbOk = false;
+        }
+        (0, output_1.out)('note: simulator screenshots + launch/stop work via simctl; ui/tap/text/swipe/key/logs use idb.');
+        return idbOk ? 0 : 3;
     }
     const adb = process.env.ADB || 'adb';
     try {
         (0, output_1.out)('adb: ' + (0, exec_1.runText)(adb, ['version']).stdout.split('\n')[0]);
     }
-    catch {
-        (0, output_1.err)('adb: NOT FOUND on PATH');
+    catch (e) {
+        // Not necessarily missing: runText also throws on a spawn timeout or other exec
+        // failure — surface the real reason rather than always claiming "NOT FOUND".
+        (0, output_1.err)(`adb: ${e.message}`);
         return 3;
     }
     const devices = ctx.driver.listDevices();
@@ -1294,5 +1326,7 @@ GLOBAL FLAGS
 EXIT CODES
   0 success · 1 not found / assertion failed / timeout · 2 usage or ambiguous selector · 3 environment error
 
-iOS: screenshots + launch/stop work today via simctl; tap/text/swipe/hierarchy need idb (planned).`;
+iOS (--ios): full parity via idb — ui/tap/text/swipe/key + screenshot/launch/stop.
+  Needs idb (\`brew install idb-companion\` + \`pip install fb-idb\`); see \`vk doctor --ios\`.
+  Caveats: no \`clear\` (no per-app reset), \`current\` is (unknown), device logs are simulator-only.`;
 }

package/dist/drivers/index.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SimctlDriver = exports.AdbDriver = void 0;
+exports.IdbDriver = exports.AdbDriver = void 0;
 exports.getDriver = getDriver;
 const adb_1 = require("./adb");
-const simctl_1 = require("./simctl");
+const ios_1 = require("./ios");
 var adb_2 = require("./adb");
 Object.defineProperty(exports, "AdbDriver", { enumerable: true, get: function () { return adb_2.AdbDriver; } });
-var simctl_2 = require("./simctl");
-Object.defineProperty(exports, "SimctlDriver", { enumerable: true, get: function () { return simctl_2.SimctlDriver; } });
+var ios_2 = require("./ios");
+Object.defineProperty(exports, "IdbDriver", { enumerable: true, get: function () { return ios_2.IdbDriver; } });
 function getDriver(platform, device) {
-    return platform === 'ios' ? new simctl_1.SimctlDriver(device) : new adb_1.AdbDriver(device);
+    return platform === 'ios' ? new ios_1.IdbDriver(device) : new adb_1.AdbDriver(device);
 }

package/dist/drivers/ios.js

@@ -0,0 +1,351 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdbDriver = void 0;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const errors_1 = require("../errors");
+const exec_1 = require("../exec");
+const ios_parse_1 = require("../ui/ios-parse");
+// iOS driver. `xcrun simctl` / `devicectl` cover device discovery and — on a
+// simulator — screenshots, app lifecycle, and logs (no extra install needed).
+// Everything interactive (UI hierarchy, tap, type, swipe, keys, screen size) and
+// all interaction on physical devices go through Facebook's `idb`, a CLI shelled
+// one-shot exactly like `adb` — so this driver keeps verikun's zero-runtime-dep,
+// process-per-command shape. Install: `brew install idb-companion` + `pip install
+// fb-idb` (see `vk doctor --ios`).
+//
+// Coordinates are in idb's point space: `idb ui describe-all` frames, `idb ui tap`,
+// and `idb describe` screen_dimensions all agree, so element.center taps land.
+// (simctl screenshots are pixels = points × scale — they are for viewing only and
+// never feed back into a tap.)
+const XCRUN = 'xcrun';
+const IDB = process.env.IDB || 'idb';
+const DEFAULT_LOG_LINES = 200;
+const DEFAULT_LOG_WINDOW = '5m';
+// Named keys -> USB-HID keyboard usage IDs, handed to `idb ui key <code>`. Numeric
+// codes are accepted directly. Names mirror the adb driver so cross-platform
+// batch/ai scripts share one vocabulary.
+const IOS_KEYCODES = {
+    enter: 40,
+    return: 40,
+    escape: 41,
+    esc: 41,
+    del: 42,
+    delete: 42,
+    backspace: 42,
+    tab: 43,
+    space: 44,
+    forward_del: 76,
+    move_home: 74,
+    move_end: 77,
+    page_up: 75,
+    page_down: 78,
+    right: 79,
+    dpad_right: 79,
+    left: 80,
+    dpad_left: 80,
+    down: 81,
+    dpad_down: 81,
+    up: 82,
+    dpad_up: 82,
+};
+// Named hardware buttons -> `idb ui button <NAME>` (the only accepted set).
+const IOS_BUTTONS = {
+    home: 'HOME',
+    lock: 'LOCK',
+    power: 'LOCK',
+    side_button: 'SIDE_BUTTON',
+    siri: 'SIRI',
+    apple_pay: 'APPLE_PAY',
+};
+function listPhysicalDevices() {
+    const r = (0, exec_1.runText)(XCRUN, ['devicectl', 'list', 'devices']);
+    if (r.code !== 0)
+        return [];
+    const lines = r.stdout.split('\n');
+    const headerIdx = lines.findIndex((l) => l.includes('Identifier'));
+    if (headerIdx < 0)
+        return [];
+    const header = lines[headerIdx];
+    const nameCol = header.indexOf('Name');
+    const hostCol = header.indexOf('Hostname');
+    const idCol = header.indexOf('Identifier');
+    const stateCol = header.indexOf('State');
+    const modelCol = header.indexOf('Model');
+    const devices = [];
+    for (const line of lines.slice(headerIdx + 2)) {
+        if (!line.trim() || line.startsWith('-'))
+            continue;
+        const identifier = line.slice(idCol, stateCol).trim();
+        const state = line.slice(stateCol, modelCol).trim();
+        const name = line.slice(nameCol, hostCol).trim();
+        const model = line.slice(modelCol).trim();
+        if (!identifier)
+            continue;
+        const productMatch = model.match(/\(([^)]+)\)$/);
+        devices.push({
+            serial: identifier,
+            state,
+            model: name,
+            product: productMatch?.[1],
+            platform: 'ios',
+            note: 'physical — via idb (Developer mode + idb_companion; logs limited)',
+        });
+    }
+    return devices;
+}
+class IdbDriver {
+    platform = 'ios';
+    requested;
+    cachedSerial;
+    cachedIsSim;
+    constructor(device) {
+        // 'booted' is a simctl-only alias idb can't address, so treat it as "auto-resolve".
+        this.requested = device && device !== 'booted' ? device : undefined;
+    }
+    /** All available simulators (booted or shutdown) via simctl. Tolerates odd output. */
+    simulators() {
+        const devices = [];
+        const { stdout } = (0, exec_1.runText)(XCRUN, ['simctl', 'list', 'devices', 'available', '--json']);
+        try {
+            const data = JSON.parse(stdout);
+            for (const [runtime, list] of Object.entries(data.devices)) {
+                for (const d of list) {
+                    devices.push({
+                        serial: d.udid,
+                        state: d.state.toLowerCase(),
+                        model: d.name,
+                        product: runtime.split('.').pop(),
+                        platform: 'ios',
+                    });
+                }
+            }
+        }
+        catch {
+            /* tolerate unexpected simctl output */
+        }
+        return devices;
+    }
+    listDevices() {
+        return [...this.simulators(), ...listPhysicalDevices()];
+    }
+    resolvedSerial() {
+        if (this.cachedSerial)
+            return this.cachedSerial;
+        const sims = this.simulators();
+        const simUdids = new Set(sims.map((d) => d.serial));
+        if (this.requested) {
+            this.cachedSerial = this.requested;
+            this.cachedIsSim = simUdids.has(this.requested);
+            return this.cachedSerial;
+        }
+        // No explicit device: a booted simulator is the first-class, unambiguously
+        // drivable target, so prefer it. Only weigh physical devices when no simulator
+        // is booted — and only genuinely "connected" ones (devicectl also lists paired-
+        // but-idle devices as "available (paired)", which must not count as active).
+        const bootedSims = sims.filter((d) => d.state === 'booted');
+        const candidates = bootedSims.length > 0 ? bootedSims : listPhysicalDevices().filter((d) => /connected/i.test(d.state));
+        if (candidates.length === 0) {
+            throw new errors_1.CliError('No booted iOS simulator or connected device. Boot one (Simulator.app / `xcrun simctl boot`), then `verikun devices`.', 3);
+        }
+        if (candidates.length > 1) {
+            const list = candidates.map((d) => '  ' + d.serial + (d.model ? ` (${d.model})` : '')).join('\n');
+            throw new errors_1.CliError(`Multiple iOS targets; pass --device <udid> (or set VERIKUN_DEVICE):\n${list}`, 2);
+        }
+        this.cachedSerial = candidates[0].serial;
+        this.cachedIsSim = simUdids.has(candidates[0].serial);
+        return this.cachedSerial;
+    }
+    udid() {
+        return this.resolvedSerial();
+    }
+    isSimulator() {
+        this.resolvedSerial();
+        return this.cachedIsSim === true;
+    }
+    /** Run an idb subcommand against the resolved target, returning stdout. */
+    idbText(args, opts) {
+        const r = (0, exec_1.runText)(IDB, [...args, '--udid', this.udid()], opts);
+        if (r.code !== 0) {
+            throw new errors_1.CliError(`idb ${args.join(' ')} failed: ${r.stderr.trim() || `exit code ${r.code}`}`, 3);
+        }
+        return r.stdout;
+    }
+    getElements(opts = {}) {
+        // `idb ui describe-all` prints the accessibility tree as JSON (array or NDJSON);
+        // parseIosHierarchy handles either.
+        return (0, ios_parse_1.parseIosHierarchy)(this.idbText(['ui', 'describe-all'], { timeout: 15000 }), opts);
+    }
+    screenshot() {
+        const tmp = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `verikun-ios-${process.pid}.png`);
+        if (this.isSimulator()) {
+            const r = (0, exec_1.runText)(XCRUN, ['simctl', 'io', this.udid(), 'screenshot', tmp]);
+            if (r.code !== 0)
+                throw new errors_1.CliError(`simctl screenshot failed: ${r.stderr.trim()}`, 3);
+        }
+        else {
+            this.idbText(['screenshot', tmp]);
+        }
+        let buf;
+        try {
+            buf = (0, node_fs_1.readFileSync)(tmp);
+        }
+        catch (e) {
+            throw new errors_1.CliError(`Could not read iOS screenshot: ${e.message}`, 3);
+        }
+        finally {
+            try {
+                (0, node_fs_1.unlinkSync)(tmp);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+        if (buf.length < 8 || buf[0] !== 0x89 || buf[1] !== 0x50) {
+            throw new errors_1.CliError('iOS screenshot was not a PNG.', 3);
+        }
+        return buf;
+    }
+    screenSize() {
+        // Prefer idb's target description (points, same space as tap/swipe).
+        try {
+            const d = JSON.parse(this.idbText(['describe', '--json']));
+            const w = Number(d.screen_dimensions?.width);
+            const h = Number(d.screen_dimensions?.height);
+            if (w > 0 && h > 0)
+                return { width: w, height: h };
+        }
+        catch {
+            /* fall through to deriving from the hierarchy */
+        }
+        // Fallback: the extent of the on-screen hierarchy (the window/app root frame).
+        let width = 0;
+        let height = 0;
+        for (const el of (0, ios_parse_1.parseIosHierarchy)(this.idbText(['ui', 'describe-all']), { all: true })) {
+            width = Math.max(width, el.bounds.x2);
+            height = Math.max(height, el.bounds.y2);
+        }
+        if (width > 0 && height > 0)
+            return { width, height };
+        throw new errors_1.CliError('Could not determine iOS screen size via idb.', 3);
+    }
+    tap(x, y) {
+        this.idbText(['ui', 'tap', String(Math.round(x)), String(Math.round(y))]);
+    }
+    swipe(x1, y1, x2, y2, _durationMs) {
+        // idb controls swipe speed via `--delta` (px per step), not a ms duration, and
+        // the flag's availability varies by version — so we pass coordinates only for
+        // maximum compatibility. durationMs is not honored (a documented iOS gap).
+        this.idbText([
+            'ui',
+            'swipe',
+            String(Math.round(x1)),
+            String(Math.round(y1)),
+            String(Math.round(x2)),
+            String(Math.round(y2)),
+        ]);
+    }
+    inputText(text) {
+        if (!text)
+            return;
+        // Passed as a single argv (spawnSync, no host shell), so no device-shell escaping
+        // is needed — idb synthesizes the keystrokes itself.
+        this.idbText(['ui', 'text', text]);
+    }
+    pressKey(name) {
+        const key = name.toLowerCase();
+        const button = IOS_BUTTONS[key];
+        if (button) {
+            this.idbText(['ui', 'button', button]);
+            return;
+        }
+        const code = IOS_KEYCODES[key] ?? (/^\d+$/.test(name) ? Number(name) : undefined);
+        if (code === undefined) {
+            const hint = key === 'back' ? ' (iOS has no hardware Back — tap the on-screen back control instead)' : '';
+            throw new errors_1.CliError(`Unknown iOS key '${name}'${hint}. Known keys: ${Object.keys(IOS_KEYCODES).join(', ')}; ` +
+                `hardware buttons: ${Object.keys(IOS_BUTTONS).join(', ')}; or a numeric HID keycode.`, 2);
+        }
+        this.idbText(['ui', 'key', String(code)]);
+    }
+    launch(appId) {
+        if (this.isSimulator()) {
+            const r = (0, exec_1.runText)(XCRUN, ['simctl', 'launch', this.udid(), appId]);
+            if (r.code !== 0)
+                throw new errors_1.CliError(`simctl launch failed: ${r.stderr.trim()}`, 3);
+        }
+        else {
+            this.idbText(['launch', appId]);
+        }
+    }
+    stop(appId) {
+        // Best-effort force-stop. `terminate` reports a non-zero exit when the app simply
+        // wasn't running; that's a no-op success for us (parity with adb `am force-stop`,
+        // which never fails), so we don't surface it — otherwise `launch`'s default
+        // restart (stop-then-launch) would break whenever the app is already closed.
+        try {
+            if (this.isSimulator()) {
+                (0, exec_1.runText)(XCRUN, ['simctl', 'terminate', this.udid(), appId]);
+            }
+            else {
+                (0, exec_1.runText)(IDB, ['terminate', appId, '--udid', this.udid()]);
+            }
+        }
+        catch {
+            /* tool missing / target gone — nothing to stop */
+        }
+    }
+    clearApp(appId) {
+        // Honest degrade (no clean per-app data reset on iOS): don't silently uninstall.
+        throw new errors_1.CliError(`iOS app-data clearing is not supported (requested for '${appId}').\n` +
+            'iOS has no per-app data reset; the manual equivalent is uninstall + reinstall ' +
+            '(`xcrun simctl uninstall <udid> <bundleId>`), which removes the app too.', 3);
+    }
+    currentApp() {
+        // iOS exposes no reliable foreground-app query; degrade like adb's fallback.
+        return '(unknown)';
+    }
+    getLogs(opts = {}) {
+        if (!this.isSimulator()) {
+            throw new errors_1.CliError('iOS physical-device log capture is not supported (simulator logs work via `log show`).\n' +
+                'Use Console.app or `idb log` directly for a connected device.', 3);
+        }
+        // `log show` on the whole store is huge, so ALWAYS bound it: a session marker
+        // (--start) or a recent window (--last). Args go through spawnSync (no shell),
+        // so the marker/predicate need no escaping and can't inject.
+        const args = ['simctl', 'spawn', this.udid(), 'log', 'show', '--style', 'syslog'];
+        if (opts.since) {
+            args.push('--start', opts.since);
+        }
+        else {
+            args.push('--last', DEFAULT_LOG_WINDOW);
+        }
+        if (opts.appId) {
+            // Best-effort process scope: the simulator process name is usually the bundle's
+            // last component. A loose predicate is better than none for a crash trace.
+            const proc = opts.appId.split('.').pop() || opts.appId;
+            args.push('--predicate', `process CONTAINS "${proc}"`);
+        }
+        const out = (0, exec_1.runText)(XCRUN, args, { timeout: 20000 }).stdout;
+        if (opts.since)
+            return out; // the whole session window
+        // No explicit since → keep the last N lines, like adb's `logcat -t N`.
+        const n = opts.lines && opts.lines > 0 ? Math.floor(opts.lines) : DEFAULT_LOG_LINES;
+        const lines = out.split('\n');
+        return lines.slice(Math.max(0, lines.length - n)).join('\n');
+    }
+    deviceTime() {
+        // Simulator shares the host clock; sample it in `log show --start` format so the
+        // run's log window (run.ts) can anchor on it. Physical devices → '' (no marker),
+        // which disables windowing gracefully. Never throws (called at run start).
+        try {
+            if (!this.isSimulator())
+                return '';
+            return (0, exec_1.runText)(XCRUN, ['simctl', 'spawn', this.udid(), 'date', '+%Y-%m-%d %H:%M:%S']).stdout.trim();
+        }
+        catch {
+            return '';
+        }
+    }
+}
+exports.IdbDriver = IdbDriver;

package/dist/ui/ios-parse.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInteresting = isInteresting;
+exports.parseIosHierarchy = parseIosHierarchy;
+// XCUIElementType names (idb `type`) that are meaningful tap targets — used to
+// derive `clickable`, which iOS accessibility does not expose as a flag.
+const TAPPABLE_TYPES = new Set([
+    'Button', 'Cell', 'Link', 'MenuItem', 'MenuButton', 'PopUpButton', 'CheckBox',
+    'RadioButton', 'Switch', 'Toggle', 'SegmentedControl', 'Tab', 'Key', 'Stepper',
+    'Icon', 'SearchField', 'TextField', 'SecureTextField', 'DatePicker',
+]);
+const SCROLLABLE_TYPES = new Set(['ScrollView', 'Table', 'TableView', 'CollectionView', 'WebView']);
+const CHECKABLE_TYPES = new Set(['Switch', 'Toggle', 'CheckBox', 'RadioButton']);
+const TEXT_INPUT_TYPES = new Set(['TextField', 'SecureTextField', 'SearchField', 'TextView']);
+function str(v) {
+    return typeof v === 'string' ? v : v == null ? '' : String(v);
+}
+function isTrue(v) {
+    if (v === true)
+        return true;
+    const s = str(v).trim().toLowerCase();
+    return s === '1' || s === 'true' || s === 'on' || s === 'yes';
+}
+function stripAx(role) {
+    return role.startsWith('AX') ? role.slice(2) : role;
+}
+function parseFrame(raw) {
+    const f = raw.frame;
+    if (f &&
+        typeof f.x === 'number' &&
+        typeof f.y === 'number' &&
+        typeof f.width === 'number' &&
+        typeof f.height === 'number') {
+        return {
+            x1: Math.round(f.x),
+            y1: Math.round(f.y),
+            x2: Math.round(f.x + f.width),
+            y2: Math.round(f.y + f.height),
+        };
+    }
+    // Fallback: AXFrame is a string like "{{x, y}, {w, h}}".
+    const m = /\{\{\s*(-?[\d.]+),\s*(-?[\d.]+)\s*\},\s*\{\s*(-?[\d.]+),\s*(-?[\d.]+)\s*\}\}/.exec(str(raw.AXFrame));
+    if (m) {
+        const x = parseFloat(m[1]);
+        const y = parseFloat(m[2]);
+        const w = parseFloat(m[3]);
+        const h = parseFloat(m[4]);
+        return { x1: Math.round(x), y1: Math.round(y), x2: Math.round(x + w), y2: Math.round(y + h) };
+    }
+    return { x1: 0, y1: 0, x2: 0, y2: 0 };
+}
+function buildElement(raw) {
+    const bounds = parseFrame(raw);
+    const id = str(raw.AXUniqueId);
+    const type = str(raw.type) || stripAx(str(raw.role)) || 'Other';
+    const cls = str(raw.role) || type;
+    // iOS conflates "visible text" and "content-desc" into accessibilityLabel; a
+    // filled text field surfaces its contents as AXValue. Prefer the label, then a
+    // title, then the value, as the identifying text. `help` (accessibilityHint) is
+    // the closest analog to Android's content-desc, so it becomes `desc`.
+    const text = str(raw.AXLabel) || str(raw.title) || str(raw.AXValue);
+    const checkable = CHECKABLE_TYPES.has(type);
+    const clickable = TAPPABLE_TYPES.has(type) || (Array.isArray(raw.custom_actions) && raw.custom_actions.length > 0);
+    return {
+        index: -1,
+        class: cls,
+        type,
+        id,
+        idShort: id.includes('/') ? id.slice(id.lastIndexOf('/') + 1) : id,
+        text,
+        desc: str(raw.help),
+        bounds,
+        center: {
+            x: Math.floor((bounds.x1 + bounds.x2) / 2),
+            y: Math.floor((bounds.y1 + bounds.y2) / 2),
+        },
+        depth: 0,
+        clickable,
+        longClickable: false,
+        checkable,
+        checked: checkable && isTrue(raw.AXValue),
+        focusable: false,
+        focused: false,
+        scrollable: SCROLLABLE_TYPES.has(type),
+        enabled: raw.enabled === undefined ? true : isTrue(raw.enabled),
+        selected: false,
+        password: type === 'SecureTextField',
+    };
+}
+/**
+ * "Interesting" = something an agent can act on or read. Mirrors the Android
+ * filter's intent (drop pure layout containers) with iOS predicates.
+ */
+function isInteresting(el) {
+    const w = el.bounds.x2 - el.bounds.x1;
+    const h = el.bounds.y2 - el.bounds.y1;
+    if (w <= 0 || h <= 0)
+        return false; // not visible / not tappable
+    if (el.text.trim())
+        return true;
+    if (el.desc.trim())
+        return true;
+    if (el.id)
+        return true;
+    if (el.clickable || el.checkable || el.scrollable)
+        return true;
+    if (TEXT_INPUT_TYPES.has(el.type))
+        return true;
+    return false;
+}
+function parseIosHierarchy(jsonText, opts = {}) {
+    const all = parseIdbJson(jsonText).map(buildElement);
+    const result = opts.all ? all : all.filter(isInteresting);
+    result.forEach((el, idx) => {
+        el.index = idx;
+    });
+    return result;
+}
+/** idb `--json` emits a JSON array; tolerate NDJSON (one object per line) too. */
+function parseIdbJson(text) {
+    const t = text.trim();
+    if (!t)
+        return [];
+    try {
+        const parsed = JSON.parse(t);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed && typeof parsed === 'object')
+            return [parsed];
+    }
+    catch {
+        /* fall through to NDJSON */
+    }
+    const out = [];
+    for (const line of t.split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        try {
+            const o = JSON.parse(s);
+            if (o && typeof o === 'object')
+                out.push(o);
+        }
+        catch {
+            /* skip a malformed line rather than fail the whole dump */
+        }
+    }
+    return out;
+}

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.4.1';
+exports.VERSION = '0.5.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "verikun",
-  "version": "0.4.1",
-  "description": "Drive Android emulators/devices (and later iOS simulators) for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
+  "version": "0.5.0",
+  "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",
     "adb",

package/dist/drivers/simctl.js

@@ -1,156 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SimctlDriver = void 0;
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-const node_fs_1 = require("node:fs");
-const errors_1 = require("../errors");
-const exec_1 = require("../exec");
-const XCRUN = 'xcrun';
-function listPhysicalDevices() {
-    const r = (0, exec_1.runText)(XCRUN, ['devicectl', 'list', 'devices']);
-    if (r.code !== 0)
-        return [];
-    const lines = r.stdout.split('\n');
-    const headerIdx = lines.findIndex((l) => l.includes('Identifier'));
-    if (headerIdx < 0)
-        return [];
-    const header = lines[headerIdx];
-    const nameCol = header.indexOf('Name');
-    const hostCol = header.indexOf('Hostname');
-    const idCol = header.indexOf('Identifier');
-    const stateCol = header.indexOf('State');
-    const modelCol = header.indexOf('Model');
-    const devices = [];
-    for (const line of lines.slice(headerIdx + 2)) {
-        if (!line.trim() || line.startsWith('-'))
-            continue;
-        const identifier = line.slice(idCol, stateCol).trim();
-        const state = line.slice(stateCol, modelCol).trim();
-        const name = line.slice(nameCol, hostCol).trim();
-        const model = line.slice(modelCol).trim();
-        if (!identifier)
-            continue;
-        const productMatch = model.match(/\(([^)]+)\)$/);
-        devices.push({
-            serial: identifier,
-            state,
-            model: name,
-            product: productMatch?.[1],
-            platform: 'ios',
-            note: 'physical — screenshot only, tap/ui not supported',
-        });
-    }
-    return devices;
-}
-// iOS support is intentionally partial. `simctl` covers screenshots, launch,
-// and stop. Full interaction (tap, swipe, type) and the accessibility hierarchy
-// require WebDriverAgent (https://github.com/appium/WebDriverAgent) — the
-// planned next step. WDA is an open-source XCTest HTTP server: build it once
-// in Xcode, sign it with your Apple developer certificate, and run it on the
-// target device or simulator. No Python required; works on both simulators and
-// physical devices. The Driver seam is already in place so the command layer
-// won't change when WDA support is added.
-function notSupported(feature) {
-    throw new errors_1.CliError(`iOS ${feature} is not supported yet.\n` +
-        'Screenshots, launch, and stop work today via xcrun simctl.\n' +
-        'Full interaction (tap / swipe / type) and UI hierarchy inspection are planned\n' +
-        'via WebDriverAgent — build it once in Xcode and vk will drive it over HTTP.\n' +
-        'See: https://github.com/appium/WebDriverAgent', 3);
-}
-class SimctlDriver {
-    platform = 'ios';
-    udid;
-    constructor(device) {
-        this.udid = device || 'booted';
-    }
-    listDevices() {
-        const devices = [];
-        // Simulators via simctl
-        const { stdout } = (0, exec_1.runText)(XCRUN, ['simctl', 'list', 'devices', 'available', '--json']);
-        try {
-            const data = JSON.parse(stdout);
-            for (const [runtime, list] of Object.entries(data.devices)) {
-                for (const d of list) {
-                    devices.push({
-                        serial: d.udid,
-                        state: d.state.toLowerCase(),
-                        model: d.name,
-                        product: runtime.split('.').pop(),
-                        platform: 'ios',
-                    });
-                }
-            }
-        }
-        catch {
-            /* tolerate unexpected simctl output */
-        }
-        // Physical devices via devicectl (Xcode 15+)
-        devices.push(...listPhysicalDevices());
-        return devices;
-    }
-    resolvedSerial() {
-        return this.udid;
-    }
-    screenshot() {
-        const tmp = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `verikun-ios-${process.pid}.png`);
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'io', this.udid, 'screenshot', tmp]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl screenshot failed: ${r.stderr.trim()}`, 3);
-        const buf = (0, node_fs_1.readFileSync)(tmp);
-        try {
-            (0, node_fs_1.unlinkSync)(tmp);
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        return buf;
-    }
-    launch(appId) {
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'launch', this.udid, appId]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl launch failed: ${r.stderr.trim()}`, 3);
-    }
-    stop(appId) {
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'terminate', this.udid, appId]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl terminate failed: ${r.stderr.trim()}`, 3);
-    }
-    clearApp(appId) {
-        // simctl has no per-app data reset. The manual equivalent is to uninstall and
-        // reinstall, which also removes the app itself — so we don't do it implicitly.
-        throw new errors_1.CliError(`iOS app-data clearing is not supported yet (requested for '${appId}').\n` +
-            'simctl has no per-app data reset; uninstall + reinstall ' +
-            '(`xcrun simctl uninstall <udid> <bundleId>`) is the manual equivalent, but it removes the app too.', 3);
-    }
-    getElements() {
-        return notSupported('hierarchy inspection');
-    }
-    screenSize() {
-        return notSupported('screen size');
-    }
-    tap() {
-        notSupported('tap');
-    }
-    swipe() {
-        notSupported('swipe');
-    }
-    inputText() {
-        notSupported('text input');
-    }
-    pressKey() {
-        notSupported('key events');
-    }
-    currentApp() {
-        return notSupported('current app');
-    }
-    getLogs() {
-        // Eventually: `xcrun simctl spawn <udid> log show` (simulators) / devicectl
-        // (physical). Heavier (predicate language, large output) — deferred with WDA.
-        return notSupported('log capture');
-    }
-    deviceTime() {
-        return ''; // no log window to anchor while iOS log capture is unsupported
-    }
-}
-exports.SimctlDriver = SimctlDriver;