@yoqa/runner 0.3.16 → 0.3.18

package/dist/index.js

@@ -16801,7 +16801,7 @@ function getCatalogDb() {
 // package.json
 var package_default = {
   name: "@yoqa/runner",
-  version: "0.3.16",
+  version: "0.3.18",
   description: "Yoqa local runner \u2014 Appium + catalog HTTP API (Bun). Start with yoqa serve or the yoqa-runner bin.",
   license: "UNLICENSED",
   type: "module",
@@ -16896,11 +16896,458 @@ function abortAllMjpegProxies() {
 import { mkdir as mkdir3 } from "fs/promises";
 import { createServer as createServer2 } from "net";
 import { homedir as homedir6 } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { remote } from "webdriverio";
-var YOQA_ROOT4 = join6(homedir6(), ".yoqa");
+
+// src/domains/devices/application.ts
+import { mkdtemp as mkdtemp2, readFile, rm as rm2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join6 } from "path";
+
+// src/domains/devices/android-identity.ts
+function matchAndroidAppiumIdentity(deviceId, connected, knownAvds = []) {
+  const id = deviceId.trim();
+  if (!id)
+    return {};
+  const bySerial = connected.find((device) => device.serial === id);
+  if (bySerial) {
+    return {
+      udid: bySerial.serial,
+      ...bySerial.avdName ? { avd: bySerial.avdName } : {}
+    };
+  }
+  const byAvd = connected.find((device) => device.avdName === id);
+  if (byAvd) {
+    return { udid: byAvd.serial, avd: byAvd.avdName ?? id };
+  }
+  if (knownAvds.includes(id)) {
+    return { avd: id };
+  }
+  return { udid: id };
+}
+function parseAdbEmuAvdName(stdout) {
+  const name = stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line && line !== "OK");
+  return name || null;
+}
+
+// src/domains/devices/application.ts
+async function runCommand3(command, options) {
+  try {
+    const proc = Bun.spawn(command, {
+      env: options?.env ? { ...process.env, ...options.env } : process.env,
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    return { stdout, stderr, exitCode };
+  } catch {
+    return { stdout: "", stderr: `failed to spawn: ${command[0]}`, exitCode: 127 };
+  }
+}
+function androidSdkRoot() {
+  return resolveAndroidSdkRoot();
+}
+async function resolveTool(candidates) {
+  for (const candidate of candidates) {
+    if (!candidate)
+      continue;
+    const { exitCode } = await runCommand3(["test", "-x", candidate]);
+    if (exitCode === 0)
+      return candidate;
+  }
+  return null;
+}
+async function resolveAdb() {
+  const sdk = androidSdkRoot();
+  return resolveTool([...sdk ? [join6(sdk, "platform-tools/adb")] : [], "adb"]);
+}
+async function resolveEmulator() {
+  const sdk = androidSdkRoot();
+  return resolveTool([...sdk ? [join6(sdk, "emulator/emulator")] : [], "emulator"]);
+}
+function formatIosVersion(version2) {
+  const trimmed = version2.trim();
+  if (!trimmed)
+    return "iOS";
+  if (/^iOS\b/i.test(trimmed))
+    return trimmed;
+  return `iOS ${trimmed}`;
+}
+function formatAndroidVersion(apiOrVersion) {
+  const trimmed = apiOrVersion.trim();
+  if (!trimmed)
+    return "Android";
+  if (/^Android\b/i.test(trimmed))
+    return trimmed;
+  if (/^API\b/i.test(trimmed))
+    return trimmed;
+  if (/^\d+(\.\d+)?$/.test(trimmed))
+    return `API ${trimmed}`;
+  return `Android ${trimmed}`;
+}
+function titleCaseWords(value) {
+  return value.split(/\s+/).filter(Boolean).map((word) => {
+    if (/^[a-z]$/i.test(word))
+      return word.toUpperCase();
+    if (/^\d/.test(word))
+      return word;
+    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+  }).join(" ");
+}
+function runtimeVersionFromIdentifier(runtimeId) {
+  const match = runtimeId.match(/iOS-([\d-]+)$/i);
+  if (!match?.[1])
+    return "iOS";
+  return formatIosVersion(match[1].replace(/-/g, "."));
+}
+async function listIosSimulators(includeUnavailable) {
+  const { stdout, exitCode } = await runCommand3([
+    "xcrun",
+    "simctl",
+    "list",
+    "devices",
+    "available",
+    "-j"
+  ]);
+  if (exitCode !== 0)
+    return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+  const devices = [];
+  for (const [runtimeId, runtimeDevices] of Object.entries(parsed.devices ?? {})) {
+    if (!/iOS/i.test(runtimeId))
+      continue;
+    const osVersion = runtimeVersionFromIdentifier(runtimeId);
+    for (const device of runtimeDevices) {
+      if (!device.udid || !device.name)
+        continue;
+      if (device.isAvailable === false)
+        continue;
+      const state = device.state ?? "Unknown";
+      if (!includeUnavailable && state !== "Booted")
+        continue;
+      devices.push({
+        id: device.udid,
+        name: device.name,
+        osVersion,
+        platform: "ios",
+        kind: "simulator",
+        state,
+        model: device.deviceTypeIdentifier?.split(".").pop()?.replace(/-/g, " ")
+      });
+    }
+  }
+  return devices.sort((a, b) => {
+    if (a.state === "Booted" && b.state !== "Booted")
+      return -1;
+    if (b.state === "Booted" && a.state !== "Booted")
+      return 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+function isPhoneOrTablet(deviceType) {
+  if (!deviceType)
+    return false;
+  return /^(iPhone|iPad)$/i.test(deviceType);
+}
+function physicalIosState(connection) {
+  const tunnel = connection?.tunnelState?.toLowerCase() ?? "";
+  if (tunnel.includes("connected"))
+    return "connected";
+  if (tunnel.includes("unavailable"))
+    return "unavailable";
+  if (tunnel.includes("disconnected"))
+    return "disconnected";
+  if (connection?.pairingState === "paired")
+    return "paired";
+  return tunnel || connection?.pairingState || "unknown";
+}
+async function listIosPhysicalDevices(includeUnavailable) {
+  const dir = await mkdtemp2(join6(tmpdir2(), "yoqa-devices-"));
+  const jsonPath = join6(dir, "devices.json");
+  try {
+    const { exitCode } = await runCommand3([
+      "xcrun",
+      "devicectl",
+      "list",
+      "devices",
+      "--json-output",
+      jsonPath
+    ]);
+    if (exitCode !== 0)
+      return [];
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile(jsonPath, "utf8"));
+    } catch {
+      return [];
+    }
+    const devices = [];
+    for (const item of parsed.result?.devices ?? []) {
+      const hardware = item.hardwareProperties;
+      const props = item.deviceProperties;
+      if (!hardware?.udid)
+        continue;
+      if (hardware.reality && hardware.reality !== "physical")
+        continue;
+      if (!isPhoneOrTablet(hardware.deviceType))
+        continue;
+      if (hardware.platform && !/^iOS$/i.test(hardware.platform))
+        continue;
+      const state = physicalIosState(item.connectionProperties);
+      if (!includeUnavailable && state === "unavailable")
+        continue;
+      const modelName = hardware.marketingName ?? hardware.productType ?? "iPhone";
+      const owner = props?.name?.trim() || undefined;
+      devices.push({
+        id: hardware.udid,
+        name: modelName,
+        owner,
+        osVersion: formatIosVersion(props?.osVersionNumber ?? ""),
+        platform: "ios",
+        kind: "physical",
+        state,
+        model: hardware.productType
+      });
+    }
+    return devices.sort((a, b) => a.name.localeCompare(b.name));
+  } finally {
+    await rm2(dir, { recursive: true, force: true });
+  }
+}
+async function listIosDevices(options = {}) {
+  const includeUnavailable = options.includeUnavailable ?? true;
+  const [physical, simulators] = await Promise.all([
+    listIosPhysicalDevices(includeUnavailable),
+    listIosSimulators(includeUnavailable)
+  ]);
+  return [...physical, ...simulators];
+}
+function parseAdbDevices(output) {
+  const lines = output.split(`
+`).map((line) => line.trim()).filter(Boolean);
+  const results = [];
+  for (const line of lines) {
+    if (line.startsWith("List of devices"))
+      continue;
+    const parts = line.split(/\s+/);
+    const serial = parts[0];
+    const state = parts[1];
+    if (!serial || !state)
+      continue;
+    const meta = {};
+    for (const part of parts.slice(2)) {
+      const eq2 = part.indexOf(":");
+      if (eq2 <= 0)
+        continue;
+      meta[part.slice(0, eq2)] = part.slice(eq2 + 1);
+    }
+    results.push({
+      serial,
+      state,
+      product: meta.product,
+      model: meta.model,
+      device: meta.device,
+      transportId: meta.transport_id
+    });
+  }
+  return results;
+}
+function humanizeAvdName(avdName) {
+  return titleCaseWords(avdName.replace(/_/g, " "));
+}
+function humanizeModel(model) {
+  if (!model)
+    return;
+  return titleCaseWords(model.replace(/_/g, " "));
+}
+async function findAvdConfigPath(avdName) {
+  const home = process.env.HOME ?? "";
+  const roots = [join6(home, ".android/avd"), join6(home, "Library/Android/sdk/.android/avd")];
+  for (const root of roots) {
+    const direct = join6(root, `${avdName}.avd`, "config.ini");
+    try {
+      await readFile(direct, "utf8");
+      return direct;
+    } catch {}
+    try {
+      const glob = new Bun.Glob("*.avd/config.ini");
+      for await (const match of glob.scan({ cwd: root, onlyFiles: true })) {
+        const path = join6(root, match);
+        const text2 = await readFile(path, "utf8");
+        const idLine = text2.split(`
+`).find((line) => line.startsWith("AvdId="));
+        const id = idLine?.slice("AvdId=".length).trim();
+        if (id === avdName)
+          return path;
+      }
+    } catch {}
+  }
+  return null;
+}
+async function readAvdConfig(avdName) {
+  const path = await findAvdConfigPath(avdName);
+  if (!path)
+    return { api: null, deviceName: null };
+  try {
+    const text2 = await readFile(path, "utf8");
+    const imageLine = text2.split(`
+`).find((line) => line.includes("system-images") && line.includes("android-"));
+    const apiMatch = imageLine?.match(/android-([\d.]+)/);
+    const deviceLine = text2.split(`
+`).find((entry) => entry.startsWith("hw.device.name="));
+    const deviceRaw = deviceLine?.slice("hw.device.name=".length).trim();
+    return {
+      api: apiMatch?.[1] ?? null,
+      deviceName: humanizeModel(deviceRaw) ?? null
+    };
+  } catch {
+    return { api: null, deviceName: null };
+  }
+}
+async function adbAvdName(adb, serial) {
+  const fromProp = await adbGetProp(adb, serial, "ro.boot.qemu.avd_name") ?? await adbGetProp(adb, serial, "ro.kernel.qemu.avd_name");
+  if (fromProp)
+    return fromProp;
+  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "emu", "avd", "name"]);
+  if (exitCode !== 0)
+    return null;
+  return parseAdbEmuAvdName(stdout);
+}
+async function adbGetProp(adb, serial, prop) {
+  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "shell", "getprop", prop]);
+  if (exitCode !== 0)
+    return null;
+  const value = stdout.trim();
+  return value || null;
+}
+async function listAndroidAdbDevices(adb) {
+  const { stdout, exitCode } = await runCommand3([adb, "devices", "-l"]);
+  if (exitCode !== 0) {
+    return { physical: [], runningEmulators: [], runningAvdNames: new Set };
+  }
+  const entries = parseAdbDevices(stdout);
+  const physical = [];
+  const runningEmulators = [];
+  const runningAvdNames = new Set;
+  for (const entry of entries) {
+    const isEmulator = entry.serial.startsWith("emulator-") || entry.product === "sdk_gphone";
+    if (isEmulator) {
+      const avdName = await adbAvdName(adb, entry.serial);
+      if (avdName)
+        runningAvdNames.add(avdName);
+      const avdConfig = avdName ? await readAvdConfig(avdName) : null;
+      const release2 = await adbGetProp(adb, entry.serial, "ro.build.version.release") ?? avdConfig?.api ?? null;
+      const model2 = humanizeModel(entry.model) ?? avdConfig?.deviceName ?? (avdName ? humanizeAvdName(avdName) : entry.serial);
+      runningEmulators.push({
+        id: avdName ?? entry.serial,
+        name: model2,
+        osVersion: formatAndroidVersion(release2 ?? ""),
+        platform: "android",
+        kind: "emulator",
+        state: entry.state === "device" ? "online" : entry.state,
+        model: avdName ?? entry.model
+      });
+      continue;
+    }
+    const release = await adbGetProp(adb, entry.serial, "ro.build.version.release");
+    const model = humanizeModel(entry.model) ?? await adbGetProp(adb, entry.serial, "ro.product.model") ?? entry.serial;
+    physical.push({
+      id: entry.serial,
+      name: model,
+      osVersion: formatAndroidVersion(release ?? ""),
+      platform: "android",
+      kind: "physical",
+      state: entry.state,
+      model: entry.model
+    });
+  }
+  return { physical, runningEmulators, runningAvdNames };
+}
+async function listAndroidAvds(emulatorBin, runningAvdNames, includeUnavailable) {
+  const { stdout, exitCode } = await runCommand3([emulatorBin, "-list-avds"]);
+  if (exitCode !== 0)
+    return [];
+  const names = stdout.split(`
+`).map((line) => line.trim()).filter(Boolean);
+  const devices = [];
+  for (const avdName of names) {
+    const isRunning = runningAvdNames.has(avdName);
+    if (!includeUnavailable && !isRunning)
+      continue;
+    if (isRunning)
+      continue;
+    const { api, deviceName } = await readAvdConfig(avdName);
+    devices.push({
+      id: avdName,
+      name: deviceName ?? humanizeAvdName(avdName),
+      osVersion: formatAndroidVersion(api ?? ""),
+      platform: "android",
+      kind: "emulator",
+      state: "offline",
+      model: avdName
+    });
+  }
+  return devices;
+}
+async function resolveAndroidAppiumIdentity(deviceId) {
+  const [adb, emulatorBin] = await Promise.all([resolveAdb(), resolveEmulator()]);
+  const connected = [];
+  if (adb) {
+    const { stdout, exitCode } = await runCommand3([adb, "devices", "-l"]);
+    if (exitCode === 0) {
+      for (const entry of parseAdbDevices(stdout)) {
+        const isEmulator = entry.serial.startsWith("emulator-") || entry.product === "sdk_gphone";
+        connected.push({
+          serial: entry.serial,
+          avdName: isEmulator ? await adbAvdName(adb, entry.serial) : null
+        });
+      }
+    }
+  }
+  const knownAvds = [];
+  if (emulatorBin) {
+    const { stdout, exitCode } = await runCommand3([emulatorBin, "-list-avds"]);
+    if (exitCode === 0) {
+      knownAvds.push(...stdout.split(`
+`).map((line) => line.trim()).filter(Boolean));
+    }
+  }
+  return matchAndroidAppiumIdentity(deviceId, connected, knownAvds);
+}
+async function listAndroidDevices(options = {}) {
+  const includeUnavailable = options.includeUnavailable ?? true;
+  const [adb, emulatorBin] = await Promise.all([resolveAdb(), resolveEmulator()]);
+  const adbResult = adb ? await listAndroidAdbDevices(adb) : { physical: [], runningEmulators: [], runningAvdNames: new Set };
+  const offlineAvds = emulatorBin != null ? await listAndroidAvds(emulatorBin, adbResult.runningAvdNames, includeUnavailable) : [];
+  const physical = includeUnavailable ? adbResult.physical : adbResult.physical.filter((device) => device.state === "device");
+  const emulators = [...adbResult.runningEmulators, ...offlineAvds].sort((a, b) => {
+    const aOnline = a.state === "online" ? 0 : 1;
+    const bOnline = b.state === "online" ? 0 : 1;
+    if (aOnline !== bOnline)
+      return aOnline - bOnline;
+    return a.name.localeCompare(b.name);
+  });
+  return [...physical, ...emulators];
+}
+async function listDevices(platform, options = {}) {
+  if (platform === "ios")
+    return listIosDevices(options);
+  return listAndroidDevices(options);
+}
+
+// src/domains/devices/session.ts
+var YOQA_ROOT4 = join7(homedir6(), ".yoqa");
 var DEFAULT_MJPEG_PORT = Number(process.env.YOQA_MJPEG_PORT ?? "9100");
-var SCREENSHOT_DIR = join6(YOQA_ROOT4, "runs", "screenshots");
+var SCREENSHOT_DIR = join7(YOQA_ROOT4, "runs", "screenshots");
 var MJPEG_SETTINGS_BASE = {
   mjpegServerScreenshotQuality: 35,
   mjpegScalingFactor: 50
@@ -17020,8 +17467,11 @@ function mergeCapabilities(appCaps, caseCaps) {
 function looksLikePhysicalIosUdid(udid) {
   return /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{16}$/.test(udid.trim());
 }
+var PHYSICAL_IOS_SESSION_TIMEOUT_MS = 60000;
+var SIMULATOR_WDA_SESSION_TIMEOUT_MS = 600000;
+var SIMULATOR_WDA_DERIVED_DATA = join7(YOQA_ROOT4, "wda-sim");
 function iosSessionCreateTimeoutMs(deviceId) {
-  return looksLikePhysicalIosUdid(deviceId) ? 60000 : 240000;
+  return looksLikePhysicalIosUdid(deviceId) ? PHYSICAL_IOS_SESSION_TIMEOUT_MS : SIMULATOR_WDA_SESSION_TIMEOUT_MS;
 }
 async function buildW3cCapabilities(options, mjpegPort) {
   const merged = mergeCapabilities(options.appCaps, options.caseCaps);
@@ -17030,18 +17480,17 @@ async function buildW3cCapabilities(options, mjpegPort) {
   const caps = {
     platformName,
     "appium:automationName": automationName,
-    "appium:udid": options.deviceId,
     "appium:newCommandTimeout": 3600,
     "appium:mjpegServerPort": mjpegPort,
     ...Object.fromEntries(Object.entries(merged).map(([key, value]) => key.includes(":") ? [key, value] : [`appium:${key}`, value]))
   };
-  if (options.platform === "ios" && options.bundleId && !caps["appium:bundleId"]) {
-    caps["appium:bundleId"] = options.bundleId;
-  }
-  if (options.platform === "android" && options.appPackage && !caps["appium:appPackage"]) {
-    caps["appium:appPackage"] = options.appPackage;
-  }
   if (options.platform === "ios") {
+    if (caps["appium:udid"] === undefined) {
+      caps["appium:udid"] = options.deviceId;
+    }
+    if (options.bundleId && !caps["appium:bundleId"]) {
+      caps["appium:bundleId"] = options.bundleId;
+    }
     const physical = looksLikePhysicalIosUdid(options.deviceId);
     if (physical) {
       const prep = await loadDevicePrep(options.deviceId);
@@ -17071,6 +17520,23 @@ async function buildW3cCapabilities(options, mjpegPort) {
     if (caps["appium:waitForIdleTimeout"] === undefined) {
       caps["appium:waitForIdleTimeout"] = 0;
     }
+    if (!physical && caps["appium:derivedDataPath"] === undefined) {
+      await mkdir3(SIMULATOR_WDA_DERIVED_DATA, { recursive: true });
+      caps["appium:derivedDataPath"] = SIMULATOR_WDA_DERIVED_DATA;
+    }
+  }
+  if (options.platform === "android") {
+    const requested = String(caps["appium:udid"] ?? options.deviceId);
+    const identity = await resolveAndroidAppiumIdentity(requested);
+    if (identity.udid) {
+      caps["appium:udid"] = identity.udid;
+    }
+    if (identity.avd && caps["appium:avd"] === undefined) {
+      caps["appium:avd"] = identity.avd;
+    }
+    if (options.appPackage && !caps["appium:appPackage"]) {
+      caps["appium:appPackage"] = options.appPackage;
+    }
   }
   return caps;
 }
@@ -17362,7 +17828,7 @@ async function createDeviceSession(options) {
   const screenshot = async () => {
     await mkdir3(SCREENSHOT_DIR, { recursive: true });
     const frame = await captureFrame();
-    const path = join6(SCREENSHOT_DIR, `shot_${Date.now()}_${crypto.randomUUID()}.png`);
+    const path = join7(SCREENSHOT_DIR, `shot_${Date.now()}_${crypto.randomUUID()}.png`);
     await Bun.write(path, Uint8Array.from(Buffer.from(frame.base64, "base64")));
     return { path, base64: frame.base64 };
   };
@@ -23551,13 +24017,24 @@ var caseFlowStepSchema = exports_external.object({
   flowId: exports_external.string().min(1).nullable().optional()
 });
 var caseRunStatusSchema = exports_external.union([exports_external.literal("passed"), exports_external.literal("errored")]);
-var caseScriptActionSchema = exports_external.discriminatedUnion("type", [
-  exports_external.object({
-    type: exports_external.literal("tap"),
-    x: exports_external.number().min(0).max(1000),
-    y: exports_external.number().min(0).max(1000),
-    reason: exports_external.string().optional()
-  }),
+var caseScriptTapSchema = exports_external.object({
+  type: exports_external.literal("tap"),
+  x: exports_external.number().min(0).max(1000).optional(),
+  y: exports_external.number().min(0).max(1000).optional(),
+  label: exports_external.string().min(1).optional(),
+  id: exports_external.string().min(1).optional(),
+  reason: exports_external.string().optional()
+}).superRefine((value, ctx) => {
+  const hasCoords = value.x != null && value.y != null;
+  if (!hasCoords && !value.label && !value.id) {
+    ctx.addIssue({
+      code: exports_external.ZodIssueCode.custom,
+      message: "tap requires x/y or label or id"
+    });
+  }
+});
+var caseScriptActionSchema = exports_external.union([
+  caseScriptTapSchema,
   exports_external.object({
     type: exports_external.literal("type"),
     text: exports_external.string(),
@@ -23567,6 +24044,13 @@ var caseScriptActionSchema = exports_external.discriminatedUnion("type", [
     type: exports_external.literal("wait"),
     ms: exports_external.number().min(0).max(1e4),
     reason: exports_external.string().optional()
+  }),
+  exports_external.object({
+    type: exports_external.literal("assert"),
+    assertion: exports_external.union([exports_external.literal("visible"), exports_external.literal("not-visible")]).default("visible"),
+    text: exports_external.string().min(1),
+    timeoutMs: exports_external.number().min(0).max(120000).optional(),
+    reason: exports_external.string().optional()
   })
 ]);
 var caseScriptSchema = exports_external.object({
@@ -23975,6 +24459,9 @@ var createBuildRequestSchema = exports_external.object({
 var listBuildsResponseSchema = exports_external.object({
   builds: exports_external.array(buildSchema)
 });
+
+// ../../packages/runner-client/src/wait-for-run.ts
+var DEFAULT_WAIT_FOR_RUN_TIMEOUT_MS = 30 * 60 * 1000;
 // ../../packages/runner-client/src/shell-script.ts
 var DEFAULT_SHELL_SCRIPT_HEADER = [
   "#!/usr/bin/env bash",
@@ -23984,6 +24471,16 @@ var DEFAULT_SHELL_SCRIPT_HEADER = [
   ""
 ].join(`
 `);
+function screenHasText(elements, text2) {
+  const needle = text2.trim().toLowerCase();
+  if (!needle)
+    return false;
+  return (elements ?? []).some((el) => {
+    const label = el.label?.toLowerCase() ?? "";
+    const type = el.type?.toLowerCase() ?? "";
+    return label.includes(needle) || type.includes(needle);
+  });
+}
 function findElementByLabel(elements, label) {
   const needle = label.trim().toLowerCase();
   if (!needle)
@@ -24155,8 +24652,13 @@ async function installBuildOnDevice(options) {
     }
     throw new Error(`Cannot install iOS build at ${build.path}. Use a .app on simulator or install .ipa via ideviceinstaller.`);
   }
+  const identity = await resolveAndroidAppiumIdentity(deviceId);
+  const serial = identity.udid;
+  if (!serial) {
+    throw new Error(`Android emulator ${deviceId} is not running. Boot it, then retry the install.`);
+  }
   const adb = Bun.which("adb") ?? "adb";
-  const proc = Bun.spawn([adb, "-s", deviceId, "install", "-r", build.path], {
+  const proc = Bun.spawn([adb, "-s", serial, "install", "-r", build.path], {
     stdout: "pipe",
     stderr: "pipe"
   });
@@ -24979,397 +25481,6 @@ function createCatalogRoutes() {
   return app;
 }
 
-// src/domains/devices/application.ts
-import { mkdtemp as mkdtemp2, readFile, rm as rm2 } from "fs/promises";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join7 } from "path";
-async function runCommand3(command, options) {
-  try {
-    const proc = Bun.spawn(command, {
-      env: options?.env ? { ...process.env, ...options.env } : process.env,
-      stdout: "pipe",
-      stderr: "pipe"
-    });
-    const [stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited
-    ]);
-    return { stdout, stderr, exitCode };
-  } catch {
-    return { stdout: "", stderr: `failed to spawn: ${command[0]}`, exitCode: 127 };
-  }
-}
-function androidSdkRoot() {
-  return resolveAndroidSdkRoot();
-}
-async function resolveTool(candidates) {
-  for (const candidate of candidates) {
-    if (!candidate)
-      continue;
-    const { exitCode } = await runCommand3(["test", "-x", candidate]);
-    if (exitCode === 0)
-      return candidate;
-  }
-  return null;
-}
-async function resolveAdb() {
-  const sdk = androidSdkRoot();
-  return resolveTool([...sdk ? [join7(sdk, "platform-tools/adb")] : [], "adb"]);
-}
-async function resolveEmulator() {
-  const sdk = androidSdkRoot();
-  return resolveTool([...sdk ? [join7(sdk, "emulator/emulator")] : [], "emulator"]);
-}
-function formatIosVersion(version2) {
-  const trimmed = version2.trim();
-  if (!trimmed)
-    return "iOS";
-  if (/^iOS\b/i.test(trimmed))
-    return trimmed;
-  return `iOS ${trimmed}`;
-}
-function formatAndroidVersion(apiOrVersion) {
-  const trimmed = apiOrVersion.trim();
-  if (!trimmed)
-    return "Android";
-  if (/^Android\b/i.test(trimmed))
-    return trimmed;
-  if (/^API\b/i.test(trimmed))
-    return trimmed;
-  if (/^\d+(\.\d+)?$/.test(trimmed))
-    return `API ${trimmed}`;
-  return `Android ${trimmed}`;
-}
-function titleCaseWords(value) {
-  return value.split(/\s+/).filter(Boolean).map((word) => {
-    if (/^[a-z]$/i.test(word))
-      return word.toUpperCase();
-    if (/^\d/.test(word))
-      return word;
-    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-  }).join(" ");
-}
-function runtimeVersionFromIdentifier(runtimeId) {
-  const match2 = runtimeId.match(/iOS-([\d-]+)$/i);
-  if (!match2?.[1])
-    return "iOS";
-  return formatIosVersion(match2[1].replace(/-/g, "."));
-}
-async function listIosSimulators(includeUnavailable) {
-  const { stdout, exitCode } = await runCommand3([
-    "xcrun",
-    "simctl",
-    "list",
-    "devices",
-    "available",
-    "-j"
-  ]);
-  if (exitCode !== 0)
-    return [];
-  let parsed;
-  try {
-    parsed = JSON.parse(stdout);
-  } catch {
-    return [];
-  }
-  const devices = [];
-  for (const [runtimeId, runtimeDevices] of Object.entries(parsed.devices ?? {})) {
-    if (!/iOS/i.test(runtimeId))
-      continue;
-    const osVersion = runtimeVersionFromIdentifier(runtimeId);
-    for (const device of runtimeDevices) {
-      if (!device.udid || !device.name)
-        continue;
-      if (device.isAvailable === false)
-        continue;
-      const state = device.state ?? "Unknown";
-      if (!includeUnavailable && state !== "Booted")
-        continue;
-      devices.push({
-        id: device.udid,
-        name: device.name,
-        osVersion,
-        platform: "ios",
-        kind: "simulator",
-        state,
-        model: device.deviceTypeIdentifier?.split(".").pop()?.replace(/-/g, " ")
-      });
-    }
-  }
-  return devices.sort((a, b) => {
-    if (a.state === "Booted" && b.state !== "Booted")
-      return -1;
-    if (b.state === "Booted" && a.state !== "Booted")
-      return 1;
-    return a.name.localeCompare(b.name);
-  });
-}
-function isPhoneOrTablet(deviceType) {
-  if (!deviceType)
-    return false;
-  return /^(iPhone|iPad)$/i.test(deviceType);
-}
-function physicalIosState(connection) {
-  const tunnel = connection?.tunnelState?.toLowerCase() ?? "";
-  if (tunnel.includes("connected"))
-    return "connected";
-  if (tunnel.includes("unavailable"))
-    return "unavailable";
-  if (tunnel.includes("disconnected"))
-    return "disconnected";
-  if (connection?.pairingState === "paired")
-    return "paired";
-  return tunnel || connection?.pairingState || "unknown";
-}
-async function listIosPhysicalDevices(includeUnavailable) {
-  const dir = await mkdtemp2(join7(tmpdir2(), "yoqa-devices-"));
-  const jsonPath = join7(dir, "devices.json");
-  try {
-    const { exitCode } = await runCommand3([
-      "xcrun",
-      "devicectl",
-      "list",
-      "devices",
-      "--json-output",
-      jsonPath
-    ]);
-    if (exitCode !== 0)
-      return [];
-    let parsed;
-    try {
-      parsed = JSON.parse(await readFile(jsonPath, "utf8"));
-    } catch {
-      return [];
-    }
-    const devices = [];
-    for (const item of parsed.result?.devices ?? []) {
-      const hardware = item.hardwareProperties;
-      const props = item.deviceProperties;
-      if (!hardware?.udid)
-        continue;
-      if (hardware.reality && hardware.reality !== "physical")
-        continue;
-      if (!isPhoneOrTablet(hardware.deviceType))
-        continue;
-      if (hardware.platform && !/^iOS$/i.test(hardware.platform))
-        continue;
-      const state = physicalIosState(item.connectionProperties);
-      if (!includeUnavailable && state === "unavailable")
-        continue;
-      const modelName = hardware.marketingName ?? hardware.productType ?? "iPhone";
-      const owner = props?.name?.trim() || undefined;
-      devices.push({
-        id: hardware.udid,
-        name: modelName,
-        owner,
-        osVersion: formatIosVersion(props?.osVersionNumber ?? ""),
-        platform: "ios",
-        kind: "physical",
-        state,
-        model: hardware.productType
-      });
-    }
-    return devices.sort((a, b) => a.name.localeCompare(b.name));
-  } finally {
-    await rm2(dir, { recursive: true, force: true });
-  }
-}
-async function listIosDevices(options = {}) {
-  const includeUnavailable = options.includeUnavailable ?? true;
-  const [physical, simulators] = await Promise.all([
-    listIosPhysicalDevices(includeUnavailable),
-    listIosSimulators(includeUnavailable)
-  ]);
-  return [...physical, ...simulators];
-}
-function parseAdbDevices(output) {
-  const lines = output.split(`
-`).map((line) => line.trim()).filter(Boolean);
-  const results = [];
-  for (const line of lines) {
-    if (line.startsWith("List of devices"))
-      continue;
-    const parts = line.split(/\s+/);
-    const serial = parts[0];
-    const state = parts[1];
-    if (!serial || !state)
-      continue;
-    const meta = {};
-    for (const part of parts.slice(2)) {
-      const eq2 = part.indexOf(":");
-      if (eq2 <= 0)
-        continue;
-      meta[part.slice(0, eq2)] = part.slice(eq2 + 1);
-    }
-    results.push({
-      serial,
-      state,
-      product: meta.product,
-      model: meta.model,
-      device: meta.device,
-      transportId: meta.transport_id
-    });
-  }
-  return results;
-}
-function humanizeAvdName(avdName) {
-  return titleCaseWords(avdName.replace(/_/g, " "));
-}
-function humanizeModel(model) {
-  if (!model)
-    return;
-  return titleCaseWords(model.replace(/_/g, " "));
-}
-async function findAvdConfigPath(avdName) {
-  const home = process.env.HOME ?? "";
-  const roots = [join7(home, ".android/avd"), join7(home, "Library/Android/sdk/.android/avd")];
-  for (const root of roots) {
-    const direct = join7(root, `${avdName}.avd`, "config.ini");
-    try {
-      await readFile(direct, "utf8");
-      return direct;
-    } catch {}
-    try {
-      const glob = new Bun.Glob("*.avd/config.ini");
-      for await (const match2 of glob.scan({ cwd: root, onlyFiles: true })) {
-        const path = join7(root, match2);
-        const text2 = await readFile(path, "utf8");
-        const idLine = text2.split(`
-`).find((line) => line.startsWith("AvdId="));
-        const id = idLine?.slice("AvdId=".length).trim();
-        if (id === avdName)
-          return path;
-      }
-    } catch {}
-  }
-  return null;
-}
-async function readAvdConfig(avdName) {
-  const path = await findAvdConfigPath(avdName);
-  if (!path)
-    return { api: null, deviceName: null };
-  try {
-    const text2 = await readFile(path, "utf8");
-    const imageLine = text2.split(`
-`).find((line) => line.includes("system-images") && line.includes("android-"));
-    const apiMatch = imageLine?.match(/android-([\d.]+)/);
-    const deviceLine = text2.split(`
-`).find((entry) => entry.startsWith("hw.device.name="));
-    const deviceRaw = deviceLine?.slice("hw.device.name=".length).trim();
-    return {
-      api: apiMatch?.[1] ?? null,
-      deviceName: humanizeModel(deviceRaw) ?? null
-    };
-  } catch {
-    return { api: null, deviceName: null };
-  }
-}
-async function adbAvdName(adb, serial) {
-  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "emu", "avd", "name"]);
-  if (exitCode !== 0)
-    return null;
-  const name = stdout.trim().split(`
-`)[0]?.trim();
-  return name || null;
-}
-async function adbGetProp(adb, serial, prop) {
-  const { stdout, exitCode } = await runCommand3([adb, "-s", serial, "shell", "getprop", prop]);
-  if (exitCode !== 0)
-    return null;
-  const value = stdout.trim();
-  return value || null;
-}
-async function listAndroidAdbDevices(adb) {
-  const { stdout, exitCode } = await runCommand3([adb, "devices", "-l"]);
-  if (exitCode !== 0) {
-    return { physical: [], runningEmulators: [], runningAvdNames: new Set };
-  }
-  const entries = parseAdbDevices(stdout);
-  const physical = [];
-  const runningEmulators = [];
-  const runningAvdNames = new Set;
-  for (const entry of entries) {
-    const isEmulator = entry.serial.startsWith("emulator-") || entry.product === "sdk_gphone";
-    if (isEmulator) {
-      const avdName = await adbAvdName(adb, entry.serial);
-      if (avdName)
-        runningAvdNames.add(avdName);
-      const avdConfig = avdName ? await readAvdConfig(avdName) : null;
-      const release2 = await adbGetProp(adb, entry.serial, "ro.build.version.release") ?? avdConfig?.api ?? null;
-      const model2 = humanizeModel(entry.model) ?? avdConfig?.deviceName ?? (avdName ? humanizeAvdName(avdName) : entry.serial);
-      runningEmulators.push({
-        id: avdName ?? entry.serial,
-        name: model2,
-        osVersion: formatAndroidVersion(release2 ?? ""),
-        platform: "android",
-        kind: "emulator",
-        state: entry.state === "device" ? "online" : entry.state,
-        model: avdName ?? entry.model
-      });
-      continue;
-    }
-    const release = await adbGetProp(adb, entry.serial, "ro.build.version.release");
-    const model = humanizeModel(entry.model) ?? await adbGetProp(adb, entry.serial, "ro.product.model") ?? entry.serial;
-    physical.push({
-      id: entry.serial,
-      name: model,
-      osVersion: formatAndroidVersion(release ?? ""),
-      platform: "android",
-      kind: "physical",
-      state: entry.state,
-      model: entry.model
-    });
-  }
-  return { physical, runningEmulators, runningAvdNames };
-}
-async function listAndroidAvds(emulatorBin, runningAvdNames, includeUnavailable) {
-  const { stdout, exitCode } = await runCommand3([emulatorBin, "-list-avds"]);
-  if (exitCode !== 0)
-    return [];
-  const names = stdout.split(`
-`).map((line) => line.trim()).filter(Boolean);
-  const devices = [];
-  for (const avdName of names) {
-    const isRunning = runningAvdNames.has(avdName);
-    if (!includeUnavailable && !isRunning)
-      continue;
-    if (isRunning)
-      continue;
-    const { api, deviceName } = await readAvdConfig(avdName);
-    devices.push({
-      id: avdName,
-      name: deviceName ?? humanizeAvdName(avdName),
-      osVersion: formatAndroidVersion(api ?? ""),
-      platform: "android",
-      kind: "emulator",
-      state: "offline",
-      model: avdName
-    });
-  }
-  return devices;
-}
-async function listAndroidDevices(options = {}) {
-  const includeUnavailable = options.includeUnavailable ?? true;
-  const [adb, emulatorBin] = await Promise.all([resolveAdb(), resolveEmulator()]);
-  const adbResult = adb ? await listAndroidAdbDevices(adb) : { physical: [], runningEmulators: [], runningAvdNames: new Set };
-  const offlineAvds = emulatorBin != null ? await listAndroidAvds(emulatorBin, adbResult.runningAvdNames, includeUnavailable) : [];
-  const physical = includeUnavailable ? adbResult.physical : adbResult.physical.filter((device) => device.state === "device");
-  const emulators = [...adbResult.runningEmulators, ...offlineAvds].sort((a, b) => {
-    const aOnline = a.state === "online" ? 0 : 1;
-    const bOnline = b.state === "online" ? 0 : 1;
-    if (aOnline !== bOnline)
-      return aOnline - bOnline;
-    return a.name.localeCompare(b.name);
-  });
-  return [...physical, ...emulators];
-}
-async function listDevices(platform, options = {}) {
-  if (platform === "ios")
-    return listIosDevices(options);
-  return listAndroidDevices(options);
-}
-
 // src/interfaces/http/devices.ts
 function createDevicesRoutes() {
   const app = new Hono2;
@@ -97429,6 +97540,10 @@ var defaultClock = {
 };
 async function executeScriptCase(deps) {
   const perform = deps.performAction ?? performAction;
+  const readScreen = deps.readScreen ?? (async (session) => {
+    const screen = await getScreen(session, { full: false });
+    return { elements: screen.elements };
+  });
   const clock = deps.clock ?? defaultClock;
   const settleMs = deps.settleMs ?? POST_ACTION_SETTLE_MS;
   let stepIdx = 0;
@@ -97446,7 +97561,16 @@ async function executeScriptCase(deps) {
         return "cancelled";
       }
       if (action.type === "tap") {
-        await perform(deps.session, { kind: "tap", x: action.x, y: action.y });
+        const tapBody = { kind: "tap" };
+        if (action.label)
+          tapBody.label = action.label;
+        if (action.id)
+          tapBody.id = action.id;
+        if (action.x != null)
+          tapBody.x = action.x;
+        if (action.y != null)
+          tapBody.y = action.y;
+        await perform(deps.session, tapBody);
         await clock.sleep(settleMs);
         await deps.appendStep({
           idx: stepIdx,
@@ -97454,13 +97578,15 @@ async function executeScriptCase(deps) {
             type: "tap",
             x: action.x,
             y: action.y,
+            label: action.label,
+            id: action.id,
             reason: action.reason ?? "Replayed saved script tap",
             thoughts: "Replaying the saved script without calling the AI agent."
           },
           screenshotUri: shot.path,
           ok: true,
           latencyMs,
-          detail: action.reason ?? null
+          detail: action.reason ?? action.label ?? action.id ?? null
         });
       } else if (action.type === "type") {
         await perform(deps.session, { kind: "input", text: action.text });
@@ -97478,6 +97604,40 @@ async function executeScriptCase(deps) {
           latencyMs,
           detail: action.reason ?? null
         });
+      } else if (action.type === "assert") {
+        const timeoutMs = action.timeoutMs ?? 5000;
+        const assertion = action.assertion;
+        const deadline = clock.now() + timeoutMs;
+        for (;; ) {
+          if (deps.isAborted()) {
+            return "cancelled";
+          }
+          const screen = await readScreen(deps.session);
+          const found = screenHasText(screen.elements, action.text);
+          if (assertion === "visible" && found)
+            break;
+          if (assertion === "not-visible" && !found)
+            break;
+          if (clock.now() >= deadline) {
+            throw new Error(assertion === "visible" ? `Expected visible text not found within ${Math.round(timeoutMs / 1000)}s: ${action.text}` : `Unexpected text still visible after ${Math.round(timeoutMs / 1000)}s: ${action.text}`);
+          }
+          await clock.sleep(400);
+        }
+        await deps.appendStep({
+          idx: stepIdx,
+          action: {
+            type: "assert",
+            assertion,
+            text: action.text,
+            timeoutMs,
+            reason: action.reason ?? `Assert ${assertion}: ${action.text}`,
+            thoughts: "Replaying the saved script without calling the AI agent."
+          },
+          screenshotUri: shot.path,
+          ok: true,
+          latencyMs,
+          detail: action.reason ?? `${assertion}: ${action.text}`
+        });
       } else {
         const waitMs = Math.min(3000, Math.max(500, action.ms));
         await clock.sleep(waitMs);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yoqa/runner",
-	"version": "0.3.16",
+	"version": "0.3.18",
 	"description": "Yoqa local runner — Appium + catalog HTTP API (Bun). Start with yoqa serve or the yoqa-runner bin.",
 	"license": "UNLICENSED",
 	"type": "module",