simtap 0.0.0-stage → 0.6.0

package/dist/engine/simctl.js

@@ -0,0 +1,191 @@
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.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);
+    if (!fresh && cached && Date.now() - cached.at < CACHE_MS)
+        return cached.devices;
+    try {
+        const { stdout } = await run("xcrun", ["simctl", "list", "devices", "--json"], { timeoutMs: 20_000 });
+        cached = { at: Date.now(), devices: parseDevices(stdout) };
+        return cached.devices;
+    }
+    catch (error) {
+        throw new ToolError(`${NO_SIMULATOR} (${error.message})`, "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;
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/**
+ * One boot at a time on this Mac, across every simtap process (each agent runs its own). 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; and only its owner removes it.
+ */
+async function withBootLock(work) {
+    const dir = join(tmpdir(), "simtap");
+    await mkdir(dir, { recursive: true });
+    const lock = join(dir, "boot.lock.d");
+    const owner = join(lock, "pid");
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(owner, String(process.pid));
+            break;
+        }
+        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;
+            }
+            if (Date.now() > deadline)
+                throw new ToolError("Another Simulator is still booting, and boots never overlap.", "Call device_use again in 30 s.");
+            await new Promise((r) => setTimeout(r, 500));
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        if (Number(await readFile(owner, "utf8").catch(() => "0")) === process.pid)
+            await rm(lock, { recursive: true, force: true });
+    }
+}
+/**
+ * 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 (SIMTAP_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 simtap (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,30 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * What a call can leave for the next one.
+ * - The device this agent holds lives in memory: each agent runs its own MCP server, so two agents never share it.
+ * - 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;
+export const holdDevice = (udid) => {
+    held = udid;
+};
+export const heldDevice = () => held;
+/** Where simtap keeps a device's app output: the print() lines of apps it launched. */
+export async function deviceDir(udid) {
+    const dir = join(tmpdir(), "simtap", 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,253 @@
+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 { tmpdir } from "node:os";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.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}`;
+}
+/** 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(tmpdir(), "simtap", "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(tmpdir(), "simtap", "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(tmpdir(), "simtap", "last-project.json"), "utf8")).project;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function setLastProject(project) {
+    await mkdir(join(tmpdir(), "simtap"), { recursive: true });
+    await writeFile(join(tmpdir(), "simtap", "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 };
+}

package/dist/engine/xcresult.js

@@ -0,0 +1,95 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { run } from "./exec.js";
+/** Failures as Xcode records them: the test, and "File.swift:12: message" for each failed assertion. */
+export function failuresIn(nodes, bundle = "") {
+    const out = [];
+    for (const node of nodes) {
+        if (node.nodeType === "Test Case" && node.result === "Failed") {
+            const messages = [];
+            const collect = (n) => {
+                if (n.nodeType === "Failure Message" && n.name)
+                    messages.push(n.name);
+                n.children?.forEach(collect);
+            };
+            node.children?.forEach(collect);
+            // The identifier already holds the suite (SignInTests/testX()); the bundle makes it -only-testing ready.
+            const id = node.nodeIdentifier ?? node.name ?? "?";
+            const test = [bundle, id].filter(Boolean).join("/");
+            for (const message of messages.length ? messages : ["failed (no message recorded)"])
+                out.push({ test, id, message });
+        }
+        else if (node.children) {
+            out.push(...failuresIn(node.children, /test bundle$/i.test(node.nodeType ?? "") ? (node.name ?? bundle) : bundle));
+        }
+    }
+    return out;
+}
+export async function readTestReport(bundle) {
+    // Right after xcodebuild exits, one read of a finished bundle failed once; the same read a moment later worked.
+    const get = async (what, more = []) => {
+        const args = ["xcresulttool", "get", "test-results", what, ...more, "--path", bundle];
+        const out = await run("xcrun", args, { timeoutMs: 60_000 }).catch(async () => {
+            await new Promise((r) => setTimeout(r, 1_000));
+            return run("xcrun", args, { timeoutMs: 60_000 });
+        });
+        return JSON.parse(out.stdout);
+    };
+    const [summary, tests] = await Promise.all([get("summary"), get("tests")]);
+    const failures = failuresIn(tests.testNodes ?? []);
+    // Xcode 26 starts a failure message with "File.swift:12: "; Xcode 27 keeps the place in the test's details.
+    for (const f of failures.filter((x) => !/^[^\s/:]+\.\w+:\d+: /.test(x.message)).slice(0, 10)) {
+        const details = await get(`test-details`, ["--test-id", f.id]).catch(() => undefined);
+        const place = details && sourceLocation(details.testRuns ?? []);
+        if (place?.filePath)
+            Object.assign(f, { file: place.filePath, line: place.lineNumber });
+    }
+    return {
+        result: summary.result,
+        passed: summary.passedTests ?? 0,
+        failed: summary.failedTests ?? 0,
+        skipped: summary.skippedTests ?? 0,
+        total: summary.totalTestCount ?? 0,
+        failures,
+    };
+}
+/** The first source location in a test's details: where the failed assertion is. */
+export function sourceLocation(nodes) {
+    for (const node of nodes) {
+        if (node.sourceLocation?.filePath)
+            return node.sourceLocation;
+        const inner = sourceLocation(node.children ?? []);
+        if (inner)
+            return inner;
+    }
+    return undefined;
+}
+/** "SignInTests.swift:12: ..." names the file only; this finds it in the project to give its path. */
+export function locate(message, projectDir) {
+    const match = /^([^\s/:]+\.(?:swift|m|mm)):(\d+): /.exec(message);
+    if (!match)
+        return message;
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > 6 || found.length > 1)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith(".") || /^(DerivedData|build|Pods|node_modules|Carthage)$/.test(entry) || entry.endsWith(".xcodeproj") || entry.endsWith(".xcworkspace"))
+                continue;
+            const full = join(dir, entry);
+            if (entry === match[1])
+                found.push(full);
+            else if (statSync(full).isDirectory())
+                walk(full, depth + 1);
+        }
+    };
+    walk(projectDir, 0);
+    return found.length === 1 ? `${relative(projectDir, found[0])}${message.slice(match[1].length)}` : message;
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+/** A failure the agent can act on: what went wrong, and the next step. */
+export class ToolError extends Error {
+    next;
+    constructor(message, next) {
+        super(message);
+        this.next = next;
+    }
+    toText() {
+        return this.next ? `${this.message}\nNext: ${this.next}` : this.message;
+    }
+}

package/dist/look/read.js

@@ -0,0 +1,50 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { AccessibilityStarting, describeUi } from "../engine/axe.js";
+import { render, snapshot } from "./snapshot.js";
+/** Right after a launch the app's accessibility tree is empty for a moment (seen on Xcode 27). */
+const NOT_READY_RETRIES = 4;
+const NOT_READY_WAIT_MS = 750;
+const SETTLE_START_MS = 120;
+const SETTLE_TIMEOUT_MS = 4_000;
+/** How long a call keeps trying while accessibility starts, leaving room in the 45 s a call may take. */
+const STARTING_BUDGET_MS = 35_000;
+/** Reads the tree, waiting out a starting accessibility service for up to 35 s before giving up. */
+async function describeWhenReady(udid) {
+    const deadline = Date.now() + STARTING_BUDGET_MS;
+    for (;;) {
+        try {
+            return await describeUi(udid);
+        }
+        catch (error) {
+            if (!(error instanceof AccessibilityStarting) || Date.now() > deadline)
+                throw error;
+            await sleep(1_000);
+        }
+    }
+}
+export async function readScreen(udid, waitUntilReady = true) {
+    let tree = await describeWhenReady(udid);
+    let snap = snapshot(tree);
+    for (let i = 0; waitUntilReady && i < NOT_READY_RETRIES && !snap.elements.length && !snap.tabs.length; i++) {
+        await sleep(NOT_READY_WAIT_MS);
+        tree = await describeUi(udid);
+        snap = snapshot(tree);
+    }
+    return { tree, snap };
+}
+/**
+ * Waits for the screen to stop changing after an action: two reads in a row that look the same.
+ * `settled: false` means it was still moving at the timeout (an animation, a ticker, a spinner).
+ */
+export async function settle(udid) {
+    const deadline = Date.now() + SETTLE_TIMEOUT_MS;
+    await sleep(SETTLE_START_MS);
+    let last = (await readScreen(udid, false)).snap;
+    while (Date.now() < deadline) {
+        const next = (await readScreen(udid, false)).snap;
+        if (render(next) === render(last))
+            return { snap: next, settled: true };
+        last = next;
+    }
+    return { snap: last, settled: false };
+}