onbuzz 4.7.2 → 4.8.0

package/src/tools/desktop/__tests__/osController.test.js

@@ -0,0 +1,364 @@
+/**
+ * OSController tests — all native calls injected via `nutImpl`.
+ *
+ * Verifies:
+ *   - capability gating (refuses ops the OS reports as unsupported)
+ *   - coord / arg validation
+ *   - op delegation to nut.js with the right shapes
+ *   - error wrapping (raw → typed OSError codes)
+ *   - lazy-load failure surfaces as NATIVE_UNAVAILABLE
+ */
+
+import { describe, test, expect, beforeEach, jest } from '@jest/globals';
+import { createOSController, OSController, OSError } from '../osController.js';
+
+// ─── nut.js test double ────────────────────────────────────────────────
+
+function makeFakeNut(overrides = {}) {
+  const calls = [];
+  const record = (name) => (...args) => { calls.push({ name, args }); return Promise.resolve(); };
+
+  // Minimal Point / Region / Button shims so the controller's `new Point(x,y)`
+  // calls don't blow up.
+  class Point  { constructor(x, y) { this.x = x; this.y = y; } }
+  class Region { constructor(x, y, w, h) { Object.assign(this, { x, y, width: w, height: h }); } }
+  const Button = { LEFT: 'L', RIGHT: 'R', MIDDLE: 'M' };
+  // Real nut.js v4 exposes ONLY Left/Right modifier names — no plain
+  // "Control"/"Shift". Reflect that here so the alias map gets the
+  // same exercise as production. Plain "Control" → LeftControl via
+  // KEY_ALIASES in osController.js.
+  const Key = {
+    LeftControl: 'CTRL', LeftShift: 'SHIFT', LeftAlt: 'ALT', LeftWin: 'WIN',
+    S: 'S', F5: 'F5', Enter: 'ENTER', Escape: 'ESC',
+  };
+
+  const fakeImage = { toPng: async () => Buffer.from('png-bytes') };
+
+  const nut = {
+    screen: {
+      grab:       jest.fn(async () => fakeImage),
+      grabRegion: jest.fn(async () => fakeImage),
+      width:      jest.fn(async () => 1920),
+      height:     jest.fn(async () => 1080),
+    },
+    mouse: {
+      move:          jest.fn(record('mouse.move')),
+      click:         jest.fn(record('mouse.click')),
+      doubleClick:   jest.fn(record('mouse.doubleClick')),
+      pressButton:   jest.fn(record('mouse.pressButton')),
+      releaseButton: jest.fn(record('mouse.releaseButton')),
+      scrollDown:    jest.fn(record('mouse.scrollDown')),
+      scrollUp:      jest.fn(record('mouse.scrollUp')),
+    },
+    keyboard: {
+      config: { autoDelayMs: 0 },
+      type:       jest.fn(record('keyboard.type')),
+      pressKey:   jest.fn(record('keyboard.pressKey')),
+      releaseKey: jest.fn(record('keyboard.releaseKey')),
+    },
+    getWindows: jest.fn(async () => []),
+    Point, Region, Button, Key,
+    _calls: calls,
+    ...overrides,
+  };
+  return nut;
+}
+
+const FULL_CAPS = Object.freeze({
+  os: 'win32', display: null,
+  screenshot: true, mouseInput: true, keyboardInput: true,
+  windowEnumeration: true, windowFocus: true,
+  permissions: {}, degradedReason: null, probedAt: Date.now(),
+});
+
+const WAYLAND_CAPS = Object.freeze({
+  os: 'linux', display: 'wayland',
+  screenshot: true, mouseInput: false, keyboardInput: false,
+  windowEnumeration: true, windowFocus: false,
+  permissions: { portalsOnly: true },
+  degradedReason: 'Wayland blocks input injection.',
+  probedAt: Date.now(),
+});
+
+// ─── factory / lifecycle ───────────────────────────────────────────────
+
+describe('createOSController', () => {
+  test('returns an OSController instance', () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    expect(c).toBeInstanceOf(OSController);
+  });
+});
+
+describe('lazy native loading', () => {
+  test('describeCapabilities reports nativeLoaded=true after first op when nutImpl is injected', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    const info = await c.describeCapabilities();
+    expect(info.nativeLoaded).toBe(true);
+    expect(info.os).toBe('win32');
+  });
+});
+
+// ─── screenshot ────────────────────────────────────────────────────────
+
+describe('screenshot', () => {
+  test('full-screen grab → png buffer', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    const buf = await c.screenshot();
+    expect(Buffer.isBuffer(buf)).toBe(true);
+    expect(nut.screen.grab).toHaveBeenCalledTimes(1);
+    expect(nut.screen.grabRegion).not.toHaveBeenCalled();
+  });
+
+  test('region grab passes a Region with the right dims', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.screenshot({ region: { x: 10, y: 20, width: 100, height: 50 } });
+    expect(nut.screen.grabRegion).toHaveBeenCalledTimes(1);
+    const region = nut.screen.grabRegion.mock.calls[0][0];
+    expect(region).toMatchObject({ x: 10, y: 20, width: 100, height: 50 });
+  });
+
+  test('invalid region → OS_INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.screenshot({ region: { x: -1, y: 0, width: 10, height: 10 } }))
+      .rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('refuses when caps say screenshot is false', async () => {
+    const caps = { ...FULL_CAPS, screenshot: false, degradedReason: 'no perms' };
+    const c = createOSController({ capabilities: caps, nutImpl: makeFakeNut() });
+    await expect(c.screenshot()).rejects.toMatchObject({ code: OSError.UNSUPPORTED });
+  });
+});
+
+// ─── mouse ─────────────────────────────────────────────────────────────
+
+describe('mouseMove / mouseClick', () => {
+  test('mouseMove delegates to nut.mouse.move with a Point', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.mouseMove(100, 200);
+    expect(nut.mouse.move).toHaveBeenCalledTimes(1);
+    const arr = nut.mouse.move.mock.calls[0][0];
+    expect(arr[0]).toMatchObject({ x: 100, y: 200 });
+  });
+
+  test('negative coords → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.mouseMove(-1, 0)).rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('mouseClick single = move + click', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.mouseClick(50, 60);
+    expect(nut.mouse.move).toHaveBeenCalledTimes(1);
+    expect(nut.mouse.click).toHaveBeenCalledTimes(1);
+    expect(nut.mouse.click).toHaveBeenCalledWith('L');
+    expect(nut.mouse.doubleClick).not.toHaveBeenCalled();
+  });
+
+  test('mouseClick count=2 → doubleClick', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.mouseClick(50, 60, { count: 2, button: 'right' });
+    expect(nut.mouse.doubleClick).toHaveBeenCalledWith('R');
+  });
+
+  test('unknown button → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.mouseClick(1, 1, { button: 'sideways' }))
+      .rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('mouseInput=false → UNSUPPORTED with remediation', async () => {
+    const c = createOSController({ capabilities: WAYLAND_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.mouseClick(1, 1)).rejects.toMatchObject({
+      code: OSError.UNSUPPORTED,
+    });
+  });
+});
+
+describe('mouseScroll', () => {
+  test('dy > 0 → scrollDown', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.mouseScroll(10, 10, 3);
+    expect(nut.mouse.scrollDown).toHaveBeenCalledWith(3);
+  });
+  test('dy < 0 → scrollUp', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.mouseScroll(10, 10, -5);
+    expect(nut.mouse.scrollUp).toHaveBeenCalledWith(5);
+  });
+  test('dy non-finite → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.mouseScroll(0, 0, NaN)).rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+});
+
+describe('mouseDrag', () => {
+  test('press → move → release', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.mouseDrag({ x: 0, y: 0 }, { x: 100, y: 100 });
+    expect(nut.mouse.pressButton).toHaveBeenCalledWith('L');
+    expect(nut.mouse.releaseButton).toHaveBeenCalledWith('L');
+    expect(nut.mouse.move).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ─── keyboard ──────────────────────────────────────────────────────────
+
+describe('typeText / keyPress', () => {
+  test('typeText forwards string and sets autoDelay', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.typeText('hello', { delayMs: 5 });
+    expect(nut.keyboard.type).toHaveBeenCalledWith('hello');
+    expect(nut.keyboard.config.autoDelayMs).toBe(5);
+  });
+
+  test('empty text → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.typeText('')).rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('keyPress resolves chord through Key enum', async () => {
+    const nut = makeFakeNut();
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.keyPress(['Control', 'S']);
+    expect(nut.keyboard.pressKey).toHaveBeenCalledWith('CTRL', 'S');
+    expect(nut.keyboard.releaseKey).toHaveBeenCalledWith('CTRL', 'S');
+  });
+
+  test('unknown key → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.keyPress(['Bogus'])).rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('cross-platform aliases (Meta/Command/Cmd/Windows/Win) resolve to OS keys', async () => {
+    // Build a fake nut.Key that includes the realistic names we want
+    // aliases to resolve to. The alias map should normalise BEFORE the
+    // strict Key[name] lookup so an agent's natural "Meta" works on
+    // Windows even though nut.js calls it LeftWin.
+    const nut = makeFakeNut({
+      Key: { LeftWin: 'WIN', LeftCmd: 'CMD', LeftSuper: 'SUPER', LeftControl: 'CTRL', S: 'S' },
+    });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await c.keyPress(['Meta']);
+    expect(nut.keyboard.pressKey).toHaveBeenCalledWith('WIN');
+    await c.keyPress(['Command']);
+    expect(nut.keyboard.pressKey).toHaveBeenCalledWith('CMD');
+    await c.keyPress(['Win', 'S']);
+    expect(nut.keyboard.pressKey).toHaveBeenCalledWith('WIN', 'S');
+  });
+
+  test('error message hints at nearby key names', async () => {
+    const nut = makeFakeNut({
+      Key: { LeftWin: 'WIN', LeftCmd: 'CMD', LeftSuper: 'SUPER' },
+    });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    try {
+      await c.keyPress(['LeftWinx']);
+      throw new Error('should have thrown');
+    } catch (e) {
+      expect(e.code).toBe(OSError.INVALID_INPUT);
+      expect(e.message).toMatch(/did you mean.*LeftWin/);
+    }
+  });
+
+  test('empty keys → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.keyPress([])).rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('keyboardInput=false → UNSUPPORTED', async () => {
+    const c = createOSController({ capabilities: WAYLAND_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.typeText('hi')).rejects.toMatchObject({ code: OSError.UNSUPPORTED });
+  });
+});
+
+// ─── windows ───────────────────────────────────────────────────────────
+
+describe('listWindows / focusWindow', () => {
+  function fakeWin({ title, bounds }) {
+    return {
+      getTitle:  async () => title,
+      getRegion: async () => bounds,
+      focus:     jest.fn(async () => {}),
+    };
+  }
+
+  test('listWindows returns titles + bounds', async () => {
+    const w1 = fakeWin({ title: 'Editor', bounds: { x: 0, y: 0, width: 800, height: 600 } });
+    const nut = makeFakeNut({ getWindows: jest.fn(async () => [w1]) });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    const list = await c.listWindows();
+    expect(list).toHaveLength(1);
+    expect(list[0]).toMatchObject({ title: 'Editor', bounds: { width: 800 } });
+  });
+
+  test('focusWindow matches by substring (case-insensitive)', async () => {
+    const target = fakeWin({ title: 'My App — Untitled', bounds: {} });
+    const other  = fakeWin({ title: 'Browser',           bounds: {} });
+    const nut = makeFakeNut({ getWindows: jest.fn(async () => [other, target]) });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    const r = await c.focusWindow({ titleMatch: 'my app' });
+    expect(r.focused).toBe(true);
+    expect(target.focus).toHaveBeenCalled();
+    expect(other.focus).not.toHaveBeenCalled();
+  });
+
+  test('focusWindow with regex', async () => {
+    const target = fakeWin({ title: 'VS Code', bounds: {} });
+    const nut = makeFakeNut({ getWindows: jest.fn(async () => [target]) });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    const r = await c.focusWindow({ titleMatch: /VS\s*Code/ });
+    expect(r.focused).toBe(true);
+  });
+
+  test('focusWindow no match → focused:false', async () => {
+    const nut = makeFakeNut({ getWindows: jest.fn(async () => []) });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    const r = await c.focusWindow({ titleMatch: 'nope' });
+    expect(r.focused).toBe(false);
+  });
+
+  test('focusWindow without titleMatch → INVALID_INPUT', async () => {
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.focusWindow({})).rejects.toMatchObject({ code: OSError.INVALID_INPUT });
+  });
+
+  test('windowFocus=false → UNSUPPORTED', async () => {
+    const c = createOSController({ capabilities: WAYLAND_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.focusWindow({ titleMatch: 'x' })).rejects.toMatchObject({
+      code: OSError.UNSUPPORTED,
+    });
+  });
+});
+
+// ─── error wrapping ────────────────────────────────────────────────────
+
+describe('error wrapping', () => {
+  test('"not authorized" raw error → PERMISSION_DENIED', async () => {
+    const nut = makeFakeNut();
+    nut.mouse.click = jest.fn(async () => { throw new Error('not authorized to send events'); });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await expect(c.mouseClick(1, 1)).rejects.toMatchObject({ code: OSError.PERMISSION_DENIED });
+  });
+
+  test('generic raw error → OP_FAILED', async () => {
+    const nut = makeFakeNut();
+    nut.mouse.click = jest.fn(async () => { throw new Error('some random failure'); });
+    const c = createOSController({ capabilities: FULL_CAPS, nutImpl: nut });
+    await expect(c.mouseClick(1, 1)).rejects.toMatchObject({ code: OSError.OP_FAILED });
+  });
+
+  test('UNSUPPORTED bubbles through unmodified', async () => {
+    const c = createOSController({ capabilities: WAYLAND_CAPS, nutImpl: makeFakeNut() });
+    await expect(c.mouseClick(1, 1)).rejects.toMatchObject({ code: OSError.UNSUPPORTED });
+  });
+});

package/src/tools/desktop/osCapabilities.js

@@ -0,0 +1,248 @@
+/**
+ * OS / display-server capability detection for the desktop-control
+ * subsystem.
+ *
+ * Probed ONCE at boot. The result is a frozen snapshot the rest of
+ * the DesktopTool stack consults synchronously before every op:
+ *
+ *   const caps = await detectOSCapabilities();
+ *   if (!caps.mouseInput) return { code: 'OS_UNSUPPORTED', remediation: caps.degradedReason };
+ *
+ * Why probe at boot, not per-op:
+ *   - OS / display server doesn't change while the CLI runs
+ *   - Permission grants do, but those are caught at the op boundary
+ *     when nut.js itself fails (handled in OSController)
+ *   - Probing once means the rest of the code can branch on a
+ *     plain object without async overhead
+ *
+ * No native deps — pure Node stdlib + child_process for tiny probes.
+ * The OS-specific permission checks use `osascript` (macOS) and
+ * `wmctrl --version` (Linux X11 probe). Failures fall through to
+ * permissive defaults rather than blocking startup.
+ *
+ * @typedef {Object} OSCapabilities
+ * @property {'win32'|'darwin'|'linux'|'unknown'} os
+ * @property {'x11'|'wayland'|null} display          - null on non-Linux
+ * @property {boolean} screenshot
+ * @property {boolean} mouseInput
+ * @property {boolean} keyboardInput
+ * @property {boolean} windowEnumeration
+ * @property {boolean} windowFocus
+ * @property {boolean} dpiAware
+ * @property {Object} permissions
+ * @property {boolean} permissions.requiresAccessibility       - macOS only
+ * @property {boolean} permissions.requiresScreenRecording     - macOS only
+ * @property {boolean} permissions.portalsOnly                 - Linux Wayland
+ * @property {boolean|null} permissions.accessibilityGranted   - null = unknown
+ * @property {boolean|null} permissions.screenRecordingGranted - null = unknown
+ * @property {string|null} degradedReason   - operator-friendly explanation
+ * @property {number} probedAt              - epoch ms
+ */
+
+import { exec as execCb } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execCb);
+
+/** Identifiers we standardise on across the codebase. */
+export const PlatformId = Object.freeze({
+  WIN:   'win32',
+  MAC:   'darwin',
+  LINUX: 'linux',
+  UNKNOWN: 'unknown',
+});
+
+export const DisplayServer = Object.freeze({
+  X11:     'x11',
+  WAYLAND: 'wayland',
+});
+
+/** Tiny exec timeout for permission probes — fail fast. */
+const PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Build and return a capability snapshot for the current process.
+ *
+ * Cached after first call; pass `{ refresh: true }` to re-probe.
+ *
+ * @param {Object} [opts]
+ * @param {boolean} [opts.refresh=false]
+ * @param {Object}  [opts.env=process.env]      - injectable for tests
+ * @param {string}  [opts.platform=process.platform] - injectable for tests
+ * @returns {Promise<OSCapabilities>}
+ */
+let cached = null;
+export async function detectOSCapabilities(opts = {}) {
+  if (cached && !opts.refresh) return cached;
+
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const os = mapPlatform(platform);
+  const display = os === PlatformId.LINUX ? detectDisplayServer(env) : null;
+
+  // Permissive defaults — every OS is fully-capable until proven otherwise.
+  const caps = {
+    os,
+    display,
+    screenshot:        true,
+    mouseInput:        true,
+    keyboardInput:     true,
+    windowEnumeration: true,
+    windowFocus:       true,
+    dpiAware:          true,
+    permissions: {
+      requiresAccessibility:    os === PlatformId.MAC,
+      requiresScreenRecording:  os === PlatformId.MAC,
+      portalsOnly:              display === DisplayServer.WAYLAND,
+      accessibilityGranted:     null,
+      screenRecordingGranted:   null,
+    },
+    degradedReason: null,
+    probedAt: Date.now(),
+  };
+
+  // OS-specific overrides — these MUTATE caps in place because each
+  // probe is independent and writes only its own fields.
+  if (os === PlatformId.LINUX && display === DisplayServer.WAYLAND) {
+    applyWaylandDegradation(caps);
+  }
+  if (os === PlatformId.MAC) {
+    await applyMacOSPermissionProbes(caps);
+  }
+
+  cached = Object.freeze(deepFreeze(caps));
+  return cached;
+}
+
+/** Reset cache (tests only). */
+export function _resetCacheForTests() {
+  cached = null;
+}
+
+// ─── internal helpers ───────────────────────────────────────────────
+
+function mapPlatform(p) {
+  if (p === 'win32')  return PlatformId.WIN;
+  if (p === 'darwin') return PlatformId.MAC;
+  if (p === 'linux')  return PlatformId.LINUX;
+  return PlatformId.UNKNOWN;
+}
+
+function detectDisplayServer(env) {
+  // XDG_SESSION_TYPE is the standard freedesktop signal. Wayland
+  // sessions set it to 'wayland'. Anything else (or unset) → assume X11.
+  const xdg = (env.XDG_SESSION_TYPE || '').toLowerCase();
+  if (xdg === 'wayland') return DisplayServer.WAYLAND;
+  return DisplayServer.X11;
+}
+
+/**
+ * Wayland blocks input injection by design (the security model
+ * forbids one app from synthesising events into another). We can
+ * still capture screen via xdg-desktop-portal but mouse/keyboard
+ * are off-limits.
+ */
+function applyWaylandDegradation(caps) {
+  caps.mouseInput    = false;
+  caps.keyboardInput = false;
+  caps.windowFocus   = false;
+  caps.degradedReason =
+    'Wayland blocks input injection by design. DesktopTool runs in ' +
+    'read-only mode (screenshot + window listing only). Switch to an ' +
+    'X11 session, or install a compositor portal that grants input ' +
+    'capabilities, to enable full control.';
+}
+
+/**
+ * macOS requires the host app to be explicitly granted two
+ * permissions:
+ *   - Accessibility  (for input injection)
+ *   - Screen Recording (for screenshots that include other apps)
+ *
+ * Probing them programmatically without native bindings is fragile;
+ * we use the standard `osascript` route which returns a deterministic
+ * error if not granted. If the probe itself fails (osascript missing
+ * — extremely rare on real macOS) we leave the booleans as null and
+ * let runtime errors surface at op time.
+ */
+async function applyMacOSPermissionProbes(caps) {
+  caps.permissions.accessibilityGranted   = await probeMacOSAccessibility();
+  caps.permissions.screenRecordingGranted = await probeMacOSScreenRecording();
+
+  if (caps.permissions.accessibilityGranted === false) {
+    caps.mouseInput    = false;
+    caps.keyboardInput = false;
+    caps.degradedReason =
+      'macOS Accessibility permission is not granted. Open System ' +
+      'Settings > Privacy & Security > Accessibility and enable Loxia.';
+  }
+  if (caps.permissions.screenRecordingGranted === false) {
+    caps.screenshot = false;
+    caps.degradedReason = (caps.degradedReason ? caps.degradedReason + ' ' : '') +
+      'Screen Recording permission is also required for full-screen ' +
+      'capture (System Settings > Privacy & Security > Screen Recording).';
+  }
+}
+
+/**
+ * Returns true if granted, false if denied, null if undetermined.
+ * The trick: trigger an AppleScript that probes UI Element control
+ * via System Events. If denied, the script errors with code -1719
+ * or "not authorized to send Apple events".
+ */
+async function probeMacOSAccessibility() {
+  // Non-intrusive probe: just count the menus of the frontmost app.
+  // Doesn't change anything; only requires the same entitlement as
+  // any UI control would.
+  const script =
+    'tell application "System Events" to count of UI elements of (first process whose frontmost is true)';
+  try {
+    await exec(`osascript -e ${shellQuote(script)}`, { timeout: PROBE_TIMEOUT_MS });
+    return true;
+  } catch (err) {
+    const msg = (err.stderr || err.message || '').toLowerCase();
+    if (msg.includes('not authorized') || msg.includes('1719')) return false;
+    // Unknown failure — be conservative and report unknown.
+    return null;
+  }
+}
+
+/**
+ * Screen Recording is harder to probe without invoking a capture.
+ * We use a lightweight `screencapture -x -t png -` to stdout and
+ * check if any bytes came back. If permission is denied, macOS
+ * silently writes a black image — we can't distinguish from a
+ * legitimate black screen. Best-effort only; the runtime check at
+ * actual screenshot time is authoritative.
+ */
+async function probeMacOSScreenRecording() {
+  try {
+    const { stdout, stderr } = await exec(
+      'screencapture -x -t png -C - </dev/null',
+      { timeout: PROBE_TIMEOUT_MS, encoding: 'buffer', maxBuffer: 10 * 1024 * 1024 }
+    );
+    if (stdout && stdout.length > 100) return true;
+    if (stderr && stderr.toString().toLowerCase().includes('permission')) return false;
+    return null;
+  } catch (err) {
+    const msg = (err.stderr?.toString?.() || err.message || '').toLowerCase();
+    if (msg.includes('permission') || msg.includes('not authorized')) return false;
+    return null;
+  }
+}
+
+/**
+ * Single-quote a string for use in a shell command. Handles the
+ * embedded-single-quote case by closing → escaping → reopening.
+ */
+function shellQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+/** Freeze every level of a nested object. */
+function deepFreeze(obj) {
+  Object.values(obj).forEach(v => {
+    if (v && typeof v === 'object' && !Object.isFrozen(v)) deepFreeze(v);
+  });
+  return Object.freeze(obj);
+}