simframe 0.6.1 → 0.7.0

package/src/platform/host.js

@@ -0,0 +1,15 @@
+// Host-side tools, shared by every backend.
+//
+// `resize` was on the Phase 8 list of eleven platform functions and does not
+// belong there: it downscales a PNG file with sips and never touches a device.
+// Behind the platform boundary it would have to be declared once per backend,
+// identically, for no reason. Here both backends get it and neither owns it.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/** Resample with sips, which ships with macOS, so simframe needs no image deps. */
+export async function resize(inFile, outFile, maxDim) {
+  await run('sips', ['-Z', String(maxDim), inFile, '--out', outFile], { timeout: 10_000 });
+}

package/src/platform/index.js

@@ -0,0 +1,248 @@
+// The platform boundary.
+//
+// Above this line nothing knows what a simulator is. `src/index.js`,
+// `daemon.js`, `actions.js`, `mcp.js` and `cli.js` used to import
+// `src/simctl.js` directly — eleven functions and a constant, none of them
+// conceptually iOS: list devices, resolve one, launch and terminate an app,
+// open a URL, set the pasteboard, grant a permission, take a screenshot. Every
+// one has an `adb` equivalent, which is exactly why the boundary had to exist
+// before a second backend rather than beside it.
+//
+// The Swift half has had this since Phase 0: a 21-method `SimulatorPlatform`
+// protocol in `PrivateAPI`, with a stub implementation proving the protocol is
+// satisfiable by something that is not a simulator. `PLATFORM_SURFACE` below is
+// the same idea for JavaScript, and `test/unit.test.mjs` holds every registered
+// backend to it.
+//
+// **Dispatch is by device, not by a process-wide default.** A device is iOS or
+// Android; nothing about the host decides which. So `listDevices` unions the
+// backends and stamps each record with the platform it came from, and every
+// function that takes a udid routes on that udid — `ownsUdid` answers that from
+// the id's own shape, because the question is asked from inside a capture loop
+// in a process that never listed anything.
+import { platform as android } from './android.js';
+import { platform as ios } from './ios.js';
+
+export { resize } from './host.js';
+
+/**
+ * @typedef {object} Device
+ * @property {string} udid
+ * @property {string} name
+ * @property {string} runtime
+ * @property {string} state    'Booted' when the device can be driven
+ * @property {string} platform stamped by the seam, never by the backend
+ */
+
+/**
+ * @typedef {object} Platform
+ * @property {string} id
+ * @property {string} deviceNoun            what to call a device in user-facing text
+ * @property {(opts?: object) => Promise<Device[]>} listDevices
+ * @property {(opts?: object) => Promise<Device[]>} bootedDevices
+ * @property {(query?: string, opts?: object) => Promise<Device>} resolveDevice
+ * @property {(udid: string) => boolean} isBootedSync
+ * @property {(udid: string) => boolean} ownsUdid   sync, no I/O — see ios.js
+ * @property {Function} geometry     the device's real point size, or null if this backend cannot say
+ * @property {Function} inputDriver  this backend's own input path, or null if input comes from above
+ * @property {Function} screenshot
+ * @property {Function} launchApp
+ * @property {Function} terminateApp
+ * @property {Function} openUrl
+ * @property {Function} setPermission
+ * @property {Function} setPasteboard
+ * @property {() => string[]} permissionServices
+ * @property {() => {captureEngines: string[], input: object, ax: object}} capabilities
+ * @property {() => Array<{name: string, level: string, detail: string}>} toolchain
+ */
+
+/** Every member a backend must provide. A backend missing one fails a test, not a user. */
+export const PLATFORM_SURFACE = Object.freeze([
+  'id', 'deviceNoun',
+  'listDevices', 'bootedDevices', 'resolveDevice', 'isBootedSync', 'ownsUdid',
+  'geometry', 'inputDriver',
+  'screenshot', 'launchApp', 'terminateApp', 'openUrl',
+  'setPermission', 'setPasteboard', 'permissionServices', 'capabilities', 'toolchain',
+]);
+
+/** @type {Record<string, Platform>} */
+export const PLATFORMS = Object.freeze({ ios, android });
+
+/** @returns {Platform[]} in registration order, which is the order devices are listed in. */
+export function backends() {
+  return Object.values(PLATFORMS);
+}
+
+// udid → platform id, learned from every listing and every resolve. A device
+// cannot change platform, so this never goes stale and never needs clearing.
+const learned = new Map();
+
+/**
+ * Which backend owns this device.
+ *
+ * Synchronous by requirement: `isBootedSync` is called from the capture loop,
+ * in a daemon process that was handed a udid and never listed anything. So the
+ * answer comes from what a listing already taught us, or from the id's own
+ * shape, and never from the device.
+ *
+ * With one backend registered an unrecognised id still routes there, so a
+ * typo'd udid gets simctl's own error rather than one from the seam — which is
+ * what it got before the seam existed.
+ *
+ * @returns {Platform}
+ */
+export function platformFor(udid) {
+  return chooseBackend(udid, backends());
+}
+
+/**
+ * The routing decision itself, over a given set of backends, so it can be
+ * tested against two of them before a second one exists. Everything here is a
+ * decision about *which* backend; nothing here talks to a device.
+ */
+export function chooseBackend(udid, all) {
+  const remembered = learned.get(udid);
+  const known = all.find((b) => b.id === remembered);
+  if (known) return known;
+  const claimed = all.filter((b) => b.ownsUdid(udid));
+  if (claimed.length === 1) return claimed[0];
+  if (claimed.length === 0 && all.length === 1) return all[0];
+  throw new Error(
+    claimed.length > 1
+      ? `device id "${udid}" is claimed by ${claimed.map((b) => b.id).join(' and ')}`
+      : `no platform recognises the device id "${udid}" (tried ${all.map((b) => b.id).join(', ')})`,
+  );
+}
+
+/** Stamp the platform onto a record without mutating a backend's cached copy. */
+function stamp(device, backend) {
+  learned.set(device.udid, backend.id);
+  return { ...device, platform: backend.id };
+}
+
+/** Every device every backend can see, in registration order. @returns {Promise<Device[]>} */
+export async function listDevices(opts) {
+  const out = [];
+  for (const backend of backends()) {
+    for (const device of await backend.listDevices(opts)) out.push(stamp(device, backend));
+  }
+  return out;
+}
+
+/** @returns {Promise<Device[]>} */
+export async function bootedDevices(opts) {
+  const out = [];
+  for (const backend of backends()) {
+    for (const device of await backend.bootedDevices(opts)) out.push(stamp(device, backend));
+  }
+  return out;
+}
+
+/**
+ * Resolve a device string against every backend.
+ *
+ * A backend that finds nothing is passed over. A backend that finds the query
+ * *ambiguous* is not: that error wins even when another backend matched
+ * exactly, because answering an ambiguous query with the other platform's
+ * device is the wrong-device bug wearing a different hat.
+ *
+ * Cross-platform ambiguity — one name matching a simulator and an emulator — is
+ * reported rather than guessed at. Which of them a bare query should prefer is
+ * a question for the step that adds the second backend, not one to invent an
+ * answer to here.
+ *
+ * @returns {Promise<Device>}
+ */
+export async function resolveDevice(query, opts) {
+  return resolveAcross(query, opts, backends());
+}
+
+/** As above, over a given set of backends — the testable half. @returns {Promise<Device>} */
+export async function resolveAcross(query, opts, all) {
+  const hits = [];
+  const misses = [];
+  for (const backend of all) {
+    try {
+      hits.push(stamp(await backend.resolveDevice(query, opts), backend));
+    } catch (err) {
+      if (err?.ambiguous) throw err;
+      misses.push(err);
+    }
+  }
+  if (hits.length === 1) return hits[0];
+  if (hits.length > 1) {
+    throw new Error(
+      `"${query}" matches a device on more than one platform: ` +
+        `${hits.map((d) => `${d.name} (${d.platform})`).join(', ')} — name one by its id`,
+    );
+  }
+  // One backend: its own message, unchanged. It is the better message, because
+  // it knows what it looked in.
+  if (misses.length === 1) throw misses[0];
+  throw new Error(misses.map((e) => e.message).join('; '));
+}
+
+// Device-keyed dispatch. The udid is passed through as well as routed on:
+// backends keep the signatures they always had, and the seam decides which
+// backend a call reaches, never what the call means.
+export const isBootedSync = (udid, ...args) => platformFor(udid).isBootedSync(udid, ...args);
+export const screenshot = (udid, ...args) => platformFor(udid).screenshot(udid, ...args);
+export const launchApp = (udid, ...args) => platformFor(udid).launchApp(udid, ...args);
+export const terminateApp = (udid, ...args) => platformFor(udid).terminateApp(udid, ...args);
+export const openUrl = (udid, ...args) => platformFor(udid).openUrl(udid, ...args);
+export const setPermission = (udid, ...args) => platformFor(udid).setPermission(udid, ...args);
+export const setPasteboard = (udid, ...args) => platformFor(udid).setPasteboard(udid, ...args);
+
+/**
+ * The permission services a device understands, or every service any backend
+ * understands when no device is named.
+ *
+ * simctl's list has no Android meaning and Android's has no iOS meaning, so the
+ * unioned form is only honest as a menu — `setPermission` validates against the
+ * backend that will actually run it. `docs/DEFERRED.md` has the open question:
+ * the two platforms do not have the same permissions, and the MCP tool
+ * description is written once, before any device is chosen.
+ */
+export function permissionServices(udid) {
+  if (udid !== undefined) return platformFor(udid).permissionServices();
+  const all = [];
+  for (const backend of backends()) {
+    for (const service of backend.permissionServices()) if (!all.includes(service)) all.push(service);
+  }
+  return all;
+}
+
+/**
+ * The device's real point size and scale, or null when the backend cannot say
+ * and something above the boundary has to.
+ *
+ * Android's only source for this is the backend, and without it the geometry
+ * fell through to a guess derived from the capture image — an emulator reported
+ * "393x700pt", which is the ring size and not any coordinate space the device
+ * knows. Tap points computed from that are wrong, and nothing says so.
+ */
+export const geometryFor = (udid) => platformFor(udid).geometry(udid);
+
+/**
+ * The backend's own input path, or null when input comes from above the
+ * boundary. iOS is null: Indigo HID lives in the daemon, which is simframe's
+ * engine rather than the platform's. Android is the emulator console.
+ */
+export const inputDriverFor = (udid) => platformFor(udid).inputDriver(udid);
+
+/**
+ * What a device's platform can currently do: which capture engines it has, and
+ * whether input and the accessibility tree are implemented for it at all.
+ *
+ * This exists because doctor, asked about an Android emulator, reported "input
+ * driver: idb" and "accessibility tree: idb" — a claim about a tool that has
+ * never spoken to an Android device. A layer above the boundary must not
+ * describe a device in the other platform's terms, and the only way it can
+ * avoid that is to ask.
+ */
+export const capabilitiesFor = (udid) => platformFor(udid).capabilities();
+
+/** What `simframe doctor` should check: each registered backend's own toolchain. */
+export function toolchainChecks() {
+  return backends().flatMap((backend) => backend.toolchain());
+}

package/src/{simctl.js → platform/ios.js}

@@ -1,4 +1,9 @@
-// Everything that shells out to Xcode's command line tools.
+// The iOS backend: everything that shells out to Xcode's command line tools.
+//
+// Nothing outside src/platform/ may import this file. Callers go through
+// src/platform/index.js, which is why every function here is module-private
+// and reachable only through the `platform` object at the bottom — the
+// JavaScript counterpart of the `SimulatorPlatform` protocol in Swift.
 import { execFile, execFileSync } from 'node:child_process';
 import { promisify } from 'node:util';
 
@@ -10,7 +15,7 @@ const DEVICE_CACHE_MS = 4000;
 let deviceCache = { at: 0, devices: null, inflight: null };
 
 /** @returns {Promise<Array<{udid: string, name: string, runtime: string, state: string}>>} */
-export async function listDevices({ maxAgeMs = DEVICE_CACHE_MS } = {}) {
+async function listDevices({ maxAgeMs = DEVICE_CACHE_MS } = {}) {
   if (deviceCache.devices && Date.now() - deviceCache.at <= maxAgeMs) return deviceCache.devices;
   if (deviceCache.inflight) return deviceCache.inflight;
   deviceCache.inflight = fetchDevices()
@@ -47,7 +52,7 @@ async function fetchDevices() {
   return out;
 }
 
-export async function bootedDevices(opts) {
+async function bootedDevices(opts) {
   return (await listDevices(opts)).filter((d) => d.state === 'Booted');
 }
 
@@ -56,7 +61,7 @@ export async function bootedDevices(opts) {
  * booted device. Prefers booted devices; falls back to a clear error listing
  * what is actually available.
  */
-export async function resolveDevice(query, opts) {
+async function resolveDevice(query, opts) {
   const all = await listDevices(opts);
   const booted = all.filter((d) => d.state === 'Booted');
   if (!query) {
@@ -71,13 +76,19 @@ export async function resolveDevice(query, opts) {
     const partial = pool.filter((d) => d.name.toLowerCase().includes(q));
     if (partial.length === 1) return partial[0];
     if (partial.length > 1) {
-      throw new Error(`"${query}" matches ${partial.length} devices: ${partial.map((d) => d.name).join(', ')}`);
+      // Marked, because the seam asks every backend to resolve and must not
+      // answer with an Android device when the query was ambiguous here. A
+      // plain "no match" may be passed over; an ambiguity may not.
+      throw Object.assign(
+        new Error(`"${query}" matches ${partial.length} devices: ${partial.map((d) => d.name).join(', ')}`),
+        { ambiguous: true },
+      );
     }
   }
   throw new Error(`no simulator matches "${query}"; booted: ${booted.map((d) => d.name).join(', ') || 'none'}`);
 }
 
-export function isBootedSync(udid) {
+function isBootedSync(udid) {
   try {
     const out = execFileSync('xcrun', ['simctl', 'list', 'devices', '--json'], {
       maxBuffer: 8 << 20,
@@ -95,7 +106,7 @@ export function isBootedSync(udid) {
   return false;
 }
 
-export async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
+async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
   try {
     await run('xcrun', ['simctl', 'io', udid, 'screenshot', '--type=png', `--mask=${mask}`, outFile], {
       timeout: 10_000,
@@ -109,11 +120,6 @@ export async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
   }
 }
 
-/** Resample with sips, which ships with macOS, so simframe needs no image deps. */
-export async function resize(inFile, outFile, maxDim) {
-  await run('sips', ['-Z', String(maxDim), inFile, '--out', outFile], { timeout: 10_000 });
-}
-
 /**
  * Launch, optionally with arguments and environment.
  *
@@ -121,7 +127,7 @@ export async function resize(inFile, outFile, maxDim) {
  * `SIMCTL_CHILD_`-prefixed variables of its own process — which is why env has
  * to be set on the child rather than passed as flags.
  */
-export async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst = false } = {}) {
+async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst = false } = {}) {
   if (terminateFirst) {
     // A launch against an already-running app is a no-op that reports success,
     // which is how a flow "relaunched" an app and tested the screen it was
@@ -148,15 +154,15 @@ export async function launchApp(udid, bundleId, { args = [], env = {}, terminate
   }
 }
 
-export async function terminateApp(udid, bundleId) {
+async function terminateApp(udid, bundleId) {
   await run('xcrun', ['simctl', 'terminate', udid, bundleId], { timeout: 20_000 });
 }
 
-export async function openUrl(udid, url) {
+async function openUrl(udid, url) {
   await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: 20_000 });
 }
 
-export const PERMISSION_SERVICES = [
+const PERMISSION_SERVICES = [
   'all', 'calendar', 'contacts-limited', 'contacts', 'location', 'location-always',
   'photos-add', 'photos', 'media-library', 'microphone', 'motion', 'reminders', 'siri',
 ];
@@ -168,7 +174,7 @@ export const PERMISSION_SERVICES = [
  * tapping a system alert, and a system alert is not part of the app under test:
  * its buttons move between iOS versions and its appearance is a race.
  */
-export async function setPermission(udid, action, service, bundleId) {
+async function setPermission(udid, action, service, bundleId) {
   const verb = String(action).toLowerCase();
   if (!['grant', 'revoke', 'reset'].includes(verb)) {
     throw new Error(`permission action must be grant, revoke or reset (got "${action}")`);
@@ -188,7 +194,7 @@ export async function setPermission(udid, action, service, bundleId) {
 }
 
 /** Put text on the device pasteboard — far faster than typing a long string. */
-export async function setPasteboard(udid, value) {
+async function setPasteboard(udid, value) {
   const child = execFile('xcrun', ['simctl', 'pbcopy', udid], { timeout: 10_000 });
   child.stdin.end(value);
   await new Promise((resolve, reject) => {
@@ -196,3 +202,90 @@ export async function setPasteboard(udid, value) {
     child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`pbcopy exited ${code}`))));
   });
 }
+
+/**
+ * Does this backend own that device id, judged without touching the device?
+ *
+ * The routing question is asked from inside a capture loop and from a daemon
+ * process that never resolved the device itself, so it has to be answered
+ * synchronously and for free. A simulator udid is a UUID; an emulator serial
+ * (`emulator-5554`) is not, and cannot be mistaken for one.
+ */
+function ownsUdid(udid) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(udid ?? ''));
+}
+
+/**
+ * The prerequisites `simframe doctor` reports for this backend. Returned rather
+ * than printed so doctor stays one renderer: a backend says what it needs, and
+ * a machine missing it is told which tool, not which platform.
+ */
+function toolchain() {
+  try {
+    const version = execFileSync('xcrun', ['--version'], { encoding: 'utf8' }).trim().split('\n')[0];
+    return [{ name: 'xcrun', level: 'ok', detail: version }];
+  } catch (err) {
+    return [{ name: 'xcrun', level: 'fail', detail: err.message }];
+  }
+}
+
+/**
+ * iOS geometry does not come from here.
+ *
+ * The daemon holds the device's own point size and scale and is both
+ * authoritative and free, and idb can answer when the daemon cannot. Both sit
+ * above this boundary, so this backend has nothing to add — and returning null
+ * says that, where a guess would have been believed.
+ */
+function geometry() {
+  return null;
+}
+
+/**
+ * Nor does iOS input.
+ *
+ * It is Indigo HID inside `simframed`, reached over the control socket: that is
+ * simframe's own engine, not something the platform provides. Android's input
+ * *is* the platform's — the emulator console — which is why this is a question
+ * a backend gets asked at all.
+ */
+function inputDriver() {
+  return null;
+}
+
+/**
+ * What this backend can currently do, so nothing above the boundary has to
+ * assume. iOS has both capture engines, input through Indigo HID and the
+ * accessibility tree through AXPTranslator — which is to say, everything, and
+ * that is exactly why the shape of this was invisible until a second backend
+ * turned up without it.
+ */
+function capabilities() {
+  return {
+    captureEngines: ['simframed', 'screenshot'],
+    input: { supported: true, via: 'daemon' },
+    ax: { supported: true },
+  };
+}
+
+/** @type {import('./index.js').Platform} */
+export const platform = {
+  id: 'ios',
+  deviceNoun: 'simulator',
+  listDevices,
+  bootedDevices,
+  resolveDevice,
+  isBootedSync,
+  ownsUdid,
+  geometry,
+  inputDriver,
+  screenshot,
+  launchApp,
+  terminateApp,
+  openUrl,
+  setPermission,
+  setPasteboard,
+  permissionServices: () => PERMISSION_SERVICES,
+  capabilities,
+  toolchain,
+};

package/src/screenmap.js

@@ -16,7 +16,7 @@ import * as regions from './regions.js';
 import { informative } from './refs.js';
 import * as store from './store.js';
 
-const MAP_VERSION = 6; // dates, prices and phone numbers no longer contribute labels
+const MAP_VERSION = 7; // footprintless elements and containers no longer enter identity
 
 function mapDir(udid) {
   return path.join(store.deviceDir(udid), 'screens');

package/src/store.js

@@ -30,9 +30,41 @@ export function paths(udid) {
     heartbeat: path.join(dir, 'heartbeat'),
     log: path.join(dir, 'daemon.log'),
     lock: path.join(dir, 'daemon.lock'),
+    // Written by whichever capture loop is running, and only when capture is
+    // wedged. It cannot ride in state.json: that is written when a frame is
+    // recorded, and a stall is the absence of frames.
+    captureHealth: path.join(dir, 'capture-health.json'),
   };
 }
 
+/** What the capture loop last said about its own health, or null if it has no complaint. */
+export function captureHealth(udid) {
+  return readJson(paths(udid).captureHealth);
+}
+
+/**
+ * Publish a complaint, or clear it with `null`.
+ *
+ * The directory is created rather than assumed. A capture loop has always made
+ * it already, so the first version of this left it out and swallowed the
+ * failure — which meant the write silently did nothing for every other caller,
+ * and the test that caught it was the first thing to ask.
+ */
+export function writeCaptureHealth(udid, health) {
+  const p = paths(udid);
+  try {
+    if (health) {
+      fs.mkdirSync(p.dir, { recursive: true });
+      writeAtomic(p.captureHealth, JSON.stringify(health));
+    } else {
+      fs.rmSync(p.captureHealth, { force: true });
+    }
+  } catch {
+    // Never let bookkeeping stop capture. Anything that reaches here has
+    // already failed to make a directory, which capture itself will report.
+  }
+}
+
 export function ensureDirs(udid) {
   const p = paths(udid);
   fs.mkdirSync(p.ring, { recursive: true });