@nomac/cli 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Ship iOS apps to TestFlight and the App Store without a Mac — built for agents.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -47,12 +47,25 @@ status                         # poll ~30s until ready | failed
 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).
+   (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` (no confirm) → staged dry-run; fix any Apple blockers it returns.
 4. Ask the human explicitly before `publish confirm=true` — it's irreversible.
 
+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.
+
 ## When stuck
 
 `report_issue` with the failing `ref_id` files a support ticket with full
-context auto-attached (deduped, so safe to call). Read replies with the same
-tool. Never retry-loop an identical failure more than twice.
+context auto-attached (deduped, so safe to call). Its optional `email` requests
+a direct resolution update; without it, read replies with the same tool. If the
+tool returns a Private Relay warning, explain that Apple relay addresses may
+reject later mail and offer a non-relay address. Never show that warning for a
+normal address such as `@icloud.com`. Never retry-loop an identical failure
+more than twice.

package/src/api.mjs

@@ -1,10 +1,12 @@
 import { loadApiKey, loadApiUrl } from "./config.mjs";
 
 export class CliError extends Error {
-  constructor(message, friendly) {
+  constructor(message, friendly, status, code) {
     super(message);
     this.friendly = friendly ?? message;
     this.exitCode = 1;
+    this.status = status;
+    this.code = code;
   }
 }
 
@@ -21,7 +23,7 @@ export async function apiPublic(method, path, body) {
   try {
     json = text ? JSON.parse(text) : {};
   } catch {
-    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
+    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`, undefined, res.status);
   }
   return { status: res.status, ok: res.ok, json };
 }
@@ -53,13 +55,15 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
   try {
     json = text ? JSON.parse(text) : {};
   } catch {
-    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
+    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`, undefined, res.status);
   }
   if (!res.ok) {
     const err = json?.error ?? {};
     throw new CliError(
       `HTTP ${res.status} ${err.code ?? ""}`,
       err.message ?? `API error (HTTP ${res.status})`,
+      res.status,
+      err.code,
     );
   }
   return json;

package/src/cli.mjs

@@ -2,6 +2,7 @@ import { basename } from "node:path";
 import { api, CliError } from "./api.mjs";
 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)
 
@@ -85,36 +86,7 @@ async function push() {
   const { tarball, files } = await packTarball(process.cwd());
   console.log(`${files.length} files, ${(tarball.length / 1024).toFixed(0)} KB compressed`);
 
-  // preferred: direct-to-storage upload (no ~4MB API body limit), then confirm.
-  // Servers without the uploads route get the legacy inline body instead.
-  let grant = null;
-  try {
-    grant = await api("POST", `/api/v1/projects/${state.project_id}/snapshots/uploads`);
-  } catch {
-    grant = null;
-  }
-  let res;
-  if (grant) {
-    if (tarball.length > grant.max_bytes) {
-      throw new CliError(
-        "tarball too large",
-        `Packed source is ${(tarball.length / 1048576).toFixed(1)} MB; the limit is ${(grant.max_bytes / 1048576).toFixed(0)} MB. Check .gitignore: build artifacts are recreated on the build VM.`,
-      );
-    }
-    const up = await fetch(grant.upload_url, {
-      method: "PUT",
-      headers: { "content-type": "application/gzip" },
-      body: tarball,
-    });
-    if (!up.ok) throw new CliError(`upload failed (HTTP ${up.status})`);
-    res = await api("POST", `/api/v1/projects/${state.project_id}/snapshots`, {
-      body: { upload_key: grant.upload_key },
-    });
-  } else {
-    res = await api("POST", `/api/v1/projects/${state.project_id}/snapshots`, {
-      raw: tarball,
-    });
-  }
+  const res = await uploadSourceSnapshot(state.project_id, tarball);
   console.log(`✅ snapshot ${res.snapshot_id} (commit ${res.commit.slice(0, 8)})`);
   const d = res.detected ?? {};
   const framework = d.project_kind
@@ -169,6 +141,7 @@ const SPINNER_STATES = {
 async function waitForBuild(id) {
   const started = Date.now();
   let last = "";
+  let lastNotice = "";
   for (;;) {
     const b = await api("GET", `/api/v1/builds/${id}`);
     if (b.state !== last) {
@@ -176,6 +149,12 @@ async function waitForBuild(id) {
       console.log(`   [${t}s] ${SPINNER_STATES[b.state] ?? b.state}`);
       last = b.state;
     }
+    const notice = b.error?.stage === "testflight" ? b.error.raw : "";
+    if (notice && notice !== lastNotice) {
+      console.log(`   ${notice}`);
+      if (b.error.url) console.log(`   ${b.error.url}`);
+    }
+    lastNotice = notice;
     if (b.state === "ready") {
       console.log(
         b.workflow === "smoke"

package/src/mcp.mjs

@@ -7,6 +7,7 @@ import { createInterface } from "node:readline";
 import { api } from "./api.mjs";
 import { loadProjectState, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
+import { uploadSourceSnapshot } from "./upload.mjs";
 
 const PROTOCOL_FALLBACK = "2025-06-18";
 
@@ -43,6 +44,15 @@ export const TOOLS = [
       return text({ org: me.org, connection: detail });
     },
   },
+  {
+    name: "set_project_connection",
+    description: "Choose an Apple connection for a project, including after key rotation. Verifies the app's bundle ID. Active release builds must finish first.",
+    inputSchema: {
+      type: "object", properties: { project_id: { type: "string" }, connection_id: { type: "string" } },
+      required: ["connection_id"], additionalProperties: false,
+    },
+    handler: async args => text(await api("PATCH", `/api/v1/projects/${await resolveProjectId(args)}`, { body: { connection_id: args.connection_id } })),
+  },
   {
     name: "push_project",
     description:
@@ -64,9 +74,7 @@ export const TOOLS = [
         saveProjectState(state, dir);
       }
       const { tarball, files } = await packTarball(dir);
-      const res = await api("POST", `/api/v1/projects/${state.project_id}/snapshots`, {
-        raw: tarball,
-      });
+      const res = await uploadSourceSnapshot(state.project_id, tarball);
       saveProjectState({ ...state, last_snapshot: res.snapshot_id }, dir);
       return text({ project_id: state.project_id, files_packed: files.length, ...res });
     },
@@ -89,8 +97,22 @@ export const TOOLS = [
         body: { project_id, workflow: args?.workflow ?? "release" },
         idempotencyKey: `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
       });
+      let warning;
+      try {
+        const state = loadProjectState();
+        if (state?.project_id === project_id) {
+          saveProjectState({ ...state, last_build: res.id });
+        } else {
+          warning = "Build started for a project outside this directory's saved project. Pass build_id to status.";
+        }
+      } catch {
+        // The paid attempt already exists. Return its ID even when the local
+        // directory is read-only, so the agent can poll without starting again.
+        warning = "Build started, but its ID could not be saved locally. Pass build_id to status.";
+      }
       return text({
         ...res,
+        ...(warning ? { warning } : {}),
         note: "poll `status` every ~30s; a release build reaching `ready` means the phone can install it from TestFlight",
       });
     },
@@ -141,24 +163,26 @@ export const TOOLS = [
   },
   {
     name: "get_metadata",
-    description: "Current App Store metadata (app + latest version localizations) from App Store Connect.",
+    description: "Current App Store metadata (app + selected iOS version localizations) from App Store Connect.",
     inputSchema: {
       type: "object",
-      properties: { project_id: { type: "string" } },
+      properties: { project_id: { type: "string" }, version_string: { type: "string", description: "Defaults to the pushed source marketing version" } },
       additionalProperties: false,
     },
     handler: async (args) =>
-      text(await api("GET", `/api/v1/projects/${await resolveProjectId(args)}/metadata`)),
+      text(await api("GET", `/api/v1/projects/${await resolveProjectId(args)}/metadata${args?.version_string ? `?version_string=${encodeURIComponent(args.version_string)}` : ""}`)),
   },
   {
     name: "set_metadata",
     description:
-      "Write App Store metadata YOU authored (validated against limits before any Apple call). fields: description, keywords, whats_new, support_url, marketing_url, promotional_text, name, subtitle, privacy_policy_url. Also: primary_category (e.g. UTILITIES), age_rating (attestations from your human), content_rights, copyright, review_contact{...,demo_account}, price:'FREE'.",
+      "Write App Store metadata YOU authored (validated against limits before any Apple call). fields: description, keywords, whats_new, support_url, marketing_url, promotional_text, name, subtitle, privacy_policy_url. Also: primary_category (e.g. UTILITIES), age_rating (attestations from your human), content_rights, copyright, review_contact{...,demo_account}, price:'FREE'. On pending, repeat unchanged arguments with the returned request_key; get_store_operation recovers a lost response.",
     inputSchema: {
       type: "object",
       properties: {
         project_id: { type: "string" },
         locale: { type: "string", default: "en-US" },
+        version_string: { type: "string", description: "Defaults to the pushed source marketing version; select a live version explicitly for promotional text" },
+        request_key: { type: "string", description: "Reuse the returned key to resume pending work with the original unchanged arguments" },
         fields: { type: "object" },
         primary_category: { type: "string" },
         age_rating: { type: "object" },
@@ -170,21 +194,23 @@ export const TOOLS = [
       additionalProperties: false,
     },
     handler: async (args) => {
-      const { project_id: _p, ...rest } = args ?? {};
+      const { project_id: _p, request_key, ...rest } = args ?? {};
       const project_id = await resolveProjectId(args);
-      return text(await api("PUT", `/api/v1/projects/${project_id}/metadata`, { body: rest }));
+      return text(await api("PUT", `/api/v1/projects/${project_id}/metadata`, { body: rest, idempotencyKey: request_key }));
     },
   },
   {
     name: "upload_screenshots",
     description:
-      "Replace one display type's screenshot set (all-or-nothing swap; exact dimensions validated first — see get_metadata_schema). 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, data: base64 PNG}].",
     inputSchema: {
       type: "object",
       properties: {
         project_id: { type: "string" },
         display_type: { type: "string" },
+        request_key: { type: "string", description: "Unique per replacement; reuse this key and the same images on a retry" },
         locale: { type: "string", default: "en-US" },
+        version_string: { type: "string", description: "Defaults to the pushed source marketing version" },
         images: { type: "array", items: { type: "object" } },
       },
       required: ["display_type", "images"],
@@ -192,19 +218,38 @@ export const TOOLS = [
     },
     handler: async (args) => {
       const project_id = await resolveProjectId(args);
-      const { project_id: _p, ...rest } = args;
-      return text(await api("POST", `/api/v1/projects/${project_id}/screenshots`, { body: rest }));
+      const { project_id: _p, request_key, ...rest } = args;
+      return text(await api("POST", `/api/v1/projects/${project_id}/screenshots`, { body: rest, idempotencyKey: request_key }));
     },
   },
+  {
+    name: "get_screenshot_upload",
+    description: "Check screenshot replacement/restoration. Omit operation_id to list recent operations after a lost upload response. complete confirms processed images; rolled_back means previous images were retained/restored; needs_attention requires support reconciliation.",
+    inputSchema: {
+      type: "object", properties: { project_id: { type: "string" }, operation_id: { type: "string" } },
+      additionalProperties: false,
+    },
+    handler: async args => {
+      const project_id = await resolveProjectId(args);
+      return text(await api("GET", `/api/v1/projects/${project_id}/screenshots${args.operation_id ? `?operation_id=${encodeURIComponent(args.operation_id)}` : ""}`));
+    },
+  },
+  {
+    name: "get_store_operation",
+    description: "Read saved publish/metadata requests and recover a lost response or request_key. Resume pending work by repeating the original publish/set_metadata arguments with its returned request_key. This status call performs no Apple writes.",
+    inputSchema: { type: "object", properties: { project_id: { type: "string" }, request_key: { type: "string" } }, additionalProperties: false },
+    handler: async args => text(await api("GET", `/api/v1/projects/${await resolveProjectId(args)}/operations${args?.request_key ? `?request_key=${encodeURIComponent(args.request_key)}` : ""}`)),
+  },
   {
     name: "publish",
     description:
-      "Submit for App Store review (3-step reviewSubmissions). IRREVERSIBLE once confirmed — requires confirm:true; run once without confirm first to see the staged result + any Apple blockers. Costs nothing; the review decision takes ~1-3 days.",
+      "Submit for App Store review (3-step reviewSubmissions). IRREVERSIBLE once confirmed — requires confirm:true; run once without confirm first to see the staged result + any Apple blockers. Costs nothing; the review decision takes ~1-3 days. On pending, repeat unchanged arguments with the returned request_key; get_store_operation recovers a lost response.",
     inputSchema: {
       type: "object",
       properties: {
         project_id: { type: "string" },
         confirm: { type: "boolean", default: false },
+        request_key: { type: "string", description: "Only supply to resume an interrupted invocation with its original unchanged arguments" },
         force: { type: "boolean", default: false, description: "override a red lint gate (not recommended)" },
       },
       additionalProperties: false,
@@ -216,7 +261,7 @@ export const TOOLS = [
       // this project forever. A later invocation must re-run mutable lint and
       // App Store preflight checks; retries inside this invocation reuse this
       // single key.
-      const idempotencyKey = `mcp-pub-${project_id}-${mode}-${randomUUID()}`;
+      const idempotencyKey = args?.request_key ?? `mcp-pub-${project_id}-${mode}-${randomUUID()}`;
       return text(
         await api("POST", "/api/v1/publish", {
           body: { project_id, confirm: args?.confirm ?? false, force: args?.force ?? false },
@@ -240,12 +285,18 @@ 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. Read replies by calling with no 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.",
     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" },
+        email: {
+          type: "string",
+          format: "email",
+          maxLength: 320,
+          description: "optional follow-up email for a direct resolution update",
+        },
       },
       additionalProperties: false,
     },

package/src/pack.mjs

@@ -1,5 +1,5 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, sep } from "node:path";
 import ignoreFactory from "ignore";
 import * as tar from "tar";
 
@@ -24,21 +24,31 @@ const ALWAYS_IGNORE = [
 ];
 
 export function collectFiles(dir) {
-  const ig = ignoreFactory().add(ALWAYS_IGNORE);
-  try {
-    ig.add(readFileSync(join(dir, ".gitignore"), "utf8"));
-  } catch {
-    // no .gitignore — fine
-  }
-
+  const denied = ignoreFactory().add(ALWAYS_IGNORE);
+  const relativePath = (base, path) => relative(base, path).split(sep).join("/");
   const files = [];
-  const walk = (current) => {
+  const walk = (current, inherited = []) => {
+    let scopes = inherited;
+    try {
+      const rules = readFileSync(join(current, ".gitignore"), "utf8");
+      scopes = [...inherited, { base: current, ignore: ignoreFactory().add(rules) }];
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       const full = join(current, entry.name);
-      const rel = relative(dir, full);
+      const rel = relativePath(dir, full);
       const relForIgnore = entry.isDirectory() ? `${rel}/` : rel;
-      if (ig.ignores(relForIgnore)) continue;
-      if (entry.isDirectory()) walk(full);
+      if (denied.ignores(relForIgnore)) continue;
+      let ignored = false;
+      for (const scope of scopes) {
+        const scoped = relativePath(scope.base, full) + (entry.isDirectory() ? "/" : "");
+        const result = scope.ignore.test(scoped);
+        if (result.ignored) ignored = true;
+        else if (result.unignored) ignored = false;
+      }
+      if (ignored) continue;
+      if (entry.isDirectory()) walk(full, scopes);
       else if (entry.isFile()) files.push(rel);
     }
   };

package/src/upload.mjs

@@ -0,0 +1,36 @@
+import { api, CliError } from "./api.mjs";
+
+/** Shared by the CLI and stdio MCP so both bypass the API's 4 MiB body limit. */
+export async function uploadSourceSnapshot(projectId, tarball) {
+  const path = `/api/v1/projects/${projectId}/snapshots`;
+  let grant;
+  try {
+    grant = await api("POST", `${path}/uploads`);
+  } catch (error) {
+    // Older servers have no grant route. Outages and authorization failures
+    // should remain actionable, not silently retry through another transport.
+    if (!(error instanceof CliError) || error.status !== 404 || error.code) throw error;
+    if (tarball.length > 4 * 1024 * 1024) {
+      throw new CliError("direct uploads unavailable", "This server does not support direct source uploads. Update the server or reduce the compressed archive to 4 MiB.");
+    }
+    return api("POST", path, { raw: tarball });
+  }
+  if (typeof grant.upload_url !== "string" || typeof grant.upload_key !== "string" ||
+    !Number.isSafeInteger(grant.max_bytes) || grant.max_bytes <= 0) {
+    throw new CliError("invalid source upload grant");
+  }
+  if (tarball.length > grant.max_bytes) {
+    throw new CliError(
+      "tarball too large",
+      `Packed source is ${(tarball.length / 1048576).toFixed(1)} MiB; the limit is ${(grant.max_bytes / 1048576).toFixed(0)} MiB. Check .gitignore: build artifacts are recreated on the build VM.`,
+    );
+  }
+  const uploaded = await fetch(grant.upload_url, {
+    method: "PUT",
+    headers: { "content-type": "application/gzip", "content-length": String(tarball.length) },
+    body: tarball,
+  });
+  await uploaded.body?.cancel();
+  if (!uploaded.ok) throw new CliError(`upload failed (HTTP ${uploaded.status})`);
+  return api("POST", path, { body: { upload_key: grant.upload_key } });
+}