@nomac/cli 0.5.6 → 0.5.8

package/package.json

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

package/skill/SKILL.md

@@ -3,8 +3,7 @@ name: nomac
 description: >
   Use a full cloud Mac over SSH, HTTPS or MCP for macOS tools, Xcode and iOS
   development. Start sessions, sync files, run commands, retrieve work and
-  stop. Also supports the separate iOS Builder product for TestFlight and
-  App Store publishing, signing, screenshots, metadata and review replies.
+  stop.
 ---
 
 # nomac — a Mac for your agent
@@ -40,155 +39,17 @@ Keep the same request key and arguments after uncertain responses; inspect
 the original job before retrying. Output retrieval failure is not job failure.
 Managed jobs have a 600-second limit; SSH can run longer within session limits.
 CLI sync skips symlinks and preserves remote extra files; use native SSH/rsync
-when needed. GUI/simulator control and persistent disks are not currently offered.
+when needed. Agents have no GUI control: drive the Simulator with simctl, and
+give the human `open_mac_desktop` when a screen needs a person. Persistent disks
+are not currently offered.
 Report failures using `report_issue` with `session_id`, optional `job_id` and
 a description without secrets. Read https://nomac.app/llms.txt for full limits.
 
-## Separate Builder product
+## Builder (existing subscribers only)
 
-nomac is the hands; you are the brain. It builds, signs, uploads, lints for
-review-readiness, writes store metadata, manages pricing/products and submits for review —
-via MCP tools (preferred) or the `nomac` CLI.
-
-## Setup check
-
-1. MCP tools available (`connect_status`, `push_project`, `build`, …)? Use them.
-2. Otherwise: `npx @nomac/cli whoami`. If not logged in, run
-   `npx @nomac/cli login`; give the human the device URL and code to approve.
-   Then `claude mcp add nomac -- npx @nomac/cli mcp`.
-3. `connect_status` must show a healthy Apple connection. If not, the human
-   connects at the dashboard (60 seconds, one .p8 upload). Don't guess —
-   verify, then proceed.
-
-## Ship to TestFlight
-
-```
-push_project                    # after every code change
-build workflow=release         # ~3 min; smoke = fast compile-only check
-status                         # poll ~30s until ready | failed
-```
-
-- `ready` → tell the human: "open TestFlight on your phone." Their taps are
-  the test run; read `get_feedback` for crashes/comments afterwards.
-- `failed` → `get_failure`: kind=project means you fix source and re-push;
-  kind=account means relay the link to the human. Don't burn release builds
-  debugging compile errors — use `build workflow=smoke`.
-
-## Submit for App Store review
-
-1. `review_lint` → fix every red. Apply returned patches (e.g. generated
-   `PrivacyInfo.xcprivacy`) directly to the source. Yellow "signals"
-   (4.3 distinctiveness, thin listing) are yours to judge and improve.
-2. `set_metadata` — you write the copy; check `get_metadata_schema` for
-   limits. Age rating + data usage answers are legal attestations: ask the
-   human, relay their answers. `upload_screenshots` needs exact dimensions
-   (in the schema). It runs in the background: poll `get_screenshot_upload`
-   until complete before publishing. A rolled-back or paused replacement
-   needs the returned recovery instructions before starting another upload.
-3. `publish` without confirm stages real Apple drafts/build attachments but
-   does not submit. Fix the returned blockers; retain the exact build/submission IDs.
-4. `publish confirm=true` sends the app to Apple. Ensure the human authorized
-   this app/version; honor authorization already given. New versions use manual
-   release, while existing versions retain their Apple release policy.
-
-If metadata or publish returns pending, keep its `request_key` and repeat
-the original arguments with that key. `get_store_operation` recovers the key
-and progress after a lost response. A new key starts a separate operation;
-do not use one to bypass an unconfirmed Apple request. Staging and confirmation
-remain separate invocations. For screenshots, keep the original `request_key`
-too, and use `get_screenshot_upload` to find or poll the existing operation.
-
-## Fix review rejections and release
-
-- `get_review` lists live Apple submissions, including ones created outside
-  nomac. Pass `asc_submission_id` for all item states and exact version/build IDs.
-- Apple does not expose App Review messages through its public API. Use the
-  returned App Store Connect handoff to have the human provide the actual text.
-  Never invent a rejection reason from a status code or public customer review.
-- Fix metadata/screenshots on the exact `version_string`. A binary change needs
-  push/build, then `publish` with the exact `build_id` and `asc_submission_id`.
-  `resolve_rejection:true` explicitly asserts that this version's issue is fixed.
-- `prepare_review_reply` prepares your authored text but always returns `sent:false`.
-  The human sends it and any message attachments in App Store Connect. Changing
-  review_contact.notes is not a reply; sending a reply is not resubmission.
-- `update_review` supports `resolve_item`, `remove_item`, `cancel`, `resubmit`,
-  and `release`. Preview without confirm; confirm the exact requested action.
-  Fix issues before marking items resolved. Every rejected item must be resolved
-  or removed before resubmitting. Removed items cannot be added back to that submission.
-- Poll `get_review`; approval and release are separate. Release requires an
-  app-version item in Pending Developer Release. Edit subscription/IAP products,
-  events and custom pages through the store catalog below. Apple/account/legal
-  decisions still require the relevant Apple workflow.
-
-## External TestFlight
-
-`ready` from a nomac build means internal TestFlight readiness. External testing
-requires its own review and distribution:
-
-1. `get_testflight` lists groups, test information and recent Apple builds. Use
-   `asc_build_id` for a specific build's beta-review/external state, or `group_id`
-   to list testers. Never infer external approval from internal readiness.
-2. `manage_testflight action=metadata` sets app_info (description/feedbackEmail/URLs),
-   review_contact (Apple contact/demo fields), locale, and build whats_new.
-3. Select/create an external group. `invite_tester`/`remove_tester` use an explicit
-   email/tester ID and group_id. `update_group` can enable an optional public link.
-4. `distribute` requires asc_build_id and explicit group_ids. It submits beta
-   review if needed, then assigns those groups. auto_notify defaults false;
-   `notify` starts testing after approval. `remove_build` affects one group;
-   `expire` stops testing for the build across all groups.
-5. All actions preview without confirm and apply with confirm:true. Pending
-   requests use their original key/body; get_store_operation recovers them.
-6. Relay an accurate human-provided uses_non_exempt_encryption with action=encryption
-   when appropriate. Never guess. Encryption declarations/documents use the
-   store catalog; rejected beta messages require App Store Connect. Fix the cause
-   before resubmitting a rejected binary.
-
-## Pricing, products, customer reviews and the wider store API
-
-1. `get_store_capabilities` lists operations by category/search with next_offset.
-   Pass `operation` to get that operation's exact Apple request/query schema.
-   Categories: listing, releases, pricing, purchases, subscriptions, reviews,
-   marketing, assets, testflight, analytics, compliance, webhooks.
-2. `read_store` executes listed GET operations. Begin with an `apps_*` relationship
-   and `scope:[]` for the linked app. Every child has a reusable `scope`; copy it
-   into the next read/write. Keep the query when following `next_cursor`.
-3. `update_store` takes the operation, scope and exact JSON:API `body`. For creation,
-   scope the parent. Every existing relationship ID needs its own verified scope
-   in `references`; the target and its ancestors are already verified. Territories
-   and categories are global. Inline creates use local IDs such as `${price1}`.
-4. Preview without confirm. `confirm:true` applies real paid prices, availability,
-   products/offers, public responses, release settings or event subscriptions.
-   Honor the human's existing authorization; do not ask again for authorized work.
-   Do not invent prices, legal answers or factual claims in public replies.
-5. `customerReviewResponses_createInstance` replies to a public customer review.
-   It does not send a message to Apple reviewers. Read their actual messages in
-   App Store Connect; `prepare_review_reply` only drafts the response.
-6. Product management covers subscriptions/IAP versions, localization, prices,
-   availability, grace periods and offers. First IAP approval may require the
-   app version submission. Draft review submission items can attach products;
-   use `publish` / `update_review` to submit, resolve, resubmit and release.
-7. Events, custom pages, experiments, accessibility and phased releases use their
-   catalog operations. Apple still validates account permissions and valid states.
-   Analytics report segments supply download URLs; offer-code CSV exports return
-   bounded base64 downloads. Webhooks send app events to an owner-selected receiver;
-   that receiver is responsible for running an agent when events arrive.
-
-`upload_store_asset` handles new Apple file resources: previews, screenshot files,
-purchase images, supplemental review attachments and encryption documents. Choose
-the asset create operation, provide its parent relationship/body, and pass a local
-`file_path` (CLI, up to 500 MiB) or `data_base64` (hosted, up to 2 MiB). Apple also
-has asset-specific limits. The tool reserves, uploads each requested byte range,
-then commits its checksum. Keep the same request_key and original bytes to resume.
-`uploaded:true` is not processing success: poll `read_store` until
-`assetDeliveryState.state` is `COMPLETE`. FAILED requires addressing Apple's errors.
-This adds a new file; use `upload_screenshots` for managed screenshot replacement.
-
-Keep pending write keys and unchanged bodies. `get_store_operation` exposes captured
-targets and receipts. Unknown Apple outcomes remain pending and block other writes
-to the app until reconciled; never use a fresh key to bypass one. Corrected inputs
-or a new intentional action require a fresh key. Correspondence, appeals, App Privacy
-questionnaire answers and account-wide financial/admin APIs are not exposed.
-This catalog does not run simulators or Xcode Cloud jobs.
+The separate iOS Builder publishing product is closed to new subscriptions.
+If `get_billing_status` shows a Builder plan, its tools are listed and
+https://nomac.app/llms.txt describes them. Otherwise use the cloud Mac above.
 
 ## When stuck
 

package/src/cli.mjs

@@ -13,6 +13,7 @@ Nomac 2.0 cloud Macs:
   nomac exec --request-key KEY -- command args
   nomac job JOB_ID             inspect a submitted command
   nomac output JOB_ID          read resumable command output
+  nomac desktop                the Mac's full desktop in your browser
   nomac start --help           session limits and usage
 
 Existing Mac workspaces:
@@ -28,14 +29,9 @@ Nomac 2.0 transport probe:
   nomac tunnel <session>       SSH through the configured port-443 gateway
   nomac transport --help       HTTPS jobs, resumable output and binary probes
 
-Existing publishing commands:
+Account and agents:
   nomac login                  connect this device (approve in the browser)
   nomac login <api-key>        store an nmk_ key directly (CI / power users)
-  nomac push                   pack this directory and upload a snapshot
-  nomac build [--smoke]        start a release (or smoke) build
-  nomac build --testflight     release build; waits until TestFlight-ready
-  nomac status [build-id]      show latest (or given) build status
-  nomac logs <build-id>        show build logs
   nomac mcp                    run the stdio MCP server (for agents)
   nomac whoami                 show org + usage
 
@@ -66,6 +62,7 @@ export async function main(argv) {
     case "output":
     case "sync":
     case "ssh":
+    case "desktop":
     case "pull":
     case "stop":
     case "session": {

package/src/desktop.mjs

@@ -0,0 +1,26 @@
+import { loadApiUrl } from "./config.mjs";
+import { openUrl } from "./mac-credits.mjs";
+
+/**
+ * `nomac desktop`: the Mac's full macOS desktop in the browser. The page on
+ * nomac.app connects through the gateway to the VM's own display, so there is
+ * nothing to install and no password to type. macOS has no RDP.
+ */
+export const DESKTOP_HELP = `nomac desktop [--no-open] [--json]
+  Open the Mac's full macOS desktop in your browser: mouse and keyboard,
+  nothing to install. Sign in to nomac.app if asked. (macOS has no RDP.)
+  The session stays busy while the desktop is open; the page disconnects after
+  15 minutes without input. Credit is used while the Mac is ready: nomac stop when done.`;
+
+export const desktopUrl = id => `${loadApiUrl()}/mac/desktop/${encodeURIComponent(id)}`;
+
+export function desktop(local, { values = {}, print = console.log, open = openUrl } = {}) {
+  const url = desktopUrl(local.id);
+  const opened = values["no-open"] ? false : open(url);
+  if (values.json) return print(JSON.stringify({ session_id: local.id, url, opened_in_browser: opened }));
+  print([
+    `Mac desktop: ${url}`,
+    opened ? "Opened in your browser. Sign in to nomac.app if asked." : "Open this link in your browser and sign in to nomac.app.",
+    "Credit is used while the Mac is ready: nomac stop when done.",
+  ].join("\n"));
+}

package/src/hosted-sessions.mjs

@@ -7,12 +7,14 @@ import { sessionStore } from "./session-store.mjs";
 import { forwardingArg, runProcess, sshArgs, workspaceCommand } from "./session-ssh.mjs";
 import { pullProject, syncProject } from "./session-transfer.mjs";
 import { macRequest, sessionId, transportOptions } from "./mac-transport.mjs";
+import { desktop, DESKTOP_HELP } from "./desktop.mjs";
 
 const HELP = `Nomac cloud Mac sessions
   nomac start [--wait 300] [--max-duration 7200] [--idle-timeout 600] [--max-cost 5] [--json]
   nomac sync . [--dry-run]           upload changed files
   nomac ssh [--forward 8080:3000]    full Mac shell and port forwarding
   nomac ssh -- command args         run any command over SSH
+  nomac desktop [--no-open] [--json] the full macOS desktop in your browser
   nomac exec --request-key KEY -- command args
   nomac job JOB_ID                  reconcile a submitted command
   nomac output JOB_ID [--cursor 0] [--stream stdout|stderr]
@@ -33,6 +35,7 @@ const options = {
   "max-cost": { type: "string" }, "request-key": { type: "string" }, timeout: { type: "string" },
   overwrite: { type: "boolean" }, "dry-run": { type: "boolean" }, from: { type: "string" },
   forward: { type: "string", multiple: true }, cursor: { type: "string" }, stream: { type: "string" },
+  "no-open": { type: "boolean" },
 };
 function budget(value = "5") {
   if (!/^(?:0|[1-9][0-9]{0,5})(?:\.[0-9]{1,6})?$/.test(value)) throw new CliError("--max-cost must be a positive USD amount, for example 5 or 2.50.");
@@ -69,7 +72,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   try { parsed = parseArgs({ args: argv, options, allowPositionals: true }); }
   catch (error) { throw new CliError(error.message); }
   const { values, positionals } = parsed;
-  if (values.help) return print(HELP);
+  if (values.help) return print(command === "desktop" ? DESKTOP_HELP : HELP);
   const wait = ["start", "stop"].includes(command) ? integer(values.wait, command === "start" ? 300 : 60, 0, command === "start" ? 600 : 300) : 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.");
   const output = result => {
@@ -122,6 +125,10 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     }
     return output(await hostedRequest(local.id, method, path, params, { request, transport }));
   }
+  if (command === "desktop") {
+    if (positionals.length) throw new CliError("Usage: nomac desktop [--no-open] [--json]");
+    return desktop(await ready(localSession()), { values, print });
+  }
   if (command === "ssh") {
     if (values.json) throw new CliError("SSH streams bytes. Use session status --json for metadata.");
     const local = await ready(localSession());

package/src/mac-tools.mjs

@@ -1,5 +1,6 @@
 import { api } from "./api.mjs";
 import { openUrl } from "./mac-credits.mjs";
+import { desktopUrl } from "./desktop.mjs";
 const text = value => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
 const session = { type: "string", pattern: "^ses_[A-Za-z0-9_-]{1,80}$" };
 const job = { type: "string", pattern: "^job_[a-f0-9]{40}$" };
@@ -16,6 +17,12 @@ export const MAC_TOOLS = [
   { name: "start_mac", description: "Allocate a full cloud Mac VM, billed from prepaid credit at $0.80 an hour by the minute. If it returns insufficient_credit, call get_mac_checkout, have the human pay, then retry with the same request_key. Supply a stable request_key; SSH public_key is optional for HTTPS-only agents; reuse both after a lost response. Inspect the returned offer and limits. Poll get_mac_session until ready. No project pipeline is imposed; stop_mac deletes the VM and files.", inputSchema: schema({ public_key: { type: "string" }, request_key: key, limits: { type: "object", properties: { max_duration_seconds: { type: "integer", minimum: 60, maximum: 28800 }, idle_timeout_seconds: { type: "integer", minimum: 60, maximum: 3600 }, spend_cap_microunits: { type: "string", pattern: "^[1-9][0-9]{0,17}$" } }, additionalProperties: false } }, ["request_key"]), handler: async ({ request_key, ...body }) => text(await api("POST", "/api/v1/mac/sessions", { body, idempotencyKey: request_key })) },
   { name: "list_mac_sessions", description: "Find existing Mac sessions, including after losing a response. Shows state, cost, limits and cleanup.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/sessions")) },
   { name: "get_mac_session", description: "Read live Mac allocation state, cost, funded time and cleanup confirmation. queued/provisioning means wait; stopping is not yet confirmed cleanup.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("GET", base(args))) },
+  { name: "open_mac_desktop", description: "Open the Mac's full macOS desktop in the human's browser on this machine, with mouse and keyboard and nothing to install. Use it when the human wants to see or click something on the Mac, for example Xcode, the Simulator or a sign-in window. The session must be ready. If opened_in_browser is false, give the human the returned url; it opens after they sign in to nomac.app. The session stays busy while the desktop is open and the page disconnects after 15 minutes without input. To show the iOS Simulator there, boot a device with simctl, then run open \"$(xcode-select -p)/Applications/Simulator.app\" with exec_mac. macOS has no RDP.", inputSchema: schema({ session_id: session, open: { type: "boolean", default: true, description: "Open the link in this machine's browser." } }, ["session_id"]), handler: async ({ session_id, open = true }) => {
+    const view = await api("GET", base({ session_id }));
+    if (view?.session?.state !== "ready") return text({ error: { code: "session_not_ready", message: "The Mac is not ready. Wait until get_mac_session shows ready, then call open_mac_desktop again." } });
+    const url = desktopUrl(session_id), opened = open ? openUrl(url) : false;
+    return text({ session_id, url, opened_in_browser: opened, message: opened ? "The desktop opened in the human's browser; they may need to sign in to nomac.app." : "Give the human this link; it opens after they sign in to nomac.app." });
+  } },
   { name: "stop_mac", description: "Stop billing by shutting down the VM and deleting its files. Retrieve files first. Poll get_mac_session until cleanup_confirmed; stopping only acknowledges the request.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("DELETE", base(args))) },
   { name: "exec_mac", description: "Run any argv command in your cloud Mac workspace. Returns a durable job ID; poll get_mac_job and read_mac_output. Reuse request_key and identical arguments after lost responses; never submit a new key blindly. Use bash -lc explicitly for shell syntax. timeout_seconds defaults to 300 and caps at 600; raise it for slow work such as a first simulator boot, which needs about 90 seconds. A command (argv plus env) can be at most 64 KiB; to put larger files on the Mac, fetch them there (git clone, curl) or write them in parts of up to about 40 KiB (e.g. base64 -d >> file).", inputSchema: schema({ session_id: session, request_key: key, argv: { type: "array", items: { type: "string" }, minItems: 1 }, timeout_seconds: { type: "integer", minimum: 1, maximum: 600 } }, ["session_id", "request_key", "argv"]), handler: async ({ session_id, request_key, ...body }) => text(await api("POST", `${base({ session_id })}/jobs`, { body, idempotencyKey: request_key })) },
   { name: "get_mac_job", description: "Inspect the existing command without rerunning it. Retain its job ID until completion and retrieve output before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}`)) },

package/src/mac-transport.mjs

@@ -5,6 +5,8 @@ import { getProxyForUrl } from "proxy-from-env";
 import WebSocket, { createWebSocketStream } from "ws";
 import { CliError } from "./api.mjs";
 import { clientHeaders } from "./client-info.mjs";
+// Bytes in flight per relay hop. 64 KiB capped a ~190 ms transatlantic path near 0.3 MB/s.
+const RELAY_BUFFER = 1024 * 1024;
 
 export function sessionId(value) {
   const id = String(value ?? "").replace(/^nomac-/, "");
@@ -105,7 +107,7 @@ export function tunnel(value, { input = process.stdin, output = process.stdout,
       handshakeTimeout: 15_000, perMessageDeflate: false, maxPayload: 1024 * 1024,
       followRedirects: false,
     });
-    const stream = createWebSocketStream(ws, { highWaterMark: 64 * 1024 });
+    const stream = createWebSocketStream(ws, { highWaterMark: RELAY_BUFFER });
     let failure, closedCode, settled = false;
     const finish = () => {
       if (settled) return;

package/src/mcp.mjs

@@ -40,11 +40,6 @@ export const TOOLS = [
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     handler: async () => text(await api("GET", "/api/v1/billing/status")),
   },
-  {
-    name: "get_checkout_link", description: "Return an org-bound checkout link; the human chooses a plan and pays explicitly. This tool does not charge them. Reuses pending checkout; existing subscribers get billing management instead.",
-    inputSchema: { type: "object", properties: { plan: { type: "string", enum: ["starter", "pro"] } }, additionalProperties: false },
-    handler: async args => text(await api("POST", "/api/v1/billing/checkout", { body: args })),
-  },
   {
     name: "get_refund_status", description: "Read the progress of a refund the account owner requested at nomac.app/usage. Agents cannot request refunds; point the human to that page. Does not submit a refund or cancel anything.",
     inputSchema: { type: "object", properties: { request_id: { type: "string" } }, required: ["request_id"], additionalProperties: false },
@@ -383,6 +378,20 @@ export const TOOLS = [
   },
 ];
 
+/** Shown to everyone: the Mac tools and support. The rest serve Builder subscribers. */
+const PUBLIC_TOOLS = new Set([...MAC_TOOLS.map(t => t.name), "report_issue"]);
+let subscriber;
+
+/**
+ * The Builder (publishing) plans are closed to new subscriptions, so their tools
+ * are listed only for accounts that still have one. Hidden tools still answer
+ * when called, so existing subscribers' agents keep working.
+ */
+export async function listedTools(isSubscriber = () => (subscriber ??= api("GET", "/api/v1/billing/status").then(s => Boolean(s?.tier) && s.tier !== "none", () => false))) {
+  const legacy = await isSubscriber();
+  return TOOLS.filter(t => legacy || PUBLIC_TOOLS.has(t.name));
+}
+
 export async function runMcpServer() {
   const rl = createInterface({ input: process.stdin, terminal: false });
   const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
@@ -417,7 +426,7 @@ export async function runMcpServer() {
           break;
         case "tools/list":
           reply({
-            tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+            tools: (await listedTools()).map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
           });
           break;
         case "tools/call": {