@nomac/cli 0.3.0-beta.1 → 0.3.1

package/bin/nomac.mjs

@@ -3,7 +3,7 @@ import { main } from "../src/cli.mjs";
 
 main(process.argv.slice(2)).catch((err) => {
   const args = process.argv.slice(2);
-  if (["start", "sync", "pull", "stop", "session", "transport"].includes(args[0]) && args.includes("--json")) {
+  if (["start", "sync", "pull", "stop", "session", "transport", "exec", "job", "output"].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/package.json

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

package/skill/SKILL.md

@@ -1,15 +1,44 @@
 ---
 name: nomac
 description: >
-  Ship iOS apps to TestFlight and the App Store without a Mac. Use when the
-  user asks to build, test on a phone, publish, or submit an iOS app for
-  review — or mentions TestFlight, App Store Connect, signing, provisioning,
-  screenshots/metadata for the App Store, or app review rejections. Works from
-  any directory containing an Xcode project (SwiftUI vibe-code exports
-  included).
+  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.
 ---
 
-# nomac — ship iOS without a Mac
+# nomac — a Mac for your agent
+
+NoMac 2.0 provides a full macOS VM with administrator access. You choose the
+commands and tools. A weekly Mac subscription is separate from Builder.
+
+## Cloud Mac setup and workflow
+
+1. Sign in at https://nomac.app/mac. The human chooses $5/week for 5 hours
+   or $20/week for 25 hours. Verify with `get_mac_credits`; a checkout URL
+   is not a payment. No Apple Developer account is needed for an unsigned build.
+2. Install `npm install -g @nomac/cli`, run `nomac login`, and give the human
+   the printed device URL and code. MCP: `claude mcp add nomac -- npx @nomac/cli mcp`.
+   Hosted MCP: https://mcp.nomac.app/mcp with `Authorization: Bearer <nmk_key>`.
+3. `nomac start --json`, wait until ready, `nomac sync .`, then `nomac ssh`.
+   For managed commands: `nomac exec --request-key stable-key-0001 -- COMMAND`,
+   then `nomac job JOB_ID` and `nomac output JOB_ID`. MCP equivalents are
+   `start_mac`, `exec_mac`, `get_mac_job`, `read_mac_output`, `stop_mac`.
+4. Download work with `nomac pull ./build` (use `--from PATH` for another
+   remote directory), then `nomac stop --json`. Confirm `cleanup_confirmed`.
+
+Stopping deletes files and logs. Download before stopping. SSH disconnects
+do not stop the session. Ready time includes idle time; queue/setup are free.
+Unused hours expire weekly. One session at a time; no automatic overage.
+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.
+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
 
 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 —

package/src/hosted-sessions.mjs

@@ -45,6 +45,12 @@ function integer(value, fallback, min, max) {
   if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max) throw new CliError("Invalid numeric option.");
   return Number(value);
 }
+const validRequestKey = value => typeof value === "string" && /^[A-Za-z0-9_.:-]{8,128}$/.test(value);
+// Only explicit pre-allocation rejections permit a fresh intent. A timeout,
+// unreadable response or idempotency conflict may still own a real session.
+const startRejections = new Set(["invalid_request", "invalid_public_key", "profile_unavailable", "session_cap_too_low",
+  "weekly_time_unavailable", "weekly_time_expired", "insufficient_compute_credit", "compute_account_blocked",
+  "session_limit_reached", "organization_not_found", "compute_unavailable", "unauthenticated", "invalid_origin"]);
 export async function sessionAccess(id, request = api) {
   sessionId(id);
   const access = await request("POST", `/api/v1/mac/sessions/${id}/access`);
@@ -63,6 +69,8 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   catch (error) { throw new CliError(error.message); }
   const { values, positionals } = parsed;
   if (values.help) return print(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 => {
     const billing = result.session?.billing;
     const usage = billing?.mode === "weekly_included"
@@ -124,6 +132,9 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       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"]) };
+      // Older CLIs persisted invalid keys before contacting the API. Such a key
+      // cannot pass server validation and therefore cannot have allocated a VM.
+      if (local && !local.id && !validRequestKey(local.requestKey)) { local.state = "failed"; store.save(local); }
       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.");
@@ -133,14 +144,23 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       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 } };
+        local = { mode: "hosted", state: "requesting", outcomeUnknown: false, 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 });
+        const previouslyUncertain = local.outcomeUnknown !== false;
+        local.outcomeUnknown = true; store.save(local); // A crash after dispatch must reconcile this intent.
+        let result;
+        try { result = await request("POST", "/api/v1/mac/sessions", { idempotencyKey: local.requestKey, body: local.request }); }
+        catch (error) {
+          if (!previouslyUncertain && startRejections.has(error.code) && Number.isInteger(error.status) && error.status >= 400 && error.status <= 503) {
+            local.state = "failed"; local.rejection = error.code; store.save(local);
+          }
+          throw error;
+        }
         saveView(local, result.session);
       }
-      const deadline = now() + integer(values.wait, 300, 0, 600) * 1000;
+      const deadline = now() + wait * 1000;
       for (;;) {
         await refresh(local);
         if (!["queued", "provisioning"].includes(local.state) || now() >= deadline) break;
@@ -153,7 +173,7 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     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;
+      const deadline = now() + wait * 1000;
       while (!["stopped", "failed"].includes(local.state) && now() < deadline) { await sleep(1000); await refresh(local); }
       return output({ session: local.snapshot });
     }

package/src/mac-tools.mjs

@@ -14,5 +14,5 @@ export const MAC_TOOLS = [
   { 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.", 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)}`)) },
-  { name: "read_mac_output", description: "Read a bounded stdout/stderr chunk by byte cursor. data_base64 preserves binary output. Resume from next_cursor; retrieve before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job, cursor: { type: "integer", minimum: 0 }, stream: { type: "string", enum: ["stdout", "stderr"] } }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}/output?${new URLSearchParams({ cursor: String(args.cursor ?? 0), stream: args.stream ?? "stdout" })}`)) },
+  { name: "read_mac_output", description: "Read stdout/stderr as base64 chunks; resume from next_cursor. If truncated, the final response includes tail_base64 and its absolute tail_offset. Retrieve promptly: only recent completed jobs retain output. output_expired preserves the job receipt and never means rerun. Retrieve before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job, cursor: { type: "integer", minimum: 0 }, stream: { type: "string", enum: ["stdout", "stderr"] } }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}/output?${new URLSearchParams({ cursor: String(args.cursor ?? 0), stream: args.stream ?? "stdout" })}`)) },
 ];

package/src/mcp.mjs

@@ -363,12 +363,14 @@ export const TOOLS = [
   {
     name: "report_issue",
     description:
-      "File an unknown/unfixable error with nomac support. Auto-attaches build error, logs (redacted) and lint state when you pass ref_id (a bld_… id). Deduped by error fingerprint. An optional email requests a direct resolution update; replies are always available by calling with no description.",
+      "File an unknown/unfixable error with nomac support. For a Mac use session_id and optional job_id; for a build use ref_id (bld_…). Attaches account-scoped context and deduplicates repeats. An optional email requests a direct resolution update; replies are always available by calling with no description.",
     inputSchema: {
       type: "object",
       properties: {
         description: { type: "string", description: "what went wrong + what you tried (≥10 chars). Omit to read existing tickets/replies." },
         ref_id: { type: "string" },
+        session_id: { type: "string", pattern: "^ses_[A-Za-z0-9_-]{1,80}$" },
+        job_id: { type: "string", pattern: "^job_[a-f0-9]{40}$" },
         email: {
           type: "string",
           format: "email",