@nomac/cli 0.2.2 → 0.2.4

package/package.json

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

package/skill/SKILL.md

@@ -18,9 +18,9 @@ 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, ask the human for an API
-   key from nomac.app → API keys, then `npx @nomac/cli login <nmk_…>` and
-   `claude mcp add nomac -- npx @nomac/cli mcp`.
+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.
@@ -47,9 +47,64 @@ 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).
-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.
+   (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. Apple/account/legal decisions
+  and unsupported product edits 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. Rejected beta messages and compliance documents
+   require App Store Connect; do not blindly resubmit an unchanged rejected binary.
 
 ## When stuck
 

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/lifecycle-schemas.json

@@ -0,0 +1,215 @@
+{
+  "update_review": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "asc_submission_id": {
+        "type": "string",
+        "minLength": 1
+      },
+      "action": {
+        "type": "string",
+        "enum": [
+          "resolve_item",
+          "remove_item",
+          "cancel",
+          "resubmit",
+          "release"
+        ]
+      },
+      "item_id": {
+        "type": "string",
+        "minLength": 1
+      },
+      "confirm": {
+        "default": false,
+        "type": "boolean"
+      },
+      "force": {
+        "default": false,
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "asc_submission_id",
+      "action"
+    ],
+    "additionalProperties": false
+  },
+  "prepare_review_reply": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "asc_submission_id": {
+        "type": "string",
+        "minLength": 1
+      },
+      "reply": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 4000
+      }
+    },
+    "required": [
+      "asc_submission_id",
+      "reply"
+    ],
+    "additionalProperties": false
+  },
+  "manage_testflight": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "enum": [
+          "metadata",
+          "create_group",
+          "update_group",
+          "invite_tester",
+          "remove_tester",
+          "remove_build",
+          "distribute",
+          "notify",
+          "expire",
+          "encryption"
+        ]
+      },
+      "asc_build_id": {
+        "type": "string",
+        "minLength": 1
+      },
+      "group_ids": {
+        "minItems": 1,
+        "maxItems": 100,
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "group_id": {
+        "type": "string",
+        "minLength": 1
+      },
+      "name": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 100
+      },
+      "email": {
+        "type": "string",
+        "format": "email",
+        "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+      },
+      "first_name": {
+        "type": "string",
+        "maxLength": 100
+      },
+      "last_name": {
+        "type": "string",
+        "maxLength": 100
+      },
+      "tester_id": {
+        "type": "string",
+        "minLength": 1
+      },
+      "public_link_enabled": {
+        "type": "boolean"
+      },
+      "public_link_limit": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 10000
+      },
+      "auto_notify": {
+        "default": false,
+        "type": "boolean"
+      },
+      "uses_non_exempt_encryption": {
+        "type": "boolean"
+      },
+      "locale": {
+        "default": "en-US",
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 35
+      },
+      "app_info": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "maxLength": 4000
+          },
+          "feedbackEmail": {
+            "type": "string",
+            "format": "email",
+            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+          },
+          "marketingUrl": {
+            "type": "string",
+            "maxLength": 255,
+            "format": "uri"
+          },
+          "privacyPolicyUrl": {
+            "type": "string",
+            "maxLength": 255,
+            "format": "uri"
+          }
+        },
+        "additionalProperties": false
+      },
+      "review_contact": {
+        "type": "object",
+        "properties": {
+          "contactFirstName": {
+            "type": "string",
+            "maxLength": 100
+          },
+          "contactLastName": {
+            "type": "string",
+            "maxLength": 100
+          },
+          "contactPhone": {
+            "type": "string",
+            "maxLength": 100
+          },
+          "contactEmail": {
+            "type": "string",
+            "format": "email",
+            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+          },
+          "demoAccountRequired": {
+            "type": "boolean"
+          },
+          "demoAccountName": {
+            "type": "string",
+            "maxLength": 100
+          },
+          "demoAccountPassword": {
+            "type": "string",
+            "maxLength": 100
+          },
+          "notes": {
+            "type": "string",
+            "maxLength": 4000
+          }
+        },
+        "additionalProperties": false
+      },
+      "whats_new": {
+        "type": "string",
+        "maxLength": 4000
+      },
+      "confirm": {
+        "default": false,
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "action"
+    ],
+    "additionalProperties": false
+  }
+}

package/src/mcp.mjs

@@ -3,10 +3,13 @@
 // Works in every MCP client day one; the hosted transport is mcp.nomac.app.
 
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+const lifecycleSchemas = JSON.parse(readFileSync(new URL("./lifecycle-schemas.json", import.meta.url), "utf8"));
 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 +46,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 +76,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 +99,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 +165,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 +196,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 +220,41 @@ 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/review/TestFlight requests and recover a lost response or request_key. Resume pending work by repeating the original tool 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). Requires confirm:true with authorization for this app/version; 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" },
+        build_id: { type: "string", description: "Exact nomac release build to attach" },
+        asc_submission_id: { type: "string", description: "Exact Apple submission from get_review" },
+        resolve_rejection: { type: "boolean", default: false, description: "Assert this version rejection was fixed; mark its item ready for review" },
         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,15 +266,36 @@ 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 },
+          body: { project_id, ...(args?.build_id ? { build_id: args.build_id } : {}), ...(args?.asc_submission_id ? { asc_submission_id: args.asc_submission_id } : {}), ...(args?.resolve_rejection !== undefined ? { resolve_rejection: args.resolve_rejection } : {}), confirm: args?.confirm ?? false, force: args?.force ?? false },
           idempotencyKey,
         }),
       );
     },
   },
+  ...[
+    ["get_review", "reviews", "asc_submission_id", "Read live App Review submissions including those created outside nomac. Pass asc_submission_id for all items, version/build/contact details. Reviewer messages require the App Store Connect handoff in the result."],
+    ["get_testflight", "testflight", "asc_build_id", "Read external/internal groups and test metadata. Pass asc_build_id for exact beta review and distribution state. Internal readiness does not imply external approval."],
+  ].map(([name, path, filter, description]) => ({
+    name, description,
+    inputSchema: { type: "object", properties: { project_id: { type: "string" }, [filter]: { type: "string" }, ...(name === "get_testflight" ? { group_id: { type: "string" } } : {}) }, additionalProperties: false },
+    handler: async args => text(await api("GET", `/api/v1/projects/${encodeURIComponent(await resolveProjectId(args))}/${path}${args?.[filter] || args?.group_id ? `?${new URLSearchParams({ ...(args?.[filter] ? { [filter]: args[filter] } : {}), ...(args?.group_id ? { group_id: args.group_id } : {}) })}` : ""}`)),
+  })),
+  ...[
+    ["update_review", "reviews", "Resolve a fixed rejected item, remove an item, cancel review, resubmit ready items or release an approved version. Use exact IDs from get_review. Preview without confirm; confirm:true performs the action. Removal cannot be undone in that submission. Fix actual issues before resolving. On pending, repeat unchanged arguments with request_key; get_store_operation recovers it."],
+    ["manage_testflight", "testflight", "Set beta metadata/contact/demo credentials, create/update external groups/public links, invite/remove an explicit tester, distribute a specific Apple build to explicit groups and Beta App Review, notify after approval, expire testing, or relay a human-provided encryption answer. Preview without confirm; confirm:true applies. auto_notify defaults false. Never guess attestations. On pending, repeat unchanged arguments with request_key."],
+    ["prepare_review_reply", "reviews/reply", "Prepare YOUR authored reply with an App Store Connect handoff. Always returns sent:false: Apple's public API cannot read or send reviewer messages. The human must paste and send it. This does not change reviewer notes or public customer reviews."],
+  ].map(([name, path, description]) => ({
+    name, description,
+    inputSchema: { ...lifecycleSchemas[name], properties: { project_id: { type: "string" }, ...lifecycleSchemas[name].properties, ...(name !== "prepare_review_reply" ? { request_key: { type: "string" } } : {}) } },
+    handler: async args => {
+      const projectId = await resolveProjectId(args);
+      const { project_id: _project, request_key, ...body } = args;
+      return text(await api("POST", `/api/v1/projects/${encodeURIComponent(projectId)}/${path}`, { body, idempotencyKey: request_key ?? randomUUID() }));
+    },
+  })),
   {
     name: "get_feedback",
     description:

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 } });
+}