simulator-use 0.0.0-stage → 0.8.0

package/dist/cli.js

@@ -0,0 +1,201 @@
+/**
+ * The command line, built from the same tool list as the MCP server:
+ * `simulator-use look --find "Sign In"` calls ui_look with { find: "Sign In" }.
+ */
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { persistHeld } from "./engine/state.js";
+import { serve } from "./mcp.js";
+import { callTool, toContent, TOOLS, VERSION } from "./registry.js";
+const flag = (name) => `--${name.replace(/_/g, "-")}`;
+/** Parses `--name value` and `--switch` into arguments the tool's schema accepts. */
+export function parseArgs(tool, argv) {
+    const props = tool.inputSchema.properties;
+    const args = {};
+    const list = Object.entries(props).find(([, p]) => p.type === "array")?.[0];
+    const words = [...(tool.positional ?? [])];
+    for (let i = 0; i < argv.length; i++) {
+        const raw = argv[i];
+        if (!raw.startsWith("--")) {
+            // Bare words fill the tool's positional arguments in order, then a list argument takes the rest.
+            const next = words.find((w) => !(w in args));
+            if (next) {
+                args[next] = raw;
+                continue;
+            }
+            if (list) {
+                args[list] = [...(args[list] ?? []), raw];
+                continue;
+            }
+            return `Unexpected "${raw}". ${usage(tool)}`;
+        }
+        const [name, inline] = raw.startsWith("--") ? raw.slice(2).split(/=(.*)/s, 2) : [undefined, undefined];
+        const key = name?.replace(/-/g, "_");
+        const prop = key ? props[key] : undefined;
+        if (!key || !prop || prop.type === "array")
+            return `Unknown option ${raw}. ${usage(tool)}`;
+        if (prop.type === "boolean") {
+            args[key] = inline === undefined ? true : inline !== "false";
+            continue;
+        }
+        const value = inline ?? argv[++i];
+        if (value === undefined)
+            return `${flag(key)} needs a value.`;
+        args[key] = prop.type === "number" ? Number(value) : value;
+    }
+    return args;
+}
+export function usage(tool) {
+    const entries = Object.entries(tool.inputSchema.properties);
+    const bare = (tool.positional ?? []).map((key) => ` [${key}]`).join("");
+    const options = entries.filter(([key, p]) => p.type !== "array" && !tool.positional?.includes(key)).map(([key, p]) => `${flag(key)}${p.type === "boolean" ? "" : ` <${p.type}>`}`);
+    const words = entries.filter(([, p]) => p.type === "array").map(([key]) => ` <${key}...>`).join("");
+    return `Usage: simulator-use ${tool.command}${bare}${options.length ? ` [${options.join("] [")}]` : ""}${words}`;
+}
+const quoteWord = (value) => (/^[\w@./:#+=,-]+$/.test(value) ? value : JSON.stringify(value));
+/** A hint's MCP arguments (`{device: "X", crashes: true}`) as the command's words and options. */
+function commandArgs(tool, body) {
+    const words = [];
+    const positional = [...(tool.positional ?? [])];
+    for (const [, key, raw] of body.matchAll(/(\w+):\s*("(?:[^"\\]|\\.)*"|[^,]+)/g)) {
+        let value = raw.trim();
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            // A bare word stays as it is.
+        }
+        if (positional[0] === key) {
+            positional.shift();
+            words.push(quoteWord(String(value)));
+        }
+        else if (value === true)
+            words.push(flag(key));
+        else
+            words.push(`${flag(key)}${value === false ? "=false" : ` ${quoteWord(String(value))}`}`);
+    }
+    return words;
+}
+/**
+ * On the command line a hint names commands, not MCP tools: `device_use {device: "X"}` reads `simulator-use use X`,
+ * and "pass device" reads "pass --device". Only "Next:" lines change: other lines can hold the app's own text.
+ */
+export function forCommandLine(text) {
+    const byName = new Map(TOOLS.map((t) => [t.name, t]));
+    const options = new Set(TOOLS.flatMap((t) => Object.keys(t.inputSchema.properties)));
+    const tools = new RegExp(`\\b(${TOOLS.map((t) => t.name).join("|")})\\b(?:\\s*\\{([^{}]*)\\})?`, "g");
+    return text
+        .split("\n")
+        .map((line) => line.startsWith("Next:")
+        ? line
+            .replace(tools, (_match, name, body) => {
+            const tool = byName.get(name);
+            return ["simulator-use", tool.command, ...(body ? commandArgs(tool, body) : [])].join(" ");
+        })
+            .replace(/\b([Pp]ass) (\w+)\b/g, (match, verb, key) => (options.has(key) ? `${verb} ${flag(key)}` : match))
+        : line)
+        .join("\n");
+}
+/** The first sentence of a description, ending in one period. */
+const summary = (description) => `${description.split(/\.\s/)[0].replace(/\.$/, "")}.`;
+export function help() {
+    const width = Math.max(...TOOLS.map((t) => t.command.length), 3);
+    return [
+        `simulator-use ${VERSION}: give your agent a phone.`,
+        "",
+        "Commands:",
+        ...TOOLS.map((t) => `  ${t.command.padEnd(width)}  ${summary(t.description)}`),
+        `  ${"mcp".padEnd(width)}  Run the MCP server on stdio.`,
+        `  ${"call".padEnd(width)}  Call a tool by its MCP name with JSON arguments and print one JSON line: simulator-use call ui_look '{"find":"Sign In"}'.`,
+        "",
+        "Examples:",
+        "  simulator-use run                      build, install and launch the Xcode project in this folder",
+        "  simulator-use look                     read the screen",
+        '  simulator-use act "fill #email a@b.co" "tap #signIn" \'wait "Welcome"\'',
+        "  simulator-use logs --crashes           why did it crash",
+        "",
+        "Run simulator-use <command> --help for its options.",
+    ].join("\n");
+}
+/** One command's help: what it does, its words and options with their choices. */
+export function commandHelp(tool) {
+    const lines = [tool.description, "", usage(tool)];
+    for (const [key, p] of Object.entries(tool.inputSchema.properties)) {
+        const choices = p.type !== "array" && p.enum ? ` (${p.enum.join(", ")})` : "";
+        const name = p.type === "array" ? `<${key}...>` : tool.positional?.includes(key) ? `[${key}] or ${flag(key)}` : flag(key);
+        lines.push(`  ${name}  ${p.description}${choices}`);
+    }
+    return lines.join("\n");
+}
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        console.log(help());
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(VERSION);
+        return 0;
+    }
+    if (command === "mcp") {
+        await serve();
+        // The client closed stdin: answer what was in flight, then go, even if a child process still holds a pipe.
+        process.exit(0);
+    }
+    // From here on each command is its own process: the Simulator chosen with `use` is kept in a file.
+    persistHeld();
+    if (command === "call")
+        return call(rest);
+    const tool = TOOLS.find((t) => t.command === command || t.name === command);
+    if (!tool) {
+        console.error(`Unknown command "${command}".\n\n${help()}`);
+        return 2;
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        console.log(commandHelp(tool));
+        return 0;
+    }
+    const args = parseArgs(tool, rest);
+    if (typeof args === "string") {
+        console.error(args);
+        return 2;
+    }
+    const out = await callTool(tool.name, args, { waitForJobs: true });
+    let text = out.text;
+    if (out.image) {
+        const file = join(tmpdir(), `simulator-use-${Date.now()}.${out.image.mimeType === "image/png" ? "png" : "jpg"}`);
+        await writeFile(file, out.image.data);
+        text += `\nscreenshot: ${file}`;
+    }
+    (out.isError ? console.error : console.log)(forCommandLine(text));
+    return out.isError ? 1 : 0;
+}
+/**
+ * `simulator-use call <tool> [json]`: one tool by its MCP name, answered as one line of MCP content
+ * ({content, isError}), images as base64, for programs that run simulator-use a call at a time.
+ */
+async function call([name, json, ...extra]) {
+    const fail = (text) => {
+        console.log(JSON.stringify(toContent({ text, isError: true })));
+        return 2;
+    };
+    if (!name)
+        return fail(`Usage: simulator-use call <tool> [json]. Tools: ${TOOLS.map((t) => t.name).join(", ")}.`);
+    if (extra.length)
+        return fail("simulator-use call takes one JSON object of arguments; quote it as one word.");
+    let args = {};
+    if (json !== undefined) {
+        try {
+            args = JSON.parse(json);
+        }
+        catch (error) {
+            return fail(`The arguments are not JSON: ${error.message}.`);
+        }
+    }
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return fail("The arguments must be a JSON object, like {\"find\":\"Sign In\"}.");
+    const out = await callTool(name, args, { waitForJobs: true });
+    console.log(JSON.stringify(toContent(out)));
+    return out.isError ? 1 : 0;
+}

package/dist/cloud-hint.js

@@ -0,0 +1,14 @@
+import { setting } from "./settings.js";
+/**
+ * Where simulator-use can't run (no Mac, no Xcode, no Simulator runtime), the agent is told where to get a Mac: NoMac,
+ * which makes simulator-use, rents agents cloud Macs with Xcode by the minute. Never shown when simulator-use works;
+ * SIMULATOR_USE_NO_CLOUD_HINT=1 hides it.
+ */
+export const NOMAC_URL = "https://nomac.app/?utm_source=simulator-use";
+export function cloudHint() {
+    if (setting("NO_CLOUD_HINT"))
+        return "";
+    return `No Mac to run it on? NoMac gives your agent a cloud Mac with Xcode and the iOS Simulator ready, billed by the minute: ${NOMAC_URL}`;
+}
+/** A next step, with the hint after it when it is on. */
+export const withCloudHint = (next) => [next, cloudHint()].filter(Boolean).join(" ");

package/dist/engine/apps.js

@@ -0,0 +1,153 @@
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ToolError } from "../errors.js";
+import { isOurs, run } from "./exec.js";
+import { deviceDir } from "./state.js";
+const simctl = (args, timeoutMs = 60_000) => run("xcrun", ["simctl", ...args], { timeoutMs });
+/** The value of a key in `simctl appinfo`'s old-style plist output. */
+export function plistValue(text, key) {
+    const match = new RegExp(`\\b${key} = "?([^";\\n]+)"?;`).exec(text);
+    return match?.[1]?.trim();
+}
+export async function appInfo(udid, bundleId) {
+    try {
+        const { stdout } = await simctl(["appinfo", udid, bundleId], 15_000);
+        if (!stdout.includes("CFBundleIdentifier"))
+            return undefined;
+        // simctl escapes non-ASCII names (Café as Caf\U00e9): the app's own Info.plist has them as written.
+        const path = plistValue(stdout, "Path");
+        const fromPlist = async (key) => path ? (await run("plutil", ["-extract", key, "raw", join(path, "Info.plist")], { timeoutMs: 10_000 }).catch(() => undefined))?.stdout.trim() || undefined : undefined;
+        const name = (await fromPlist("CFBundleDisplayName")) ?? (await fromPlist("CFBundleName")) ?? plistValue(stdout, "CFBundleDisplayName") ?? plistValue(stdout, "CFBundleName");
+        return { executable: (await fromPlist("CFBundleExecutable")) ?? plistValue(stdout, "CFBundleExecutable"), name };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A bundle id as Apple allows it, so it can name files safely. */
+export const BUNDLE_ID = /^[A-Za-z0-9.-]+$/;
+/** Reads the bundle id from a built .app, so `install` can name what it installed. */
+export async function bundleIdOf(appPath) {
+    const plist = join(appPath, "Info.plist");
+    if (!existsSync(plist))
+        throw new ToolError(`${appPath} is not an .app bundle (no Info.plist).`, "Pass the path to a Simulator build, such as build/Build/Products/Debug-iphonesimulator/MyApp.app.");
+    const { stdout } = await run("plutil", ["-extract", "CFBundleIdentifier", "raw", plist], { timeoutMs: 10_000 });
+    return stdout.trim();
+}
+export async function install(udid, appPath) {
+    try {
+        await simctl(["install", udid, appPath], 120_000);
+    }
+    catch (error) {
+        throw new ToolError(`Could not install ${appPath}: ${error.message}`, "Check it is built for the Simulator (iphonesimulator), not a device.");
+    }
+}
+/** The file a launched app's print() output goes to, kept while the app runs. */
+export async function consoleFile(udid, bundleId) {
+    return join(await deviceDir(udid), `${bundleId}.console.log`);
+}
+/**
+ * Launches fresh (any running copy is stopped) and keeps the app's print() output for app_logs.
+ * simctl's --stdout wrote nothing on iOS 26.5, so a detached `simctl launch --console-pty` holds the app's
+ * output instead, writing to a file until the app ends; NSUnbufferedIO is what Xcode sets so lines arrive at once.
+ */
+export async function launch(udid, bundleId) {
+    const file = await consoleFile(udid, bundleId);
+    const fd = openSync(file, "w");
+    const child = spawn("xcrun", ["simctl", "launch", "--console-pty", "--terminate-running-process", udid, bundleId], {
+        detached: true,
+        stdio: ["ignore", fd, fd],
+        env: { ...process.env, SIMCTL_CHILD_NSUnbufferedIO: "YES" },
+    });
+    closeSync(fd);
+    // A launch that fails ends the launcher within moments; a running app keeps it alive.
+    const code = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), 2_000);
+        child.once("exit", (c) => (clearTimeout(timer), resolve(c)));
+        child.once("error", () => (clearTimeout(timer), resolve(-1)));
+    });
+    child.unref();
+    if (code !== undefined && code !== 0) {
+        const output = readFileSync(file, "utf8").trim();
+        if (/not installed|FBSOpenApplicationServiceErrorDomain|Unable to find|could not be found/i.test(output)) {
+            throw new ToolError(`${bundleId} is not installed on this Simulator.`, 'Install it first: app_control {action: "install", app: "path/to/App.app"}.');
+        }
+        throw new ToolError(`Could not launch ${bundleId}: ${output.split("\n").slice(-3).join(" ")}`);
+    }
+}
+/** The app's own system log lines, streamed to a file while simulator-use watches it. */
+export async function streamFile(udid, bundleId) {
+    return join(await deviceDir(udid), `${bundleId}.syslog.log`);
+}
+/**
+ * The system log predicate for what an app itself logged: its own sender or subsystem. Apple's frameworks
+ * also log faults from inside the app (on iOS 27, a keyboard queue timeout on every first focus); a grep
+ * reaches those, and a crash is in the crash report and the print output.
+ */
+export function ownLines(executable, bundleId) {
+    const name = executable.replace(/"/g, "");
+    return `process == "${name}" AND (sender == "${name}" OR subsystem BEGINSWITH "${bundleId.replace(/"/g, "")}")`;
+}
+/**
+ * Streams the app's own log lines to a file from before it launches. \`log show\` is not enough: macOS keeps
+ * info lines only in memory, and the Simulator's UIKit noise pushed the sample app's "signed in" line out
+ * within 30 s (October 19). One stream per app and device; a new launch replaces the old stream.
+ */
+export async function startLogStream(udid, bundleId, executable) {
+    await stopLogStream(udid, bundleId);
+    const file = await streamFile(udid, bundleId);
+    const fd = openSync(file, "w");
+    const child = spawn("xcrun", ["simctl", "spawn", udid, "log", "stream", "--style", "compact", "--level", "info", "--predicate", ownLines(executable, bundleId)], {
+        detached: true,
+        stdio: ["ignore", fd, "ignore"],
+    });
+    closeSync(fd);
+    child.unref();
+    if (child.pid)
+        writeFileSync(`${file}.pid`, String(child.pid));
+    // The stream needs a moment to attach before the app's first lines.
+    await new Promise((r) => setTimeout(r, 300));
+}
+export async function stopLogStream(udid, bundleId) {
+    const pidFile = `${await streamFile(udid, bundleId)}.pid`;
+    const pid = existsSync(pidFile) ? Number(readFileSync(pidFile, "utf8")) : 0;
+    if (await isOurs(pid, /simctl spawn .* log stream/)) {
+        try {
+            process.kill(pid);
+        }
+        catch {
+            // Gone between the check and the signal.
+        }
+    }
+    rmSync(pidFile, { force: true });
+}
+export async function simctlAction(args, what, timeoutMs = 30_000) {
+    try {
+        return (await simctl(args, timeoutMs)).stdout.trim();
+    }
+    catch (error) {
+        throw new ToolError(`Could not ${what}: ${error.message}`);
+    }
+}
+export async function pushPayload(udid, bundleId, payload) {
+    await new Promise((resolve, reject) => {
+        const child = spawn("xcrun", ["simctl", "push", udid, bundleId, "-"], { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new ToolError(`Could not send the push: ${stderr.trim()}`))));
+        child.stdin.end(payload);
+    });
+}
+/** Puts text on the Simulator's clipboard, for pasting what the keyboard can't type (é, 日本, emoji). */
+export async function setPasteboard(udid, text) {
+    await new Promise((resolve, reject) => {
+        const child = spawn("xcrun", ["simctl", "pbcopy", udid], { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new ToolError(`Could not set the Simulator's clipboard: ${stderr.trim()}`))));
+        child.stdin.end(text);
+    });
+}

package/dist/engine/axe.js

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ToolError } from "../errors.js";
+import { run } from "./exec.js";
+import { setting } from "../settings.js";
+/**
+ * AXe (MIT, github.com/cameroncooke/AXe) reads the Simulator's accessibility tree and sends touches and keys,
+ * with no test runner to build. The package carries a pinned copy in vendor/axe; SIMULATOR_USE_AXE overrides it.
+ */
+export function axePath() {
+    const override = setting("AXE");
+    if (override)
+        return override;
+    // src/engine and dist/engine are both two levels below the package root.
+    const bundled = fileURLToPath(new URL("../../vendor/axe/axe", import.meta.url));
+    return existsSync(bundled) ? bundled : "axe";
+}
+/**
+ * After a Simulator's first boot, its accessibility service takes a while to accept a reader: on a fresh
+ * Xcode 27 Mac, describe-ui failed with this for about 75 s, then worked.
+ */
+export class AccessibilityStarting extends ToolError {
+}
+// Also right after a boot: "No translation object returned for simulator" (iPhone 17e, 5 s after booting).
+const STARTING = /remote automation session|No translation object returned/i;
+export async function describeUi(udid) {
+    try {
+        const { stdout } = await run(axePath(), ["describe-ui", "--udid", udid], { timeoutMs: 30_000 });
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new ToolError("AXe is missing from this install.", "Reinstall simulator-use, or set SIMULATOR_USE_AXE to an axe binary.");
+        if (STARTING.test(error.message)) {
+            throw new AccessibilityStarting("The Simulator's accessibility service is still starting; after a first boot this can take a minute or two.", "Call again in 30 seconds.");
+        }
+        throw new ToolError(`Could not read the screen: ${error.message}`, "Wait a second and call ui_look again; if it keeps failing, check the Simulator is booted with devices.");
+    }
+}
+/** A JPEG of the screen sized to points, so a point in the picture is a point to tap (402x874 is about 470 image tokens). */
+export async function screenshot(udid, points) {
+    const dir = await mkdtemp(join(tmpdir(), "simulator-use-"));
+    try {
+        const png = join(dir, "screen.png");
+        const jpg = join(dir, "screen.jpg");
+        await run(axePath(), ["screenshot", "--output", png, "--udid", udid], { timeoutMs: 30_000 });
+        const size = points.width > 0 && points.height > 0 ? ["-z", String(Math.round(points.height)), String(Math.round(points.width))] : [];
+        await run("sips", [...size, "-s", "format", "jpeg", "-s", "formatOptions", "70", png, "--out", jpg], { timeoutMs: 30_000 });
+        return await readFile(jpg);
+    }
+    catch (error) {
+        throw new ToolError(`Could not take a screenshot: ${error.message}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+const axe = (udid, args, timeoutMs = 30_000) => run(axePath(), [...args, "--udid", udid], { timeoutMs });
+/** One AXe process for several input steps (tap, type, key, key-combo, swipe, sleep): about 0.2 s cheaper per step. */
+export async function batch(udid, steps) {
+    try {
+        await axe(udid, ["batch", "--ax-cache", "none", "--type-submission", "composite", ...steps.flatMap((s) => ["--step", s])], 60_000);
+    }
+    catch (error) {
+        throw new ToolError(`The Simulator did not take the input: ${error.message}`);
+    }
+}
+/** A drag or swipe on its own: AXe's batch takes swipe but not drag. */
+export async function gesture(udid, args) {
+    try {
+        await axe(udid, args, 30_000);
+    }
+    catch (error) {
+        throw new ToolError(`The Simulator did not take the gesture: ${error.message}`);
+    }
+}
+/** The single element at a point, for reading back a field right after typing (about 0.15 s). */
+export async function elementAt(udid, x, y) {
+    try {
+        // Normally 0.15 s; on a fresh Xcode 27 VM some hung for 8 to 11 s, so a slow one is abandoned for a full read.
+        const { stdout } = await axe(udid, ["describe-ui", "--point", `${Math.round(x)},${Math.round(y)}`], 3_000);
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) ? parsed[0] : parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A step string for AXe batch: text goes in single quotes, with any single quote escaped the shell way. */
+export function typeStep(text) {
+    return `type '${text.replace(/'/g, `'\\''`)}'`;
+}
+export async function pressButton(udid, button) {
+    await axe(udid, ["button", button]);
+}
+/** Sets a slider by accessibility id or label to a percent; AXe drags it there. */
+export async function setSlider(udid, target, percent) {
+    const by = target.id ? ["--id", target.id] : ["--label", target.label ?? ""];
+    try {
+        await axe(udid, ["slider", ...by, "--value", String(percent)]);
+    }
+    catch (error) {
+        throw new ToolError(`Could not set the slider: ${error.message}`);
+    }
+}

package/dist/engine/exec.js

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+import { setting } from "../settings.js";
+/** Runs a program without a shell. Rejects with its stderr when it fails or runs past the timeout. */
+export function run(file, args, options = {}) {
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        execFile(file, args, { timeout: options.timeoutMs ?? 30_000, maxBuffer: options.maxBytes ?? 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+            // SIMULATOR_USE_DEBUG=1 prints every program run and how long it took, to find where time goes.
+            if (setting("DEBUG"))
+                process.stderr.write(`simulator-use:   ${file.split("/").pop()} ${args.slice(0, 2).join(" ")} ${Date.now() - started} ms${error ? " (failed)" : ""}\n`);
+            if (!error)
+                return resolve({ stdout, stderr });
+            const code = error.code;
+            const reason = code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+                ? "printed more output than can be read"
+                : error.killed
+                    ? `timed out after ${Math.round((options.timeoutMs ?? 30_000) / 1000)} s`
+                    : (stderr || error.message).trim();
+            reject(Object.assign(new Error(`${file.split("/").pop()} ${args[0] ?? ""}: ${reason}`), { stderr, code: error.code }));
+        });
+    });
+}
+/**
+ * Whether a pid still belongs to the process we started: a pid file can outlive its process (the Simulator shut
+ * down, the Mac restarted), and the number may by then belong to something else that must not be signalled.
+ */
+export async function isOurs(pid, pattern) {
+    if (!pid)
+        return false;
+    try {
+        const { stdout } = await run("ps", ["-o", "command=", "-p", String(pid)], { timeoutMs: 5_000 });
+        return pattern.test(stdout);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/engine/jobs.js

@@ -0,0 +1,108 @@
+import { randomBytes } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { tryLock } from "./lock.js";
+import { setting } from "../settings.js";
+const jobs = new Map();
+let latest;
+/** Stops every running job: the server is going away, and a build nobody can follow should not keep compiling. */
+export function cancelAllJobs() {
+    for (const job of jobs.values())
+        if (!job.result)
+            job.cancel?.();
+}
+// Node runs no exit handler when a signal ends the process, so the signals stop the jobs themselves.
+process.on("exit", cancelAllJobs);
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.once(signal, () => {
+        cancelAllJobs();
+        process.exit(128 + { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 }[signal]);
+    });
+}
+export function startJob(title, work) {
+    const id = `job_${randomBytes(4).toString("hex")}`;
+    const job = { id, title, started: Date.now(), step: "starting", tail: [] };
+    const progress = {
+        step: (step) => {
+            job.step = step;
+        },
+        line: (line) => {
+            job.tail.push(line);
+            if (job.tail.length > 20)
+                job.tail.shift();
+        },
+        // Cleared once the part that can be stopped (the build) is over, so a late cancel doesn't claim it stopped.
+        setCancel: (cancel) => {
+            job.cancel = cancel
+                ? () => {
+                    job.cancelled = true;
+                    cancel();
+                }
+                : undefined;
+        },
+        setLog: (file) => {
+            job.log = file;
+        },
+    };
+    job.done = work(progress)
+        .catch((error) => ({ text: error.toText?.() ?? `${title} failed: ${error.message}`, isError: true }))
+        .then((result) => {
+        // Whatever the stopped work reported (a build "fails" when killed), the truth is it was stopped.
+        if (job.cancelled)
+            result = { text: `${title} was stopped by job_cancel after ${elapsed(job)}.`, isError: true };
+        job.result = result;
+        job.cancel = undefined;
+        return result;
+    });
+    jobs.set(id, job);
+    latest = id;
+    return job;
+}
+export const getJob = (id) => jobs.get(id ?? latest ?? "");
+/** Waits for a job up to `ms`, so a caller can answer with the result when it comes soon, or with progress. */
+export async function waitFor(job, ms) {
+    if (job.result)
+        return job.result;
+    return Promise.race([job.done, delay(ms, undefined, { ref: false })]);
+}
+export const elapsed = (job) => {
+    const s = Math.round((Date.now() - job.started) / 1000);
+    return s >= 60 ? `${Math.floor(s / 60)} min ${s % 60} s` : `${s} s`;
+};
+/** A call answers within this (40 s); longer work goes on as a job. */
+export const ANSWER_WITHIN_MS = (Number(setting("JOB_AFTER_S")) || 40) * 1000;
+/** The result if it comes within 40 s, else the job to follow; the CLI just waits. */
+export async function answer(job, waitForJobs) {
+    if (waitForJobs)
+        return job.done;
+    const done = await waitFor(job, ANSWER_WITHIN_MS);
+    if (done)
+        return done;
+    return { text: `${job.title} is still ${job.step} after ${elapsed(job)}: job ${job.id}.\nNext: job_status {job_id: "${job.id}"}; it waits up to 40 s for the result.` };
+}
+/** Which running job holds a project: xcodebuild runs in that project's DerivedData, which only one may use. */
+const projects = new Map();
+/**
+ * Claims a project for a job, or names what already builds it: a job of this process, or the pid of another
+ * simulator-use process (each CLI call is its own). Released when the job ends.
+ */
+export async function claimProject(projectPath, job) {
+    const holder = projects.get(projectPath);
+    if (holder && !holder.result && holder !== job)
+        return holder;
+    // Claimed here first, so a second call of this process waiting on the lock below names this job.
+    projects.set(projectPath, job);
+    const taken = await tryLock(`project-${projectPath}`);
+    if ("holder" in taken) {
+        if (projects.get(projectPath) === job)
+            projects.delete(projectPath);
+        return taken.holder;
+    }
+    void job.done.finally(() => {
+        if (projects.get(projectPath) === job)
+            projects.delete(projectPath);
+        void taken.release();
+    });
+    return undefined;
+}
+/** The job this one is: for work that runs inside it and needs to claim things in its name. */
+export const currentJob = (id) => jobs.get(id);