@nomac/cli 0.11.9 → 0.11.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.11.9",
+  "version": "0.11.11",
   "description": "Cloud Mac sessions over SSH and HTTPS, plus iOS builds and publishing — built for agents.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -27,7 +27,8 @@ commands and tools. Mac time is prepaid credit, separate from Builder.
    Hosted MCP: https://mcp.nomac.app/mcp with `Authorization: Bearer <nmk_key>`.
 3. `nomac start --json`, wait until ready, `nomac sync .`, then `nomac ssh`.
    Run commands with `nomac exec -- COMMAND`: it prints the output as it
-   arrives and exits with the command's code, waiting at most 30 s. For builds and tests use
+   arrives and exits with the command's code, waiting at most 30 s (or the
+   `--timeout` given, up to 600 s). For builds and tests use
    `nomac exec --wait 600 -- COMMAND`. Exit code 75 means still running: wait
    with `nomac job JOB_ID --wait 600`, never rerun. In scripts add
    `--request-key stable-key-0001`. A command may run an hour (`--timeout

package/src/hosted-sessions.mjs

@@ -48,7 +48,8 @@ const HELP = `Nomac cloud Mac sessions
   nomac exec [--wait 30] -- command args
                                     runs it, prints its output as it arrives,
                                     exits with its code.
-                                    Waits up to 30 s; for builds and tests use --wait 600.
+                                    Waits up to 30 s, or with --timeout N up to N s
+                                    (at most 600); for builds and tests use --wait 600.
                                     Exit code 75 means still running: see nomac job.
                                     (--request-key KEY makes a scripted retry safe)
   nomac job JOB_ID [--wait 600]     wait for a command that outlasted --wait
@@ -178,11 +179,11 @@ export const STILL_RUNNING = 75;
 const POLL_MS = [250, 500];
 const NOTICE_MS = 5000;
 /**
- * nomac exec waits like a local command: up to --wait seconds (default 30), then
- * prints stdout and stderr and exits with the command's own exit code. The wait
- * is a ceiling: a quick command returns as soon as it finishes. A command still
- * running keeps running on the Mac; the CLI says how to wait for it and exits
- * 75. --wait 0 only starts it.
+ * nomac exec waits like a local command: up to --wait seconds (default 30, or
+ * --timeout's up to 600), then prints stdout and stderr and exits with the
+ * command's own exit code. The wait is a ceiling: a quick command returns as soon
+ * as it finishes. A command still running keeps running on the Mac; the CLI
+ * says how to wait for it and exits 75. --wait 0 only starts it.
  */
 /** "13:05 UTC", when a running command's time limit stops it. */
 const stopsAt = job => Number.isFinite(job?.deadline) && job.deadline > Date.UTC(2020, 0) ? ` Its time limit (--timeout) stops it at ${new Date(job.deadline).toISOString().slice(11, 16)} UTC.` : "";
@@ -307,14 +308,17 @@ export function projectLine({ path, on_drive }) {
   return on_drive ? `Project: ${short}, on your drive: kept when the Mac stops, and the next session builds only what changed.`
     : `Project: ${short}, deleted when the Mac stops: nomac pull what you need first.`;
 }
+/** "Mac: macOS 26.6.2, Xcode 27.0 (default) and Xcode 26.6 (/Applications/Xcode-26.6.app), iOS 27.0 Simulator", or "". */
+export function macLine(image) {
+  if (!image?.macos) return "";
+  // An image with a second Xcode names it and its path, as the API's image line does.
+  const others = (image.xcodes ?? []).filter(x => !x.default);
+  const xcode = others.length ? `Xcode ${image.xcode} (default) and ${others.map(x => `Xcode ${x.version} (${x.path})`).join(" and ")}` : `Xcode ${image.xcode}`;
+  return `Mac: macOS ${image.macos.split(" ")[0]}, ${xcode}${(image.simulator_runtimes ?? []).map(r => `, ${r} Simulator`).join("")}`;
+}
 export function statusSummary(session, image) {
   const lines = [`${session.id}: ${session.state}`];
-  if (image?.macos) {
-    // An image with a second Xcode names it and its path, as the API's image line does.
-    const others = (image.xcodes ?? []).filter(x => !x.default);
-    const xcode = others.length ? `Xcode ${image.xcode} (default) and ${others.map(x => `Xcode ${x.version} (${x.path})`).join(" and ")}` : `Xcode ${image.xcode}`;
-    lines.push(`Mac: macOS ${image.macos.split(" ")[0]}, ${xcode}${(image.simulator_runtimes ?? []).map(r => `, ${r} Simulator`).join("")}`);
-  }
+  if (macLine(image)) lines.push(macLine(image));
   if (["ready", "provisioning", "queued"].includes(session.state)) lines.push(`Cost so far: ${usd(session.cost?.accrued_microunits)} ($0.80/hour, billed by the minute while ready). Credit left: nomac credits`);
   const a = session.activity ?? {};
   if (session.state === "ready") {
@@ -350,6 +354,8 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   if (values.help) return print(command === "desktop" ? DESKTOP_HELP : HELP);
   const wait = ["start", "attach", "stop"].includes(command) ? integer(values.wait, command === "stop" ? 60 : 300, 0, command === "stop" ? 300 : 600) : 0;
   if (command === "start" && values["request-key"] !== undefined && !validRequestKey(values["request-key"])) throw new CliError("Use a request key of 8–128 letters, digits, underscores, periods, colons or hyphens.");
+  // The image the last read reported (macOS, Xcodes, Simulators), for start's summary.
+  let lastImage;
   const output = result => {
     // Sync, pull and the other commands answer with their own result, which has no session.
     if (values.json || !["start", "attach", "stop"].includes(command)) { print(JSON.stringify(result, null, 2)); return result; }
@@ -363,7 +369,9 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       : ["stopped", "failed"].includes(result.session.state) ? `${result.session.drive ? "The drive saves in the background (nomac drive shows it). " : ""}Start another: nomac start`
       : result.session.state === "stopping" ? "Stopping. Check: nomac status"
       : "Check: nomac status";
-    print(`${result.attached ? `${result.attached}\n` : ""}${result.session.id}: ${result.session.state}\n${next}\n${usage}${result.warning ? `\n${result.warning}` : ""}`);
+    // A ready Mac says what is on it, as nomac status does.
+    const mac = result.session.state === "ready" && macLine(lastImage) ? `${macLine(lastImage)}\n` : "";
+    print(`${result.attached ? `${result.attached}\n` : ""}${result.session.id}: ${result.session.state}\n${mac}${next}\n${usage}${result.warning ? `\n${result.warning}` : ""}`);
     return result;
   };
   const saveView = (local, view) => {
@@ -372,7 +380,11 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     Object.assign(local, { id: view.id, state: view.state, snapshot: view }); store.save(local);
     return view;
   };
-  const refresh = async local => saveView(local, (await request("GET", `/api/v1/mac/sessions/${sessionId(local.id)}`)).session);
+  const refresh = async local => {
+    const answer = await request("GET", `/api/v1/mac/sessions/${sessionId(local.id)}`);
+    if (answer.image) lastImage = answer.image;
+    return saveView(local, answer.session);
+  };
   async function ready(local) {
     await refresh(local);
     if (local.state !== "ready") throw new CliError("Mac is not ready.", `Session ${local.id} is ${local.state}. Run nomac session status --json.`, undefined, "session_not_ready");
@@ -487,7 +499,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   }
   if (["exec", "job", "output"].includes(command)) {
     const local = localSession(), base = `/api/v1/mac/sessions/${sessionId(local.id)}`;
-    let path, method = "GET", params = {};
+    let path, method = "GET", params = {}, waitSeconds = integer(values.wait, 30, 0, 3600);
     if (command === "exec") {
       if (!positionals.length || !argv.includes("--")) throw new CliError("Use nomac exec -- command args");
       if (!local.workspaceDecided && !local.workspace) { await refresh(local); if (local.state === "ready") await placeWorkspace(local); }
@@ -496,8 +508,11 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       // Without a key, a long wait implies a long command, so the command's own limit follows it unless set.
       // With a key the limit must not depend on --wait: a retry with another --wait is the same command.
       // A command may run an hour (the gateway's limit); waiting can cover all of it.
-      const waitFor = integer(values.wait, 30, 0, 3600);
-      const timeout = integer(values.timeout, values["request-key"] === undefined ? Math.max(300, waitFor) : 600, 1, 3600);
+      // A command given a long --timeout and no --wait is waited for too, up to 10 minutes (what an
+      // agent's shell usually allows); the line printed after 5 s says how to go on if interrupted.
+      const given = values.timeout === undefined ? null : integer(values.timeout, 0, 1, 3600);
+      const waitFor = waitSeconds = integer(values.wait, given === null ? 30 : Math.min(given, 600), 0, 3600);
+      const timeout = given ?? (values["request-key"] === undefined ? Math.max(300, waitFor) : 600);
       const line = isShellLine(positionals), dir = local.workspaceOnDrive ? local.workspace : null;
       const remote = dir ? (line ? ["/bin/bash", "-lc", `cd ${shellQuote(dir)} && ${positionals[0]}`] : ["/bin/bash", "-lc", `cd ${shellQuote(dir)} && exec "$@"`, "nomac", ...positionals])
         : line ? ["/bin/bash", "-lc", positionals[0]] : positionals;
@@ -528,7 +543,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       if (at) next[job] = { stdout: at.stdout, stderr: at.stderr };
       store.saveJobCursors(next);
     };
-    return waitForCommand(local.id, base, result, integer(values.wait, 30, 0, 3600), { request, transport, cache, print, stdout, stderr, exitWith, sleep, now, json: Boolean(values.json), timeoutSeconds: params.body?.timeout_seconds,
+    return waitForCommand(local.id, base, result, waitSeconds, { request, transport, cache, print, stdout, stderr, exitWith, sleep, now, json: Boolean(values.json), timeoutSeconds: params.body?.timeout_seconds,
       cursors: command === "job" ? kept[result.id] ?? null : null, keepCursors });
   }
   if (command === "screenshot") {
@@ -642,7 +657,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
         do {
           again = false;
           try {
-            const result = await store.locked(async () => syncProject(await ready(localSession()), store, { overwrite: values.overwrite, deleteMissing: values.delete, run }));
+            const result = await store.locked(async () => syncProject(await ready(localSession()), store, { overwrite: values.overwrite, deleteMissing: values.delete, run }), "nomac sync --watch");
             skipped = result.skipped;
             if (first) print(`${describeSync(result)}\nWatching ${store.project} for changes; Ctrl-C stops.`);
             else if (result.changed.length || result.deleted?.length || result.kept_on_mac?.length) print(`${clock()} ${describeSync({ ...result, skipped: [] })}`);
@@ -763,11 +778,13 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       return output(result);
     }
     if (command === "pull") {
+      // Like cp, the Mac's path first: say the command that does it.
+      if (positionals.length === 2 && values.from === undefined) throw new CliError("pull usage", `nomac pull takes one path, where the files go here; the Mac's path goes in --from: nomac pull ${shellWords([positionals[1]])} --from ${shellWords([positionals[0]])}`);
       if (positionals.length !== 1) throw new CliError("Usage: nomac pull LOCAL_PATH [--from PATH_ON_THE_MAC]");
       const result = await pullProject(local, store, positionals[0], { from: values.from, overwrite: values.overwrite, dryRun: values["dry-run"], run });
       if (!values.json) { print(describePull(result)); return result; }
       return output(result);
     }
     throw new CliError("Unknown cloud session command.");
-  });
+  }, `nomac ${command}`);
 }

package/src/mcp.mjs

@@ -70,7 +70,7 @@ export const TOOLS = [
     handler: async args => text(await api("GET", `/api/v1/store-capabilities?${new URLSearchParams(Object.entries(args ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]))}`)),
   },
   ...[
-    ["read_store", "read", "Read a discovered Apple GET operation. Start with an apps_* relationship and scope:[]; reuse the returned resource scopes. Paginate with next_cursor and unchanged query. Raw IDs are accepted only for global lookups. Reads live Apple state, file upload operations and analytics report URLs."],
+    ["read_store", "read", "Read a discovered Apple GET operation. Start with an apps_* relationship and scope:[]; reuse the returned resource scopes. Paginate with next_cursor and unchanged query. Raw IDs are accepted only for global lookups. Reads live Apple state and analytics report URLs; a file's upload ranges come only in the answer to its reservation, so use upload_store_asset."],
     ["set_subscription_prices", "subscription-prices", "Sets a subscription's price in every territory from one base price point, using Apple's equalized prices (what App Store Connect's all-territories pricing does): territories already at that price are skipped, the others are set one by one, about 40 per call within 35 seconds. Call again (a new request_key, or none) until remaining is 0; a repeat changes nothing. Apple's refusal for a territory is listed in failed (UNSUPPORTED_TERRITORY: set the subscription's availability there first). Without confirm it returns a preview with the counts. Prices come from the human."],
     ["update_store", "write", "Execute a discovered Apple write using its exact JSON:API body. Copy scope and relationship references from read_store. Preview by default; confirm:true changes real Apple resources. Use owner-authorized prices and attestations. On pending, retry identical arguments with request_key; get_store_operation recovers lost keys. Use publish/update_review/manage_testflight for their dedicated lifecycle actions."],
   ].map(([name, route, description]) => ({
@@ -260,7 +260,7 @@ export const TOOLS = [
   {
     name: "upload_screenshots",
     description:
-      "Start a screenshot replacement for one display type and iOS version. PNGs are validated and prior images are backed up. Reuse request_key and the original body when retrying. Poll get_screenshot_upload until complete, rolled_back or needs_attention; accepted means still in progress. images: [{filename, data: base64 PNG}].",
+      "Start a screenshot replacement for one display type and iOS version. PNGs are validated and prior images are backed up. Reuse request_key and the original body when retrying. Poll get_screenshot_upload until complete, rolled_back or needs_attention; accepted means still in progress. images: [{filename, link}] with a create_mac_download_link url for each PNG on the Mac (any size; preferred), or [{filename, data: base64 PNG}] for small images (a request is capped near 4.5 MB in all).",
     inputSchema: {
       type: "object",
       properties: {

package/src/session-store.mjs

@@ -4,6 +4,20 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { CliError } from "./api.mjs";
 
+/** Who holds a folder's lock, or null for a lock without a readable record (an older nomac's). */
+function lockOwner(file) {
+  try {
+    const owner = JSON.parse(readFileSync(file, "utf8"));
+    return Number.isSafeInteger(owner?.pid) && owner.pid > 0 ? { pid: owner.pid, command: String(owner.command ?? "a nomac command"), started_at: String(owner.started_at ?? "") } : null;
+  } catch { return null; }
+}
+
+/** Whether a process with this ID exists (one of another user's counts). */
+function running(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === "EPERM"; }
+}
+
 /** Session metadata stays outside the project: a checkout cannot choose an SSH target. */
 export function sessionStore(projectDir = process.cwd(), stateDir = join(homedir(), ".nomac", "sessions")) {
   const project = realpathSync(projectDir);
@@ -39,12 +53,30 @@ export function sessionStore(projectDir = process.cwd(), stateDir = join(homedir
     savePulled: (value) => write(pulledFile, value),
     jobCursors: () => read(cursorsFile) ?? {},
     saveJobCursors: (value) => write(cursorsFile, value),
-    async locked(operation) {
-      const lock = join(directory, "operation.lock");
-      try { mkdirSync(lock, { mode: 0o700 }); }
+    /** Runs operation (nomac sync, pull, start…) alone for this folder; `what` names it to a second one. */
+    async locked(operation, what = "a nomac command") {
+      const lock = join(directory, "operation.lock"), ownerFile = join(lock, "owner.json");
+      const take = () => {
+        mkdirSync(lock, { mode: 0o700 });
+        writeFileSync(ownerFile, JSON.stringify({ pid: process.pid, command: what, started_at: new Date().toISOString() }) + "\n", { mode: 0o600 });
+      };
+      try { take(); }
       catch (error) {
         if (error.code !== "EEXIST") throw error;
-        throw new CliError("session busy", `Another session operation is running. If it was interrupted, verify it has ended before removing ${lock}.`);
+        const owner = lockOwner(ownerFile);
+        if (!owner) throw new CliError("session busy", `Another nomac command is using this folder (an older nomac's lock, which does not say which). If no other nomac command is running, remove it: rm -r '${lock}'`);
+        if (running(owner.pid)) throw new CliError("session busy", `Another nomac command is using this folder: ${owner.command} (pid ${owner.pid}, since ${owner.started_at}). Wait for it to finish, or stop it: kill ${owner.pid}. If pid ${owner.pid} is not nomac, remove the lock: rm -r '${lock}'`);
+        // Its process has ended (killed, or its terminal closed): move that lock aside, the same one
+        // only (another command may have just replaced it), and take it.
+        const aside = `${lock}.${randomUUID()}.ended`;
+        try { renameSync(lock, aside); } catch (moved) { if (moved.code !== "ENOENT") throw moved; }
+        if (existsSync(aside) && JSON.stringify(lockOwner(join(aside, "owner.json"))) !== JSON.stringify(owner)) {
+          try { renameSync(aside, lock); } catch { /* its command's own cleanup removes it */ }
+          throw new CliError("session busy", "Another nomac command is using this folder. Wait for it to finish.");
+        }
+        rmSync(aside, { recursive: true, force: true });
+        try { take(); }
+        catch (again) { if (again.code === "EEXIST") throw new CliError("session busy", "Another nomac command is using this folder. Wait for it to finish."); throw again; }
       }
       try { return await operation(); }
       finally { rmSync(lock, { recursive: true, force: true }); }

package/src/session-transfer.mjs

@@ -296,7 +296,13 @@ export async function syncProject(session, store, { overwrite = false, dryRun =
   const deleted = removable.length ? await removeOnMac(session, removable, { run }) : [];
   for (const path of [...deleted, ...gone.filter(path => onMac[path] === "missing")]) delete baseline[path];
   store.saveBaseline(baseline);
-  if (changedDuringTransfer.length) throw new CliError("transfer changed during verification", "Some files changed during transfer. Stop concurrent edits and rerun sync; verified files were recorded.");
+  if (changedDuringTransfer.length) {
+    const one = changedDuringTransfer.length === 1;
+    const error = new CliError("transfer changed during verification", `Changed here while being sent: ${listed(changedDuringTransfer)}. The Mac may not have ${one ? "its" : "their"} latest version; once edits stop, run nomac sync again to send ${one ? "it" : "them"}.${conflicts.length
+      ? ` Not sent, because changed on the Mac since this folder last synced: ${listed(conflicts)}. Keep the Mac's version: nomac pull ${conflicts[0]}. Replace it with yours: nomac sync . --overwrite` : " Everything else was sent."}`);
+    error.details = { changed_during_transfer: changedDuringTransfer, ...(conflicts.length ? { conflicts } : {}) };
+    throw error;
+  }
   if (conflicts.length) throw syncConflictError(conflicts, changed.length, deleteMissing ? { deleted, kept_on_mac: keptOnMac } : {});
   return { files: paths.length, changed, ...(deleteMissing ? { deleted, kept_on_mac: keptOnMac } : {}), ...summary, output };
 }

package/src/sessions.mjs

@@ -140,5 +140,5 @@ export async function sessionCommand(command, argv, { store: suppliedStore, run
       return output(result, describePull(result));
     }
     throw new CliError("unknown session command");
-  });
+  }, `nomac ${command}`);
 }

package/src/store-upload.mjs

@@ -1,6 +1,6 @@
 // Shared by the hosted upload endpoint and the published CLI (copied by the
-// schema generator). Provider upload URLs come only from an authenticated,
-// app-scoped read_store response; Nomac credentials never go to those URLs.
+// schema generator). Provider upload URLs come only from the authenticated,
+// app-scoped answer to the reservation; Nomac credentials never go to those URLs.
 import { createHash, randomUUID } from 'node:crypto';
 import { open } from 'node:fs/promises';
 import { basename } from 'node:path';
@@ -82,8 +82,9 @@ export async function uploadStoreAsset(args, call) {
     stage = 'upload';
     const completed = ['UPLOAD_COMPLETE', 'COMPLETE', 'FAILED'].includes(attributes.assetDeliveryState?.state);
     if (!completed) {
-      const operations = attributes.uploadOperations;
-      if (!Array.isArray(operations) || !operations.length) throw new Error('Apple has not exposed upload operations yet. Retry this same upload.');
+      // Apple lists the upload ranges in its answer to the reservation only (a later read has none).
+      const operations = reservation.upload_operations?.length ? reservation.upload_operations : attributes.uploadOperations;
+      if (!Array.isArray(operations) || !operations.length) throw new Error(`Apple gives a file's upload links only in its answer to the reservation, and this request has none (that answer was lost). Delete the reservation (update_store with ${args.operation.replace(/_createInstance$/, '_deleteInstance')} and this scope), then upload again with a new request_key.`);
       let end = 0;
       for (const op of [...operations].sort((a, b) => a.offset - b.offset)) {
         if (op.method !== 'PUT' || !Number.isSafeInteger(op.offset) || !Number.isSafeInteger(op.length) || op.length < 1 || op.offset !== end || op.offset + op.length > size) throw new Error('Apple returned invalid or incomplete upload byte ranges.');
@@ -105,7 +106,7 @@ export async function uploadStoreAsset(args, call) {
         const part = await source(op.offset, op.length);
         try {
           const response = await fetch(op.url, { method: 'PUT', headers, body: part, duplex: 'half', redirect: 'error', signal: AbortSignal.timeout(120_000) });
-          if (!response.ok) throw new Error(`Apple asset upload returned HTTP ${response.status}. Retry with this same request key to refresh its upload URLs.`);
+          if (!response.ok) throw new Error(`Apple asset upload returned HTTP ${response.status}. Retry with this same request key; if it fails again, its upload links have expired: delete the reservation (update_store with ${args.operation.replace(/_createInstance$/, '_deleteInstance')} and this scope) and upload again with a new request_key.`);
           await response.body?.cancel();
         } finally { if (typeof part.destroy === 'function') part.destroy(); }
       }