@unotest/mobile 0.1.1 → 0.8.0

package/dist/runner/install.js

@@ -0,0 +1,1967 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/runner/install.ts
+import { config as loadDotenv2 } from "dotenv";
+import { existsSync as existsSync4 } from "fs";
+import { resolve as resolve3 } from "path";
+
+// src/config/env.ts
+import { config as loadDotenv } from "dotenv";
+import { z } from "zod";
+var ENV_FILE_PATH = "unotest/.env";
+var loaded = false;
+function ensureLoaded() {
+  if (loaded) return;
+  loadDotenv({ path: ENV_FILE_PATH });
+  loaded = true;
+}
+__name(ensureLoaded, "ensureLoaded");
+var EnvSchema = z.object({
+  // APP_BUNDLE_ID — required at appLaunch / install time. We let the schema
+  // accept it as optional so commands that don't touch the app (`doctor`,
+  // `lint`) work without it. Use-site (WdaDriver) validates and errors with
+  // a clear message if missing.
+  APP_BUNDLE_ID: z.string().min(1).optional(),
+  // APP_URL_SCHEME — only consumed by the (currently unimplemented) Expo
+  // dev-client recovery flow. Optional; reserved for future use.
+  APP_URL_SCHEME: z.string().min(1).optional(),
+  // APP_PERMISSIONS — comma-separated `simctl privacy` services that
+  // `install --clean` (CLI + MCP) auto-grants before launch. Populated
+  // by `install --update-env` from detected NS*UsageDescription keys in
+  // the .app's Info.plist (P4 / S4). Optional — apps that don't request
+  // privacy services leave this unset.
+  // Example: APP_PERMISSIONS=location,motion
+  APP_PERMISSIONS: z.string().optional(),
+  // API_BASE_URL — only required if scenarios call `apiCall(...)`. Lazy:
+  // the ApiClient is constructed at first use, not at startup.
+  API_BASE_URL: z.string().url().optional(),
+  // PROJECT_ROOT — optional default cwd for the `shell(...)` DSL primitive.
+  // When unset, shell commands run from process.cwd(). Set to the absolute
+  // path of the project-under-test when its CLI must be invoked from a
+  // specific directory (e.g. monorepo root).
+  PROJECT_ROOT: z.string().optional(),
+  // DATABASE_URL — only required if scenarios call `dbQuery(...)` /
+  // `dbExec(...)`. Lazy: the DbClient is constructed at first use, not at
+  // startup. Format examples:
+  //   postgresql://user:pass@host:5432/dbname
+  //   mysql://user:pass@host:3306/dbname
+  //   sqlite:./e2e.db
+  //   sqlite::memory:
+  DATABASE_URL: z.string().min(1).optional(),
+  // SIM_A_NAME / SIM_B_NAME — schema-optional so non-UI commands work
+  // without them. Pool-aware validation in loadEnv() below requires the
+  // names for slots actually present in SIM_POOL.
+  SIM_A_NAME: z.string().min(1).optional(),
+  SIM_B_NAME: z.string().min(1).optional(),
+  SIM_POOL: z.string().default("A,B"),
+  // METRO_URL — only consumed by the (currently unimplemented) Expo
+  // dev-client recovery flow. Optional; reserved for future use.
+  METRO_URL: z.string().url().optional(),
+  // Expo dev-client builds show a "Development Servers" launcher after a clean
+  // launch. When true, the driver auto-opens
+  // `exp+<APP_URL_SCHEME>://expo-development-client/?url=<METRO_URL>` after
+  // `app_launch clean: true` to bypass the launcher. (Flow not yet wired.)
+  EXPO_DEV_CLIENT: z.string().optional().transform((v) => v === "true" || v === "1"),
+  SESSION_LOG_PATH: z.string().default("unotest/sessions/current.jsonl"),
+  // Explicit kill-switch for session recording. When "1"/"true", or when
+  // SESSION_LOG_PATH is empty, buildApp wires a NoopSessionRecorder. Used
+  // by evals harness and any consumer that wants the MCP server to make
+  // no on-disk session log.
+  SESSION_LOG_DISABLE: z.string().optional().transform((v) => v === "1" || v === "true"),
+  // When true, recorder writes the FULL tool result alongside the
+  // truncated preview. Off by default — snapshots can be megabytes.
+  SESSION_LOG_FULL: z.string().optional().transform((v) => v === "1" || v === "true"),
+  ARTIFACTS_DIR: z.string().default("unotest/artifacts"),
+  // Where ExplorationService persists per-session JSONL recording logs.
+  // Default: <ARTIFACTS_DIR>/explorations. Folded into the gitignored
+  // `unotest/artifacts/` tree by the init template.
+  EXPLORATIONS_DIR: z.string().optional(),
+  // WDA per-slot port mapping (D-13 parallel multi-device). Stored as a
+  // comma-separated `slot=port` list, e.g. "A=8100,B=8101". Each slot present
+  // in SIM_POOL needs a port.
+  WDA_PORTS: z.string().default("A=8100,B=8101"),
+  // Implicit auto-wait on selector-bearing actions (D-18).
+  WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
+  WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
+  PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
+});
+var cached = null;
+function loadEnv() {
+  if (cached) return cached;
+  ensureLoaded();
+  const parsed = EnvSchema.safeParse(process.env);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new Error(
+      `Invalid environment. Copy unotest/.env.example to unotest/.env and fill required values.
+${issues}`
+    );
+  }
+  const raw = parsed.data;
+  const simPool = raw.SIM_POOL.split(",").map((s) => s.trim()).filter(Boolean);
+  const simBySlot = {};
+  for (const slot of simPool) {
+    const key = `SIM_${slot}_NAME`;
+    const value = process.env[key];
+    if (!value) {
+      throw new Error(
+        `SIM_POOL lists slot "${slot}" but ${key} is not set in unotest/.env. Either add ${key}=<simulator-name> or shrink SIM_POOL to omit slot "${slot}".`
+      );
+    }
+    simBySlot[slot] = value;
+  }
+  const wdaPortBySlot = {};
+  for (const entry of raw.WDA_PORTS.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const [slot, portStr] = entry.split("=").map((s) => s.trim());
+    if (!slot || !portStr) {
+      throw new Error(`Invalid WDA_PORTS entry "${entry}". Expected "slot=port"`);
+    }
+    const port = Number.parseInt(portStr, 10);
+    if (!Number.isFinite(port) || port <= 0) {
+      throw new Error(`Invalid WDA_PORTS port "${portStr}" for slot "${slot}"`);
+    }
+    wdaPortBySlot[slot] = port;
+  }
+  for (const slot of simPool) {
+    if (wdaPortBySlot[slot] == null) {
+      throw new Error(
+        `SIM_POOL includes slot "${slot}" but WDA_PORTS has no entry for it. Add "${slot}=<port>" to WDA_PORTS in unotest/.env.`
+      );
+    }
+  }
+  cached = {
+    ...raw,
+    simPool,
+    simBySlot,
+    wdaPortBySlot,
+    defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
+    defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
+    explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
+  };
+  return cached;
+}
+__name(loadEnv, "loadEnv");
+
+// src/driver/ios-utils.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var exec = promisify(execFile);
+async function listSimulators() {
+  const { stdout } = await exec("xcrun", ["simctl", "list", "-j", "devices"]);
+  const parsed = JSON.parse(stdout);
+  const out = [];
+  for (const [runtime, list] of Object.entries(parsed.devices)) {
+    for (const d of list) {
+      if (d.isAvailable === false) continue;
+      out.push({ name: d.name, udid: d.udid, state: d.state, runtime });
+    }
+  }
+  return out;
+}
+__name(listSimulators, "listSimulators");
+function friendlyRuntime(runtime) {
+  const m = runtime.match(/SimRuntime\.([A-Za-z]+)-(\d+)-(\d+)$/);
+  if (!m) return runtime;
+  return `${m[1]} ${m[2]}.${m[3]}`;
+}
+__name(friendlyRuntime, "friendlyRuntime");
+async function resolveSimByName(spec) {
+  const { name, runtimeHint } = parseSimSpec(spec);
+  const all = await listSimulators();
+  let matches = all.filter((s) => s.name === name);
+  if (runtimeHint) {
+    matches = matches.filter((s) => friendlyRuntime(s.runtime).toLowerCase().includes(runtimeHint.toLowerCase()));
+  }
+  if (matches.length === 0) {
+    const available = all.map((s) => `${s.name} @ ${friendlyRuntime(s.runtime)}`).join(", ") || "(none)";
+    throw new Error(
+      `Sim "${spec}" not found. Available: ${available}. If you have multiple sims with the same name, disambiguate via "<name> @ <runtime>" (e.g. "iPhone 16 @ iOS 17.5").`
+    );
+  }
+  const booted = matches.find((s) => s.state === "Booted");
+  return booted ?? matches[0];
+}
+__name(resolveSimByName, "resolveSimByName");
+function parseSimSpec(spec) {
+  const idx = spec.lastIndexOf("@");
+  if (idx === -1) return { name: spec.trim() };
+  return {
+    name: spec.slice(0, idx).trim(),
+    runtimeHint: spec.slice(idx + 1).trim()
+  };
+}
+__name(parseSimSpec, "parseSimSpec");
+async function bootSim(udid) {
+  try {
+    await exec("xcrun", ["simctl", "boot", udid]);
+    if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+    return;
+  } catch (e) {
+    const msg = e.stderr ?? String(e);
+    if (msg.includes("Booted") || msg.includes("current state: Booted")) {
+      if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+      return;
+    }
+    const state = await currentSimState(udid).catch(() => null);
+    if (state === "Booted") {
+      if (process.env.SIMCTL_HEADLESS !== "1") await openSimulatorApp();
+      return;
+    }
+    if (state && state !== "Shutdown") {
+      throw new Error(
+        `simctl boot ${udid} failed and sim is in transitional state "${state}". Wait a few seconds and retry, or force-shutdown: \`xcrun simctl shutdown ${udid}\`.
+Original error: ${msg.trim().split("\n").slice(0, 4).join(" | ")}`
+      );
+    }
+    throw new Error(
+      `simctl boot ${udid} failed. Sim is "${state ?? "unknown"}".
+Common fixes:
+  \u2022 Open Simulator.app, pick this device manually, ensure it boots.
+  \u2022 Erase: \`xcrun simctl erase ${udid}\` (wipes content & settings).
+  \u2022 Restart CoreSimulator: \`sudo killall -9 com.apple.CoreSimulator.CoreSimulatorService\`.
+Original error: ${msg.trim().split("\n").slice(0, 4).join(" | ")}`
+    );
+  }
+}
+__name(bootSim, "bootSim");
+async function currentSimState(udid) {
+  const sims = await listSimulators();
+  const sim = sims.find((s) => s.udid === udid);
+  return sim ? sim.state : null;
+}
+__name(currentSimState, "currentSimState");
+async function openSimulatorApp() {
+  try {
+    await exec("open", ["-a", "Simulator"]);
+  } catch {
+  }
+}
+__name(openSimulatorApp, "openSimulatorApp");
+async function shutdownSim(udid) {
+  try {
+    await exec("xcrun", ["simctl", "shutdown", udid]);
+  } catch {
+  }
+}
+__name(shutdownSim, "shutdownSim");
+async function openUrl(udid, url) {
+  await exec("xcrun", ["simctl", "openurl", udid, url]);
+}
+__name(openUrl, "openUrl");
+async function screenshotPng(udid) {
+  const { stdout } = await exec("xcrun", ["simctl", "io", udid, "screenshot", "--type=png", "-"], {
+    encoding: "buffer",
+    maxBuffer: 32 * 1024 * 1024
+  });
+  return stdout;
+}
+__name(screenshotPng, "screenshotPng");
+async function terminateApp(udid, bundleId) {
+  try {
+    await exec("xcrun", ["simctl", "terminate", udid, bundleId]);
+  } catch {
+  }
+}
+__name(terminateApp, "terminateApp");
+async function launchApp(udid, bundleId, args = []) {
+  const { stdout } = await exec("xcrun", ["simctl", "launch", udid, bundleId, ...args]);
+  const m = stdout.match(/:\s*(\d+)/);
+  const pid = m ? Number.parseInt(m[1], 10) : 0;
+  return { pid };
+}
+__name(launchApp, "launchApp");
+async function isPidAlive(pid) {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isPidAlive, "isPidAlive");
+async function assertLaunchedAndStable(udid, bundleId, pid, options = {}) {
+  const settleMs = options.settleMs ?? 1500;
+  await new Promise((r) => setTimeout(r, settleMs));
+  const alive = await isPidAlive(pid);
+  if (alive) return;
+  const procName = bundleId.split(".").pop() ?? bundleId;
+  throw new Error(
+    `App "${bundleId}" started (PID ${pid}) but exited within ${settleMs}ms \u2014 looks like a crash on launch.
+See the crash reason:
+  xcrun simctl spawn ${udid} log show --predicate 'process == "${procName}" OR senderImagePath CONTAINS "${bundleId}"' --last 30s --info
+Or open Console.app, filter by your app name.
+Common causes: missing native module (rebuild after changing native deps), JS bundle baked against wrong workspace/env, signing issues.`
+  );
+}
+__name(assertLaunchedAndStable, "assertLaunchedAndStable");
+async function uninstallApp(udid, bundleId) {
+  try {
+    await exec("xcrun", ["simctl", "uninstall", udid, bundleId]);
+  } catch {
+  }
+}
+__name(uninstallApp, "uninstallApp");
+async function installApp(udid, appPath) {
+  await exec("xcrun", ["simctl", "install", udid, appPath]);
+}
+__name(installApp, "installApp");
+async function isAppInstalled(udid, bundleId) {
+  try {
+    await exec("xcrun", ["simctl", "get_app_container", udid, bundleId]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isAppInstalled, "isAppInstalled");
+async function eraseSim(udid) {
+  await exec("xcrun", ["simctl", "erase", udid]);
+}
+__name(eraseSim, "eraseSim");
+async function keychainResetSim(udid) {
+  await exec("xcrun", ["simctl", "keychain", udid, "reset"]);
+}
+__name(keychainResetSim, "keychainResetSim");
+async function privacyGrantSim(udid, service, bundleId) {
+  await exec("xcrun", ["simctl", "privacy", udid, "grant", service, bundleId]);
+}
+__name(privacyGrantSim, "privacyGrantSim");
+async function pinEnglishKeyboardSim(udid) {
+  await exec("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleKeyboards",
+    "-array",
+    "en_US@hw=US;sw=QWERTY"
+  ]);
+  await exec("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleLanguages",
+    "-array",
+    "en"
+  ]);
+  await exec("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "-g",
+    "AppleLocale",
+    "-string",
+    "en_US"
+  ]);
+}
+__name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
+
+// src/driver/simctl/adapter.ts
+var SimctlAdapter = class {
+  static {
+    __name(this, "SimctlAdapter");
+  }
+  async resolveByName(name) {
+    return resolveSimByName(name);
+  }
+  async boot(udid) {
+    return bootSim(udid);
+  }
+  async shutdown(udid) {
+    return shutdownSim(udid);
+  }
+  async install(udid, appPath) {
+    return installApp(udid, appPath);
+  }
+  async uninstall(udid, bundleId) {
+    return uninstallApp(udid, bundleId);
+  }
+  async launch(udid, bundleId, args) {
+    return launchApp(udid, bundleId, args);
+  }
+  async assertLaunchedAndStable(udid, bundleId, pid, settleMs) {
+    return assertLaunchedAndStable(udid, bundleId, pid, settleMs !== void 0 ? { settleMs } : {});
+  }
+  async terminate(udid, bundleId) {
+    return terminateApp(udid, bundleId);
+  }
+  async openUrl(udid, url) {
+    return openUrl(udid, url);
+  }
+  async screenshot(udid) {
+    return screenshotPng(udid);
+  }
+  async isInstalled(udid, bundleId) {
+    return isAppInstalled(udid, bundleId);
+  }
+  async erase(udid) {
+    return eraseSim(udid);
+  }
+  /** B5 — wipes simulator keychain so auth tokens don't survive `clean`
+   *  launches. Used by `installApp({clean})` and `WdaDriver.appLaunch({clean})`. */
+  async keychainReset(udid) {
+    return keychainResetSim(udid);
+  }
+  /** S4 — pre-grant an iOS privacy service to a bundle so the app skips
+   *  the SpringBoard permission dialog on first launch. */
+  async privacyGrant(udid, service, bundleId) {
+    return privacyGrantSim(udid, service, bundleId);
+  }
+  /** S8 — pin the sim's keyboard to en_US@QWERTY so WDA's typeText
+   *  doesn't drop Latin chars when the sim was last on a Cyrillic layout. */
+  async pinEnglishKeyboard(udid) {
+    return pinEnglishKeyboardSim(udid);
+  }
+  async openSimulatorApp() {
+    return openSimulatorApp();
+  }
+};
+
+// src/util/cli-entry.ts
+function runMain(main2, errorExitCode) {
+  main2().then(
+    (code) => process.exit(code),
+    (e) => {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`\u2717 ${msg}
+`);
+      if (process.env.UNOTEST_DEBUG === "1" && e instanceof Error && e.stack) {
+        process.stderr.write(`${e.stack}
+`);
+      }
+      process.exit(errorExitCode);
+    }
+  );
+}
+__name(runMain, "runMain");
+
+// src/util/interactive-select.ts
+import { emitKeypressEvents } from "readline";
+function reduceSelect(state, key) {
+  if (key.ctrl && key.name === "c") return { kind: "abort", reason: "ctrl-c" };
+  if (key.name === "escape") return { kind: "abort", reason: "esc" };
+  if (key.name === "return" || key.name === "enter") {
+    const choice = state.choices[state.index];
+    if (!choice || choice.disabled) return { kind: "noop" };
+    return { kind: "done", value: choice.value };
+  }
+  if (key.name === "up" || key.name === "k") {
+    return { kind: "redraw", state: { ...state, index: stepIndex(state, -1) } };
+  }
+  if (key.name === "down" || key.name === "j") {
+    return { kind: "redraw", state: { ...state, index: stepIndex(state, 1) } };
+  }
+  if (key.name === "home" || key.name === "g" && !key.ctrl) {
+    return { kind: "redraw", state: { ...state, index: firstEnabled(state.choices, 0, 1) } };
+  }
+  if (key.name === "end" || key.name === "G" && !key.ctrl) {
+    return {
+      kind: "redraw",
+      state: { ...state, index: firstEnabled(state.choices, state.choices.length - 1, -1) }
+    };
+  }
+  return { kind: "noop" };
+}
+__name(reduceSelect, "reduceSelect");
+function stepIndex(state, dir) {
+  const n = state.choices.length;
+  if (n === 0) return 0;
+  let i = state.index;
+  for (let attempts = 0; attempts < n; attempts++) {
+    i = (i + dir + n) % n;
+    if (!state.choices[i]?.disabled) return i;
+  }
+  return state.index;
+}
+__name(stepIndex, "stepIndex");
+function firstEnabled(choices, start, dir) {
+  const n = choices.length;
+  let i = start;
+  for (let attempts = 0; attempts < n; attempts++) {
+    if (!choices[i]?.disabled) return i;
+    i += dir;
+    if (i < 0 || i >= n) break;
+  }
+  return start;
+}
+__name(firstEnabled, "firstEnabled");
+function initialCursorIndex(choices, requested) {
+  if (choices.length === 0) return 0;
+  const clamped = Math.max(0, Math.min(requested, choices.length - 1));
+  if (!choices[clamped]?.disabled) return clamped;
+  for (let i = clamped + 1; i < choices.length; i++) if (!choices[i]?.disabled) return i;
+  for (let i = clamped - 1; i >= 0; i--) if (!choices[i]?.disabled) return i;
+  return clamped;
+}
+__name(initialCursorIndex, "initialCursorIndex");
+var SelectAbortedError = class extends Error {
+  constructor(reason) {
+    super(`select aborted (${reason})`);
+    this.reason = reason;
+    this.name = "SelectAbortedError";
+  }
+  reason;
+  static {
+    __name(this, "SelectAbortedError");
+  }
+};
+async function interactiveSelect(opts, io = {}) {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stderr;
+  if (!input.isTTY) {
+    throw new Error(
+      `interactiveSelect: input stream is not a TTY. Caller must check isTTY upstream and use a non-interactive code path.`
+    );
+  }
+  if (opts.choices.length === 0) {
+    throw new Error(`interactiveSelect: choices is empty`);
+  }
+  const initialIndex = initialCursorIndex(opts.choices, opts.initialIndex ?? 0);
+  let state = { choices: opts.choices, index: initialIndex };
+  output.write("\x1B[?25l");
+  emitKeypressEvents(input);
+  const wasRaw = input.isRaw ?? false;
+  input.setRawMode(true);
+  input.resume();
+  const renderedLines = render(output, opts.message, state);
+  let linesOnScreen = renderedLines;
+  const cleanup = /* @__PURE__ */ __name(() => {
+    input.setRawMode(wasRaw);
+    input.pause();
+    input.removeListener("keypress", onKey);
+    output.write("\x1B[?25h");
+  }, "cleanup");
+  let onKey;
+  return new Promise((resolve4, reject) => {
+    onKey = /* @__PURE__ */ __name((_str, key) => {
+      const action = reduceSelect(state, key ?? {});
+      if (action.kind === "noop") return;
+      if (action.kind === "abort") {
+        cleanup();
+        reject(new SelectAbortedError(action.reason));
+        return;
+      }
+      if (action.kind === "done") {
+        cleanup();
+        eraseLines(output, linesOnScreen);
+        const chosenLabel = state.choices[state.index]?.label ?? String(action.value);
+        output.write(`${opts.message}
+  \u2713 ${chosenLabel}
+`);
+        resolve4(action.value);
+        return;
+      }
+      state = action.state;
+      eraseLines(output, linesOnScreen);
+      linesOnScreen = render(output, opts.message, state);
+    }, "onKey");
+    input.on("keypress", onKey);
+  });
+}
+__name(interactiveSelect, "interactiveSelect");
+function render(output, message, state) {
+  const messageLines = message.split("\n");
+  for (const line of messageLines) output.write(`${line}
+`);
+  for (let i = 0; i < state.choices.length; i++) {
+    const choice = state.choices[i];
+    const marker = i === state.index ? "\u276F" : " ";
+    const label = choice.disabled ? dim(choice.label) : choice.label;
+    const line = i === state.index ? highlight(`${marker} ${label}`) : `${marker} ${label}`;
+    output.write(`${line}
+`);
+  }
+  output.write(dim("(\u2191/\u2193 to move, enter to select, ctrl-c to abort)\n"));
+  return messageLines.length + state.choices.length + 1;
+}
+__name(render, "render");
+function eraseLines(output, n) {
+  for (let i = 0; i < n; i++) {
+    output.write("\x1B[1A");
+    output.write("\x1B[2K");
+  }
+}
+__name(eraseLines, "eraseLines");
+function highlight(s) {
+  return `\x1B[36m${s}\x1B[0m`;
+}
+__name(highlight, "highlight");
+function dim(s) {
+  return `\x1B[2m${s}\x1B[0m`;
+}
+__name(dim, "dim");
+
+// src/util/log.ts
+var SGR = {
+  reset: "\x1B[0m",
+  dim: "\x1B[2m",
+  bold: "\x1B[1m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  boldCyan: "\x1B[1;36m"
+};
+function colorsEnabled() {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(process.stdout.isTTY);
+}
+__name(colorsEnabled, "colorsEnabled");
+function paint(color, s) {
+  if (!colorsEnabled()) return s;
+  return `${SGR[color]}${s}${SGR.reset}`;
+}
+__name(paint, "paint");
+function createLogger(prefix = "") {
+  const p = prefix ? `${paint("dim", `[${prefix}]`)} ` : "";
+  return {
+    info: /* @__PURE__ */ __name((m, ...r) => console.log(`${p}${m}`, ...r), "info"),
+    warn: /* @__PURE__ */ __name((m, ...r) => console.warn(`${p}${paint("yellow", "warn")} ${m}`, ...r), "warn"),
+    error: /* @__PURE__ */ __name((m, ...r) => console.error(`${p}${paint("red", "error")} ${m}`, ...r), "error"),
+    debug: /* @__PURE__ */ __name((m, ...r) => {
+      if (process.env.E2E_DEBUG) console.log(`${p}${paint("dim", "debug")} ${m}`, ...r);
+    }, "debug"),
+    step: /* @__PURE__ */ __name((m, ...r) => console.log(`${p}${paint("cyan", "\u2192")} ${m}`, ...r), "step"),
+    child: /* @__PURE__ */ __name((sub) => createLogger(prefix ? `${prefix}/${sub}` : sub), "child")
+  };
+}
+__name(createLogger, "createLogger");
+
+// src/runner/init/run.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/runner/init/environment-check.ts
+import { execFileSync } from "child_process";
+var ExecError = class extends Error {
+  constructor(cmd, args) {
+    super(`${cmd} ${args.join(" ")} failed`);
+    this.cmd = cmd;
+    this.args = args;
+  }
+  cmd;
+  args;
+  static {
+    __name(this, "ExecError");
+  }
+};
+function defaultExec(cmd, args) {
+  try {
+    return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    throw new ExecError(cmd, args);
+  }
+}
+__name(defaultExec, "defaultExec");
+function runEnvironmentChecks(opts = {}) {
+  const results = [];
+  const platform = opts.platform ?? process.platform;
+  const nodeVersion = opts.nodeVersion ?? process.versions.node;
+  const exec4 = opts.exec ?? defaultExec;
+  if (platform !== "darwin") {
+    results.push({
+      name: "platform",
+      severity: opts.allowNonMacos ? "warning" : "error",
+      message: `macOS required (got "${platform}"). iOS simulators only run on macOS (Apple licensing).`,
+      detail: opts.allowNonMacos ? "Continuing with --allow-non-macos. Tests cannot run without a macOS host." : "Re-run with --allow-non-macos if you only need to scaffold files (e.g. preparing a macOS CI runner)."
+    });
+    if (!opts.allowNonMacos) return results;
+  } else {
+    results.push({ name: "platform", severity: "ok", message: "macOS detected" });
+  }
+  const major = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+  if (major < 20) {
+    results.push({
+      name: "node",
+      severity: "error",
+      message: `Node 20+ required (got ${nodeVersion}).`,
+      detail: "Upgrade via nvm/fnm/volta."
+    });
+    return results;
+  }
+  results.push({ name: "node", severity: "ok", message: `Node ${nodeVersion}` });
+  if (platform !== "darwin") return results;
+  try {
+    const xcodePath = exec4("xcode-select", ["-p"]).trim();
+    results.push({ name: "xcode-cli", severity: "ok", message: `Xcode CLI tools at ${xcodePath}` });
+  } catch {
+    results.push({
+      name: "xcode-cli",
+      severity: "error",
+      message: "Xcode Command Line Tools not found.",
+      detail: "Install: `xcode-select --install`"
+    });
+    return results;
+  }
+  try {
+    exec4("xcrun", ["simctl", "help"]);
+    results.push({ name: "simctl", severity: "ok", message: "xcrun simctl available" });
+  } catch {
+    results.push({
+      name: "simctl",
+      severity: "error",
+      message: "xcrun simctl not available.",
+      detail: "Install full Xcode (from Mac App Store), not just Command Line Tools."
+    });
+    return results;
+  }
+  try {
+    const json = exec4("xcrun", ["simctl", "list", "devices", "available", "--json"]);
+    const parsed = JSON.parse(json);
+    const total = Object.values(parsed.devices).reduce((sum, list) => sum + list.length, 0);
+    if (total === 0) {
+      results.push({
+        name: "simulators",
+        severity: "warning",
+        message: "No iOS simulators found.",
+        detail: "Create one in Xcode \u2192 Window \u2192 Devices and Simulators \u2192 '+'."
+      });
+    } else {
+      results.push({ name: "simulators", severity: "ok", message: `${total} simulators available` });
+    }
+  } catch {
+    results.push({
+      name: "simulators",
+      severity: "warning",
+      message: "Could not enumerate simulators."
+    });
+  }
+  try {
+    const pkgRaw = exec4("cat", ["package.json"]);
+    const pkg = JSON.parse(pkgRaw);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const isRn = "react-native" in deps || "expo" in deps;
+    if (isRn) {
+      results.push({ name: "project-type", severity: "ok", message: "React Native / Expo detected" });
+    } else {
+      results.push({
+        name: "project-type",
+        severity: "ok",
+        message: "no React Native / Expo dependency in package.json",
+        detail: "Assuming a native iOS app (Swift/SwiftUI/Obj-C) or a non-Node project. Selectors resolve via the iOS accessibility tree \u2014 set accessibilityIdentifier on the views you want to target."
+      });
+    }
+  } catch {
+    results.push({
+      name: "project-type",
+      severity: "ok",
+      message: "no package.json in current directory",
+      detail: "That's fine for native iOS projects. If this is a Node-based project, run from its root so unotest-mobile can detect React Native / Expo."
+    });
+  }
+  return results;
+}
+__name(runEnvironmentChecks, "runEnvironmentChecks");
+
+// src/runner/init/file-templates.ts
+var templates = {
+  smokeWelcome: `// id-smoke-welcome
+// First-run sanity: harness reaches sim, WDA, and app launch handshake
+// #00aa00
+function test_smoke_welcome() {
+  setDevice("A");
+  appLaunch(true);
+}
+`,
+  // Canonical syntax reference for AI agents writing new scenarios. The
+  // sentinel banner up top is the strongest single-line signal against the
+  // default "this is modern JS" assumption that drives agents to write
+  // import/export/async/await. Skill references this file by path; eval
+  // harness seeds the same content into temp workdirs.
+  e2eTemplateExample: `// unotest-mobile JS-DSL \u2014 NOT Node.js.
+//
+// Bare top-level functions only. NO \`import\`/\`export\`/\`async\`/\`await\`/
+// \`const\`/\`let\`/\`var\`/arrow-functions. Assignments are bare-name: \`x = expr;\`.
+// Member access (\`obj.field\`) and object literals (\`{key: value}\`) are
+// forbidden \u2014 payloads are passed as JSON strings.
+//
+// After editing any scenario in this directory:
+//   npx unotest-mobile lint
+//
+// Below: minimal valid example. Copy its shape when writing new scenarios.
+
+// id-example-001
+// Example sign-in flow
+// #4a90e2
+function test_example() {
+  setDevice("A");
+  appLaunch(true);
+
+  type(getByTestId("email-input"), "user@example.com");
+  type(getByTestId("password-input"), "secret123");
+  tap(getByTestId("signin-button"));
+
+  waitFor(getByTestId("home-screen"), 15000);
+}
+`,
+  scenarioTemplate: `// id-<your-scenario-id>
+// <one-line description>
+// #888888
+function test_<your_name>() {
+  // 1. SETUP \u2014 DB / API fixtures (helpers from _helpers/)
+  //    wipe_e2e_users();
+  //    user_id = seed_user("e2e@example.com", "e2e-pass");
+
+  // 2. ENTER \u2014 bring app to initial UI state
+  setDevice("A");
+  appLaunch(true);
+  waitFor(getByTestId("screen-welcome"), 15000);
+
+  // 3. ACT \u2014 actions you're testing
+  //    signin("e2e@example.com", "e2e-pass");
+  //    tap(getByTestId("btn-something"));
+
+  // 4. ASSERT \u2014 UI + DB / API checks
+  //    assertVisible(getByTestId("screen-target"));
+  //    count = dbQuery("SELECT count(*)::text FROM x WHERE ...");
+  //    assertEqual(count, "1");
+}
+`,
+  agentsMd: `# AI Agents: how to write e2e tests for this project
+
+This project uses [\`@unotest/mobile\`](https://www.npmjs.com/package/@unotest/mobile)
+for end-to-end testing of iOS React Native flows.
+
+## Layout
+
+- \`unotest/e2e/\` \u2014 scenarios (one \`test_*\` entry function per file)
+- \`unotest/e2e/_helpers/\` \u2014 project-specific helpers, visible to all scenarios
+- \`unotest/e2e/<feature>/\` \u2014 feature-scoped subfolders (recommended)
+
+## How to write a test
+
+The full guide \u2014 DSL functions, scenario shape, helper rules, linter codes,
+debugging \u2014 is the \`write-e2e-test\` Claude Code skill at
+\`.claude/skills/write-e2e-test.md\`. It is the single source of truth for
+both Claude Code and other AI agents. Read it before writing tests.
+
+## Running
+
+- \`npx @unotest/mobile e2e <name>\` \u2014 run \`unotest/e2e/<name>.js\`
+- \`npx @unotest/mobile lint\` \u2014 static check of all scenarios
+- \`npx @unotest/mobile doctor\` \u2014 re-check environment
+
+Inside Claude Code, prefer the MCP \`run_test\` tool with
+\`pauseOnFailure: true\` \u2014 it pauses on the failed step so you can
+\`inspect_runtime\`, fix the scenario, and \`resume\`.
+`,
+  envExample: `# unotest-mobile \u2014 copied to unotest/.env by \`init\`. Fill in only what
+# your scenarios actually use. Most variables are optional.
+
+# --- Simulators (required for any UI scenario) -----------------------------
+# Names must match \`xcrun simctl list devices\`. SIM_POOL controls which
+# slots are active; each slot in the pool needs the matching SIM_<slot>_NAME.
+#
+# If you have multiple sims with the same name across iOS versions,
+# disambiguate via "<name> @ <runtime>" \u2014 runtime is a substring match,
+# so "iOS 17" or "iOS 17.5" both work.
+# SIM_A_NAME=                        # pick interactively on first \`install\`
+# SIM_A_NAME=iPhone 16 @ iOS 17.5    # pin to a specific runtime
+# SIM_B_NAME=                        # only needed if SIM_POOL includes "B"
+# SIM_POOL=A,B                       # default \u2014 drop "B" if you only need one sim
+
+# --- App under test (required if scenarios call appLaunch / openDeeplink) --
+APP_BUNDLE_ID=com.example.myapp
+# APP_URL_SCHEME=myapp           # only used by Expo dev-client recovery flow
+# Optional. Path to a built .app bundle. When set, \`unotest-mobile install\`
+# (and the \`app_install\` MCP tool) can be invoked without an explicit path.
+# Useful for repeated installs after each app rebuild.
+# APP_PATH=./build-sim/Build/Products/Release-iphonesimulator/MyApp.app
+# Comma-separated \`simctl privacy\` services to auto-grant on \`install --clean\`.
+# Populated by \`unotest-mobile install --update-env\` from your app's
+# Info.plist NS*UsageDescription keys. Pre-empts the iOS permission dialog
+# on first launch \u2014 those dialogs live in SpringBoard, not in the app's
+# a11y tree, and would otherwise block your scenarios.
+# APP_PERMISSIONS=location,motion
+
+# --- Backend (optional \u2014 only required if scenarios use apiCall / db) ------
+# API_BASE_URL=http://localhost:3000/api
+# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_test
+#   Drivers (install peer-deps as needed):
+#     npm i -D pg @types/pg              # for postgresql://
+#     npm i -D mysql2                    # for mysql://
+#   SQLite via better-sqlite3 is bundled \u2014 no separate install.
+#   Docker-compose Postgres/MySQL: ensure host port is exposed
+#   (\`ports: ["5432:5432"]\`). Native clients connect from the host, not
+#   from inside the compose network.
+
+# --- Optional: shell() default cwd -----------------------------------------
+# Absolute path used as default cwd for the \`shell(...)\` DSL primitive.
+# When unset, shell commands run from process.cwd(). Set to your project
+# root if your scenarios shell out to project-local CLIs that must run
+# from there.
+# PROJECT_ROOT=
+
+# --- WebDriverAgent --------------------------------------------------------
+# Per-slot WDA ports. Each slot in SIM_POOL needs one. Format: "slot=port".
+WDA_PORTS=A=8100,B=8101
+# WDA_DEFAULT_ACTION_WAIT_MS=2000
+# WDA_DEFAULT_WAITFOR_TIMEOUT_MS=10000
+
+# --- Artifacts / sessions / paused-runtime TTL -----------------------------
+# Defaults are sensible \u2014 uncomment only to override.
+# SESSION_LOG_PATH=unotest/sessions/current.jsonl
+# ARTIFACTS_DIR=unotest/artifacts
+# PAUSED_RUNTIME_TTL_MS=1800000  # 30 min before paused-on-failure auto-abort
+
+# --- Expo dev-client (reserved for future use) -----------------------------
+# METRO_URL=http://localhost:8081
+# EXPO_DEV_CLIENT=false
+`,
+  gitignoreLines: [
+    "",
+    "# unotest-mobile",
+    "unotest/.env",
+    "unotest/artifacts/",
+    "unotest/sessions/"
+  ],
+  mcpServerEntry: {
+    command: "npx",
+    args: ["-y", "@unotest/mobile"]
+  }
+};
+
+// src/runner/init/mcp-config-merger.ts
+var McpJsonParseError = class extends Error {
+  static {
+    __name(this, "McpJsonParseError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "McpJsonParseError";
+  }
+};
+function mergeMcpConfig(existingSource, serverName, serverConfig, options = {}) {
+  if (existingSource === null) {
+    const content2 = JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2) + "\n";
+    return { action: "created", newContent: content2 };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(existingSource);
+  } catch (e) {
+    throw new McpJsonParseError(
+      `Failed to parse .mcp.json as JSON: ${e.message}. Fix or remove the file and re-run init.`
+    );
+  }
+  if (!parsed.mcpServers || typeof parsed.mcpServers !== "object") {
+    parsed.mcpServers = {};
+  }
+  const alreadyPresent = serverName in parsed.mcpServers;
+  if (alreadyPresent && !options.force) {
+    return { action: "already-present", newContent: existingSource };
+  }
+  parsed.mcpServers[serverName] = serverConfig;
+  const content = JSON.stringify(parsed, null, 2) + "\n";
+  return {
+    action: alreadyPresent ? "force-overwrote" : "added",
+    newContent: content
+  };
+}
+__name(mergeMcpConfig, "mergeMcpConfig");
+
+// src/runner/init/gitignore-updater.ts
+function appendUniqueLines(existingContent, linesToAdd) {
+  const existing = existingContent ?? "";
+  const existingLines = new Set(existing.split("\n").map((l) => l.trim()));
+  const added = [];
+  const alreadyPresent = [];
+  for (const line of linesToAdd) {
+    const trimmed = line.trim();
+    if (trimmed === "" || existingLines.has(trimmed)) {
+      if (trimmed !== "") alreadyPresent.push(line);
+      continue;
+    }
+    added.push(line);
+    existingLines.add(trimmed);
+  }
+  if (added.length === 0) {
+    return { added, alreadyPresent, newContent: existing };
+  }
+  const sep = existing === "" ? "" : existing.endsWith("\n") ? "" : "\n";
+  const newContent = existing + sep + added.join("\n") + "\n";
+  return { added, alreadyPresent, newContent };
+}
+__name(appendUniqueLines, "appendUniqueLines");
+
+// src/runner/init/run.ts
+var here = dirname(fileURLToPath(import.meta.url));
+var packageRoot = resolve(here, "..", "..");
+function parseInitArgs(argv) {
+  return {
+    force: argv.includes("--force"),
+    allowNonMacos: argv.includes("--allow-non-macos")
+  };
+}
+__name(parseInitArgs, "parseInitArgs");
+function symbol(severity) {
+  return severity === "ok" ? "\u2713" : severity === "warning" ? "\u26A0" : "\u2717";
+}
+__name(symbol, "symbol");
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+__name(ensureDir, "ensureDir");
+function writeIfNeeded(filePath, content, force) {
+  const exists = existsSync(filePath);
+  if (exists && !force) return "skipped";
+  ensureDir(dirname(filePath));
+  writeFileSync(filePath, content);
+  return exists ? "overwrote" : "created";
+}
+__name(writeIfNeeded, "writeIfNeeded");
+function readPackageFile(relativePath) {
+  const abs = resolve(packageRoot, relativePath);
+  if (!existsSync(abs)) return null;
+  return readFileSync(abs, "utf8");
+}
+__name(readPackageFile, "readPackageFile");
+function runInit(argv = process.argv.slice(2)) {
+  const opts = parseInitArgs(argv);
+  const target = process.cwd();
+  console.log("unotest-mobile init \u2014 bootstrapping project\n");
+  console.log("Environment:");
+  const checks = runEnvironmentChecks({ allowNonMacos: opts.allowNonMacos });
+  let hardFailed = false;
+  for (const c of checks) {
+    console.log(`  ${symbol(c.severity)} ${c.name}: ${c.message}`);
+    if (c.detail) console.log(`      ${c.detail}`);
+    if (c.severity === "error") hardFailed = true;
+  }
+  if (hardFailed) {
+    console.error("\nFix the errors above and re-run.");
+    return 1;
+  }
+  console.log("\nFiles:");
+  const summary = [];
+  ensureDir(join(target, "unotest/e2e/_helpers"));
+  ensureDir(join(target, "unotest/e2e/_template"));
+  summary.push({
+    path: "unotest/e2e/smoke-welcome.js",
+    status: writeIfNeeded(join(target, "unotest/e2e/smoke-welcome.js"), templates.smokeWelcome, opts.force)
+  });
+  summary.push({
+    path: "unotest/e2e/_template.js",
+    status: writeIfNeeded(join(target, "unotest/e2e/_template.js"), templates.scenarioTemplate, opts.force)
+  });
+  summary.push({
+    path: "unotest/e2e/_template/example.js",
+    status: writeIfNeeded(
+      join(target, "unotest/e2e/_template/example.js"),
+      templates.e2eTemplateExample,
+      opts.force
+    )
+  });
+  summary.push({
+    path: "unotest/AGENTS.md",
+    status: writeIfNeeded(join(target, "unotest/AGENTS.md"), templates.agentsMd, opts.force)
+  });
+  const skillSrc = readPackageFile(".claude/skills/write-e2e-test.md");
+  if (skillSrc !== null) {
+    summary.push({
+      path: ".claude/skills/write-e2e-test.md",
+      status: writeIfNeeded(join(target, ".claude/skills/write-e2e-test.md"), skillSrc, opts.force)
+    });
+  } else {
+    summary.push({ path: ".claude/skills/write-e2e-test.md", status: "missing-in-package" });
+  }
+  const mcpPath = join(target, ".mcp.json");
+  try {
+    const existing = existsSync(mcpPath) ? readFileSync(mcpPath, "utf8") : null;
+    const merge = mergeMcpConfig(
+      existing,
+      "unotest-mobile",
+      {
+        command: templates.mcpServerEntry.command,
+        args: [...templates.mcpServerEntry.args]
+      },
+      { force: opts.force }
+    );
+    if (merge.action !== "already-present") {
+      writeFileSync(mcpPath, merge.newContent);
+    }
+    summary.push({ path: ".mcp.json", status: merge.action });
+  } catch (e) {
+    if (e instanceof McpJsonParseError) {
+      console.error(`
+\u2717 .mcp.json: ${e.message}`);
+      return 1;
+    }
+    throw e;
+  }
+  const envExamplePath = join(target, "unotest/.env.example");
+  summary.push({
+    path: "unotest/.env.example",
+    status: writeIfNeeded(envExamplePath, templates.envExample, true)
+  });
+  const envDst = join(target, "unotest/.env");
+  if (!existsSync(envDst)) {
+    writeFileSync(envDst, templates.envExample);
+    summary.push({ path: "unotest/.env", status: "created" });
+  } else {
+    summary.push({ path: "unotest/.env", status: "skipped (exists \u2014 fill in manually)" });
+  }
+  const gitignorePath = join(target, ".gitignore");
+  const gitignoreExisting = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : null;
+  const giUpdate = appendUniqueLines(gitignoreExisting, [...templates.gitignoreLines]);
+  if (giUpdate.added.length > 0) {
+    writeFileSync(gitignorePath, giUpdate.newContent);
+    summary.push({ path: ".gitignore", status: `added ${giUpdate.added.length} line(s)` });
+  } else {
+    summary.push({ path: ".gitignore", status: "already up-to-date" });
+  }
+  for (const item of summary) {
+    const symbolForStatus = item.status === "created" || item.status.startsWith("added") ? "\u2713" : item.status === "skipped" || item.status.startsWith("already") ? "\xB7" : item.status === "overwrote" || item.status === "force-overwrote" ? "\u21BB" : "?";
+    console.log(`  ${symbolForStatus} ${item.path} \u2014 ${item.status}`);
+  }
+  console.log(`
+Next:
+  1. Edit ${relative(target, envDst) || "unotest/.env"} with your project's values
+     (DATABASE_URL, SIM_A_NAME, APP_BUNDLE_ID, ...)
+  2. Boot iOS simulators matching SIM_A_NAME / SIM_B_NAME (Xcode \u2192 Devices)
+  3. Open Claude Code in this directory \u2014 MCP server auto-registers via
+     .mcp.json. Ask the agent to write a test.
+  4. CLI: \`npx @unotest/mobile e2e smoke-welcome\` to run the starter.
+
+Re-check environment anytime: \`npx @unotest/mobile doctor\`
+`);
+  return 0;
+}
+__name(runInit, "runInit");
+
+// src/runner/install/install-app.ts
+import { execFile as execFile3 } from "child_process";
+import { existsSync as existsSync2, statSync } from "fs";
+import { resolve as resolve2 } from "path";
+import { promisify as promisify3 } from "util";
+
+// src/runner/install/info-plist.ts
+import { execFile as execFile2 } from "child_process";
+import { join as join2 } from "path";
+import { promisify as promisify2 } from "util";
+var exec2 = promisify2(execFile2);
+async function readInfoPlist(appPath) {
+  const plistPath = join2(appPath, "Info.plist");
+  const { stdout } = await exec2("plutil", ["-convert", "json", "-o", "-", plistPath]);
+  const raw = JSON.parse(stdout);
+  const bundleId = typeof raw.CFBundleIdentifier === "string" ? raw.CFBundleIdentifier : void 0;
+  const urlSchemes = [];
+  if (Array.isArray(raw.CFBundleURLTypes)) {
+    for (const type of raw.CFBundleURLTypes) {
+      if (type && typeof type === "object" && Array.isArray(type.CFBundleURLSchemes)) {
+        for (const scheme of type.CFBundleURLSchemes) {
+          if (typeof scheme === "string") urlSchemes.push(scheme);
+        }
+      }
+    }
+  }
+  const usageDescriptions = [];
+  for (const [key, value] of Object.entries(raw)) {
+    if (key.startsWith("NS") && key.endsWith("UsageDescription") && typeof value === "string") {
+      usageDescriptions.push({ key, description: value });
+    }
+  }
+  return { ...bundleId ? { bundleId } : {}, urlSchemes, usageDescriptions };
+}
+__name(readInfoPlist, "readInfoPlist");
+
+// src/runner/install/permission-mapper.ts
+var NS_TO_SIMCTL_SERVICE = Object.freeze({
+  // Location
+  NSLocationWhenInUseUsageDescription: "location",
+  NSLocationAlwaysAndWhenInUseUsageDescription: "location-always",
+  NSLocationAlwaysUsageDescription: "location-always",
+  // Media
+  NSPhotoLibraryUsageDescription: "photos",
+  NSPhotoLibraryAddUsageDescription: "photos-add",
+  NSMicrophoneUsageDescription: "microphone",
+  NSMediaLibraryUsageDescription: "media-library",
+  // Personal data
+  NSContactsUsageDescription: "contacts",
+  NSCalendarsUsageDescription: "calendar",
+  // legacy (pre-iOS 17)
+  NSCalendarsFullAccessUsageDescription: "calendar",
+  // iOS 17+ preferred
+  NSCalendarsWriteOnlyAccessUsageDescription: "calendar",
+  // iOS 17+ write-only
+  NSRemindersUsageDescription: "reminders",
+  // Sensors / device
+  NSMotionUsageDescription: "motion",
+  // Siri
+  NSSiriUsageDescription: "siri",
+  // Camera + push notifications are not exposed via `simctl privacy` —
+  // camera needs the alert-dismiss path (B1), push needs UNUserNotificationCenter.
+  NSCameraUsageDescription: null
+});
+var KNOWN_SIMCTL_SERVICES = new Set(
+  Object.values(NS_TO_SIMCTL_SERVICE).filter((v) => v !== null)
+);
+function inferSimctlServices(usageDescriptions) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const u of usageDescriptions) {
+    const svc = NS_TO_SIMCTL_SERVICE[u.key];
+    if (svc !== void 0 && svc !== null && !seen.has(svc)) {
+      seen.add(svc);
+      out.push(svc);
+    }
+  }
+  return out;
+}
+__name(inferSimctlServices, "inferSimctlServices");
+
+// src/runner/install/install-app.ts
+var exec3 = promisify3(execFile3);
+async function installApp2(opts, deps) {
+  const appPathAbsolute = resolve2(opts.appPath);
+  if (!existsSync2(appPathAbsolute)) {
+    throw new Error(`App path does not exist: ${appPathAbsolute}`);
+  }
+  if (!appPathAbsolute.endsWith(".app")) {
+    throw new Error(
+      `App path must point to a .app bundle (directory ending in .app), got: ${appPathAbsolute}. If you have an .ipa or .zip \u2014 extract it first.`
+    );
+  }
+  if (!statSync(appPathAbsolute).isDirectory()) {
+    throw new Error(`App path must be a directory (.app bundle), got file: ${appPathAbsolute}`);
+  }
+  const infoPlist = `${appPathAbsolute}/Info.plist`;
+  if (!existsSync2(infoPlist)) {
+    throw new Error(`Info.plist not found inside .app: ${infoPlist}`);
+  }
+  const readBundleId = deps.readBundleId ?? readBundleIdViaPlistBuddy;
+  const appBundleId = (await readBundleId(appPathAbsolute)).trim();
+  if (!appBundleId) {
+    throw new Error(`Could not read CFBundleIdentifier from ${infoPlist}`);
+  }
+  const readUrlScheme = deps.readUrlScheme ?? readUrlSchemeViaPlistBuddy;
+  const appUrlScheme = await readUrlScheme(appPathAbsolute);
+  const readUsageDescriptions = deps.readUsageDescriptions ?? (async (p) => (await readInfoPlist(p)).usageDescriptions);
+  const usageDescriptions = await readUsageDescriptions(appPathAbsolute);
+  const detectedPermissions = inferSimctlServices(usageDescriptions);
+  if (opts.slots.length === 0) {
+    throw new Error(`No slots to install on. Pass --slot or check SIM_POOL in unotest/.env.`);
+  }
+  for (const slot of opts.slots) {
+    if (!opts.simBySlot[slot]) {
+      throw new Error(
+        `Slot "${slot}" requested but no SIM_${slot}_NAME in unotest/.env (or not in SIM_POOL).`
+      );
+    }
+  }
+  const slotResults = [];
+  for (const slot of opts.slots) {
+    const simName = opts.simBySlot[slot];
+    const sim = await deps.simctl.resolveByName(simName);
+    let erased = false;
+    if (opts.erase) {
+      deps.logger.info(`[${slot}] erasing ${simName} (${sim.udid})`);
+      try {
+        await deps.simctl.shutdown(sim.udid);
+      } catch {
+      }
+      await deps.simctl.erase(sim.udid);
+      erased = true;
+    }
+    deps.logger.info(`[${slot}] booting ${simName} (${sim.udid})`);
+    await deps.simctl.boot(sim.udid);
+    if (process.env.SIMCTL_HEADLESS !== "1") {
+      await deps.simctl.openSimulatorApp();
+    }
+    let uninstalled = false;
+    if (opts.clean) {
+      deps.logger.info(`[${slot}] uninstalling existing ${appBundleId}`);
+      try {
+        await deps.simctl.uninstall(sim.udid, appBundleId);
+        uninstalled = true;
+      } catch {
+      }
+      deps.logger.info(`[${slot}] resetting keychain on ${sim.udid}`);
+      await deps.simctl.keychainReset(sim.udid);
+    }
+    deps.logger.info(`[${slot}] installing ${appPathAbsolute}`);
+    await deps.simctl.install(sim.udid, appPathAbsolute);
+    if (opts.permissions && opts.permissions.length > 0) {
+      for (const service of opts.permissions) {
+        deps.logger.info(`[${slot}] granting ${service} to ${appBundleId}`);
+        await deps.simctl.privacyGrant(sim.udid, service, appBundleId);
+      }
+    }
+    if (opts.pinKeyboard !== false) {
+      deps.logger.info(`[${slot}] pinning keyboard to en_US@QWERTY`);
+      await deps.simctl.pinEnglishKeyboard(sim.udid);
+    }
+    let launched = false;
+    if (opts.launch) {
+      deps.logger.info(`[${slot}] launching ${appBundleId}`);
+      const { pid } = await deps.simctl.launch(sim.udid, appBundleId);
+      await deps.simctl.assertLaunchedAndStable(sim.udid, appBundleId, pid);
+      launched = true;
+    }
+    slotResults.push({ slot, simName, udid: sim.udid, erased, uninstalled, launched });
+  }
+  return {
+    appBundleId,
+    appUrlScheme,
+    appPathAbsolute,
+    bundleIdMismatch: opts.envBundleId !== void 0 && opts.envBundleId !== appBundleId,
+    detectedPermissions,
+    slots: slotResults
+  };
+}
+__name(installApp2, "installApp");
+async function readBundleIdViaPlistBuddy(appPath) {
+  const { stdout } = await exec3("/usr/libexec/PlistBuddy", [
+    "-c",
+    "Print :CFBundleIdentifier",
+    `${appPath}/Info.plist`
+  ]);
+  return stdout;
+}
+__name(readBundleIdViaPlistBuddy, "readBundleIdViaPlistBuddy");
+async function readUrlSchemeViaPlistBuddy(appPath) {
+  try {
+    const { stdout } = await exec3("/usr/libexec/PlistBuddy", [
+      "-c",
+      "Print :CFBundleURLTypes:0:CFBundleURLSchemes:0",
+      `${appPath}/Info.plist`
+    ]);
+    const scheme = stdout.trim();
+    return scheme.length > 0 ? scheme : void 0;
+  } catch {
+    return void 0;
+  }
+}
+__name(readUrlSchemeViaPlistBuddy, "readUrlSchemeViaPlistBuddy");
+
+// src/runner/install/readline-prompt.ts
+function createReadlinePromptIO() {
+  return {
+    async promptChoice(message, options) {
+      try {
+        return await interactiveSelect(
+          {
+            message,
+            choices: options.map((o) => ({ label: o.label, value: o.value }))
+          },
+          {}
+        );
+      } catch (e) {
+        if (e instanceof SelectAbortedError) {
+          throw new Error(
+            `cancelled \u2014 re-run when ready, or pass --sim-* flags / --yes for non-interactive setup.`
+          );
+        }
+        throw e;
+      }
+    },
+    print(line) {
+      process.stderr.write(`${line}
+`);
+    },
+    close() {
+    }
+  };
+}
+__name(createReadlinePromptIO, "createReadlinePromptIO");
+
+// src/runner/install/sim-resolver.ts
+var SKIP_SLOT = "__skip__";
+var MANUAL_EDIT = "__manual__";
+var ManualEditRequested = class extends Error {
+  static {
+    __name(this, "ManualEditRequested");
+  }
+  constructor(slot) {
+    super(
+      `Slot "${slot}" left unresolved \u2014 open unotest/.env, set SIM_${slot}_NAME to one of the available simulator names, and re-run.`
+    );
+    this.name = "ManualEditRequested";
+  }
+};
+var NonInteractiveResolveError = class extends Error {
+  static {
+    __name(this, "NonInteractiveResolveError");
+  }
+  constructor(slot, reason, currentValue) {
+    const detail = reason === "missing" ? `SIM_${slot}_NAME is not set in unotest/.env` : `SIM_${slot}_NAME="${currentValue}" does not match any installed simulator`;
+    const skipHint = slot === "A" ? "" : ` (or --no-sim-${slot.toLowerCase()} to drop slot ${slot} from SIM_POOL)`;
+    super(
+      `${detail}. Running non-interactively \u2014 pass --sim-${slot.toLowerCase()}=<name>${skipHint}, or re-run in a terminal for an interactive picker.`
+    );
+    this.name = "NonInteractiveResolveError";
+  }
+};
+var NoSimulatorsAvailableError = class extends Error {
+  static {
+    __name(this, "NoSimulatorsAvailableError");
+  }
+  constructor() {
+    super(
+      `No iOS simulators found on this machine. Install Xcode and create a simulator via Xcode \u2192 Window \u2192 Devices and Simulators, then re-run.`
+    );
+    this.name = "NoSimulatorsAvailableError";
+  }
+};
+async function resolveSims(input, io) {
+  const availableNames = new Set(input.availableSims.map((s) => s.name));
+  const finalPool = [];
+  const finalMapping = {};
+  const envUpdates = [];
+  let prompted = false;
+  for (const slot of input.pool) {
+    const override = input.overrides[slot];
+    const current = input.simBySlot[slot];
+    if (override === "skip") {
+      envUpdates.push({ key: `SIM_POOL`, value: "__placeholder__" });
+      io.print(`\xB7 slot ${slot} dropped (--no-sim-${slot.toLowerCase()})`);
+      continue;
+    }
+    if (typeof override === "string") {
+      if (!availableNames.has(override)) {
+        throw new Error(
+          `--sim-${slot.toLowerCase()}="${override}" does not match any installed simulator. Available: ${formatSimList(input.availableSims)}`
+        );
+      }
+      finalPool.push(slot);
+      finalMapping[slot] = override;
+      if (override !== current) {
+        envUpdates.push({ key: `SIM_${slot}_NAME`, value: override });
+      }
+      continue;
+    }
+    if (current && availableNames.has(current)) {
+      finalPool.push(slot);
+      finalMapping[slot] = current;
+      continue;
+    }
+    if (input.nonInteractive) {
+      throw new NonInteractiveResolveError(
+        slot,
+        current ? "not-found" : "missing",
+        current
+      );
+    }
+    if (input.availableSims.length === 0) {
+      throw new NoSimulatorsAvailableError();
+    }
+    prompted = true;
+    const reason = current ? `SIM_${slot}_NAME="${current}" doesn't match any installed simulator.` : `SIM_${slot}_NAME is not set in unotest/.env.`;
+    const simChoices = input.availableSims.map((s) => ({
+      label: `${s.name} @ ${s.runtime}${s.state === "Booted" ? " (booted)" : ""}`,
+      value: s.name
+    }));
+    const options = [];
+    if (slot !== "A") {
+      options.push({
+        label: `do not configure slot ${slot} \u2014 only one simulator needed`,
+        value: SKIP_SLOT
+      });
+    }
+    options.push(...simChoices);
+    options.push({
+      label: `edit unotest/.env manually and re-run`,
+      value: MANUAL_EDIT
+    });
+    const picked = await io.promptChoice(
+      `${reason}
+Pick a simulator for slot ${slot}:`,
+      options
+    );
+    if (picked === MANUAL_EDIT) {
+      throw new ManualEditRequested(slot);
+    }
+    if (picked === SKIP_SLOT) {
+      io.print(`\xB7 slot ${slot} dropped from SIM_POOL`);
+      continue;
+    }
+    finalPool.push(slot);
+    finalMapping[slot] = picked;
+    envUpdates.push({ key: `SIM_${slot}_NAME`, value: picked });
+    io.print(`\u2713 SIM_${slot}_NAME=${picked}`);
+  }
+  if (finalPool.length === 0) {
+    throw new Error(
+      `All slots were skipped \u2014 install needs at least slot A. Re-run without --no-sim-a or pick a simulator for slot A.`
+    );
+  }
+  const finalPoolStr = finalPool.join(",");
+  const currentPoolStr = input.pool.join(",");
+  const cleanedUpdates = envUpdates.filter((u) => u.value !== "__placeholder__");
+  if (finalPoolStr !== currentPoolStr) {
+    cleanedUpdates.push({ key: "SIM_POOL", value: finalPoolStr });
+    io.print(`\u2713 SIM_POOL=${finalPoolStr}`);
+  }
+  return {
+    pool: finalPool,
+    simBySlot: finalMapping,
+    envUpdates: cleanedUpdates,
+    prompted
+  };
+}
+__name(resolveSims, "resolveSims");
+function formatSimList(sims) {
+  if (sims.length === 0) return "(none \u2014 install Xcode and create a simulator)";
+  return sims.map((s) => `${s.name} @ ${s.runtime}`).join(", ");
+}
+__name(formatSimList, "formatSimList");
+
+// src/runner/install/update-env-file.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+function updateEnvFile(path, updates) {
+  const original = existsSync3(path) ? readFileSync2(path, "utf8") : "";
+  const lines = original.split(/\r?\n/);
+  const added = [];
+  const changed = [];
+  const unchanged = [];
+  for (const { key, value } of updates) {
+    const newLine = `${key}=${value}`;
+    const re = new RegExp(`^\\s*${escapeRegex(key)}\\s*=`);
+    let foundAt = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (re.test(lines[i] ?? "")) {
+        foundAt = i;
+        break;
+      }
+    }
+    if (foundAt === -1) {
+      if (lines.length > 0 && lines[lines.length - 1] !== "") lines.push("");
+      lines.push(newLine);
+      added.push(key);
+    } else if (lines[foundAt] === newLine) {
+      unchanged.push(key);
+    } else {
+      lines[foundAt] = newLine;
+      changed.push(key);
+    }
+  }
+  if (added.length > 0 || changed.length > 0) {
+    writeFileSync2(path, lines.join("\n"));
+  }
+  return { added, changed, unchanged };
+}
+__name(updateEnvFile, "updateEnvFile");
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+
+// src/runner/install.ts
+function parseArgs(argv) {
+  const opts = {
+    slot: "A",
+    clean: false,
+    erase: false,
+    launch: false,
+    updateEnv: false,
+    noSimB: false,
+    yes: false,
+    noPermissions: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--slot") {
+      const v = argv[++i];
+      if (v !== "A" && v !== "B" && v !== "all") {
+        throw new Error(`--slot must be A, B, or all (got "${v}")`);
+      }
+      opts.slot = v;
+    } else if (a === "--clean") {
+      opts.clean = true;
+    } else if (a === "--erase") {
+      opts.erase = true;
+    } else if (a === "--launch") {
+      opts.launch = true;
+    } else if (a === "--update-env") {
+      opts.updateEnv = true;
+    } else if (a === "--no-sim-b") {
+      opts.noSimB = true;
+    } else if (a === "--yes" || a === "-y") {
+      opts.yes = true;
+    } else if (a.startsWith("--sim-a=")) {
+      opts.simA = a.slice("--sim-a=".length);
+    } else if (a.startsWith("--sim-b=")) {
+      opts.simB = a.slice("--sim-b=".length);
+    } else if (a.startsWith("--permissions=")) {
+      const raw = a.slice("--permissions=".length);
+      opts.permissionsFlag = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    } else if (a === "--no-permissions") {
+      opts.noPermissions = true;
+    } else if (a === "-h" || a === "--help") {
+      printHelp();
+      process.exit(0);
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown flag: ${a}`);
+    } else {
+      if (opts.appPath !== void 0) {
+        throw new Error(`only one path argument allowed (got "${opts.appPath}" and "${a}")`);
+      }
+      opts.appPath = a;
+    }
+  }
+  if (opts.permissionsFlag !== void 0 && opts.noPermissions) {
+    throw new Error(`--permissions=<list> and --no-permissions are mutually exclusive.`);
+  }
+  return opts;
+}
+__name(parseArgs, "parseArgs");
+function resolveCliPermissions(opts, env) {
+  if (opts.permissionsFlag !== void 0) return opts.permissionsFlag;
+  if (opts.noPermissions) return [];
+  const envValue = env.APP_PERMISSIONS;
+  if (envValue && envValue.trim().length > 0) {
+    return envValue.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  return void 0;
+}
+__name(resolveCliPermissions, "resolveCliPermissions");
+function shouldPersistPermissions(resolved, currentEnvValue) {
+  if (resolved === void 0 || resolved.length === 0) return false;
+  return resolved.join(",") !== (currentEnvValue ?? "");
+}
+__name(shouldPersistPermissions, "shouldPersistPermissions");
+function printHelp() {
+  process.stdout.write(
+    `Usage: unotest-mobile install [path-to-.app] [flags]
+
+If [path] is omitted, reads APP_PATH from unotest/.env.
+
+Flags:
+  --slot A|B|all      Which slot(s) to install on. Default: A.
+  --clean             Uninstall existing app at the same bundle id first.
+  --erase             Erase simulator content & settings before install (destructive).
+  --launch            Launch the app after install (quick sanity check).
+  --update-env        Persist what we discover (APP_PATH, APP_BUNDLE_ID,
+                      APP_URL_SCHEME, APP_PERMISSIONS) into unotest/.env.
+  --permissions=<list>  Override APP_PERMISSIONS for this run. Comma-separated
+                      simctl-privacy services (e.g. "location,motion").
+                      Empty value ("--permissions=") = grant nothing.
+  --no-permissions    Skip auto-grant even if APP_PERMISSIONS is set in env.
+                      Conflicts with --permissions=<list>.
+  --sim-a=<name>      Non-interactive: set SIM_A_NAME for this run + .env.
+  --sim-b=<name>      Non-interactive: set SIM_B_NAME for this run + .env.
+  --no-sim-b          Non-interactive: drop slot B from SIM_POOL.
+  -y, --yes           Non-interactive: accept current state; error if any
+                      slot is unresolved (use with the --sim-* flags).
+  -h, --help          This help.
+
+Examples:
+  unotest-mobile install ./build/MyApp.app
+  unotest-mobile install ./MyApp.app --slot all --clean
+  unotest-mobile install ./MyApp.app --update-env --launch
+  unotest-mobile install ./MyApp.app -y --sim-a=UnoTest-A --no-sim-b
+`
+  );
+}
+__name(printHelp, "printHelp");
+async function ensureSimsResolved(opts) {
+  loadDotenv2({ path: ENV_FILE_PATH });
+  const currentPoolStr = process.env.SIM_POOL ?? "A,B";
+  const currentPool = currentPoolStr.split(",").map((s) => s.trim()).filter(Boolean);
+  const simBySlot = {};
+  for (const slot of currentPool) {
+    simBySlot[slot] = process.env[`SIM_${slot}_NAME`];
+  }
+  const overrides = {};
+  if (opts.simA !== void 0) overrides.A = opts.simA;
+  if (opts.simB !== void 0) overrides.B = opts.simB;
+  if (opts.noSimB) overrides.B = "skip";
+  const availableSims = (await listSimulators()).map((s) => ({
+    name: s.name,
+    runtime: friendlyRuntime(s.runtime),
+    state: s.state
+  }));
+  const nonInteractive = opts.yes || !process.stdin.isTTY;
+  let io;
+  if (nonInteractive) {
+    io = {
+      promptChoice: /* @__PURE__ */ __name(async () => {
+        throw new Error("promptChoice invoked in non-interactive mode (bug)");
+      }, "promptChoice"),
+      print: /* @__PURE__ */ __name((line) => process.stderr.write(`${line}
+`), "print")
+    };
+  } else {
+    io = createReadlinePromptIO();
+  }
+  try {
+    const resolved = await resolveSims(
+      { pool: currentPool, simBySlot, availableSims, overrides, nonInteractive },
+      io
+    );
+    if (resolved.envUpdates.length > 0) {
+      const envPath = resolve3(ENV_FILE_PATH);
+      updateEnvFile(envPath, resolved.envUpdates);
+      process.stderr.write(`\u2713 updated ${envPath}
+`);
+    }
+    for (const u of resolved.envUpdates) {
+      process.env[u.key] = u.value;
+    }
+    process.env.SIM_POOL = resolved.pool.join(",");
+  } finally {
+    io.close?.();
+  }
+}
+__name(ensureSimsResolved, "ensureSimsResolved");
+async function ensureProjectInitialized(opts) {
+  if (existsSync4(ENV_FILE_PATH)) return true;
+  const nonInteractive = opts.yes || !process.stdin.isTTY;
+  if (nonInteractive) {
+    process.stderr.write(
+      `\u2717 ${ENV_FILE_PATH} not found \u2014 project hasn't been initialized.
+Run \`unotest-mobile init\` first, then re-run install.
+`
+    );
+    return false;
+  }
+  process.stderr.write(
+    `${ENV_FILE_PATH} not found \u2014 looks like this project hasn't been initialized yet.
+`
+  );
+  let choice;
+  try {
+    choice = await interactiveSelect(
+      {
+        message: `What would you like to do?`,
+        choices: [
+          {
+            label: `run \`unotest-mobile init\` now \u2014 creates unotest/ scaffold, .mcp.json, .env (recommended)`,
+            value: "init"
+          },
+          { label: `cancel \u2014 I'll run init myself`, value: "abort" }
+        ]
+      },
+      {}
+    );
+  } catch (e) {
+    if (e instanceof SelectAbortedError) {
+      process.stderr.write(`cancelled.
+`);
+      return false;
+    }
+    throw e;
+  }
+  if (choice === "abort") {
+    process.stderr.write(`Run \`unotest-mobile init\`, then re-run install.
+`);
+    return false;
+  }
+  process.stderr.write(`
+`);
+  const initExitCode = runInit([]);
+  if (initExitCode !== 0) {
+    process.stderr.write(`\u2717 init failed (exit ${initExitCode}) \u2014 aborting install.
+`);
+    return false;
+  }
+  process.stderr.write(`
+`);
+  return true;
+}
+__name(ensureProjectInitialized, "ensureProjectInitialized");
+async function confirmDetectedPermissions(detected) {
+  try {
+    return await interactiveSelect(
+      {
+        message: `Detected iOS permissions in Info.plist: ${detected.join(", ")}.
+Pre-grant on test sims (writes APP_PERMISSIONS to unotest/.env)?`,
+        choices: [
+          { label: `yes \u2014 grant ${detected.join(", ")} (recommended)`, value: true },
+          { label: `skip \u2014 don't auto-grant, leave APP_PERMISSIONS unset`, value: false }
+        ]
+      },
+      {}
+    );
+  } catch (e) {
+    if (e instanceof SelectAbortedError) return false;
+    throw e;
+  }
+}
+__name(confirmDetectedPermissions, "confirmDetectedPermissions");
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    process.stderr.write(`\u2717 ${e.message}
+`);
+    process.stderr.write(`Run \`unotest-mobile install --help\` for usage.
+`);
+    return 2;
+  }
+  try {
+    process.cwd();
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      process.stderr.write(
+        `\u2717 Current directory is invalid (was it deleted while your shell was in it?).
+Run \`cd "$(pwd -P 2>/dev/null || echo ~)"\` or simply \`cd .\` in another fresh shell, then re-run.
+`
+      );
+      return 1;
+    }
+    throw e;
+  }
+  if (!await ensureProjectInitialized(opts)) {
+    return 1;
+  }
+  try {
+    await ensureSimsResolved(opts);
+  } catch (e) {
+    if (e instanceof ManualEditRequested || e instanceof NonInteractiveResolveError || e instanceof NoSimulatorsAvailableError) {
+      process.stderr.write(`\u2717 ${e.message}
+`);
+      return 1;
+    }
+    throw e;
+  }
+  const env = loadEnv();
+  const appPath = opts.appPath ?? process.env.APP_PATH;
+  if (!appPath) {
+    process.stderr.write(
+      `\u2717 No app path provided.
+Pass it as an argument: \`unotest-mobile install <path-to-.app>\`
+Or set APP_PATH in unotest/.env to skip the argument.
+`
+    );
+    return 2;
+  }
+  const slots = opts.slot === "all" ? env.simPool : env.simPool.includes(opts.slot) ? [opts.slot] : (() => {
+    throw new Error(
+      `--slot ${opts.slot} requested but slot "${opts.slot}" is not in SIM_POOL (${env.simPool.join(",")}).`
+    );
+  })();
+  const logger = createLogger().child("install");
+  const simctl = new SimctlAdapter();
+  let permissions = resolveCliPermissions(opts, process.env);
+  const nonInteractiveTop = opts.yes || !process.stdin.isTTY;
+  if (permissions === void 0 && opts.updateEnv) {
+    try {
+      const plist = await readInfoPlist(resolve3(appPath));
+      const detected = inferSimctlServices(plist.usageDescriptions);
+      if (detected.length > 0) {
+        const confirmed = nonInteractiveTop ? true : await confirmDetectedPermissions(detected);
+        if (confirmed) permissions = detected;
+      }
+    } catch (e) {
+      process.stderr.write(
+        `[install] WARN: could not pre-read Info.plist for permissions detection: ${e.message}
+`
+      );
+    }
+  }
+  let result;
+  try {
+    result = await installApp2(
+      {
+        appPath,
+        slots,
+        simBySlot: env.simBySlot,
+        envBundleId: env.APP_BUNDLE_ID,
+        clean: opts.clean,
+        erase: opts.erase,
+        launch: opts.launch,
+        ...permissions !== void 0 ? { permissions } : {}
+        // S8 — keyboard pin is always on in v1; reserve opts.pinKeyboard
+        // for future per-call override (no CLI flag yet by design).
+      },
+      { simctl, logger }
+    );
+  } catch (e) {
+    process.stderr.write(`\u2717 install failed: ${e.message}
+`);
+    return 1;
+  }
+  if (!opts.updateEnv && result.detectedPermissions.length > 0) {
+    const envSet = new Set(
+      (process.env.APP_PERMISSIONS ?? "").split(",").map((s) => s.trim()).filter(Boolean)
+    );
+    const newOnes = result.detectedPermissions.filter((s) => !envSet.has(s));
+    if (newOnes.length > 0) {
+      process.stdout.write(
+        `
+\u2139 Detected permissions in Info.plist: ${result.detectedPermissions.join(", ")}.
+   Re-run with --update-env to persist APP_PERMISSIONS and auto-grant next time.
+`
+      );
+    }
+  }
+  process.stdout.write(`
+\u2713 Installed ${result.appBundleId}
+`);
+  process.stdout.write(`  from: ${result.appPathAbsolute}
+`);
+  if (result.appUrlScheme) {
+    process.stdout.write(`  url scheme: ${result.appUrlScheme}
+`);
+  }
+  for (const s of result.slots) {
+    const flags = [
+      s.erased ? "erased" : null,
+      s.uninstalled ? "uninstalled-old" : null,
+      s.launched ? "launched" : null
+    ].filter(Boolean).join(", ");
+    process.stdout.write(
+      `  on slot ${s.slot} \u2192 ${s.simName} (${s.udid})${flags ? ` [${flags}]` : ""}
+`
+    );
+  }
+  if (result.bundleIdMismatch) {
+    process.stdout.write(
+      `
+\u26A0 Bundle id mismatch:
+   App's CFBundleIdentifier: ${result.appBundleId}
+   APP_BUNDLE_ID in .env:    ${env.APP_BUNDLE_ID}
+   Tests will fail at appLaunch / WDA session start.
+` + (opts.updateEnv ? `   --update-env was passed \u2192 syncing .env now.
+` : `   Re-run with --update-env to sync, or fix unotest/.env manually.
+`)
+    );
+  }
+  if (opts.updateEnv) {
+    const updates = [{ key: "APP_PATH", value: result.appPathAbsolute }];
+    if (result.bundleIdMismatch) {
+      updates.push({ key: "APP_BUNDLE_ID", value: result.appBundleId });
+    }
+    if (result.appUrlScheme && !process.env.APP_URL_SCHEME) {
+      updates.push({ key: "APP_URL_SCHEME", value: result.appUrlScheme });
+    }
+    if (shouldPersistPermissions(permissions, process.env.APP_PERMISSIONS)) {
+      updates.push({ key: "APP_PERMISSIONS", value: permissions.join(",") });
+    }
+    const envPath = resolve3(ENV_FILE_PATH);
+    const upd = updateEnvFile(envPath, updates);
+    const summary = [
+      upd.added.length > 0 ? `added ${upd.added.join(",")}` : null,
+      upd.changed.length > 0 ? `changed ${upd.changed.join(",")}` : null,
+      upd.unchanged.length > 0 ? `unchanged ${upd.unchanged.join(",")}` : null
+    ].filter(Boolean).join("; ");
+    process.stdout.write(`
+\u2713 ${envPath}: ${summary}
+`);
+  }
+  return 0;
+}
+__name(main, "main");
+runMain(main, 1);
+export {
+  parseArgs,
+  resolveCliPermissions,
+  shouldPersistPermissions
+};