@beeos-ai/device-mcp-server 0.2.3

package/dist/backends/mac.js

@@ -0,0 +1,881 @@
+/**
+ * MacOsBackend — concrete `SandboxBackend` driving a real macOS host.
+ *
+ * Best-practice topology after researching the field (Anthropic Computer Use,
+ * OpenInterpreter os-mode, mac-control skill, the Python reference at
+ * `deviceagent_research/.../mcp_tools/backend_macos.py`, etc.):
+ *
+ *   - **Pointer** (click / move / drag / scroll / double / right / longPress):
+ *     `cliclick` (Homebrew, optional) preferred when on `PATH`; falls back to
+ *     `osascript` System Events when absent. cliclick is significantly more
+ *     reliable for coordinate-based mouse synthesis on modern (sandboxed) apps.
+ *   - **Keyboard** (typeText / pressKey / hotkey): `osascript` System Events.
+ *     Handles unicode, modifier chords, and raw key codes. No extra dependency.
+ *   - **Screenshot**: `screencapture -x -t png <tmpfile>`, read back into
+ *     memory, unlink — `screencapture` does NOT support stdout output despite
+ *     `-o -` / `-` folklore, so we round-trip through a per-call temp file.
+ *     `sharp` then resizes to the display's logical-point resolution so click
+ *     coords and screenshot pixels share one coordinate system (Retina-correct).
+ *   - **Screen size**: `system_profiler SPDisplaysDataType -json` parsed at
+ *     `connect()` time, cached for the process lifetime.
+ *   - **Launch app**: `open -a NAME` for human names, `open -b BUNDLE_ID` for
+ *     reverse-DNS bundle ids, `open <path>` for `.app`/`.dmg`/`.pkg`.
+ *   - **executeCommand**: `/bin/sh -c body`. Same shape as the Android backend.
+ *   - **file_read / write / list_directory**: Node `fs/promises` direct (we
+ *     run *on* the host).
+ *   - **Mobile verb aliasing** (matches reference convention): `tap → click`,
+ *     `swipe → drag`, `long_press → cliclick dd + sleep + du`. `back` is
+ *     unsupported on macOS, `home` is mapped to F11 (Mission Control "show
+ *     desktop").
+ *
+ * **Permissions**: the host process MUST hold Accessibility permission
+ * (System Settings → Privacy & Security → Accessibility). Without it macOS
+ * silently drops every synthetic input event. There is no programmatic
+ * bypass — we surface a `DeviceError("permission_required")` when cliclick /
+ * osascript exit non-zero so the operator can grant the permission.
+ *
+ * **Testability**: the constructor accepts an injected `runner` (an
+ * `execFile`-like async callable) and an `fs` shim. Defaults bind to a
+ * spawn-backed runner and `node:fs/promises`. Unit tests pass spy runners
+ * so the suite runs identically on Linux CI without any real shell calls.
+ */
+import { spawn } from "node:child_process";
+import * as fsPromises from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import sharp from "sharp";
+import { COMMON_TOOLS, DESKTOP_TOOLS, DeviceError, } from "@beeos-ai/device-common";
+import { BaseSandboxBackend, } from "./base.js";
+import { parsePngDimensions } from "../util/image-dim.js";
+/**
+ * macOS tool catalogue.
+ *
+ * Common tools minus `install_apk` (mac has no APK story) plus the full
+ * desktop catalogue. Mobile-only tools (`tap`, `swipe`, `back`, `home`,
+ * `ui_dump`) are intentionally absent — they have no macOS analogue and
+ * the OS-family split keeps prompts platform-faithful instead of
+ * relying on internal aliasing (`tap → click`, `swipe → drag`).
+ */
+const MACOS_TOOLS = new Set([
+    ...COMMON_TOOLS.filter((t) => t !== "install_apk"),
+    ...DESKTOP_TOOLS,
+]);
+/* ----------------------------------------------------------------------- */
+/* Embedded AppleScript / JXA snippets                                      */
+/* ----------------------------------------------------------------------- */
+/*
+ * IMPORTANT: System Events' `click at {x, y}` AppleScript syntax does NOT
+ * actually work as a synthetic-input primitive on modern macOS (10.14+) — it
+ * raises a -2741 syntax error or silently no-ops depending on the build. The
+ * reliable, dependency-free fallback is **JXA + Quartz CGEvent**, which every
+ * production computer-use agent on macOS uses (pyautogui, mac-control,
+ * Anthropic Computer Use, etc.). Keyboard verbs (`keystroke`, `key code`)
+ * remain on AppleScript because that path *does* work and avoids JXA's
+ * keyboard-mapping subtleties.
+ */
+/** JXA — synthetic mouse click via Quartz CGEvent. Used as cliclick fallback. */
+const _JXA_CLICK = `ObjC.import('CoreGraphics');
+function run(argv) {
+  var x = parseInt(argv[0], 10);
+  var y = parseInt(argv[1], 10);
+  var btn = argv[2] || 'left';
+  var clicks = parseInt(argv[3], 10) || 1;
+  var isRight = (btn === 'right');
+  var downType = isRight ? 4 : 1;
+  var upType = isRight ? 5 : 2;
+  var button = isRight ? 1 : 0;
+  for (var i = 0; i < clicks; i++) {
+    var p = $.CGPointMake(x, y);
+    var ed = $.CGEventCreateMouseEvent($(), downType, p, button);
+    $.CGEventPost(0, ed);
+    var eu = $.CGEventCreateMouseEvent($(), upType, p, button);
+    $.CGEventPost(0, eu);
+    delay(0.05);
+  }
+  return 'ok';
+}`;
+/** JXA — synthetic mouse drag (down → move → up). Used as cliclick fallback. */
+const _JXA_DRAG = `ObjC.import('CoreGraphics');
+function run(argv) {
+  var x1 = parseInt(argv[0], 10);
+  var y1 = parseInt(argv[1], 10);
+  var x2 = parseInt(argv[2], 10);
+  var y2 = parseInt(argv[3], 10);
+  var p1 = $.CGPointMake(x1, y1);
+  var p2 = $.CGPointMake(x2, y2);
+  var ed = $.CGEventCreateMouseEvent($(), 1, p1, 0);
+  $.CGEventPost(0, ed);
+  delay(0.05);
+  var em = $.CGEventCreateMouseEvent($(), 6, p2, 0);
+  $.CGEventPost(0, em);
+  delay(0.05);
+  var eu = $.CGEventCreateMouseEvent($(), 2, p2, 0);
+  $.CGEventPost(0, eu);
+  return 'ok';
+}`;
+/**
+ * JXA — synthetic mouse-wheel scroll. cliclick doesn't have a scroll
+ * primitive, so we ALWAYS use this script for scroll regardless of cliclick
+ * presence.
+ */
+const _JXA_SCROLL = `ObjC.import('CoreGraphics');
+function run(argv) {
+  var dx = parseInt(argv[0], 10) || 0;
+  var dy = parseInt(argv[1], 10) || 0;
+  var e;
+  if (dx === 0) {
+    e = $.CGEventCreateScrollWheelEvent($(), 1, 1, dy);
+  } else {
+    e = $.CGEventCreateScrollWheelEvent($(), 1, 2, dy, dx);
+  }
+  $.CGEventPost(0, e);
+  return 'ok';
+}`;
+/** JXA — synthetic mouse-move (no click). Used as cliclick fallback. */
+const _JXA_MOVE = `ObjC.import('CoreGraphics');
+function run(argv) {
+  var x = parseInt(argv[0], 10);
+  var y = parseInt(argv[1], 10);
+  var p = $.CGPointMake(x, y);
+  var e = $.CGEventCreateMouseEvent($(), 5, p, 0);
+  $.CGEventPost(0, e);
+  return 'ok';
+}`;
+const _OSA_TYPE = `on run argv
+  set t to item 1 of argv as text
+  tell application "System Events" to keystroke t
+end run`;
+const _OSA_KEY = `on run argv
+  set k to item 1 of argv as text
+  tell application "System Events" to key code (k as integer)
+end run`;
+const _OSA_HOTKEY = `on run argv
+  -- argv: keycode, modlist (comma-separated of: command, control, option, shift)
+  set kc to (item 1 of argv) as integer
+  set modlist to item 2 of argv as text
+  set mods to {}
+  if modlist contains "command" then set end of mods to command down
+  if modlist contains "control" then set end of mods to control down
+  if modlist contains "option"  then set end of mods to option down
+  if modlist contains "shift"   then set end of mods to shift down
+  tell application "System Events" to key code kc using mods
+end run`;
+const _OSA_HOME = `tell application "System Events" to key code 103 using {fn down}`;
+/**
+ * AppleScript key code map for common keys.
+ * Reference: https://eastmanreference.com/complete-list-of-applescript-key-codes
+ *
+ * Lookups are case-insensitive; we also accept a few aliases people commonly
+ * type (Enter ↔ Return, BackSpace ↔ Delete, Esc ↔ Escape).
+ */
+const _KEY_CODES = {
+    return: 36,
+    enter: 36,
+    tab: 48,
+    space: 49,
+    delete: 51,
+    backspace: 51,
+    escape: 53,
+    esc: 53,
+    up: 126,
+    down: 125,
+    left: 123,
+    right: 124,
+    home: 115,
+    end: 119,
+    pageup: 116,
+    pagedown: 121,
+    // Single letters/digits map to the same code as the lowercase character.
+    // Common ASCII letter codes:
+    a: 0,
+    s: 1,
+    d: 2,
+    f: 3,
+    h: 4,
+    g: 5,
+    z: 6,
+    x: 7,
+    c: 8,
+    v: 9,
+    b: 11,
+    q: 12,
+    w: 13,
+    e: 14,
+    r: 15,
+    y: 16,
+    t: 17,
+    o: 31,
+    u: 32,
+    i: 34,
+    p: 35,
+    l: 37,
+    j: 38,
+    k: 40,
+    n: 45,
+    m: 46,
+    // Function keys
+    f1: 122,
+    f2: 120,
+    f3: 99,
+    f4: 118,
+    f5: 96,
+    f6: 97,
+    f7: 98,
+    f8: 100,
+    f9: 101,
+    f10: 109,
+    f11: 103,
+    f12: 111,
+};
+function lookupKeyCode(key) {
+    return _KEY_CODES[key.toLowerCase()];
+}
+const DEFAULT_TIMEOUT_MS = 10_000;
+const SHELL_TIMEOUT_MS = 30_000;
+const SCREENCAPTURE_TIMEOUT_MS = 15_000;
+/** Default runner — `child_process.spawn` wrapper supporting stdin pipe. */
+function defaultRunner(file, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            cwd: opts.cwd,
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (c) => stdoutChunks.push(c));
+        child.stderr?.on("data", (c) => stderrChunks.push(c));
+        let timer;
+        let timedOut = false;
+        if (opts.timeoutMs && opts.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    /* swallow */
+                }
+            }, opts.timeoutMs);
+        }
+        if (opts.input !== undefined) {
+            child.stdin?.end(opts.input);
+        }
+        else {
+            child.stdin?.end();
+        }
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            if (timer)
+                clearTimeout(timer);
+            const stdoutBuf = Buffer.concat(stdoutChunks);
+            const stderr = Buffer.concat(stderrChunks).toString("utf8");
+            const stdout = opts.encoding === "buffer" ? stdoutBuf : stdoutBuf.toString("utf8");
+            if (timedOut) {
+                const e = new Error(`${file} timed out after ${opts.timeoutMs}ms`);
+                e.signal = "SIGTERM";
+                e.killed = true;
+                e.stdout = stdout;
+                e.stderr = stderr;
+                reject(e);
+                return;
+            }
+            if (code === 0) {
+                resolve({ stdout, stderr });
+                return;
+            }
+            const err = new Error(`${file} exited with code ${code}${signal ? ` (signal ${signal})` : ""}`);
+            err.stdout = stdout;
+            err.stderr = stderr;
+            // `NodeJS.ErrnoException.code` is typed as `string`; the intersection
+            // above widens it to `string | number` for the read-side, but we still
+            // need a type-safe write. Stash on a private prop so production code
+            // and tests both rely on the same field.
+            err.code =
+                typeof code === "number" ? code : 1;
+            reject(err);
+        });
+    });
+}
+function defaultFs() {
+    return {
+        readFile: (p) => fsPromises.readFile(p),
+        writeFile: (p, data) => fsPromises.writeFile(p, data),
+        readdir: (p, _opts) => fsPromises.readdir(p, { withFileTypes: true }),
+        stat: (p) => fsPromises.stat(p),
+        access: (p) => fsPromises.access(p),
+        unlink: (p) => fsPromises.unlink(p).catch(() => undefined),
+        tmpdir: () => os.tmpdir(),
+    };
+}
+export class MacOsBackend extends BaseSandboxBackend {
+    os = "desktop-macos";
+    tools = MACOS_TOOLS;
+    runner;
+    fs;
+    sleep;
+    cliclickPath;
+    cliclickProbed;
+    forceFallback;
+    cachedSize;
+    retinaScale;
+    constructor(opts = {}) {
+        super();
+        this.runner = opts.runner ?? defaultRunner;
+        this.fs = opts.fs ?? defaultFs();
+        this.sleep =
+            opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+        this.cliclickPath = opts.cliclickPath;
+        this.cliclickProbed = opts.cliclickPath !== undefined || !!opts.forceFallback;
+        this.forceFallback = !!opts.forceFallback;
+        this.cachedSize = opts.size;
+        this.retinaScale = opts.retinaScale ?? 1;
+    }
+    /* ------------------------------------------------------------------ */
+    /* Lifecycle                                                          */
+    /* ------------------------------------------------------------------ */
+    async connect() {
+        await this.probeCliclick();
+        if (!this.cachedSize) {
+            const probed = await this.probeDisplay().catch(() => undefined);
+            if (probed) {
+                this.cachedSize = { w: probed.logicalW, h: probed.logicalH };
+                this.retinaScale = probed.scale;
+            }
+            else {
+                this.cachedSize = { w: 1440, h: 900 };
+            }
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /* Info / observation                                                 */
+    /* ------------------------------------------------------------------ */
+    async info() {
+        const size = await this.screenSize();
+        const [osVersion, name] = await Promise.all([
+            this.runUtf8("sw_vers", ["-productVersion"]).catch(() => ""),
+            this.runUtf8("scutil", ["--get", "ComputerName"]).catch(() => "macOS"),
+        ]);
+        const capabilities = [
+            "screenshot",
+            "click",
+            "tap",
+            "drag",
+            "swipe",
+            "scroll",
+            "type",
+            "press_key",
+            "hotkey",
+            "launch_app",
+            "shell",
+            "file_io",
+            "home",
+        ];
+        return {
+            type: "desktop-macos",
+            name: (name || "macOS").trim(),
+            os: "macOS",
+            width: size.w,
+            height: size.h,
+            capabilities,
+            osVersion: osVersion.trim(),
+            density: 0,
+            metadata: {
+                cliclick: this.cliclickPath ? "present" : "absent",
+                retinaScale: String(this.retinaScale),
+            },
+        };
+    }
+    async screenshot() {
+        // macOS `screencapture` does NOT honour `-o -` as stdout (despite some
+        // online folklore — `-o` is not a stdout switch in the official manpage),
+        // and the bare `-` filename is also not interpreted as stdout. Real-world
+        // usage on every modern macOS release requires writing to a path, so we
+        // round-trip through a per-call temp file. This still keeps the runner
+        // injectable: tests can mock both the runner and the fs shim.
+        const tmpPath = path.join(this.fs.tmpdir(), `beeos-mac-shot-${process.pid}-${Date.now()}-${Math.floor(Math.random() * 1e6)}.png`);
+        let raw;
+        try {
+            await this.runUtf8("screencapture", ["-x", "-t", "png", tmpPath], {
+                timeoutMs: SCREENCAPTURE_TIMEOUT_MS,
+            });
+            raw = await this.fs.readFile(tmpPath);
+        }
+        finally {
+            await this.fs.unlink(tmpPath).catch(() => undefined);
+        }
+        if (!Buffer.isBuffer(raw) || raw.length < 8) {
+            throw new DeviceError("screencapture returned no data", {
+                subtype: "screenshot_failed",
+            });
+        }
+        // Non-Retina (or scale-not-yet-detected) hosts: pass the PNG straight
+        // through. Click coords already share the screencapture coordinate space.
+        if (this.retinaScale <= 1) {
+            const [rawW, rawH] = parsePngDimensions(raw);
+            return { data: raw, width: rawW, height: rawH, format: "png" };
+        }
+        const size = await this.screenSize();
+        try {
+            const data = await sharp(raw, { failOn: "none" })
+                .resize({ width: size.w, height: size.h, fit: "fill" })
+                .png()
+                .toBuffer();
+            return { data, width: size.w, height: size.h, format: "png" };
+        }
+        catch {
+            const [rawW, rawH] = parsePngDimensions(raw);
+            return { data: raw, width: rawW, height: rawH, format: "png" };
+        }
+    }
+    async screenSize() {
+        if (this.cachedSize)
+            return this.cachedSize;
+        try {
+            const probed = await this.probeDisplay();
+            this.cachedSize = { w: probed.logicalW, h: probed.logicalH };
+            this.retinaScale = probed.scale;
+            return this.cachedSize;
+        }
+        catch {
+            this.cachedSize = { w: 1440, h: 900 };
+            return this.cachedSize;
+        }
+    }
+    /* ------------------------------------------------------------------ */
+    /* Pointer / gesture                                                  */
+    /* ------------------------------------------------------------------ */
+    async click(x, y, button = "left", clicks = 1) {
+        if (this.useCliclick()) {
+            const verb = button === "right" ? "rc" : "c";
+            const args = [];
+            for (let i = 0; i < clicks; i++) {
+                args.push(`${verb}:${x},${y}`);
+            }
+            await this.runCliclick(args);
+            return;
+        }
+        await this.runJxa(_JXA_CLICK, [
+            String(x),
+            String(y),
+            button,
+            String(clicks),
+        ]);
+    }
+    async doubleClick(x, y) {
+        if (this.useCliclick()) {
+            await this.runCliclick([`dc:${x},${y}`]);
+            return;
+        }
+        await this.runJxa(_JXA_CLICK, [String(x), String(y), "left", "2"]);
+    }
+    async rightClick(x, y) {
+        return this.click(x, y, "right", 1);
+    }
+    async tap(x, y) {
+        return this.click(x, y, "left", 1);
+    }
+    async longPress(x, y, durationMs = 800) {
+        if (this.useCliclick()) {
+            await this.runCliclick([`dd:${x},${y}`]);
+            await this.sleep(durationMs);
+            await this.runCliclick([`du:${x},${y}`]);
+            return;
+        }
+        // JXA fallback: drag in place with a brief delay simulates a long press.
+        await this.runJxa(_JXA_DRAG, [
+            String(x),
+            String(y),
+            String(x),
+            String(y),
+        ]);
+    }
+    async drag(x1, y1, x2, y2, _durationMs) {
+        if (this.useCliclick()) {
+            await this.runCliclick([
+                `dd:${x1},${y1}`,
+                `m:${x2},${y2}`,
+                `du:${x2},${y2}`,
+            ]);
+            return;
+        }
+        await this.runJxa(_JXA_DRAG, [
+            String(x1),
+            String(y1),
+            String(x2),
+            String(y2),
+        ]);
+    }
+    async swipe(x1, y1, x2, y2, durationMs) {
+        return this.drag(x1, y1, x2, y2, durationMs);
+    }
+    async scroll(x, y, direction, amount = 3) {
+        // cliclick has NO scroll primitive (verified against cliclick 5.x — its
+        // command list is c/dc/rc/tc/m/dd/dm/du/kp/kd/ku/t/cp/w only). For scroll
+        // we always go through JXA + Quartz CGEventCreateScrollWheelEvent, which
+        // works regardless of cliclick installation. We optionally move the mouse
+        // first via cliclick `m:` if available so the scroll lands on the
+        // intended hit-test target; otherwise we fall back to a JXA move.
+        const dy = direction === "up" ? amount : direction === "down" ? -amount : 0;
+        const dx = direction === "right" ? amount : direction === "left" ? -amount : 0;
+        if (x !== 0 || y !== 0) {
+            await this.move(x, y);
+        }
+        await this.runJxa(_JXA_SCROLL, [String(dx), String(dy)]);
+    }
+    async move(x, y) {
+        if (this.useCliclick()) {
+            await this.runCliclick([`m:${x},${y}`]);
+            return;
+        }
+        // JXA fallback: emit a single MouseMoved CGEvent at the target point.
+        await this.runJxa(_JXA_MOVE, [String(x), String(y)]);
+    }
+    /* ------------------------------------------------------------------ */
+    /* Keyboard                                                           */
+    /* ------------------------------------------------------------------ */
+    async typeText(text) {
+        await this.runOsa(_OSA_TYPE, [text]);
+    }
+    async pressKey(key) {
+        const code = lookupKeyCode(key);
+        if (code === undefined) {
+            // Fall back to typeText for printable single chars / unknown names.
+            await this.typeText(key);
+            return;
+        }
+        await this.runOsa(_OSA_KEY, [String(code)]);
+    }
+    async hotkey(...keys) {
+        const mods = [];
+        let target;
+        for (const k of keys) {
+            const lk = k.toLowerCase();
+            if (lk === "cmd" || lk === "command" || lk === "meta" || lk === "win") {
+                mods.push("command");
+            }
+            else if (lk === "ctrl" || lk === "control") {
+                mods.push("control");
+            }
+            else if (lk === "alt" || lk === "option" || lk === "opt") {
+                mods.push("option");
+            }
+            else if (lk === "shift") {
+                mods.push("shift");
+            }
+            else {
+                target = k;
+            }
+        }
+        if (!target) {
+            throw new DeviceError("hotkey requires a non-modifier target key", {
+                subtype: "invalid_args",
+            });
+        }
+        const code = lookupKeyCode(target);
+        if (code === undefined) {
+            // No key code → emit as plain keystroke; modifiers are dropped because
+            // AppleScript `keystroke "x" using {command down}` requires a literal
+            // single character which we can pass safely only for ASCII.
+            if (mods.length === 0 && target.length === 1) {
+                await this.typeText(target);
+                return;
+            }
+            throw new DeviceError(`unknown hotkey target '${target}'`, {
+                subtype: "invalid_args",
+            });
+        }
+        await this.runOsa(_OSA_HOTKEY, [String(code), mods.join(",")]);
+    }
+    async home() {
+        await this.runOsa(_OSA_HOME, []);
+    }
+    /* ------------------------------------------------------------------ */
+    /* App lifecycle                                                      */
+    /* ------------------------------------------------------------------ */
+    async launchApp(pkgOrName, _activity) {
+        const args = [];
+        if (pkgOrName.endsWith(".app") || pkgOrName.startsWith("/")) {
+            args.push(pkgOrName);
+        }
+        else if (looksLikeBundleId(pkgOrName)) {
+            args.push("-b", pkgOrName);
+        }
+        else {
+            args.push("-a", pkgOrName);
+        }
+        await this.runUtf8("open", args);
+    }
+    /* ------------------------------------------------------------------ */
+    /* Shell / files                                                      */
+    /* ------------------------------------------------------------------ */
+    async executeCommand(body, opts = {}) {
+        const timeoutMs = (opts.timeoutS ?? SHELL_TIMEOUT_MS / 1000) * 1000;
+        try {
+            const { stdout, stderr } = await this.runner("/bin/sh", ["-c", body], {
+                encoding: "utf8",
+                timeoutMs,
+                cwd: opts.cwd,
+            });
+            return {
+                stdout: typeof stdout === "string" ? stdout : stdout.toString("utf8"),
+                stderr,
+                exitCode: 0,
+            };
+        }
+        catch (e) {
+            const err = e;
+            if (err.killed && err.signal === "SIGTERM") {
+                throw new DeviceError(`shell timed out after ${timeoutMs}ms`, {
+                    subtype: "exec_timeout",
+                    retriable: true,
+                    cause: err,
+                });
+            }
+            const stdout = typeof err.stdout === "string"
+                ? err.stdout
+                : Buffer.isBuffer(err.stdout)
+                    ? err.stdout.toString("utf8")
+                    : "";
+            return {
+                stdout,
+                stderr: err.stderr ?? err.message,
+                exitCode: typeof err.code === "number" ? err.code : 1,
+            };
+        }
+    }
+    async fileRead(path) {
+        try {
+            return await this.fs.readFile(path);
+        }
+        catch (e) {
+            throw new DeviceError(`fileRead failed: ${e.message}`, {
+                subtype: "file_read_failed",
+                cause: e,
+            });
+        }
+    }
+    async fileWrite(path, content) {
+        try {
+            await this.fs.writeFile(path, content);
+        }
+        catch (e) {
+            throw new DeviceError(`fileWrite failed: ${e.message}`, {
+                subtype: "file_write_failed",
+                cause: e,
+            });
+        }
+    }
+    async listDirectory(path) {
+        try {
+            const entries = await this.fs.readdir(path, { withFileTypes: true });
+            const result = [];
+            for (const e of entries) {
+                const isDir = e.isDirectory();
+                let size = 0;
+                if (!isDir) {
+                    try {
+                        const st = await this.fs.stat(`${path}/${e.name}`);
+                        size = st.size;
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                result.push({ name: e.name, isDir, size });
+            }
+            return result;
+        }
+        catch (e) {
+            throw new DeviceError(`listDirectory failed: ${e.message}`, {
+                subtype: "list_directory_failed",
+                cause: e,
+            });
+        }
+    }
+    async install(path) {
+        try {
+            await this.fs.access(path);
+        }
+        catch {
+            throw new DeviceError(`install: file not found '${path}'`, {
+                subtype: "invalid_args",
+            });
+        }
+        await this.runUtf8("open", [path]);
+    }
+    /* ------------------------------------------------------------------ */
+    /* Internals                                                          */
+    /* ------------------------------------------------------------------ */
+    useCliclick() {
+        if (this.forceFallback)
+            return false;
+        return !!this.cliclickPath;
+    }
+    async probeCliclick() {
+        if (this.cliclickProbed)
+            return;
+        this.cliclickProbed = true;
+        try {
+            // `command -v` is a POSIX builtin; always available via /bin/sh.
+            const { stdout } = await this.runner("/bin/sh", ["-c", "command -v cliclick"], {
+                encoding: "utf8",
+                timeoutMs: 2_000,
+            });
+            const path = (typeof stdout === "string" ? stdout : stdout.toString()).trim();
+            if (path) {
+                this.cliclickPath = path;
+            }
+        }
+        catch {
+            this.cliclickPath = undefined;
+        }
+    }
+    async probeDisplay() {
+        const { stdout } = await this.runner("system_profiler", ["SPDisplaysDataType", "-json"], { encoding: "utf8", timeoutMs: 5_000 });
+        const text = typeof stdout === "string" ? stdout : stdout.toString("utf8");
+        const data = JSON.parse(text);
+        const root = data["SPDisplaysDataType"];
+        if (!Array.isArray(root)) {
+            throw new Error("missing SPDisplaysDataType");
+        }
+        for (const node of root) {
+            const screens = node["spdisplays_ndrvs"];
+            if (!Array.isArray(screens))
+                continue;
+            // Prefer the screen marked as main when present.
+            const mainFirst = [...screens].sort((a, b) => a["spdisplays_main"] === "spdisplays_yes" ? -1 : b["spdisplays_main"] === "spdisplays_yes" ? 1 : 0);
+            for (const s of mainFirst) {
+                const resStr = s["_spdisplays_resolution"] ?? "";
+                const pxStr = s["_spdisplays_pixels"] ?? "";
+                const logical = parseDimensionString(resStr);
+                const native = parseDimensionString(pxStr) ?? logical;
+                if (logical) {
+                    const native2 = native ?? logical;
+                    const scale = native2.w > 0 && logical.w > 0
+                        ? Math.round((native2.w / logical.w) * 100) / 100
+                        : 1;
+                    return {
+                        logicalW: logical.w,
+                        logicalH: logical.h,
+                        nativeW: native2.w,
+                        nativeH: native2.h,
+                        scale: scale > 0 ? scale : 1,
+                    };
+                }
+            }
+        }
+        throw new Error("no display found in system_profiler output");
+    }
+    async runCliclick(args) {
+        const bin = this.cliclickPath ?? "cliclick";
+        try {
+            await this.runner(bin, args, {
+                encoding: "utf8",
+                timeoutMs: DEFAULT_TIMEOUT_MS,
+            });
+        }
+        catch (e) {
+            throw wrapMacRunFailure("cliclick", args, e);
+        }
+    }
+    async runOsa(script, args) {
+        try {
+            const { stdout } = await this.runner("osascript", ["-", ...args], {
+                encoding: "utf8",
+                timeoutMs: DEFAULT_TIMEOUT_MS,
+                input: script,
+            });
+            return typeof stdout === "string" ? stdout : stdout.toString("utf8");
+        }
+        catch (e) {
+            throw wrapMacRunFailure("osascript", args, e);
+        }
+    }
+    /**
+     * Run a JXA (JavaScript for Automation) script via `osascript -l JavaScript`.
+     * Used for pointer / scroll synthesis — JXA's ObjC bridge gives us direct
+     * Quartz CGEvent access, which is the only dependency-free way to drive
+     * synthetic mouse input on modern macOS (the AppleScript `click at {x, y}`
+     * surface has been broken since the 10.14 era).
+     */
+    async runJxa(script, args) {
+        try {
+            const { stdout } = await this.runner("osascript", ["-l", "JavaScript", "-", ...args], {
+                encoding: "utf8",
+                timeoutMs: DEFAULT_TIMEOUT_MS,
+                input: script,
+            });
+            return typeof stdout === "string" ? stdout : stdout.toString("utf8");
+        }
+        catch (e) {
+            // Surface this as "osascript_failed" so callers can write a single
+            // error-handler that matches the AppleScript and JXA paths uniformly.
+            throw wrapMacRunFailure("osascript", args, e);
+        }
+    }
+    async runUtf8(file, args, opts = {}) {
+        try {
+            const { stdout } = await this.runner(file, args, {
+                encoding: "utf8",
+                timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+            return typeof stdout === "string" ? stdout : stdout.toString("utf8");
+        }
+        catch (e) {
+            throw wrapMacRunFailure(file, args, e);
+        }
+    }
+    async runBuffer(file, args, opts = {}) {
+        try {
+            const { stdout } = await this.runner(file, args, {
+                encoding: "buffer",
+                timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            });
+            return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
+        }
+        catch (e) {
+            throw wrapMacRunFailure(file, args, e);
+        }
+    }
+}
+/* ----------------------------------------------------------------------- */
+/* Module-level helpers                                                    */
+/* ----------------------------------------------------------------------- */
+function looksLikeBundleId(s) {
+    return /^[a-z0-9-]+(\.[a-z0-9-]+){2,}$/i.test(s);
+}
+function parseDimensionString(s) {
+    if (!s)
+        return null;
+    const m = s.match(/(\d+)\s*x\s*(\d+)/i);
+    if (!m)
+        return null;
+    const w = Number(m[1]);
+    const h = Number(m[2]);
+    if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0)
+        return null;
+    return { w, h };
+}
+function wrapMacRunFailure(file, args, cause) {
+    const err = cause;
+    const isTimeout = err.killed && err.signal === "SIGTERM";
+    const subtype = isTimeout
+        ? `${file}_timeout`
+        : file === "cliclick"
+            ? "cliclick_failed"
+            : file === "osascript"
+                ? "osascript_failed"
+                : `${file}_failed`;
+    const summary = err.stderr?.trim() || err.message || "unknown error";
+    const argSnippet = args.slice(0, 3).join(" ");
+    return new DeviceError(`${file} ${argSnippet}: ${summary}`, {
+        subtype,
+        retriable: !!isTimeout,
+        cause: err,
+    });
+}
+//# sourceMappingURL=mac.js.map