@nomac/cli 0.14.0 → 0.15.0

package/README.md

@@ -21,7 +21,7 @@ claude mcp add nomac -- npx @nomac/cli mcp
 codex mcp add nomac -- npx @nomac/cli mcp
 ```
 
-Both MCP servers, `nomac mcp` here and the hosted `https://mcp.nomac.app/mcp` (no install), list the Mac and the cloud iPhone (the `phone` tools). App Store work (signing, TestFlight and App Store Connect) is `https://mcp.nomac.app/appstore` on the same sign-in, and `https://mcp.nomac.app/all` has everything. The cloud iPhone alone (NoMac Simulator): `https://mcp.nomac.app/simulator`, or `npx simulator-use cloud start` from any terminal.
+Both MCP servers, `nomac mcp` here and the hosted `https://mcp.nomac.app/mcp` (no install), list the Mac and the cloud iPhone (the `phone` tools). App Store work (signing, TestFlight and App Store Connect) is `https://mcp.nomac.app/appstore` on the same sign-in, and `https://mcp.nomac.app/all` has everything. The cloud iPhone alone (NoMac Simulator): `https://mcp.nomac.app/simulator`, or `npx simulator-use cloud start` from any terminal. In `nomac mcp`, `phone_app_run` with `local_path` sends this machine's project to the phone, only the files that changed.
 
 ## What else
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "A real cloud Mac for AI agents: Xcode, the iOS Simulator, signing, TestFlight and App Store publishing, by the minute, over MCP, SSH and HTTPS.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -19,7 +19,10 @@ phone tools (`phone`, `phone_app_run`, `phone_ui_look`, `phone_ui_act` and the
 other `phone_*`), which NoMac's MCP lists beside the Mac (`nomac mcp` and
 https://mcp.nomac.app/mcp); https://mcp.nomac.app/simulator for the phone
 alone; or `npx simulator-use cloud start` from a terminal
-(https://nomac.app/simulator).
+(https://nomac.app/simulator). `phone_app_run` builds from a git link, or from
+the project here: in `nomac mcp`, `local_path` sends the folder (only what
+changed); on the hosted server, `phone_upload_link` answers one command that
+sends it.
 
 ## Cloud Mac setup and workflow
 

package/src/mcp.mjs

@@ -18,7 +18,7 @@ const PROTOCOL_FALLBACK = "2025-06-18";
 /** How the tools fit together, sent once at initialize (the hosted server sends the same kind of text), within the 4,096 characters Claude Code keeps. */
 const INSTRUCTIONS = [
   "NoMac gives you a cloud iPhone and a cloud Mac with Xcode, billed from prepaid credit ($0.80 an hour, by the minute).",
-  "The cloud iPhone (the phone tools: phone and phone_*) builds, runs and tests an iOS app, ready in seconds, no shell: phone with action start (its answer has links.view for the person); phone_app_run with git (an https repository link) or upload (phone_upload_link) builds and runs the app, incrementally; phone_ui_look reads the screen as text, phone_ui_act taps and types by label; phone_app_logs, phone_tests_run; a long build answers with a job for phone_job_status; phone with action stop when done. The Mac (start_mac and the Mac tools) does the rest.",
+  "The cloud iPhone (the phone tools: phone and phone_*) builds, runs and tests an iOS app, ready in seconds, no shell: phone with action start (its answer has links.view for the person); phone_app_run with local_path (a folder here, only changes sent) or git (an https repository link) builds and runs the app, incrementally; phone_ui_look reads the screen as text, phone_ui_act taps and types by label; phone_app_logs, phone_tests_run; a long build answers with a job for phone_job_status; phone with action stop when done. The Mac (start_mac and the Mac tools) does the rest.",
   "Use it when work needs macOS this machine lacks (Windows, Linux, a cloud sandbox): an iOS, iPadOS, watchOS, visionOS or macOS app (Swift, SwiftUI, React Native, Expo, Flutter, Capacitor), Xcode, signing, TestFlight or the App Store.",
   "Typical flow: get_mac_credits, start_mac, poll get_mac_session until ready, put code there (exec_mac with git clone into ~/drive/src, write_mac_file, fetch_to_mac, create_mac_upload_link), run exec_mac, get results with read_mac_file or create_mac_download_link, then stop_mac.",
   "The account's drive at ~/drive (20 GB) is on every Mac and kept between sessions; everything outside it is deleted at stop. Clone and build in ~/drive/src/<repo> so the next session rebuilds only what changed; keep it under 10 GB (nomac-drive shows what takes the space, nomac-drive clean deletes stale build products).",
@@ -32,7 +32,7 @@ const INSTRUCTIONS = [
   "The Mac is fully enabled for you: sudo needs no password, prompts and password dialogs are answered within seconds, the screen never locks, and the login password is in $NOMAC_MAC_PASSWORD on it. nomac-permit APP camera (with exec_mac) grants an app privacy permissions before it asks. To type or click as a person would, also on the lock screen, call mac_input; when screenshot_mac reports screen_locked or a dialog, follow its next_step.",
   "A Mac stops at its time limit (2 hours unless start_mac set max_duration_seconds), its spend cap, its idle timeout or when credit runs out; everything outside ~/drive is deleted then. In its last 15 minutes answers carry stop_notice: extend_mac keeps it running (time limit or spend cap), or the human adds credit (reason credit). Before a long build, check that it fits.",
   "When an answer carries cli_update, this NoMac CLI is out of date: tell the human, who updates it with npm install -g @nomac/cli@latest (or nomac update) and restarts this MCP server.",
-  "Always stop_mac when finished, after reading any output you need, so credit is not spent on an idle Mac.",
+  "Always stop_mac when finished, after reading the output you need, so no credit goes to an idle Mac.",
 ].join(" ");
 
 const text = (obj) => ({

package/src/phone-sync.mjs

@@ -0,0 +1,314 @@
+// A folder on this machine to the cloud iPhone's workspace, for local_path on the phone tools: simulator-use's own
+// sync (its cloud mode, src/cloud/sync.ts), through the same REST API. The manifest (each file's path, size, mtime
+// and SHA-256) goes in pages; the phone 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 phone. A
+// file's hash is kept in an index on this machine, so only files that changed since the last sync are read again.
+
+import { execFile, spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream, existsSync, lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readlink, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { api } from "./api.mjs";
+
+/** Folders a build makes or a package manager fills: never sent, never removed on the phone. */
+const SKIP_DIRS = new Set([".git", ".hg", ".svn", "DerivedData", "build", ".build", "node_modules", "Pods", "xcuserdata", ".swiftpm", ".expo", ".gradle"]);
+/**
+ * Key and credential files, never sent even when git tracks them: environment files (but their examples), signing
+ * keys and certificates, provisioning profiles, keystores, SSH keys and .netrc. A Simulator build needs none of them.
+ */
+const secretFile = name => (/^\.env(\..+)?$/.test(name) && !/\.(example|sample|template)$/.test(name)) ||
+  /\.(p8|p12|pfx|pem|key|mobileprovision|provisionprofile|keystore|jks)$/i.test(name) ||
+  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/.test(name) || name === ".netrc";
+const SKIP_FILES = name => name === ".DS_Store" || name.endsWith(".xcuserstate") || secretFile(name);
+// 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;
+/** Files hashed at once. */
+const HASHING = 8;
+/** A file changed within this long of a scan is read again at the next one (coarse mtimes on some file systems). */
+const RACY_MS = 2_000;
+
+const sha256 = data => createHash("sha256").update(data).digest("hex");
+const phones = "/api/v1/simulator/sessions";
+
+/** Runs a program without a shell; rejects with its stderr when it fails or runs past the timeout. */
+const run = (file, args, timeoutMs = 30_000) => new Promise((resolve_, reject) => {
+  execFile(file, args, { timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+    if (!error) return resolve_({ stdout });
+    reject(new Error(`${file} ${args[0] ?? ""}: ${error.killed ? `timed out after ${Math.round(timeoutMs / 1000)} s` : (stderr || error.message).trim()}`));
+  });
+});
+
+/**
+ * The files git tracks in folder, or would (untracked but not ignored), from the folder, a submodule's too; undefined
+ * when folder is not a repository's top (or git is not there).
+ */
+async function filesInGit(folder) {
+  try {
+    const top = (await run("git", ["-C", folder, "rev-parse", "--show-toplevel"], 5_000)).stdout.trim();
+    if (realpathSync(top) !== realpathSync(folder)) return undefined;
+  } catch {
+    return undefined;
+  }
+  const list = async (dir, prefix, depth) => {
+    const listed = (await run("git", ["-C", dir, "ls-files", "-co", "--exclude-standard", "-z"], 60_000)).stdout.split("\0").filter(Boolean);
+    const out = [];
+    for (const rel of listed.map(path => path.replace(/\/+$/, ""))) {
+      // A submodule (or a repository inside) is listed as its folder: its own files, by its own rules.
+      if (depth < 4 && lstatSync(join(dir, rel), { throwIfNoEntry: false })?.isDirectory()) out.push(...await list(join(dir, rel), `${prefix}${rel}/`, depth + 1).catch(() => []));
+      else out.push(`${prefix}${rel}`);
+    }
+    return out;
+  };
+  try {
+    return await list(folder, "", 0);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The files git tracks as executable (mode 100755) under folder, by their path from it; none outside a repository. */
+async function executablesInGit(folder) {
+  try {
+    const listed = (await run("git", ["-C", folder, "ls-files", "-s", "-z"], 30_000)).stdout;
+    // Each entry: <mode> <object> <stage>\t<path>, NUL-separated; the paths are from the folder.
+    return new Set(listed.split("\0").filter(e => e.startsWith("100755 ")).map(e => e.slice(e.indexOf("\t") + 1)));
+  } catch {
+    return new Set();
+  }
+}
+
+const indexFile = (folder, only) => join(homedir(), ".nomac", "phone-sync-index", `${sha256(`${realpathSync(folder)}\0${only ?? ""}`).slice(0, 32)}.json`);
+async function readIndex(file) {
+  try {
+    const index = JSON.parse(await readFile(file, "utf8"));
+    return typeof index.scanned_ms === "number" && index.files && typeof index.files === "object" ? index : undefined;
+  } catch {
+    return undefined;
+  }
+}
+async function writeIndex(file, index) {
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(index), { mode: 0o600 });
+  await rename(tmp, file);
+}
+/** A file's SHA-256: small files read at once, larger ones streamed. */
+async function hashFile(path, size) {
+  if (size < 1024 * 1024) return sha256(await readFile(path));
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest("hex");
+}
+/** Runs work on each item, at most limit at a time. */
+async function eachLimit(items, limit, work) {
+  let next = 0;
+  const worker = async () => { while (next < items.length) { const i = next++; await work(items[i], i); } };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+
+/**
+ * The project's files as the phone is to have them: in a git repository, the files git tracks or would track
+ * (.gitignore's rules kept), else the folder's; build output, dependencies, editor state and key or credential files
+ * left out either way. With only (a .app beside others in its folder), that one alone and all of it: a bundle's own
+ * folders are part of the app. A file whose size, mtime, ctime and inode match the index is not read again.
+ */
+export async function listProject(folder, only) {
+  const found = [];
+  const walk = (dir, whole) => {
+    for (const name of readdirSync(dir).sort()) {
+      if (!whole && SKIP_FILES(name)) continue;
+      const path = join(dir, name);
+      const st = lstatSync(path);
+      if (st.isDirectory()) {
+        if (whole || !SKIP_DIRS.has(name)) walk(path, whole);
+        continue;
+      }
+      if (st.isSymbolicLink() || st.isFile()) found.push({ rel: relative(folder, path).split(sep).join("/"), path, st });
+    }
+  };
+  if (only) {
+    const top = join(folder, only);
+    if (lstatSync(top, { throwIfNoEntry: false })?.isDirectory()) walk(top, true);
+  } else {
+    const tracked = await filesInGit(folder);
+    if (!tracked) walk(folder, false);
+    else {
+      for (const rel of tracked.sort()) {
+        const parts = rel.split("/");
+        if (SKIP_FILES(parts.at(-1)) || parts.slice(0, -1).some(part => SKIP_DIRS.has(part))) continue;
+        const path = join(folder, ...parts);
+        const st = lstatSync(path, { throwIfNoEntry: false });
+        if (st && (st.isSymbolicLink() || st.isFile())) found.push({ rel, path, st });
+      }
+    }
+  }
+  // Windows keeps no executable bit: git's index has it for the files it tracks (a build phase's script).
+  const gitExecutable = process.platform === "win32" ? await executablesInGit(folder) : undefined;
+  const file = indexFile(folder, only);
+  const last = await readIndex(file);
+  const scanned = Date.now();
+  const next = {};
+  const out = new Array(found.length);
+  await eachLimit(found, HASHING, async ({ rel, path, st }, i) => {
+    if (st.isSymbolicLink()) {
+      const target = await readlink(path);
+      out[i] = { path: rel, size: Buffer.byteLength(target), mtime_ms: Math.floor(st.mtimeMs), sha256: sha256(target), kind: "symlink" };
+      return;
+    }
+    const known = last?.files[rel];
+    // Git's rule for a racy entry: a file changed within RACY_MS of the last scan may have changed again since,
+    // with the same mtime, so it is read again.
+    const same = known && known.size === st.size && known.mtime_ms === st.mtimeMs && known.ctime_ms === st.ctimeMs && known.ino === st.ino && st.mtimeMs < last.scanned_ms - RACY_MS;
+    const hash = same ? known.sha256 : await hashFile(path, st.size);
+    next[rel] = { size: st.size, mtime_ms: st.mtimeMs, ctime_ms: st.ctimeMs, ino: st.ino, sha256: hash };
+    const executable = gitExecutable ? gitExecutable.has(rel) : Boolean(st.mode & 0o111);
+    out[i] = { path: rel, size: st.size, mtime_ms: Math.floor(st.mtimeMs), sha256: hash, kind: executable ? "executable" : "file" };
+  });
+  await writeIndex(file, { scanned_ms: scanned, files: next }).catch(() => undefined);
+  return out;
+}
+
+/** 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;
+}
+
+/** 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$/, "");
+  }
+}
+
+/**
+ * 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, and
+ * where simulator-use's cloud mode puts it too.
+ */
+export async function projectId(folder) {
+  let key = realpathSync(folder);
+  try {
+    const remote = (await run("git", ["-C", folder, "config", "--get", "remote.origin.url"], 5_000)).stdout.trim();
+    const top = (await run("git", ["-C", folder, "rev-parse", "--show-toplevel"], 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)}`;
+}
+
+/** 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 phone (the path the phone's tools take) and what went. */
+export async function syncFolder(session, folder, options = {}) {
+  const { only } = options;
+  const started = Date.now();
+  const entries = await listProject(folder, only);
+  if (!entries.length) throw new Error(`${folder} has no files to send.`);
+  const project = options.project ?? await projectId(folder);
+  const sync = `cli-${randomBytes(16).toString("hex")}`;
+  const book = pages(entries);
+  if (book.length > 256) throw new Error(`${folder} has ${entries.length} files: more than NoMac's sync takes (256 pages).`);
+  // Pages go 4 at a time: the phone keeps each by its number, and places once it has them all.
+  const answered = new Array(book.length);
+  await eachLimit(book, 4, async (entriesOfPage, page) => {
+    const answer = await api("POST", `${phones}/${session}/sync`, { body: { op: "manifest", sync, project, page, pages: book.length, entries: entriesOfPage } });
+    // Only paths this page listed are packed: an answer naming any other file of the folder sends nothing more.
+    const listed = new Set(entriesOfPage.map(e => e.path));
+    answered[page] = (answer.missing ?? []).filter(path => typeof path === "string" && listed.has(path));
+  });
+  const missing = answered.flat();
+  let archive;
+  let bytes = 0;
+  if (missing.length) {
+    const dir = await mkdtemp(join(tmpdir(), "nomac-phone-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 += CHUNK) {
+          await api("PUT", `${phones}/${session}/sync/blobs/${sum}?size=${bytes}&offset=${offset}`, { raw: data.subarray(offset, Math.min(offset + CHUNK, bytes)) });
+        }
+        archive = { blob: sum };
+      } else {
+        // Larger archives go straight to storage, and the phone fetches them from there.
+        const link = await api("POST", `${phones}/${session}/sync/upload`, { body: { 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 });
+    }
+  }
+  for (const deadline = Date.now() + 10 * 60_000; ;) {
+    const placed = await api("POST", `${phones}/${session}/sync`, { body: { 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(r => setTimeout(r, 1_000));
+  }
+}
+
+/**
+ * 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.
+ */
+export async function projectRoot(path) {
+  const local = resolve(path);
+  if (!existsSync(local)) throw new Error(`No project at ${local}. Pass local_path: the folder with the .xcodeproj, .xcworkspace or Package.swift.`);
+  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"], 5_000)).stdout.trim());
+  } catch {
+    // Not in a repository: the folder itself.
+  }
+  return { folder, inside: relative(folder, realpathSync(local)).split(sep).join("/") };
+}
+
+/** A .app built for the Simulator on this machine, sent as a project of its own, so it never touches the files of the project it was built from. */
+export async function syncApp(session, path) {
+  const app = resolve(path);
+  if (extname(app) !== ".app" || !existsSync(app) || !statSync(app).isDirectory()) throw new Error(`${path} is not a .app built for the Simulator: build with xcodebuild -sdk iphonesimulator; the .app is under Build/Products/Debug-iphonesimulator.`);
+  const project = `prj_${sha256(`app:${realpathSync(app)}`).slice(0, 32)}`;
+  const synced = await syncFolder(session, dirname(app), { only: basename(app), project });
+  return { ...synced, app: `${synced.root}/${basename(app)}` };
+}

package/src/phone-tools.json

@@ -120,9 +120,9 @@
      "pattern": "^[A-Z_][A-Z0-9_]{0,63}$"
     },
     "upload": {
-     "description": "Instead of git: the sha256 of a .tar.gz or .zip put to phone_upload_link's link, unpacked into the phone's workspace (only what changed)",
+     "description": "Instead of git: the upload phone_upload_link answered (a folder or archive sent to its link), unpacked into the phone's workspace (only what changed)",
      "type": "string",
-     "pattern": "^[a-f0-9]{64}$"
+     "pattern": "^(up_[a-f0-9]{32}|[a-f0-9]{64})$"
     },
     "name": {
      "description": "With upload: where it goes, the same name each time keeps builds incremental; default: upload",
@@ -251,12 +251,12 @@
      "type": "string"
     },
     "upload": {
-     "description": "install: the sha256 of a .zip or .tar.gz holding the .app, put to phone_upload_link's link",
+     "description": "install: the upload phone_upload_link answered, a .zip or .tar.gz holding the .app",
      "type": "string",
-     "pattern": "^[a-f0-9]{64}$"
+     "pattern": "^(up_[a-f0-9]{32}|[a-f0-9]{64})$"
     },
     "name": {
-     "description": "With upload: where it goes, the same name each time keeps builds incremental; default: upload",
+     "description": "With upload: where it goes; default: app",
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{1,80}$"
     },
@@ -362,9 +362,9 @@
      "pattern": "^[A-Z_][A-Z0-9_]{0,63}$"
     },
     "upload": {
-     "description": "Instead of git: the sha256 of a .tar.gz or .zip put to phone_upload_link's link, unpacked into the phone's workspace (only what changed)",
+     "description": "Instead of git: the upload phone_upload_link answered (a folder or archive sent to its link), unpacked into the phone's workspace (only what changed)",
      "type": "string",
-     "pattern": "^[a-f0-9]{64}$"
+     "pattern": "^(up_[a-f0-9]{32}|[a-f0-9]{64})$"
     },
     "name": {
      "description": "With upload: where it goes, the same name each time keeps builds incremental; default: upload",
@@ -466,31 +466,27 @@
  },
  {
   "name": "phone_upload_link",
-  "description": "Cloud iPhone: Answers a link to PUT a .tar.gz or .zip to (a project without a git link, or a .app built elsewhere), up to 2 GB, for the account's running phone. Then pass its sha256 as upload to phone_app_run, phone_tests_run or phone_app_control install.",
+  "description": "Cloud iPhone: Answers a link for the account's running phone that takes a project folder from this machine (a project without a git link) or a .app built elsewhere, up to 2 GB, and upload_command, which packs the folder it runs in and sends it in one step. Then pass upload to phone_app_run, phone_tests_run or phone_app_control install. size and sha256 together make a link for that one archive instead.",
   "inputSchema": {
    "type": "object",
    "properties": {
     "size": {
+     "description": "With sha256: the archive's exact size in bytes; the link then takes only that archive",
      "type": "integer",
      "minimum": 1,
-     "maximum": 9007199254740991,
-     "description": "The archive's exact size in bytes: the link takes only that size"
+     "maximum": 9007199254740991
     },
     "sha256": {
+     "description": "With size: the archive's sha256, which upload is then",
      "type": "string",
-     "pattern": "^[a-f0-9]{64}$",
-     "description": "The archive's sha256 (shasum -a 256)"
+     "pattern": "^[a-f0-9]{64}$"
     },
     "session_id": {
      "description": "The phone; default: the account's running phone",
      "type": "string",
      "pattern": "^ses_[A-Za-z0-9_-]{1,80}$"
     }
-   },
-   "required": [
-    "size",
-    "sha256"
-   ]
+   }
   }
  },
  {

package/src/phone-tools.mjs

@@ -5,7 +5,9 @@
 
 import { randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { api } from "./api.mjs";
+import { projectRoot, syncApp, syncFolder } from "./phone-sync.mjs";
 
 const LISTED = JSON.parse(readFileSync(new URL("./phone-tools.json", import.meta.url), "utf8"));
 /** A phone tool's simulator-use name for its listed one: phone is cloud, phone_ui_look is ui_look. */
@@ -55,7 +57,8 @@ async function place(phone, input, args, tool, key, fits) {
     if (cloned.state !== "done") return asText(cloned.state === "running" ? { state: "running", next: `The repository is still being fetched. Call ${tool} again with the same request_key.`, request_key: key } : { error: { code: String(cloned.error ?? "clone_failed"), message: String(cloned.message ?? "The repository could not be fetched.") } });
     args.path = typeof args.path === "string" && args.path ? `${cloned.root}/${args.path.replace(/^\/+/, "")}` : cloned.root;
   } else if (upload) {
-    const body = { sha256: upload, ...(name ? { name } : {}) };
+    // A .app has a place of its own, so installing one never replaces an uploaded project's files.
+    const body = { ...(upload.startsWith("up_") ? { upload } : { sha256: upload }), name: name ?? (tool === "phone_app_control" ? "app" : "upload") };
     let fetched = await api("POST", `${phones}/${phone}/sync/fetch`, { body, idempotencyKey: `${key}-fetch` });
     for (let i = 0; fetched.state === "running" && i < 3 && fits(2); i++) fetched = await api("POST", `${phones}/${phone}/sync/fetch`, { body, idempotencyKey: `${key}-fetch` });
     if (fetched.state !== "done") return asText(fetched.state === "running" ? { state: "running", next: `The upload is still being unpacked. Call ${tool} again with the same request_key.`, request_key: key } : { error: { code: String(fetched.error ?? "fetch_failed"), message: String(fetched.message ?? "The upload could not be unpacked.") } });
@@ -71,23 +74,40 @@ async function place(phone, input, args, tool, key, fits) {
 
 /** One of simulator-use's tools on the account's phone. */
 const simulatorTool = (listed, bare) => async input => {
-  const { session_id, request_key, git, ref, secret, upload, name, ...args } = input;
+  const { session_id, request_key, git, ref, secret, upload, name, local_path, ...args } = input;
+  if (local_path !== undefined && (git || upload)) return error("invalid_request", `local_path, git and upload each say where the project comes from: pass one. Nothing was sent; call ${listed} again.`);
+  if (local_path !== undefined && listed === "phone_app_control" && args.action !== "install") return error("invalid_request", "local_path is for install: the .app to send from this machine. Nothing was sent.");
   const phone = session_id ?? await runningPhone();
   if (typeof phone !== "string") return phone;
   const key = request_key ?? newKey();
   // An MCP client gives a call about two minutes: a fetch and the tool call each take up to 45 s.
   const began = Date.now();
   const fits = calls => Date.now() - began + calls * 47_000 < 112_000;
+  let sent;
+  if (local_path !== undefined) {
+    // Only what the phone lacks goes: a one-line change sends one file, and the build stays incremental.
+    const synced = listed === "phone_app_control" ? await syncApp(phone, local_path)
+      : await projectRoot(typeof args.path === "string" && args.path ? join(local_path, args.path) : local_path).then(async ({ folder, inside }) => ({ ...await syncFolder(phone, folder), inside }));
+    if (listed === "phone_app_control") args.app = synced.app;
+    else args.path = synced.inside ? `${synced.root}/${synced.inside}` : synced.root;
+    sent = 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.` : `Sent nothing: the phone has all ${synced.files} files.`;
+  }
   const placed = await place(phone, { git, ref, secret, upload, name }, args, listed, key, fits);
   if (placed) return placed;
-  if ((git || upload) && !fits(1)) return asText({ state: "running", request_key: key, next: `The project is on the phone. Call ${listed} again with the same arguments and request_key ${key} to run it.` });
-  return phoneReply(await api("POST", `${phones}/${phone}/tools/${bare}`, { body: args, idempotencyKey: key }), listed, key);
+  if ((git || upload || sent) && !fits(1)) return asText({ state: "running", request_key: key, ...(sent ? { sent } : {}), next: `The project is on the phone. Call ${listed} again with the same arguments and request_key ${key} to run it${sent ? " (only what changed is sent again)" : ""}.` });
+  const reply = phoneReply(await api("POST", `${phones}/${phone}/tools/${bare}`, { body: args, idempotencyKey: key }), listed, key);
+  if (!sent) return reply;
+  // What was sent comes first, as the local tool's note does; after an error, which stays the answer's first part.
+  return { ...reply, content: reply.isError ? [...reply.content, { type: "text", text: sent }] : [{ type: "text", text: sent }, ...reply.content] };
 };
 
 async function uploadLink({ size, sha256, session_id }) {
+  if ((size === undefined) !== (sha256 === undefined)) return error("invalid_request", "Pass size and sha256 together, or neither for a link that takes any upload. Nothing was sent; call phone_upload_link again.");
   const phone = session_id ?? await runningPhone();
   if (typeof phone !== "string") return phone;
-  const link = await api("POST", `${phones}/${phone}/sync/upload`, { body: { size, sha256 } });
+  const link = await api("POST", `${phones}/${phone}/sync/upload`, { body: sha256 ? { size, sha256 } : {} });
+  if (!sha256) return asText({ upload: link.upload, upload_url: link.upload_url, upload_command: link.upload_command, expires_at: link.expires_at,
+    next: `Here, local_path does it in one call instead: phone_app_run or phone_tests_run with local_path (the project's folder) sends only what changed; phone_app_control install with local_path sends a .app. Otherwise run upload_command in the project's folder, then call phone_app_run or phone_tests_run with upload "${link.upload}"; the link takes a new upload until expires_at.` });
   return asText({ upload_url: link.upload_url, expires_at: link.expires_at, upload_command: `curl -fsS -T PATH_TO_ARCHIVE '${String(link.upload_url)}'`, next: `Upload the archive to upload_url (an HTTP PUT), then pass upload: "${sha256}" to phone_app_run, phone_tests_run or phone_app_control install.` });
 }
 
@@ -141,7 +161,15 @@ async function cloud(input) {
   return asText(await api("GET", `${phones}/${phone}`));
 }
 
+/** This machine's files, which only the CLI reaches: local_path sends them to the phone first. */
+const LOCAL_PATH = {
+  phone_app_run: "Instead of git or upload: the project's folder on this machine (or its .xcodeproj or .xcworkspace), sent to the phone first, only the files it lacks (from the git repository it is in, as git lists them; never build output, dependencies or key files); path is then a folder inside it",
+  phone_tests_run: "Instead of git or upload: the project's folder on this machine (or its .xcodeproj or .xcworkspace), sent to the phone first, only the files it lacks; path is then a folder inside it",
+  phone_app_control: "install: a .app built for the Simulator on this machine, sent to the phone first",
+};
 export const PHONE_TOOLS = LISTED.map(({ name, description, inputSchema }) => ({
-  name, description, inputSchema,
+  name,
+  description: LOCAL_PATH[name] ? `${description} Here, local_path sends ${name === "phone_app_control" ? "a .app" : "a project folder"} from this machine in the same call.` : description,
+  inputSchema: LOCAL_PATH[name] ? { ...inputSchema, properties: { ...inputSchema.properties, local_path: { type: "string", minLength: 1, maxLength: 4096, description: LOCAL_PATH[name] } } } : inputSchema,
   handler: name === "phone" ? cloud : name === "phone_upload_link" ? uploadLink : simulatorTool(name, bareOf(name)),
 }));