simulator-use 0.9.1 → 0.10.0

package/README.md

@@ -63,17 +63,18 @@ Every step is checked, so nothing succeeds silently:
 
 | Tool | CLI | Does |
 |---|---|---|
-| `app_run` | `simulator-use run` | Builds the Xcode project here, installs and launches it, answers with the first screen; errors as `file:line` |
-| `devices` | `simulator-use devices` | Lists the Simulators on this Mac with their runtime, UDID and state |
+| `app_run` | `simulator-use run` | Builds the Xcode project here, installs and launches it, answers with the first screen; errors as `file:line`; `--xcode 26.6` builds with another installed Xcode |
+| `devices` | `simulator-use devices` | Lists the Simulators on this Mac with their runtime, UDID and state, and its Xcodes |
 | `device_use` | `simulator-use use "iPhone 17 Pro"` | Chooses the Simulator the other tools use, booting it (one boot at a time); dark mode, a clean status bar |
-| `app_control` | `simulator-use app launch dev.example.app` | `install`, `launch` (answers with the first screen), `terminate`, `uninstall`, `open_url`; `grant`, `revoke` and `reset_permissions`; `location`; `push` |
+| `app_control` | `simulator-use app launch dev.example.app` | `install`, `launch` (answers with the first screen), `terminate`, `uninstall`, `open_url`; `grant`, `revoke` and `reset_permissions`; `location`; `push`; the phone's `appearance`, `locale`, `timezone`, `text_size` and a clean `status_bar` |
 | `ui_look` | `simulator-use look` | Reads the screen; `find` keeps matching lines, `screenshot` adds a picture, `full` saves the whole tree |
 | `ui_act` | `simulator-use act "tap #signIn" ...` | Does steps in order and answers with what changed |
 | `app_logs` | `simulator-use logs` | The app's print output and its own system log lines; `grep`, `wait_for`, `crashes` |
-| `tests_run` | `simulator-use test` | Runs the unit and UI tests; counts, and each failure as `file:line`; "0 tests ran" is an error |
+| `tests_run` | `simulator-use test` | Runs the unit and UI tests; each case as it finishes, counts, each failure as `file:line` and the slowest; "0 tests ran" is an error |
 | `screen_record` | `simulator-use record start` | Starts or stops a video of the screen; stop answers with the MP4 |
 | `job_status` | `simulator-use job` | Waits up to 40 s for a long build and answers with its result, or its progress |
 | `job_cancel` | `simulator-use cancel` | Stops a job |
+| `cloud` | `simulator-use cloud start` | `start`, `status`, `stop` a NoMac cloud phone that every tool then runs on; `run` builds, tests and stops in one call (see Cloud) |
 
 The MCP server and the CLI are built from one list, so they always match. The tool list and instructions stay under 4,000 tokens; a test enforces it.
 
@@ -81,6 +82,8 @@ The MCP server and the CLI are built from one list, so they always match. The to
 
 `app_run` does the whole loop in one call: it finds the project (a workspace first, then a project, an XcodeGen spec, or `ios/`), picks the scheme, builds for the Simulator, installs, launches, and answers with the first screen.
 
+The app's permissions are granted when it is installed and its first launch's prompts (notifications too) are answered, so no prompt stops the agent; `permissions: "ask"` keeps iOS's prompts, to test them. `open_url` answers iOS's "Open in …?" for a link that opens another app.
+
 ```
 Built Demo in 4.2 s, installed dev.simtap.demo.
 Launched Demo in 3.9 s.
@@ -93,6 +96,7 @@ textfield "Email" #email @201,194
 - Each folder (each git worktree) builds into its own DerivedData, so rebuilds are incremental and worktrees never share products. `SIMULATOR_USE_CACHE_DIR` puts it on a disk you keep, so the next machine's build is incremental too.
 - An XcodeGen project is regenerated from `project.yml` before each build (skipped when nothing changed), so new files are always in it.
 - The next call in the same folder needs no arguments.
+- `env: "API_URL=http://127.0.0.1:8080 MODE=test"` gives the app those variables (it reads them from `ProcessInfo`), as an Xcode scheme does; they stay for its later launches, and `env: ""` clears them.
 - An MCP call answers within 40 s; a longer build answers with a job, and `job_status` waits for it. From the CLI, `simulator-use run` simply waits.
 - Two builds of one project never run at once, also from two processes: the second says which process is building it.
 - Expo, React Native, Flutter and Capacitor builds are not done yet; build them with their own tools, then `app_control install`.
@@ -175,9 +179,44 @@ Agents that work from a shell can use the CLI instead; `skill/SKILL.md` in the p
 
 From a shell: `npx simulator-use look`.
 
+## Cloud
+
+Where this machine can't run the Simulator (Linux, Windows, a cloud agent), or for CI, the same tools run on a cloud iPhone Simulator on [NoMac](https://nomac.app/?utm_source=simulator-use), a Mac with Xcode, $0.80 an hour by the minute:
+
+```
+simulator-use cloud start      # signs in through a link the first time (or NOMAC_API_KEY), starts a phone
+simulator-use run              # every tool now runs there; run and test send the project first
+simulator-use cloud stop       # ends it; the tools run on this machine again
+simulator-use cloud run . --tests   # CI in one line: start, build, run, test, a screenshot and a recording, stop
+```
+
+Only the files the phone lacks are sent (a one-file change sends one file), into the account's own encrypted workspace, kept between sessions so builds stay incremental; build output and dependencies stay behind. The `cloud` tool does the same over MCP.
+
+`cloud start` answers a link for a person to watch the phone in a browser and one to use it. `cloud stop` answers the session's replay: the screen as a video beside every call (typed text left out), kept for 7 days.
+
+An app that talks to a backend on your machine reaches it through a tunnel (Node 22 or later):
+
+```
+simulator-use cloud tunnel 8080    # until Ctrl-C: the phone reaches localhost:8080 here, each request printed
+```
+
+The answer says the address the phone's apps use, such as `http://127.0.0.1:20199`; point the app there, for example with `run --env "API_URL=http://127.0.0.1:20199"`. Each request that passes is listed with its status and time (`cloud tunnel` without a port shows them over MCP). It lasts while the phone runs and comes back by itself after a dropped connection; `cloud tunnel` with port 0 closes it.
+
+On GitHub, from any runner, with the result posted on each pull request and the screenshot and recording kept as artifacts:
+
+```yaml
+permissions:
+  pull-requests: write
+steps:
+  - uses: actions/checkout@v5
+  - uses: NoMac-app/simulator-use@v0.10
+    with:
+      api-key: ${{ secrets.NOMAC_API_KEY }}
+```
+
 ## Privacy
 
-simulator-use sends nothing anywhere. There is no telemetry and no network access at runtime: it runs `xcrun simctl`, the bundled AXe binary and `sips`, all on your Mac.
+simulator-use sends nothing unless cloud mode is on. There is no telemetry and no network access at runtime: it runs `xcrun simctl`, the bundled AXe binary and `sips`, all on your Mac. With cloud on, it sends the project being run or tested, and the tools' calls, to NoMac, which keeps the session's replay for 7 days.
 
 ## How it works
 

package/dist/act/resolve.js

@@ -2,8 +2,26 @@ import { line } from "../look/snapshot.js";
 import { describeTarget } from "./steps.js";
 /** Kinds a person taps, preferred over plain text with the same label. */
 const TAPPABLE = new Set(["button", "back", "link", "cell", "tab", "switch", "checkbox", "radio", "textfield", "securefield", "searchfield", "textview", "popup", "menu", "segmented", "picker", "slider", "stepper"]);
+/** Words that turn a label into the opposite of the target that follows them: "Don’t Allow" is not "Allow". */
+const NEGATED = /(?:^|[^\p{L}\p{N}])(?:don['’]?t|do not|not|never|no)\s+$/iu;
 /**
- * Finds a target on the screen: by #id exactly; by label exactly (any case), then by a unique partial match;
+ * Whether a label holds the target as words of its own, not negated: "Allow" is in "Allow While Using App" and
+ * "Count: 2, Increment" holds "Increment", but "Don’t Allow" and "Disallow" do not hold "Allow" (an agent's
+ * "tap Allow" on a prompt whose buttons are "Don’t Allow" and "Continue" tapped Don’t Allow, October 23).
+ */
+function holds(label, want) {
+    const word = /^[\p{L}\p{N}]/u.test(want);
+    for (let at = label.indexOf(want); at >= 0; at = label.indexOf(want, at + 1)) {
+        const before = label.slice(0, at);
+        if ((word && /[\p{L}\p{N}]$/u.test(before)) || NEGATED.test(before))
+            continue;
+        return true;
+    }
+    return false;
+}
+/**
+ * Finds a target on the screen: by #id exactly; by label exactly (any case), then by a unique partial match (the
+ * target as words of the label, not negated);
  * or a point as given. Ties go to tappable elements; a tie that remains is an error listing the candidates.
  */
 export function resolve(snap, target) {
@@ -19,7 +37,7 @@ export function resolve(snap, target) {
         const ofKind = target.kind ? all.filter((e) => e.kind === target.kind) : all;
         found = ofKind.filter((e) => e.label?.toLowerCase() === want);
         if (!found.length)
-            found = ofKind.filter((e) => e.label?.toLowerCase().includes(want) || e.value?.toLowerCase() === want);
+            found = ofKind.filter((e) => (e.label !== undefined && holds(e.label.toLowerCase(), want)) || e.value?.toLowerCase() === want);
     }
     if (found.length > 1) {
         const tappable = found.filter((e) => TAPPABLE.has(e.kind));
@@ -47,3 +65,12 @@ export function resolve(snap, target) {
     };
 }
 export const isResolved = (r) => !("error" in r);
+const TEXT_FIELDS = new Set(["textfield", "securefield", "searchfield", "textview"]);
+/**
+ * The text field under a point, the smallest when fields nest: what `fill @x,y` aims at, so its kind is known
+ * (a secure field reads back as dots) even when the step named a point, not the field.
+ */
+export function fieldAt(elements, point) {
+    const holding = elements.filter((e) => TEXT_FIELDS.has(e.kind) && point.x >= e.frame.x && point.x <= e.frame.x + e.frame.width && point.y >= e.frame.y && point.y <= e.frame.y + e.frame.height);
+    return holding.sort((a, b) => a.frame.width * a.frame.height - b.frame.width * b.frame.height)[0];
+}

package/dist/cli.js

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import { persistHeld } from "./engine/state.js";
 import { serve } from "./mcp.js";
 import { callTool, toContent, TOOLS, VERSION } from "./registry.js";
+import { relay, relayPorts } from "./tunnel-relay.js";
 const flag = (name) => `--${name.replace(/_/g, "-")}`;
 /** Parses `--name value` and `--switch` into arguments the tool's schema accepts. */
 export function parseArgs(tool, argv) {
@@ -138,6 +139,17 @@ export async function main(argv) {
         console.log(VERSION);
         return 0;
     }
+    // The host's tunnel relay for a NoMac phone (not for people): its stdout is the tunnel, so nothing else is printed.
+    if (command === "tunnel-relay") {
+        try {
+            await relay(process.stdin, process.stdout, relayPorts(process.env.SIMULATOR_USE_PORTS));
+        }
+        catch (error) {
+            console.error(`tunnel-relay: ${error.message}`);
+            process.exit(1);
+        }
+        process.exit(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.

package/dist/cloud/account.js

@@ -0,0 +1,110 @@
+/**
+ * Cloud mode's account and phone: the NoMac account it signs in to (NOMAC_API_KEY, else the NoMac CLI's
+ * ~/.nomac/credentials.json, else NoMac's device sign-in, whose key is saved there for both tools), and the phone
+ * it uses, kept in simulator-use's state folder so every CLI call reaches the same one.
+ */
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { join } from "node:path";
+import { stateDir } from "../engine/state.js";
+import { CloudApi } from "./api.js";
+export const DEFAULT_API = "https://nomac.app";
+const credentialsFile = () => join(homedir(), ".nomac", "credentials.json");
+async function readCredentials() {
+    try {
+        return JSON.parse(await readFile(credentialsFile(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** The signed-in account's API, or nothing when there is no key yet. */
+export async function account() {
+    const stored = await readCredentials();
+    const key = process.env.NOMAC_API_KEY || stored.api_key;
+    if (!key)
+        return undefined;
+    return new CloudApi(process.env.NOMAC_API_URL || stored.api_url || DEFAULT_API, key);
+}
+/** The key from a device sign-in, kept for simulator-use and the NoMac CLI alike (mode 0600), other fields kept. */
+async function saveKey(key, base) {
+    const stored = await readCredentials();
+    await mkdir(join(homedir(), ".nomac"), { recursive: true, mode: 0o700 });
+    await writeFile(credentialsFile(), `${JSON.stringify({ ...stored, api_key: key, ...(base !== DEFAULT_API ? { api_url: base } : {}) }, null, 2)}\n`, { mode: 0o600 });
+    await chmod(credentialsFile(), 0o600);
+}
+const stateFile = () => join(stateDir(), "cloud.json");
+export async function cloudState() {
+    try {
+        return JSON.parse(await readFile(stateFile(), "utf8"));
+    }
+    catch {
+        return { on: false };
+    }
+}
+export async function setCloudState(state) {
+    await mkdir(stateDir(), { recursive: true });
+    await writeFile(stateFile(), JSON.stringify(state), { mode: 0o600 });
+}
+// ---- Device sign-in ---------------------------------------------------------------------------------------
+/** How long one call waits for the person to approve before answering with the link again. */
+const SIGN_IN_WAIT_MS = 25_000;
+/**
+ * Signs in through NoMac's device page: the first call answers the link to open (the agent shows it to its
+ * person); later calls wait up to 25 s for the approval, then save the key. Answers the account once signed in.
+ */
+export async function signIn() {
+    const ready = await account();
+    if (ready)
+        return { api: ready };
+    const state = await cloudState();
+    const base = (process.env.NOMAC_API_URL || DEFAULT_API).replace(/\/+$/, "");
+    let pending = state.signIn && state.signIn.expires_at > Date.now() && state.signIn.base === base ? state.signIn : undefined;
+    if (!pending) {
+        const started = await post(base, "/api/v1/device/start", { client_name: `simulator-use on ${hostname()}`.slice(0, 100) });
+        pending = {
+            device_code: String(started.device_code),
+            user_code: String(started.user_code),
+            url: withSource(String(started.verification_uri_complete ?? started.verification_uri)),
+            expires_at: Date.now() + Number(started.expires_in ?? 900) * 1000,
+            base,
+        };
+        await setCloudState({ ...state, signIn: pending });
+        return { link: pending.url, code: pending.user_code };
+    }
+    for (const deadline = Date.now() + SIGN_IN_WAIT_MS; Date.now() < deadline;) {
+        const answer = await post(base, "/api/v1/device/token", { device_code: pending.device_code });
+        if (answer.status === "approved" && typeof answer.api_key === "string") {
+            await saveKey(answer.api_key, base);
+            await setCloudState({ ...(await cloudState()), signIn: undefined });
+            return { api: new CloudApi(base, answer.api_key) };
+        }
+        if (answer.status === "denied" || answer.status === "expired" || answer.status === "claimed") {
+            await setCloudState({ ...(await cloudState()), signIn: undefined });
+            throw new Error(answer.status === "denied" ? "The sign-in was denied on NoMac's page." : "The sign-in link expired. Call cloud start again for a new one.");
+        }
+        await new Promise((resolve) => setTimeout(resolve, answer.status === "slow_down" ? 10_000 : 5_000));
+    }
+    return { link: pending.url, code: pending.user_code };
+}
+/** The sign-in link with simulator-use as its source, so a signup through the tool says where it came from. */
+export function withSource(link) {
+    try {
+        const url = new URL(link);
+        url.searchParams.set("utm_source", "simulator-use");
+        return url.toString();
+    }
+    catch {
+        return link;
+    }
+}
+async function post(base, path, body) {
+    const response = await fetch(`${base}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+    const payload = (await response.json().catch(() => ({})));
+    // 429 is the token route's slow_down: a pending sign-in, polled less often.
+    if (!response.ok && response.status !== 429) {
+        const error = (payload.error ?? {});
+        throw new Error(`NoMac's sign-in answered ${response.status}${error.message ? `: ${error.message}` : ""}.`);
+    }
+    return payload;
+}

package/dist/cloud/api.js

@@ -0,0 +1,62 @@
+/**
+ * NoMac's REST API as cloud mode calls it: the account's key on every request, JSON in and out, a retry for what
+ * passes (a lost connection, NoMac or the phone busy for a moment), and NoMac's own words when it refuses.
+ */
+import { VERSION } from "../registry.js";
+export class CloudError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+const PASSING = new Set([429, 502, 503, 504]);
+export class CloudApi {
+    base;
+    key;
+    constructor(base, key) {
+        this.base = base.replace(/\/+$/, "");
+        this.key = key;
+    }
+    /** One request: an object goes as JSON, bytes as a chunk. The idempotency key makes a retry the same request. */
+    async json(method, path, body, idempotencyKey) {
+        const headers = { authorization: `Bearer ${this.key}`, "user-agent": `simulator-use/${VERSION}` };
+        if (idempotencyKey)
+            headers["idempotency-key"] = idempotencyKey;
+        const raw = body instanceof Uint8Array;
+        if (body !== undefined)
+            headers["content-type"] = raw ? "application/octet-stream" : "application/json";
+        for (let attempt = 1;; attempt++) {
+            let response;
+            try {
+                response = await fetch(`${this.base}${path}`, { method, headers, body: body === undefined ? undefined : raw ? body : JSON.stringify(body), signal: AbortSignal.timeout(90_000) });
+            }
+            catch (error) {
+                if (attempt < 4) {
+                    await pause(attempt);
+                    continue;
+                }
+                throw new CloudError("unreachable", `NoMac did not answer (${error.message}).`, 0);
+            }
+            const text = await response.text();
+            let payload = {};
+            try {
+                payload = text ? JSON.parse(text) : {};
+            }
+            catch {
+                payload = {};
+            }
+            if (response.ok)
+                return payload;
+            const error = (payload.error ?? {});
+            if (PASSING.has(response.status) && attempt < 4) {
+                await pause(attempt, Number(response.headers.get("retry-after")));
+                continue;
+            }
+            throw new CloudError(error.code ?? `http_${response.status}`, error.message ?? `NoMac answered ${response.status}.`, response.status);
+        }
+    }
+}
+const pause = (attempt, retryAfter) => new Promise((resolve) => setTimeout(resolve, Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 30) * 1000 : attempt * 2000));

package/dist/cloud/forward.js

@@ -0,0 +1,109 @@
+/**
+ * With cloud on, every tool runs on the NoMac phone instead of this machine: called by name through NoMac's API
+ * and polled until it ends. app_run and tests_run send their project first, and app_control install its .app, so
+ * the paths the phone takes are its own. Answers read as a local tool's do; files they name are links.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, extname, relative, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { run } from "../engine/exec.js";
+import { ToolError } from "../errors.js";
+import { account, cloudState, setCloudState } from "./account.js";
+import { CloudError } from "./api.js";
+import { randomKey, syncFolder } from "./sync.js";
+const JOB = /Next: job_status \{job_id: "([^"]+)"\}/;
+/** The phone cloud mode uses, or why there is none. */
+export async function cloudPhone() {
+    const state = await cloudState();
+    const api = await account();
+    if (!api)
+        throw new ToolError("Cloud is on but this machine is not signed in to NoMac.", "Call cloud start to sign in, or cloud stop to run tools on this machine.");
+    if (!state.session)
+        throw new ToolError("Cloud is on but has no phone.", "Call cloud start for one, or cloud stop to run tools on this machine.");
+    return { api, session: state.session };
+}
+/** A phone that ended (its limit, an idle stop, stopped elsewhere): cloud mode forgets it and says so. */
+async function ended(session) {
+    const state = await cloudState();
+    if (state.session === session)
+        await setCloudState({ ...state, session: undefined });
+    return { text: `The cloud phone ${session} has ended (its time limit, an idle stop, or stopped elsewhere).\nNext: cloud start for a new one, or cloud stop to run tools on this machine again.`, isError: true };
+}
+/**
+ * Where a project is sent from: the repository it is in (so local packages beside it come along), else its own
+ * folder; and the path inside that the phone's tool takes.
+ */
+async function projectRoot(path) {
+    const local = resolve(path);
+    if (!existsSync(local))
+        throw new ToolError(`No project at ${local}.`, "Pass path: the folder with the .xcodeproj, .xcworkspace or project.yml.");
+    const isProject = [".xcodeproj", ".xcworkspace"].includes(extname(local));
+    const dir = isProject || !statSync(local).isDirectory() ? dirname(local) : local;
+    let folder = realpathSync(dir);
+    try {
+        folder = realpathSync((await run("git", ["-C", dir, "rev-parse", "--show-toplevel"], { timeoutMs: 5_000 })).stdout.trim());
+    }
+    catch {
+        // Not in a repository: the folder itself.
+    }
+    return { folder, inside: relative(folder, realpathSync(local)).split(sep).join("/") };
+}
+/** Runs one tool on the phone and answers as the local tool would. */
+export async function forward(name, args, context) {
+    const { api, session } = await cloudPhone();
+    let sent = args;
+    let note = "";
+    try {
+        if (name === "app_run" || name === "tests_run") {
+            const { folder, inside } = await projectRoot(typeof args.path === "string" ? args.path : ".");
+            const synced = await syncFolder(api, session, folder);
+            sent = { ...args, path: inside ? `${synced.root}/${inside}` : synced.root };
+            note = synced.sent ? `Sent ${synced.sent} of ${synced.files} files (${Math.max(1, Math.round(synced.bytes / 1024))} KB) in ${(synced.ms / 1000).toFixed(1)} s.\n` : `Sent nothing: the phone has all ${synced.files} files.\n`;
+        }
+        else if (name === "app_control" && args.action === "install" && typeof args.app === "string") {
+            const app = resolve(args.app);
+            if (extname(app) !== ".app" || !existsSync(app) || !statSync(app).isDirectory())
+                throw new ToolError(`${args.app} is not a .app built for the Simulator.`, "Build with xcodebuild -sdk iphonesimulator; the .app is under Build/Products/Debug-iphonesimulator.");
+            // Its own project on the phone, so this upload never touches the files of the project it was built from.
+            const project = `prj_${createHash("sha256").update(`app:${realpathSync(app)}`).digest("hex").slice(0, 32)}`;
+            const synced = await syncFolder(api, session, dirname(app), { only: basename(app), project });
+            sent = { ...args, app: `${synced.root}/${basename(app)}` };
+        }
+        let result = await call(api, session, name, sent);
+        // The command line waits for a long build, as it does on this Mac: job_status until the job ends.
+        for (let rounds = 0; context.waitForJobs && rounds < 60; rounds++) {
+            const job = JOB.exec(result.text)?.[1];
+            if (!job)
+                break;
+            result = await call(api, session, "job_status", { job_id: job });
+        }
+        return note ? { ...result, text: `${note}${result.text}` } : result;
+    }
+    catch (error) {
+        if (error instanceof CloudError && (error.code === "session_not_found" || error.code === "session_not_ready" || error.code === "session_expired"))
+            return ended(session);
+        if (error instanceof CloudError)
+            return { text: `NoMac: ${error.message}`, isError: true };
+        throw error;
+    }
+}
+async function call(api, session, name, args) {
+    let answer = await api.json("POST", `/api/v1/simulator/sessions/${session}/tools/${name}`, args, `cli-${name}-${randomKey()}`);
+    while (answer.state === "running" && typeof answer.id === "string") {
+        await new Promise((r) => setTimeout(r, 1_000));
+        answer = await api.json("GET", `/api/v1/simulator/sessions/${session}/calls/${answer.id}`);
+    }
+    if (answer.state === "cancelled")
+        return { text: `${name} was cancelled.`, isError: true };
+    const result = answer.result;
+    if (!result)
+        return { text: `${name} failed on the phone: ${String(answer.error ?? answer.state)}.`, isError: true };
+    const text = (result.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n");
+    const picture = (result.content ?? []).find((c) => c.type === "image" && c.data);
+    const notices = answer.notices?.includes("phone_restarted") ? "\nThe phone restarted; its apps and data are kept." : "";
+    return {
+        text: `${text}${notices}`,
+        ...(picture ? { image: { data: Buffer.from(picture.data, "base64"), mimeType: picture.mimeType === "image/png" ? "image/png" : "image/jpeg" } } : {}),
+        ...(result.isError ? { isError: true } : {}),
+    };
+}

package/dist/cloud/sync.js

@@ -0,0 +1,173 @@
+/**
+ * NoMac Simulator's sync, from cloud mode: a project folder sent to the phone's workspace with only what the
+ * workspace lacks. The manifest (each file's path, size, mtime and SHA-256) goes in pages; the host answers the
+ * paths it lacks; those go as one gzip tar, in 256 KiB chunks up to 8 MiB, else to an upload link; place writes
+ * them and every mtime (new mtimes alone make Xcode compile again), and removes what the folder no longer has.
+ * Build output and dependencies are left out, and left alone on the host.
+ */
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, sep } from "node:path";
+import { run } from "../engine/exec.js";
+/** Folders a build makes or a package manager fills: never sent, never removed on the host. */
+export const SKIP_DIRS = new Set([".git", ".hg", ".svn", "DerivedData", "build", ".build", "node_modules", "Pods", "xcuserdata", ".swiftpm", ".expo", ".gradle"]);
+const SKIP_FILES = (name) => name === ".DS_Store" || name.endsWith(".xcuserstate");
+// The protocol's limits (NoMac's mac-protocol, simManifestEntrySchema and the sim route's body).
+const PAGE_ENTRIES = 1000;
+const PAGE_BYTES = 192 * 1024;
+const CHUNK = 256 * 1024;
+const INLINE_MAX = 8 * 1024 * 1024;
+const ARCHIVE_MAX = 2 * 1024 ** 3;
+/** The project's files as the host is to have them: build output, dependencies and editor state left out. */
+export function listProject(folder) {
+    const out = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir).sort()) {
+            if (SKIP_FILES(name))
+                continue;
+            const path = join(dir, name);
+            const st = lstatSync(path);
+            if (st.isDirectory()) {
+                if (!SKIP_DIRS.has(name))
+                    walk(path);
+                continue;
+            }
+            const rel = relative(folder, path).split(sep).join("/");
+            if (st.isSymbolicLink()) {
+                const target = readlinkSync(path);
+                out.push({ path: rel, size: Buffer.byteLength(target), mtime_ms: Math.floor(st.mtimeMs), sha256: sha256(target), kind: "symlink" });
+            }
+            else if (st.isFile()) {
+                out.push({ path: rel, size: st.size, mtime_ms: Math.floor(st.mtimeMs), sha256: sha256(readFileSync(path)), kind: st.mode & 0o111 ? "executable" : "file" });
+            }
+        }
+    };
+    walk(folder);
+    return out;
+}
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+/** Pages of at most 1000 entries and about 192 KiB each, in the manifest's order. */
+export function pages(entries) {
+    const out = [[]];
+    let bytes = 0;
+    for (const entry of entries) {
+        const size = JSON.stringify(entry).length + 1;
+        if (out.at(-1).length >= PAGE_ENTRIES || (bytes + size > PAGE_BYTES && out.at(-1).length)) {
+            out.push([]);
+            bytes = 0;
+        }
+        out.at(-1).push(entry);
+        bytes += size;
+    }
+    return out;
+}
+/**
+ * The project's id on NoMac: the hash of its git remote (and its folder inside the repository), or of the folder's
+ * path where it has none, so the same project lands in the same place in the account's workspace from any clone.
+ */
+export async function projectId(folder) {
+    let key = realpathSync(folder);
+    try {
+        const remote = (await run("git", ["-C", folder, "config", "--get", "remote.origin.url"], { timeoutMs: 5_000 })).stdout.trim();
+        const top = (await run("git", ["-C", folder, "rev-parse", "--show-toplevel"], { timeoutMs: 5_000 })).stdout.trim();
+        if (remote && top)
+            key = `${normalizeRemote(remote)}#${relative(realpathSync(top), key).split(sep).join("/")}`;
+    }
+    catch {
+        // Not a git repository, or no remote: the folder's own path.
+    }
+    return `prj_${sha256(key).slice(0, 32)}`;
+}
+/** git@github.com:a/b.git, https://user:token@github.com/a/b and https://github.com/a/b/ are one remote. */
+export function normalizeRemote(remote) {
+    const scp = /^[\w.-]+@([^:/]+):(.+)$/.exec(remote);
+    const url = scp ? `ssh://${scp[1]}/${scp[2]}` : remote;
+    try {
+        const u = new URL(url);
+        return `${u.hostname.toLowerCase()}/${u.pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/, "")}`;
+    }
+    catch {
+        return remote.replace(/\.git$/, "");
+    }
+}
+/** A gzip tar of these paths, without macOS's metadata files, paths read NUL-separated from a list. */
+async function pack(folder, paths, file) {
+    const list = `${file}.list`;
+    await writeFile(list, `${paths.join("\0")}\0`);
+    const args = [...(process.platform === "darwin" ? ["--no-mac-metadata"] : []), "--null", "-czf", file, "-C", folder, "-T", list];
+    await new Promise((resolve, reject) => {
+        const child = spawn("tar", args, { env: { ...process.env, COPYFILE_DISABLE: "1" }, stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`tar: ${stderr.trim().slice(0, 300) || `exit ${code}`}`))));
+    });
+}
+/** Sends a folder to the phone's workspace. Answers where it is on the host: the path app_run and tests_run take. */
+export async function syncFolder(api, session, folder, options = {}) {
+    const { only, onStep } = options;
+    const started = Date.now();
+    const entries = listProject(folder).filter((e) => !only || e.path === only || e.path.startsWith(`${only}/`));
+    if (!entries.length)
+        throw new Error(`${folder} has no files to send.`);
+    const project = options.project ?? (await projectId(folder));
+    const sync = `cli-${randomKey()}`;
+    const book = pages(entries);
+    if (book.length > 256)
+        throw new Error(`${folder} has ${entries.length} files: more than NoMac's sync takes (256 pages).`);
+    onStep?.(`listing ${entries.length} files`);
+    const missing = [];
+    for (let page = 0; page < book.length; page++) {
+        const answer = await api.json("POST", `/api/v1/simulator/sessions/${session}/sync`, { op: "manifest", sync, project, page, pages: book.length, entries: book[page] });
+        missing.push(...(answer.missing ?? []));
+    }
+    let archive;
+    let bytes = 0;
+    if (missing.length) {
+        onStep?.(`sending ${missing.length} file${missing.length > 1 ? "s" : ""}`);
+        const dir = await mkdtemp(join(tmpdir(), "simulator-use-sync-"));
+        try {
+            const file = join(dir, "archive.tgz");
+            await pack(folder, missing, file);
+            const data = await readFile(file);
+            bytes = data.length;
+            if (bytes > ARCHIVE_MAX)
+                throw new Error(`The changed files pack to ${Math.round(bytes / 1024 ** 2)} MB: more than the 2 GB a sync takes.`);
+            const sum = sha256(data);
+            if (bytes <= INLINE_MAX) {
+                for (let offset = 0; offset < bytes || offset === 0; offset += CHUNK) {
+                    await api.json("PUT", `/api/v1/simulator/sessions/${session}/sync/blobs/${sum}?size=${bytes}&offset=${offset}`, data.subarray(offset, Math.min(offset + CHUNK, bytes)));
+                    if (bytes === 0)
+                        break;
+                }
+                archive = { blob: sum };
+            }
+            else {
+                // Larger archives go straight to storage, and the host fetches them from there.
+                const link = await api.json("POST", `/api/v1/simulator/sessions/${session}/sync/upload`, { size: bytes, sha256: sum });
+                const put = await fetch(String(link.upload_url), { method: "PUT", body: data, headers: { "content-length": String(bytes) } });
+                if (!put.ok)
+                    throw new Error(`The upload to NoMac's storage failed: ${put.status}.`);
+                archive = link.archive;
+            }
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    }
+    onStep?.("placing");
+    for (const deadline = Date.now() + 10 * 60_000;;) {
+        const placed = await api.json("POST", `/api/v1/simulator/sessions/${session}/sync`, { op: "place", sync, ...(archive ? { archive } : {}) });
+        if (placed.state === "done")
+            return { root: String(placed.root), files: entries.length, sent: missing.length, bytes, ms: Date.now() - started };
+        if (placed.state !== "running")
+            throw new Error(`The sync failed on the phone: ${String(placed.error ?? placed.state)}.`);
+        if (Date.now() > deadline)
+            throw new Error("The sync was still being written after 10 minutes.");
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+    }
+}
+export const randomKey = () => randomBytes(16).toString("hex");