@nomac/cli 0.2.4 → 0.3.0-beta.1

package/bin/nomac.mjs

@@ -2,6 +2,9 @@
 import { main } from "../src/cli.mjs";
 
 main(process.argv.slice(2)).catch((err) => {
-  console.error(err?.friendly ?? err?.message ?? String(err));
+  const args = process.argv.slice(2);
+  if (["start", "sync", "pull", "stop", "session", "transport"].includes(args[0]) && args.includes("--json")) {
+    console.error(JSON.stringify({ error: { code: err?.code ?? "session_error", message: err?.friendly ?? err?.message ?? String(err), ...(err?.details ? { details: err.details } : {}) } }));
+  } else console.error(err?.friendly ?? err?.message ?? String(err));
   process.exit(err?.exitCode ?? 1);
 });

package/bin/rsync-ssh.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Private rsync transport. stdout is the binary rsync protocol, never CLI logging.
+import { rsyncServerCommand, runProcess, sshArgs } from "../src/session-ssh.mjs";
+
+try {
+  const session = JSON.parse(process.env.NOMAC_TRANSFER_SESSION ?? "null");
+  if (!session) throw new Error("This helper is started by nomac sync/pull.");
+  const command = rsyncServerCommand(session, process.argv.slice(2), session.remoteDirectory);
+  await runProcess("ssh", [...sshArgs(session), session.target, command], { inherit: true });
+} catch (error) {
+  console.error(error.friendly ?? error.message);
+  process.exitCode = error.exitCode ?? 1;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomac/cli",
-  "version": "0.2.4",
-  "description": "Ship iOS apps to TestFlight and the App Store without a Mac — built for agents.",
+  "version": "0.3.0-beta.1",
+  "description": "Cloud Mac sessions over SSH and HTTPS, plus iOS builds and publishing — built for agents.",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
@@ -20,7 +20,10 @@
   },
   "dependencies": {
     "ignore": "^7.0.0",
-    "tar": "^7.4.0"
+    "tar": "^7.4.0",
+    "ws": "^8.21.3",
+    "https-proxy-agent": "^9.1.0",
+    "proxy-from-env": "^2.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",

package/skill/SKILL.md

@@ -12,7 +12,7 @@ description: >
 # nomac — ship iOS without a Mac
 
 nomac is the hands; you are the brain. It builds, signs, uploads, lints for
-review-readiness, writes store metadata you author, and submits for review —
+review-readiness, writes store metadata, manages pricing/products and submits for review —
 via MCP tools (preferred) or the `nomac` CLI.
 
 ## Setup check
@@ -81,8 +81,9 @@ too, and use `get_screenshot_upload` to find or poll the existing operation.
   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. Apple/account/legal decisions
-  and unsupported product edits still require the relevant Apple workflow.
+  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
 
@@ -103,8 +104,56 @@ requires its own review and distribution:
 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. Rejected beta messages and compliance documents
-   require App Store Connect; do not blindly resubmit an unchanged rejected binary.
+   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.
 
 ## When stuck
 

package/src/api.mjs

@@ -1,12 +1,13 @@
 import { loadApiKey, loadApiUrl } from "./config.mjs";
 
 export class CliError extends Error {
-  constructor(message, friendly, status, code) {
+  constructor(message, friendly, status, code, details) {
     super(message);
     this.friendly = friendly ?? message;
     this.exitCode = 1;
     this.status = status;
     this.code = code;
+    this.details = details;
   }
 }
 
@@ -33,7 +34,7 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
   if (!key) {
     throw new CliError(
       "not logged in",
-      "Not logged in. Run `nomac login <api-key>` (create a key in the dashboard) or set NOMAC_API_KEY.",
+      "Not logged in. Run `nomac login` and approve access in your browser, or set NOMAC_API_KEY.",
     );
   }
   const url = `${loadApiUrl()}${path}`;
@@ -49,13 +50,17 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
       ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
     },
     body: raw ?? (body !== undefined ? JSON.stringify(body) : undefined),
+  }).catch(() => {
+    throw new CliError("Request outcome unknown", "The response was lost. Reconcile the previous operation before retrying; reuse its request_key.", undefined, "outcome_unknown", { code: "outcome_unknown", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
+  });
+  const text = await res.text().catch(() => {
+    throw new CliError("Response body was lost", "Reconcile the previous operation before retrying; reuse its request_key.", res.status, "outcome_unknown", { code: "outcome_unknown", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
   });
-  const text = await res.text();
   let json;
   try {
     json = text ? JSON.parse(text) : {};
   } catch {
-    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`, undefined, res.status);
+    throw new CliError(`API returned non-JSON (HTTP ${res.status})`, "The response could not be read. Reconcile the operation before retrying; reuse its request_key.", res.status, "bad_response", { code: "bad_response", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
   }
   if (!res.ok) {
     const err = json?.error ?? {};
@@ -64,6 +69,7 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
       err.message ?? `API error (HTTP ${res.status})`,
       res.status,
       err.code,
+      { ...err, ...(idempotencyKey ? { request_key: idempotencyKey } : {}) },
     );
   }
   return json;

package/src/cli.mjs

@@ -4,9 +4,30 @@ import { loadProjectState, saveApiKey, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
 import { uploadSourceSnapshot } from "./upload.mjs";
 
-const HELP = `nomac — ship iOS apps without a Mac (agent-first)
+const HELP = `nomac — Mac workspaces for agents / iOS app publishing
 
-Usage:
+Nomac 2.0 cloud Macs:
+  nomac credits               weekly hours and plan checkout
+  nomac start                 allocate or reconnect to your Mac
+  nomac exec --request-key KEY -- command args
+  nomac job JOB_ID             inspect a submitted command
+  nomac output JOB_ID          read resumable command output
+  nomac start --help           session limits and usage
+
+Existing Mac workspaces:
+  nomac start --host user@mac connect a dedicated Mac you control
+  nomac sync .                upload changed project files
+  nomac ssh                   open the full Mac shell
+  nomac pull ./output         retrieve a remote directory
+  nomac session status --json show workspace and connection information
+  nomac stop                  detach locally (does not end a rental)
+  nomac start --help          setup, exclusions and preview limitations
+
+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:
   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
@@ -22,6 +43,40 @@ Environment: NOMAC_API_KEY, NOMAC_API_URL`;
 export async function main(argv) {
   const [cmd, ...rest] = argv;
   switch (cmd) {
+    case "credits": {
+      const { creditsCommand } = await import("./mac-credits.mjs");
+      return creditsCommand(rest);
+    }
+    case "tunnel": {
+      if (rest.length !== 1) throw new CliError("Usage: nomac tunnel <session-id>");
+      const { tunnel } = await import("./mac-transport.mjs");
+      if (process.env.NOMAC_SESSION_TOKEN) return tunnel(rest[0]);
+      const { sessionAccess } = await import("./hosted-sessions.mjs");
+      const access = await sessionAccess(rest[0].replace(/^nomac-/, ""));
+      return tunnel(rest[0], { gateway: access.gateway, token: access.token });
+    }
+    case "transport": {
+      const { transportCommand } = await import("./transport-command.mjs");
+      return transportCommand(rest);
+    }
+    case "start":
+    case "exec":
+    case "job":
+    case "output":
+    case "sync":
+    case "ssh":
+    case "pull":
+    case "stop":
+    case "session": {
+      const { sessionStore } = await import("./session-store.mjs");
+      const store = sessionStore();
+      if (!rest.includes("--host") && !rest.some(value => value.startsWith("--host=")) && store.load()?.mode !== "external_ssh") {
+        const { hostedSessionCommand } = await import("./hosted-sessions.mjs");
+        return hostedSessionCommand(cmd, rest, { store });
+      }
+      const { sessionCommand } = await import("./sessions.mjs");
+      return sessionCommand(cmd, rest);
+    }
     case "login": {
       const key = rest[0];
       if (key) {

package/src/hosted-sessions.mjs

@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { api, CliError } from "./api.mjs";
+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";
+
+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 exec --request-key KEY -- command args
+  nomac job JOB_ID                  reconcile a submitted command
+  nomac output JOB_ID [--cursor 0] [--stream stdout|stderr]
+  nomac pull ./output [--from PATH] retrieve files before stopping
+  nomac session status --json       live state, cost and cleanup status
+  nomac stop [--wait 60] --json      request shutdown and wait for confirmation
+
+Login once with nomac login. The CLI creates a local SSH key; it sends only the
+public key. Sessions use the port-443 gateway and verified guest host keys.
+Time continues while the VM is ready, including between commands. Inspect the
+returned offer and limits. Stop removes the VM and its files; pull first.
+A wait timeout leaves the session attached: inspect status or run stop.
+Use nomac start --host user@mac to connect an existing Mac instead.`;
+const options = {
+  help: { type: "boolean" }, json: { type: "boolean" }, wait: { type: "string" },
+  "max-duration": { type: "string" }, "idle-timeout": { type: "string" },
+  "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" },
+};
+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.");
+  const [whole, fraction = ""] = value.split(".");
+  const result = BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, "0"));
+  if (result <= 0n) throw new CliError("--max-cost must be positive.");
+  return result.toString();
+}
+function integer(value, fallback, min, max) {
+  if (value === undefined) return fallback;
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max) throw new CliError("Invalid numeric option.");
+  return Number(value);
+}
+export async function sessionAccess(id, request = api) {
+  sessionId(id);
+  const access = await request("POST", `/api/v1/mac/sessions/${id}/access`);
+  if (access.session_id !== id || !Number.isSafeInteger(access.generation) || access.generation < 1 || access.ssh?.username !== "agent" || !/^ssh-ed25519 [A-Za-z0-9+/]+={0,2}(?: [^\r\n\x00]*)?$/.test(access.ssh?.host_key ?? "")) throw new CliError("Invalid session access response.");
+  // Validates the gateway origin and token without saving bearer credentials to disk.
+  transportOptions({ gateway: access.gateway, token: access.token });
+  return access;
+}
+export async function hostedRequest(id, method, path, params = {}, { request = api, transport = macRequest } = {}) {
+  const access = await sessionAccess(id, request);
+  return transport(method, path, { ...params, gateway: access.gateway, token: access.token });
+}
+export async function hostedSessionCommand(command, argv, { store = sessionStore(), request = api, transport = macRequest, run = runProcess, print = console.log, sleep = ms => new Promise(r => setTimeout(r, ms)), now = Date.now } = {}) {
+  let parsed;
+  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);
+  const output = result => {
+    const billing = result.session?.billing;
+    const usage = billing?.mode === "weekly_included"
+      ? `Included time used: ${billing.used_seconds} seconds. No extra charge.`
+      : `Cost: ${JSON.stringify(result.session?.cost)}`;
+    print(values.json || !["start", "stop"].includes(command) ? JSON.stringify(result, null, 2) : `${result.session.id}: ${result.session.state}\n${result.session.state === "ready" ? "Next: nomac sync . → nomac ssh" : "Check: nomac session status --json"}\n${usage}`);
+    return result;
+  };
+  const saveView = (local, view) => {
+    if (view.id !== local.id && local.id) throw new CliError("Session response mismatch.");
+    sessionId(view.id);
+    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);
+  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");
+    const access = await sessionAccess(local.id, request);
+    if (local.generation && (local.generation !== access.generation || local.hostKey !== access.ssh.host_key)) throw new CliError("The guest identity changed. Stop this session and start a fresh one.", undefined, undefined, "host_key_changed");
+    Object.assign(local, { generation: access.generation, hostKey: access.ssh.host_key, target: `agent@nomac-${local.id}`, workspace: "/Users/agent/workspace", knownHosts: join(store.directory, "known_hosts") });
+    writeFileSync(local.knownHosts, `nomac-${local.id} ${access.ssh.host_key}\n`, { mode: 0o600 }); chmodSync(local.knownHosts, 0o600); store.save(local);
+    return local;
+  }
+  const localSession = () => {
+    const local = store.load();
+    if (local?.mode !== "hosted" || !local.id) throw new CliError("No attached cloud session.", "Run nomac start to allocate or reconcile your Mac.");
+    return local;
+  };
+  if (command === "session") {
+    if (positionals.length !== 1 || !["status", "info"].includes(positionals[0])) throw new CliError("Usage: nomac session status --json");
+    const local = localSession(); return output({ session: await refresh(local) });
+  }
+  if (["exec", "job", "output"].includes(command)) {
+    const local = localSession(), base = `/api/v1/mac/sessions/${sessionId(local.id)}`;
+    let path, method = "GET", params = {};
+    if (command === "exec") {
+      if (!positionals.length || !argv.includes("--") || !/^[A-Za-z0-9_.:-]{8,128}$/.test(values["request-key"] ?? "")) throw new CliError("Use nomac exec --request-key STABLE_KEY -- command args");
+      method = "POST"; path = `${base}/jobs`; params = { requestKey: values["request-key"], body: { argv: positionals, timeout_seconds: integer(values.timeout, 60, 1, 600) } };
+    } else {
+      if (positionals.length !== 1 || !/^job_[a-f0-9]{40}$/.test(positionals[0])) throw new CliError("Supply the existing job ID.");
+      path = `${base}/jobs/${positionals[0]}`;
+      if (command === "output") {
+        const cursor = integer(values.cursor, 0, 0, Number.MAX_SAFE_INTEGER), stream = values.stream ?? "stdout";
+        if (!["stdout", "stderr"].includes(stream)) throw new CliError("Use stdout or stderr.");
+        path += `/output?cursor=${cursor}&stream=${stream}`;
+      }
+    }
+    return output(await hostedRequest(local.id, method, path, params, { request, transport }));
+  }
+  if (command === "ssh") {
+    if (values.json) throw new CliError("SSH streams bytes. Use session status --json for metadata.");
+    const local = await ready(localSession());
+    return run("ssh", [...sshArgs(local, { batch: false }), ...(!positionals.length && process.stdin.isTTY ? ["-t"] : []), ...(values.forward ?? []).flatMap(v => ["-L", forwardingArg(v)]), "-o", "ExitOnForwardFailure=yes", local.target, workspaceCommand(local, positionals)], { inherit: true });
+  }
+  return store.locked(async () => {
+    if (command === "start") {
+      if (positionals.length) throw new CliError("Usage: nomac start [--wait SECONDS] [--json]");
+      let local = store.load();
+      if (local && local.mode !== "hosted") throw new CliError("An existing Mac workspace is attached.");
+      const limits = { max_duration_seconds: integer(values["max-duration"], 7200, 60, 86400), idle_timeout_seconds: integer(values["idle-timeout"], 600, 60, 3600), spend_cap_microunits: budget(values["max-cost"]) };
+      if (local && !["stopped", "failed"].includes(local.state)) {
+        for (const [flag, field] of [["max-duration", "max_duration_seconds"], ["idle-timeout", "idle_timeout_seconds"], ["max-cost", "spend_cap_microunits"]]) {
+          if (values[flag] !== undefined && limits[field] !== local.request.limits[field]) throw new CliError("This session already has different limits. Stop it and start a fresh session to change them.");
+        }
+        if (values["request-key"] !== undefined && values["request-key"] !== local.requestKey) throw new CliError("A session is already attached under a different request key. Inspect it or stop it before starting another.");
+      }
+      if (!local || ["stopped", "failed"].includes(local.state)) {
+        const identity = join(store.directory, `id_ed25519_${randomUUID()}`);
+        await run("ssh-keygen", ["-q", "-t", "ed25519", "-N", "", "-C", "nomac-session", "-f", identity]);
+        local = { mode: "hosted", state: "requesting", identity, requestKey: values["request-key"] ?? `cli-${randomUUID()}`, request: { profile: "standard", public_key: readFileSync(`${identity}.pub`, "utf8").trim(), limits } };
+        store.save(local); store.saveBaseline({});
+      }
+      if (!local.id) {
+        const result = await request("POST", "/api/v1/mac/sessions", { idempotencyKey: local.requestKey, body: local.request });
+        saveView(local, result.session);
+      }
+      const deadline = now() + integer(values.wait, 300, 0, 600) * 1000;
+      for (;;) {
+        await refresh(local);
+        if (!["queued", "provisioning"].includes(local.state) || now() >= deadline) break;
+        await sleep(2000);
+      }
+      if (local.state === "ready") await ready(local);
+      return output({ session: local.snapshot, request_key: local.requestKey });
+    }
+    const local = localSession();
+    if (command === "stop") {
+      if (positionals.length) throw new CliError("Usage: nomac stop [--wait SECONDS] [--json]");
+      saveView(local, (await request("DELETE", `/api/v1/mac/sessions/${sessionId(local.id)}`)).session);
+      const deadline = now() + integer(values.wait, 60, 0, 300) * 1000;
+      while (!["stopped", "failed"].includes(local.state) && now() < deadline) { await sleep(1000); await refresh(local); }
+      return output({ session: local.snapshot });
+    }
+    await ready(local);
+    if (command === "sync") {
+      if (positionals.length > 1 || (positionals[0] && resolve(positionals[0]) !== store.project)) throw new CliError("Run nomac sync . from the attached project.");
+      return output(await syncProject(local, store, { overwrite: values.overwrite, dryRun: values["dry-run"], run }));
+    }
+    if (command === "pull") {
+      if (positionals.length !== 1) throw new CliError("Usage: nomac pull LOCAL_PATH [--from REMOTE_PATH]");
+      return output(await pullProject(local, store, positionals[0], { from: values.from ?? positionals[0], overwrite: values.overwrite, dryRun: values["dry-run"], run }));
+    }
+    throw new CliError("Unknown cloud session command.");
+  });
+}