simulator-use 0.0.0-stage → 0.8.0

package/dist/engine/lock.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stateDir } from "./state.js";
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/** A lock's directory: names that are not plain words (a project's path) are hashed. */
+const lockDir = (name) => join(stateDir(), `${/^[\w.-]{1,80}$/.test(name) ? name : createHash("sha1").update(name).digest("hex").slice(0, 16)}.lock.d`);
+/**
+ * Takes a lock shared by every simulator-use process on this Mac (each agent, and each CLI call, is its own process).
+ * The lock is a directory, made atomically, holding the owner's pid; a lock whose owner died, or that was left
+ * without a pid for 60 s, is taken over. Returns its release, or the pid that holds it.
+ */
+export async function tryLock(name) {
+    await mkdir(stateDir(), { recursive: true });
+    const lock = lockDir(name);
+    const owner = join(lock, "pid");
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(owner, String(process.pid));
+            return {
+                // Only its owner removes it: one taken over from a dead owner belongs to someone else now.
+                release: async () => {
+                    if (Number(await readFile(owner, "utf8").catch(() => "0")) === process.pid)
+                        await rm(lock, { recursive: true, force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const holder = Number(await readFile(owner, "utf8").catch(() => "0"));
+            const age = Date.now() - ((await stat(lock).catch(() => undefined))?.mtimeMs ?? Date.now());
+            // An empty pid is a lock being made right now, unless it has been empty for a minute.
+            if ((holder && !alive(holder)) || (!holder && age > 60_000)) {
+                await rm(lock, { recursive: true, force: true });
+                continue;
+            }
+            return { holder };
+        }
+    }
+}
+/** Runs work holding the lock, waiting for it up to waitMs; past that, busy() says why it can't. */
+export async function withLock(name, waitMs, busy, work) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        const taken = await tryLock(name);
+        if ("release" in taken) {
+            try {
+                return await work();
+            }
+            finally {
+                await taken.release();
+            }
+        }
+        if (Date.now() > deadline)
+            throw busy(taken.holder);
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}

package/dist/engine/logs.js

@@ -0,0 +1,115 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ownLines } from "./apps.js";
+import { run } from "./exec.js";
+const LEVELS = { Df: "", I: "info", Db: "debug", E: "error", F: "fault" };
+/** `2026-10-19 01:56:22.114 E  Demo[94957:88904] (Sender) [subsystem:category] message`; sender and subsystem are optional. */
+const COMPACT = /^\d{4}-\d\d-\d\d (\d\d:\d\d:\d\d\.\d+) (\w+)\s+\S+?\[\d+:\w+\] (?:\(([^)]+)\) )?(?:\[([^\]]+)\] )?(.*)$/;
+/** Parses `log show --style compact`. Activity lines (type A) are bookkeeping, never kept. */
+export function parseSystemLog(output, appSubsystem) {
+    const lines = [];
+    for (const raw of output.split("\n")) {
+        const m = COMPACT.exec(raw);
+        if (!m || m[2] === "A")
+            continue;
+        const [, time, type, sender, source = "", text = ""] = m;
+        const [subsystem = "", category = ""] = source.split(":");
+        const tag = subsystem && appSubsystem && subsystem.startsWith(appSubsystem) ? category : source || (sender ? `(${sender})` : "");
+        lines.push({ time: time, level: LEVELS[type] ?? type, text: `${tag ? `${tag}: ` : ""}${text}` });
+    }
+    return lines;
+}
+/**
+ * The app's lines from the Simulator's system log. Apple's frameworks log a great deal from inside the app's
+ * process (UIKit's event dispatch, several lines a tap; on the Simulator, a haptics error every key press), so
+ * by default only what the app itself logged is read, and faults from anywhere; `everything` reads it all.
+ */
+export async function systemLog(udid, executable, seconds, bundleId, everything = false) {
+    const predicate = everything ? `process == "${executable.replace(/"/g, "")}"` : ownLines(executable, bundleId);
+    const { stdout } = await run("xcrun", ["simctl", "spawn", udid, "log", "show", "--style", "compact", "--info", "--last", `${Math.max(1, Math.ceil(seconds))}s`, "--predicate", predicate], {
+        timeoutMs: 12_000,
+    });
+    return parseSystemLog(stdout, bundleId);
+}
+/** Lines from the app's own log stream (startLogStream) that are newer than `since` (ms since 1970). */
+export async function streamedLines(file, since, bundleId) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const lines = [];
+    for (const raw of text.split("\n")) {
+        // The stamp is the Mac's local time, as `2026-10-19 02:04:48.818`.
+        const stamp = /^(\d{4}-\d\d-\d\d) (\d\d:\d\d:\d\d\.\d+)/.exec(raw);
+        if (!stamp || new Date(`${stamp[1]}T${stamp[2]}`).getTime() < since)
+            continue;
+        lines.push(...parseSystemLog(raw, bundleId));
+    }
+    return lines;
+}
+/** The app's print() output, without the Simulator's own start-up noise. */
+export function cleanConsole(text) {
+    return text
+        .replace(/\r/g, "")
+        .split("\n")
+        .filter((line) => line.trim() && !/^objc\[\d+\]: Class .* is implemented in both/.test(line));
+}
+/**
+ * Crash reports of a Simulator app land on the Mac itself, in ~/Library/Logs/DiagnosticReports, named after
+ * the app's executable. An .ips file is one JSON header line, then the report as JSON.
+ */
+export async function crashReports(executable, since, limit = 3) {
+    const dir = join(homedir(), "Library", "Logs", "DiagnosticReports");
+    let names;
+    try {
+        names = (await readdir(dir)).filter((n) => n.startsWith(`${executable}-`) && n.endsWith(".ips"));
+    }
+    catch {
+        return [];
+    }
+    const files = await Promise.all(names.map(async (n) => ({ file: join(dir, n), at: (await stat(join(dir, n))).mtimeMs })));
+    const recent = files.filter((f) => f.at >= since).sort((a, b) => b.at - a.at).slice(0, limit);
+    return Promise.all(recent.map(async (f) => {
+        const text = await readFile(f.file, "utf8");
+        // When it crashed, not when macOS finished writing the report (up to a minute later).
+        const time = /"captureTime"\s*:\s*"([^"]+)"/.exec(text)?.[1] ?? new Date(f.at).toISOString();
+        return { file: f.file, time, summary: summarizeIps(text, executable) };
+    }));
+}
+/**
+ * What went wrong and where: the exception, the reason, and the crashing thread from the top down to just past
+ * the app's own last frame (the rest is the framework that called it).
+ */
+export function summarizeIps(text, executable) {
+    const body = text.slice(text.indexOf("\n") + 1);
+    let ips;
+    try {
+        ips = JSON.parse(body);
+    }
+    catch {
+        return ["(unreadable crash report)"];
+    }
+    const out = [];
+    if (ips.exception)
+        out.push(`exception: ${[ips.exception.type, ips.exception.signal].filter(Boolean).join(" ")}`);
+    const reasons = [...(ips.termination?.reasons ?? []), ...Object.values(ips.asi ?? {}).flat(), ips.termination?.indicator ?? ""].filter(Boolean);
+    for (const reason of reasons.slice(0, 3))
+        out.push(`reason: ${reason.replace(/\s+/g, " ").trim()}`);
+    const thread = ips.threads?.find((t) => t.triggered) ?? ips.threads?.[ips.faultingThread ?? 0];
+    const all = thread?.frames ?? [];
+    const imageOf = (f) => ips.usedImages?.[f.imageIndex ?? -1]?.name ?? "?";
+    const own = (f) => Boolean(executable) && (imageOf(f) === executable || imageOf(f).startsWith(`${executable}.`));
+    const lastOwn = all.reduce((last, f, i) => (own(f) ? i : last), -1);
+    const frames = all.slice(0, lastOwn >= 0 ? Math.min(lastOwn + 3, 12) : 8).map((f) => {
+        const image = imageOf(f);
+        const where = f.sourceFile ? ` (${f.sourceFile}:${f.sourceLine ?? "?"})` : "";
+        return `  ${image} ${f.symbol ?? `+${f.imageOffset ?? 0}`}${where}`;
+    });
+    if (frames.length)
+        out.push("crashed thread:", ...frames);
+    return out;
+}

package/dist/engine/simctl.js

@@ -0,0 +1,156 @@
+import { withCloudHint } from "../cloud-hint.js";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.js";
+import { withLock } from "./lock.js";
+const NO_SIMULATOR = "This computer can't run the iOS Simulator: it needs macOS with Xcode and a Simulator runtime.";
+/** "com.apple.CoreSimulator.SimRuntime.iOS-26-5" becomes "iOS 26.5". */
+export function runtimeName(identifier) {
+    const match = /SimRuntime\.([A-Za-z]+)-(\d+)-(\d+)(?:-(\d+))?$/.exec(identifier);
+    if (!match)
+        return identifier;
+    const [, os, major, minor, patch] = match;
+    return `${os === "xrOS" ? "visionOS" : os} ${major}.${minor}${patch ? `.${patch}` : ""}`;
+}
+/** Parses `simctl list devices --json`: available devices only, booted first, then by runtime and name. */
+export function parseDevices(json) {
+    const parsed = JSON.parse(json);
+    const devices = [];
+    for (const [runtime, list] of Object.entries(parsed.devices ?? {})) {
+        for (const d of list) {
+            if (d.isAvailable === false)
+                continue;
+            devices.push({ udid: d.udid, name: d.name, state: d.state, runtime: runtimeName(runtime), booted: d.state === "Booted" });
+        }
+    }
+    // iOS before watchOS, tvOS and visionOS (by name, "watchOS 26" would sort first); the newest iOS first;
+    // iPhones before iPads: most agents want a phone.
+    const platform = (d) => (d.runtime.startsWith("iOS ") ? 0 : 1);
+    const version = (d) => d.runtime.replace(/^\S+\s/, "");
+    const family = (d) => ["iPhone", "iPad"].findIndex((p) => d.name.startsWith(p)) >>> 0;
+    return devices.sort((a, b) => Number(b.booted) - Number(a.booted) ||
+        platform(a) - platform(b) ||
+        version(b).localeCompare(version(a), undefined, { numeric: true }) ||
+        family(a) - family(b) ||
+        a.name.localeCompare(b.name, undefined, { numeric: true }));
+}
+/** The MCP server lives for a whole session: one list serves the calls of the next few seconds (0.35 s saved each). */
+const CACHE_MS = 5_000;
+let cached;
+export async function listDevices(fresh = false) {
+    if (process.platform !== "darwin")
+        throw new ToolError(NO_SIMULATOR, withCloudHint("Run simulator-use on a Mac with Xcode."));
+    if (!fresh && cached && Date.now() - cached.at < CACHE_MS)
+        return cached.devices;
+    try {
+        const { stdout } = await run("xcrun", ["simctl", "list", "devices", "--json"], { timeoutMs: 30_000 });
+        cached = { at: Date.now(), devices: parseDevices(stdout) };
+        return cached.devices;
+    }
+    catch (error) {
+        throw listError(error);
+    }
+}
+/**
+ * Why simctl gave no device list. A timeout means the Simulator service is still starting (it can take a minute
+ * the first time after a reboot or an Xcode update), not that this computer can't run it.
+ */
+export function listError(error) {
+    if (/timed out after/.test(error.message)) {
+        return new ToolError("The Simulator service did not answer within 30 s: it can take a minute to start the first time after a reboot or an Xcode update.", "Call again in 30 s.");
+    }
+    return new ToolError(`${NO_SIMULATOR} (${error.message})`, withCloudHint("Install Xcode from the App Store, open it once, then add an iOS Simulator runtime in Settings > Components."));
+}
+export async function xcodeVersion() {
+    try {
+        const { stdout } = await run("xcodebuild", ["-version"], { timeoutMs: 15_000 });
+        return stdout.split("\n")[0]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A device by name or UDID; a name on several runtimes means the booted one, else the newest. */
+export function findDevice(devices, wanted) {
+    const want = wanted.trim().toLowerCase();
+    const matches = devices.filter((d) => d.udid.toLowerCase() === want || d.name.toLowerCase() === want);
+    return matches.find((d) => d.booted) ?? matches[0];
+}
+/**
+ * The device a call works on: the one named (by name or UDID), else the one this agent holds (device_use),
+ * else the only booted one.
+ */
+export function pickDevice(devices, wanted, held) {
+    const booted = devices.filter((d) => d.booted);
+    if (wanted) {
+        const device = findDevice(devices, wanted);
+        if (!device)
+            throw new ToolError(`No Simulator named "${wanted}".`, "Call devices to see the names and UDIDs on this Mac.");
+        if (!device.booted)
+            throw new ToolError(`${device.name} (${device.runtime}) is not booted.`, `Call device_use {device: "${device.udid}"} to boot it.`);
+        return device;
+    }
+    const mine = held && booted.find((d) => d.udid === held);
+    if (mine)
+        return mine;
+    // The device this agent chose was shut down (by another agent's boot, say): never slide onto someone else's.
+    const gone = held && devices.find((d) => d.udid === held);
+    if (gone)
+        throw new ToolError(`${gone.name} (${gone.runtime}), the Simulator this agent was using, is no longer booted.`, `Call device_use {device: "${gone.udid}"} to boot it again, or device_use another.`);
+    if (booted.length === 1)
+        return booted[0];
+    if (!booted.length) {
+        const suggestion = devices.find((d) => d.name.startsWith("iPhone")) ?? devices[0];
+        throw new ToolError("No Simulator is booted.", suggestion ? `Call device_use {device: "${suggestion.name}"} to boot ${suggestion.name} (${suggestion.runtime}).` : "Call devices to see what this Mac has.");
+    }
+    throw new ToolError(`${booted.length} Simulators are booted: ${booted.map((d) => `${d.name} (${d.udid})`).join(", ")}.`, "Call device_use with the one to use, or pass device.");
+}
+/** A call may take 45 s: waiting for another boot and this boot share 40 of them. */
+const BOOT_BUDGET_MS = 40_000;
+const LOCK_WAIT_MS = 20_000;
+/**
+ * One boot at a time on this Mac, across every simulator-use process (each agent runs its own), held in a lock
+ * (lock.ts) that a dead owner's successor takes over.
+ */
+const withBootLock = (work) => withLock("boot", LOCK_WAIT_MS, () => new ToolError("Another Simulator is still booting, and boots never overlap.", "Call device_use again in 30 s."), work);
+/**
+ * Boots a device and waits until it is ready, within the time a call may take. Two Simulators booting at once
+ * on an 8 GB Mac pushed it into swap for minutes (measured October 18), so boots never overlap. With a limit on
+ * booted devices (SIMULATOR_USE_MAX_BOOTED), others are shut down first, inside the lock so two calls can't both
+ * see room.
+ */
+export async function bootDevice(device, maxBooted = Infinity) {
+    const asked = Date.now();
+    return withBootLock(async () => {
+        const started = Date.now();
+        // A boot started outside simulator-use (Xcode, simctl) is waited out too.
+        while (Date.now() - asked < LOCK_WAIT_MS && (await listDevices(true)).some((d) => d.state === "Booting" && d.udid !== device.udid)) {
+            await new Promise((r) => setTimeout(r, 1_000));
+        }
+        const others = (await listDevices(true)).filter((d) => d.booted && d.udid !== device.udid);
+        const shutDown = [];
+        for (const d of others.slice(0, Math.max(0, others.length - (maxBooted - 1)))) {
+            await shutdownDevice(d);
+            shutDown.push(d.name);
+        }
+        try {
+            await run("xcrun", ["simctl", "boot", device.udid], { timeoutMs: 20_000 });
+        }
+        catch (error) {
+            if (!/current state: Booted/i.test(error.message))
+                throw new ToolError(`Could not boot ${device.name}: ${error.message}`);
+        }
+        let ready = true;
+        try {
+            await run("xcrun", ["simctl", "bootstatus", device.udid, "-b"], { timeoutMs: Math.max(5_000, BOOT_BUDGET_MS - (Date.now() - asked)) });
+        }
+        catch {
+            ready = false;
+        }
+        cached = undefined;
+        return { ms: Date.now() - started, ready, waitedMs: started - asked, shutDown };
+    });
+}
+export async function shutdownDevice(device) {
+    await run("xcrun", ["simctl", "shutdown", device.udid], { timeoutMs: 15_000 }).catch(() => undefined);
+    cached = undefined;
+}

package/dist/engine/state.js

@@ -0,0 +1,63 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setting } from "../settings.js";
+/**
+ * What a call can leave for the next one.
+ * - The device an MCP server's agent holds lives in its memory: each agent runs its own server, so two agents
+ *   never share it. A CLI call is its own process, so the CLI keeps the device in a file (persistHeld), and
+ *   `simulator-use use` carries over to the next command.
+ * - The app last launched on a device is a small file next to its log files, so the CLI and MCP see the same.
+ */
+let held;
+let persist = false;
+/** Where simulator-use keeps its files: SIMULATOR_USE_STATE_DIR, else simulator-use in the user's temporary folder. */
+export const stateDir = () => setting("STATE_DIR") || join(tmpdir(), "simulator-use");
+const heldFile = () => join(stateDir(), "held-device.json");
+/** The CLI keeps the held device between its calls. */
+export function persistHeld() {
+    persist = true;
+}
+export const holdDevice = (udid) => {
+    held = udid;
+    if (!persist)
+        return;
+    try {
+        mkdirSync(stateDir(), { recursive: true });
+        writeFileSync(heldFile(), JSON.stringify({ udid }));
+    }
+    catch {
+        // The next call falls back to the booted device.
+    }
+};
+export const heldDevice = () => {
+    if (held || !persist)
+        return held;
+    try {
+        const { udid } = JSON.parse(readFileSync(heldFile(), "utf8"));
+        if (typeof udid === "string" && /^[0-9A-Fa-f-]{36}$/.test(udid))
+            held = udid;
+    }
+    catch {
+        // None held yet.
+    }
+    return held;
+};
+/** Where simulator-use keeps a device's app output: the print() lines of apps it launched. */
+export async function deviceDir(udid) {
+    const dir = join(stateDir(), udid);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+export async function currentApp(udid) {
+    try {
+        return JSON.parse(await readFile(join(await deviceDir(udid), "app.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function setCurrentApp(udid, app) {
+    await writeFile(join(await deviceDir(udid), "app.json"), JSON.stringify(app));
+}

package/dist/engine/xcode.js

@@ -0,0 +1,259 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createWriteStream, existsSync, readdirSync, realpathSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.js";
+import { stateDir } from "./state.js";
+import { setting } from "../settings.js";
+/**
+ * The Xcode project in a folder: a workspace first (CocoaPods and multi-project setups need it), then a
+ * project; an XcodeGen spec is generated first, and again before every build. Other kinds say what is coming.
+ */
+export async function findProject(where) {
+    const path = resolve(where);
+    if (!existsSync(path))
+        throw new ToolError(`${path} does not exist.`, "Pass path: the folder with the Xcode project.");
+    const ext = extname(path);
+    if (ext === ".xcworkspace")
+        return { kind: "workspace", path, name: basename(path, ext), dir: dirname(path) };
+    if (ext === ".xcodeproj") {
+        const dir = dirname(path);
+        const note = existsSync(join(dir, "project.yml")) ? await xcodegen(dir, true) : undefined;
+        return { kind: "project", path, name: basename(path, ext), dir, note };
+    }
+    const entries = readdirSync(path);
+    // A workspace is left as it is: regenerating its project would undo what CocoaPods added to it.
+    const workspace = entries.find((e) => e.endsWith(".xcworkspace"));
+    if (workspace)
+        return { kind: "workspace", path: join(path, workspace), name: basename(workspace, ".xcworkspace"), dir: path };
+    const project = entries.find((e) => e.endsWith(".xcodeproj"));
+    if (entries.includes("project.yml")) {
+        const note = await xcodegen(path, Boolean(project));
+        const made = readdirSync(path).find((e) => e.endsWith(".xcodeproj"));
+        if (made)
+            return { kind: "project", path: join(path, made), name: basename(made, ".xcodeproj"), dir: path, generated: !project, note };
+    }
+    if (project)
+        return { kind: "project", path: join(path, project), name: basename(project, ".xcodeproj"), dir: path };
+    if (entries.includes("app.json") || entries.includes("pubspec.yaml") || entries.some((e) => e.startsWith("capacitor.config"))) {
+        throw new ToolError("Expo, React Native, Flutter and Capacitor projects are not built by app_run yet; Xcode projects are.", "Build it with its own tool for the iOS Simulator, then app_control {action: \"install\", app: \"path/to/App.app\"}.");
+    }
+    if (entries.includes("ios") && existsSync(join(path, "ios")))
+        return findProject(join(path, "ios"));
+    throw new ToolError(`No Xcode project in ${path}.`, "Pass path: the folder with the .xcodeproj or .xcworkspace.");
+}
+/**
+ * XcodeGen makes the project from project.yml, and a spec edit or a new, moved or deleted source file needs a new
+ * project, or the build misses it. So the project is regenerated before every build; --use-cache skips the work when
+ * neither the spec nor the files changed. Answers a note when an existing project had to be built as it was.
+ */
+async function xcodegen(dir, hasProject) {
+    try {
+        await run("xcodegen", ["generate", "--quiet", "--use-cache", "--spec", join(dir, "project.yml")], { timeoutMs: 60_000 });
+        return undefined;
+    }
+    catch (error) {
+        const why = (error.message.split("\n")[0] ?? "").slice(0, 200);
+        if (!hasProject)
+            throw new ToolError(`This folder has an XcodeGen spec (project.yml) but no project, and xcodegen failed: ${why}`, "Install XcodeGen (brew install xcodegen), or generate the project yourself.");
+        return `XcodeGen could not regenerate the project from project.yml (${why}), so the existing project was built; spec edits and new files are not in it.`;
+    }
+}
+/** The scheme to build: the one asked for, the only one, or the one named like the project. */
+export async function pickScheme(project, wanted) {
+    const { stdout } = await run("xcodebuild", ["-list", "-json", project.kind === "workspace" ? "-workspace" : "-project", project.path], { timeoutMs: 60_000 });
+    const list = JSON.parse(stdout);
+    const schemes = list.workspace?.schemes ?? list.project?.schemes ?? [];
+    if (wanted) {
+        if (!schemes.includes(wanted))
+            throw new ToolError(`No scheme "${wanted}" in ${basename(project.path)}. Schemes: ${schemes.join(", ") || "none"}.`);
+        return wanted;
+    }
+    const own = schemes.filter((s) => !/^Pods-|Tests$|UITests$/.test(s));
+    if (own.length === 1)
+        return own[0];
+    const named = own.find((s) => s === project.name);
+    if (named)
+        return named;
+    if (!schemes.length)
+        throw new ToolError(`${basename(project.path)} has no shared schemes.`, "Open it in Xcode once, or share a scheme (Product > Scheme > Manage Schemes).");
+    throw new ToolError(`${basename(project.path)} has several schemes: ${own.join(", ")}.`, "Pass scheme.");
+}
+const LOCATED = /^(\/[^:]+):(\d+):(?:(\d+):)? (error|warning|fatal error): (.+)$/;
+const BARE = /^(?:xcodebuild: |clang: |ld: |\s*)?(error|fatal error): (.+)$/;
+/** One line of xcodebuild output as an error or warning, or nothing. */
+export function parseIssue(line) {
+    const located = LOCATED.exec(line);
+    if (located) {
+        const [, file, row, col, severity, message] = located;
+        return { file, line: Number(row), column: col ? Number(col) : undefined, severity: severity === "warning" ? "warning" : "error", message: message.trim() };
+    }
+    const bare = BARE.exec(line);
+    if (bare)
+        return { severity: "error", message: bare[2].trim() };
+    if (/^ld: /.test(line) || /^Undefined symbols? for architecture/.test(line))
+        return { severity: "error", message: line.trim() };
+    return undefined;
+}
+/** `Sources/App.swift:49:37`, relative to the project when the file is inside it, else absolute. */
+export function place(file, line, column, base) {
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    // /tmp and /private/tmp are the same folder; compare real paths so the file reads relative.
+    const rel = relative(real(base), real(file));
+    return `${rel && !rel.startsWith("..") ? rel : file}:${line ?? "?"}${column ? `:${column}` : ""}`;
+}
+/** `Sources/App.swift:49:37: error: ...`. */
+export function formatIssue(issue, base) {
+    return `${issue.file ? `${place(issue.file, issue.line, issue.column, base)}: ` : ""}${issue.severity}: ${issue.message}`;
+}
+/**
+ * Where builds keep their products: SIMULATOR_USE_CACHE_DIR when set (a disk kept between machines, such as
+ * NoMac's ~/drive, makes the next machine's build incremental), else simulator-use's own folder.
+ */
+export const cacheDir = () => setting("CACHE_DIR") || stateDir();
+/** Each worktree builds into its own DerivedData, so builds stay incremental and never share products. */
+export function derivedDataFor(project) {
+    const key = createHash("sha1").update(project.path).digest("hex").slice(0, 12);
+    return join(cacheDir(), "DerivedData", `${project.name}-${key}`);
+}
+export async function build(project, scheme, udid, options) {
+    const derived = derivedDataFor(project);
+    await mkdir(derived, { recursive: true });
+    const log = join(derived, `${options.action ?? "build"}-${Date.now()}.log`);
+    const args = [
+        project.kind === "workspace" ? "-workspace" : "-project",
+        project.path,
+        "-scheme",
+        scheme,
+        "-configuration",
+        options.configuration ?? "Debug",
+        "-destination",
+        `id=${udid}`,
+        "-derivedDataPath",
+        derived,
+        ...(options.extra ?? []),
+        ...(options.clean ? ["clean"] : []),
+        options.action ?? "build",
+    ];
+    const started = Date.now();
+    const out = createWriteStream(log);
+    // Its own process group, so a cancel stops the compilers it started too.
+    const child = spawn("xcodebuild", args, { cwd: project.dir, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    options.onCancel?.(() => {
+        try {
+            process.kill(-child.pid, "SIGTERM");
+        }
+        catch {
+            // Already finished.
+        }
+    });
+    const seen = new Set();
+    const errors = [];
+    let warnings = 0;
+    let pending = "";
+    const tail = [];
+    const take = (chunk) => {
+        out.write(chunk);
+        pending += chunk.toString("utf8");
+        const lines = pending.split("\n");
+        pending = lines.pop() ?? "";
+        for (const line of lines) {
+            options.onLine?.(line);
+            if (line.trim()) {
+                tail.push(line.length > 200 ? `${line.slice(0, 199)}…` : line);
+                if (tail.length > 8)
+                    tail.shift();
+            }
+            const issue = parseIssue(line);
+            if (!issue)
+                continue;
+            // The same diagnostic repeats (once per architecture or compile batch).
+            const key = `${issue.file}:${issue.line}:${issue.severity}:${issue.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (issue.severity === "warning")
+                warnings++;
+            else
+                errors.push(issue);
+        }
+    };
+    child.stdout.on("data", take);
+    child.stderr.on("data", take);
+    const code = await new Promise((resolveCode) => child.on("close", resolveCode));
+    out.end();
+    return { ok: code === 0, errors, warnings, log, ms: Date.now() - started, tail };
+}
+/** The .app a Simulator build made: the scheme's own, never a test runner. */
+export function builtApp(project, scheme, configuration = "Debug") {
+    const products = join(derivedDataFor(project), "Build", "Products", `${configuration}-iphonesimulator`);
+    if (!existsSync(products))
+        return undefined;
+    const apps = readdirSync(products).filter((e) => e.endsWith(".app") && !e.endsWith("-Runner.app"));
+    const named = apps.find((a) => a === `${scheme}.app`);
+    return named || apps.length === 1 ? join(products, named ?? apps[0]) : undefined;
+}
+const memoryFile = async (dir) => {
+    const folder = join(stateDir(), "projects");
+    await mkdir(folder, { recursive: true });
+    return join(folder, `${createHash("sha1").update(resolve(dir)).digest("hex").slice(0, 16)}.json`);
+};
+export async function remembered(dir) {
+    try {
+        return JSON.parse(await readFile(await memoryFile(dir), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function remember(dir, value) {
+    await writeFile(await memoryFile(dir), JSON.stringify(value));
+}
+/** The project the last app_run or tests_run used, for calls that name none from a folder without one. */
+export async function lastProject() {
+    try {
+        return JSON.parse(await readFile(join(stateDir(), "last-project.json"), "utf8")).project;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function setLastProject(project) {
+    await mkdir(stateDir(), { recursive: true });
+    await writeFile(join(stateDir(), "last-project.json"), JSON.stringify({ project }));
+}
+/**
+ * Which project a call means: the path given; else the current folder's (or what app_run remembered for it);
+ * else the one the last call used, so an agent that named a path once can drop it.
+ */
+export async function projectFor(path, scheme) {
+    const dir = path ?? process.cwd();
+    const memory = await remembered(dir);
+    let project;
+    let note = "";
+    try {
+        project = await findProject(memory && !path ? memory.project : dir);
+    }
+    catch (error) {
+        const last = path ? undefined : await lastProject();
+        if (!last || !existsSync(last))
+            throw error;
+        project = await findProject(last);
+        note = `No project in ${dir}; using ${project.name} from the last call (${project.dir}).\n`;
+    }
+    if (project.note)
+        note += `${project.note}\n`;
+    const rememberedScheme = memory?.project === project.path ? memory.scheme : (await remembered(project.dir))?.scheme;
+    const chosen = await pickScheme(project, scheme ?? rememberedScheme);
+    await setLastProject(project.path);
+    return { project, scheme: chosen, dir: path ? dir : project.dir, note };
+}