@nomac/cli 0.2.3 → 0.2.5

package/package.json

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

package/skill/SKILL.md

@@ -12,15 +12,15 @@ 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
 
 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.
@@ -50,8 +50,11 @@ status                         # poll ~30s until ready | failed
    (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.
+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
@@ -60,6 +63,98 @@ do not use one to bypass an unconfirmed Apple request. Staging and confirmation
 remain separate invocations. For screenshots, keep the original `request_key`
 too, and use `get_screenshot_upload` to find or poll the existing operation.
 
+## Fix review rejections and release
+
+- `get_review` lists live Apple submissions, including ones created outside
+  nomac. Pass `asc_submission_id` for all item states and exact version/build IDs.
+- Apple does not expose App Review messages through its public API. Use the
+  returned App Store Connect handoff to have the human provide the actual text.
+  Never invent a rejection reason from a status code or public customer review.
+- Fix metadata/screenshots on the exact `version_string`. A binary change needs
+  push/build, then `publish` with the exact `build_id` and `asc_submission_id`.
+  `resolve_rejection:true` explicitly asserts that this version's issue is fixed.
+- `prepare_review_reply` prepares your authored text but always returns `sent:false`.
+  The human sends it and any message attachments in App Store Connect. Changing
+  review_contact.notes is not a reply; sending a reply is not resubmission.
+- `update_review` supports `resolve_item`, `remove_item`, `cancel`, `resubmit`,
+  and `release`. Preview without confirm; confirm the exact requested action.
+  Fix issues before marking items resolved. Every rejected item must be resolved
+  or removed before resubmitting. Removed items cannot be added back to that submission.
+- Poll `get_review`; approval and release are separate. Release requires an
+  app-version item in Pending Developer Release. Edit subscription/IAP products,
+  events and custom pages through the store catalog below. Apple/account/legal
+  decisions still require the relevant Apple workflow.
+
+## External TestFlight
+
+`ready` from a nomac build means internal TestFlight readiness. External testing
+requires its own review and distribution:
+
+1. `get_testflight` lists groups, test information and recent Apple builds. Use
+   `asc_build_id` for a specific build's beta-review/external state, or `group_id`
+   to list testers. Never infer external approval from internal readiness.
+2. `manage_testflight action=metadata` sets app_info (description/feedbackEmail/URLs),
+   review_contact (Apple contact/demo fields), locale, and build whats_new.
+3. Select/create an external group. `invite_tester`/`remove_tester` use an explicit
+   email/tester ID and group_id. `update_group` can enable an optional public link.
+4. `distribute` requires asc_build_id and explicit group_ids. It submits beta
+   review if needed, then assigns those groups. auto_notify defaults false;
+   `notify` starts testing after approval. `remove_build` affects one group;
+   `expire` stops testing for the build across all groups.
+5. All actions preview without confirm and apply with confirm:true. Pending
+   requests use their original key/body; get_store_operation recovers them.
+6. Relay an accurate human-provided uses_non_exempt_encryption with action=encryption
+   when appropriate. Never guess. Encryption declarations/documents use the
+   store catalog; rejected beta messages require App Store Connect. Fix the cause
+   before resubmitting a rejected binary.
+
+## Pricing, products, customer reviews and the wider store API
+
+1. `get_store_capabilities` lists operations by category/search with next_offset.
+   Pass `operation` to get that operation's exact Apple request/query schema.
+   Categories: listing, releases, pricing, purchases, subscriptions, reviews,
+   marketing, assets, testflight, analytics, compliance, webhooks.
+2. `read_store` executes listed GET operations. Begin with an `apps_*` relationship
+   and `scope:[]` for the linked app. Every child has a reusable `scope`; copy it
+   into the next read/write. Keep the query when following `next_cursor`.
+3. `update_store` takes the operation, scope and exact JSON:API `body`. For creation,
+   scope the parent. Every existing relationship ID needs its own verified scope
+   in `references`; the target and its ancestors are already verified. Territories
+   and categories are global. Inline creates use local IDs such as `${price1}`.
+4. Preview without confirm. `confirm:true` applies real paid prices, availability,
+   products/offers, public responses, release settings or event subscriptions.
+   Honor the human's existing authorization; do not ask again for authorized work.
+   Do not invent prices, legal answers or factual claims in public replies.
+5. `customerReviewResponses_createInstance` replies to a public customer review.
+   It does not send a message to Apple reviewers. Read their actual messages in
+   App Store Connect; `prepare_review_reply` only drafts the response.
+6. Product management covers subscriptions/IAP versions, localization, prices,
+   availability, grace periods and offers. First IAP approval may require the
+   app version submission. Draft review submission items can attach products;
+   use `publish` / `update_review` to submit, resolve, resubmit and release.
+7. Events, custom pages, experiments, accessibility and phased releases use their
+   catalog operations. Apple still validates account permissions and valid states.
+   Analytics report segments supply download URLs; offer-code CSV exports return
+   bounded base64 downloads. Webhooks send app events to an owner-selected receiver;
+   that receiver is responsible for running an agent when events arrive.
+
+`upload_store_asset` handles new Apple file resources: previews, screenshot files,
+purchase images, supplemental review attachments and encryption documents. Choose
+the asset create operation, provide its parent relationship/body, and pass a local
+`file_path` (CLI, up to 500 MiB) or `data_base64` (hosted, up to 2 MiB). Apple also
+has asset-specific limits. The tool reserves, uploads each requested byte range,
+then commits its checksum. Keep the same request_key and original bytes to resume.
+`uploaded:true` is not processing success: poll `read_store` until
+`assetDeliveryState.state` is `COMPLETE`. FAILED requires addressing Apple's errors.
+This adds a new file; use `upload_screenshots` for managed screenshot replacement.
+
+Keep pending write keys and unchanged bodies. `get_store_operation` exposes captured
+targets and receipts. Unknown Apple outcomes remain pending and block other writes
+to the app until reconciled; never use a fresh key to bypass one. Corrected inputs
+or a new intentional action require a fresh key. Correspondence, appeals, App Privacy
+questionnaire answers and account-wide financial/admin APIs are not exposed.
+This catalog does not run simulators or Xcode Cloud jobs.
+
 ## When stuck
 
 `report_issue` with the failing `ref_id` files a support ticket with full

package/src/lifecycle-schemas.json

@@ -0,0 +1,631 @@
+{
+  "get_store_capabilities": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "category": {
+        "type": "string",
+        "maxLength": 80
+      },
+      "operation": {
+        "type": "string",
+        "maxLength": 160
+      },
+      "search": {
+        "type": "string",
+        "maxLength": 100
+      },
+      "offset": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 1000
+      }
+    },
+    "additionalProperties": false
+  },
+  "read_store": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "operation": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 160
+      },
+      "scope": {
+        "maxItems": 8,
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "relationship": {
+              "type": "string",
+              "maxLength": 100,
+              "pattern": "^[A-Za-z][A-Za-z0-9]*$"
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "query": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 120
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "maxLength": 4096
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "maxItems": 200,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "maxLength": 1024
+                    }
+                  }
+                ]
+              }
+            }
+          },
+          "required": [
+            "relationship",
+            "id"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "query": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string",
+          "maxLength": 120
+        },
+        "additionalProperties": {
+          "anyOf": [
+            {
+              "type": "string",
+              "maxLength": 4096
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "maxItems": 200,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 1024
+              }
+            }
+          ]
+        }
+      },
+      "cursor": {
+        "type": "string",
+        "maxLength": 4096
+      },
+      "resource_id": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 512
+      }
+    },
+    "required": [
+      "operation"
+    ],
+    "additionalProperties": false
+  },
+  "update_store": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "operation": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 160
+      },
+      "scope": {
+        "maxItems": 8,
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "relationship": {
+              "type": "string",
+              "maxLength": 100,
+              "pattern": "^[A-Za-z][A-Za-z0-9]*$"
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "query": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 120
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "maxLength": 4096
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "maxItems": 200,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "maxLength": 1024
+                    }
+                  }
+                ]
+              }
+            }
+          },
+          "required": [
+            "relationship",
+            "id"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "references": {
+        "maxItems": 30,
+        "type": "array",
+        "items": {
+          "maxItems": 8,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "relationship": {
+                "type": "string",
+                "maxLength": 100,
+                "pattern": "^[A-Za-z][A-Za-z0-9]*$"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              },
+              "query": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string",
+                  "maxLength": 120
+                },
+                "additionalProperties": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 4096
+                    },
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "maxItems": 200,
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "maxLength": 1024
+                      }
+                    }
+                  ]
+                }
+              }
+            },
+            "required": [
+              "relationship",
+              "id"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "body": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {}
+      },
+      "confirm": {
+        "type": "boolean"
+      },
+      "asset_sha256": {
+        "description": "Set by upload_store_asset for exact file-reservation recovery.",
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      }
+    },
+    "required": [
+      "operation"
+    ],
+    "additionalProperties": false
+  },
+  "upload_store_asset": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "operation": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 160
+      },
+      "scope": {
+        "maxItems": 8,
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "relationship": {
+              "type": "string",
+              "maxLength": 100,
+              "pattern": "^[A-Za-z][A-Za-z0-9]*$"
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "query": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 120
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "maxLength": 4096
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "maxItems": 200,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "maxLength": 1024
+                    }
+                  }
+                ]
+              }
+            }
+          },
+          "required": [
+            "relationship",
+            "id"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "references": {
+        "maxItems": 30,
+        "type": "array",
+        "items": {
+          "maxItems": 8,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "relationship": {
+                "type": "string",
+                "maxLength": 100,
+                "pattern": "^[A-Za-z][A-Za-z0-9]*$"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              },
+              "query": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string",
+                  "maxLength": 120
+                },
+                "additionalProperties": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "maxLength": 4096
+                    },
+                    {
+                      "type": "number"
+                    },
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "maxItems": 200,
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "maxLength": 1024
+                      }
+                    }
+                  ]
+                }
+              }
+            },
+            "required": [
+              "relationship",
+              "id"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "body": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {}
+      },
+      "confirm": {
+        "type": "boolean"
+      },
+      "asset_sha256": {
+        "description": "Set by upload_store_asset for exact file-reservation recovery.",
+        "type": "string",
+        "pattern": "^[a-f0-9]{64}$"
+      },
+      "data_base64": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 3145728
+      }
+    },
+    "required": [
+      "operation",
+      "data_base64"
+    ],
+    "additionalProperties": false
+  },
+  "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,11 +3,14 @@
 // 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";
+import { uploadStoreAsset } from "./store-upload.mjs";
 
 const PROTOCOL_FALLBACK = "2025-06-18";
 
@@ -24,6 +27,29 @@ async function resolveProjectId(args) {
 }
 
 export const TOOLS = [
+  {
+    name: "upload_store_asset",
+    description: "Upload a new Apple screenshot, preview, purchase image, supplemental reviewer attachment or encryption document from file_path (up to 500 MiB, subject to Apple limits) or data_base64 (2 MiB). Discover the createInstance operation/body and parent scope with get_store_capabilities/read_store. Preview by default; confirm:true reserves, uploads and commits. Preserve request_key and identical bytes/body to resume. ready:true requires Apple processing COMPLETE. Message attachments require App Store Connect.",
+    inputSchema: { ...lifecycleSchemas.upload_store_asset, required: ["operation"], properties: { ...lifecycleSchemas.upload_store_asset.properties, project_id: { type: "string" }, file_path: { type: "string" }, request_key: { type: "string" } } },
+    handler: async args => text(await uploadStoreAsset({ ...args, project_id: await resolveProjectId(args) }, api)),
+  },
+  {
+    name: "get_store_capabilities",
+    description: "Discover useful App Store Connect operations: listing, paid pricing/availability, IAPs/subscriptions/offers, public customer-review replies, phased releases, marketing, files, analytics and webhooks. Pass category/search to list; pass operation for the exact Apple JSON:API request schema. Reviewer correspondence is a separate browser workflow.",
+    inputSchema: lifecycleSchemas.get_store_capabilities,
+    handler: async args => text(await api("GET", `/api/v1/store-capabilities?${new URLSearchParams(Object.entries(args ?? {}).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]))}`)),
+  },
+  ...[
+    ["read_store", "read", "Read a discovered Apple GET operation. Start with an apps_* relationship and scope:[]; reuse the returned resource scopes. Paginate with next_cursor and unchanged query. Raw IDs are accepted only for global lookups. Reads live Apple state, file upload operations and analytics report URLs."],
+    ["update_store", "write", "Execute a discovered Apple write using its exact JSON:API body. Copy scope and relationship references from read_store. Preview by default; confirm:true changes real Apple resources. Use owner-authorized prices and attestations. On pending, retry identical arguments with request_key; get_store_operation recovers lost keys. Use publish/update_review/manage_testflight for their dedicated lifecycle actions."],
+  ].map(([name, route, description]) => ({
+    name, description,
+    inputSchema: { ...lifecycleSchemas[name], properties: { project_id: { type: "string" }, ...lifecycleSchemas[name].properties, ...(route === "write" ? { request_key: { type: "string" } } : {}) } },
+    handler: async args => {
+      const { project_id: _project, request_key, ...body } = args;
+      return text(await api("POST", `/api/v1/projects/${encodeURIComponent(await resolveProjectId(args))}/store/${route}`, { body, ...(route === "write" ? { idempotencyKey: request_key ?? `mcp-store-${randomUUID()}` } : {}) }));
+    },
+  })),
   {
     name: "connect_status",
     description:
@@ -236,18 +262,21 @@ export const TOOLS = [
   },
   {
     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.",
+    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. On pending, repeat unchanged arguments with the returned request_key; get_store_operation recovers a lost response.",
+      "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)" },
@@ -264,12 +293,33 @@ export const TOOLS = [
       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/store-upload.mjs

@@ -0,0 +1,127 @@
+// Shared by the hosted upload endpoint and the published CLI (copied by the
+// schema generator). Provider upload URLs come only from an authenticated,
+// app-scoped read_store response; Nomac credentials never go to those URLs.
+import { createHash, randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { Readable } from 'node:stream';
+
+function unwrap(schema, components) {
+  if (schema?.$ref) return unwrap(components.schemas[schema.$ref.split('/').at(-1)], components);
+  if (schema?.anyOf) return unwrap(schema.anyOf.find(s => s.type !== 'null'), components);
+  return schema;
+}
+function fields(detail) {
+  const root = unwrap(detail.operation.body, detail.operation.components);
+  return unwrap(unwrap(root.properties.data, detail.operation.components).properties.attributes, detail.operation.components)?.properties ?? {};
+}
+const digest = (name, bytes) => createHash(name).update(bytes).digest('hex');
+
+export async function uploadStoreAsset(args, call) {
+  const requestKey = args.request_key ?? `store-upload-${randomUUID()}`;
+  let handle, current, source, md5, sha256, size, filename, reservation;
+  let stage = 'prepare';
+  try {
+    if (Boolean(args.file_path) === Boolean(args.data_base64)) throw new Error('Supply exactly one local file_path (CLI) or data_base64 (hosted).');
+    if (!args.operation?.endsWith('_createInstance')) throw new Error('Choose an asset createInstance operation from get_store_capabilities.');
+    if (args.file_path) {
+      handle = await open(args.file_path, 'r');
+      current = await handle.stat({ bigint: true });
+      if (!current.isFile() || current.size < 1n || current.size > 500n * 1024n * 1024n) throw new Error('Upload a regular file between 1 byte and 500 MiB. Apple may impose a smaller asset-specific limit.');
+      size = Number(current.size); filename = basename(args.file_path);
+      const range = async function* (offset, length) {
+        for (let position = offset; position < offset + length;) {
+          const buffer = Buffer.allocUnsafe(Math.min(1024 * 1024, offset + length - position));
+          const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+          if (!bytesRead) throw new Error('The source file was truncated during upload.');
+          position += bytesRead;
+          yield buffer.subarray(0, bytesRead);
+        }
+      };
+      const sha = createHash('sha256'), checksum = createHash('md5');
+      for await (const bytes of range(0, size)) { sha.update(bytes); checksum.update(bytes); }
+      sha256 = sha.digest('hex'); md5 = checksum.digest('hex');
+      source = async (offset, length) => {
+        const latest = await handle.stat({ bigint: true });
+        if (['size', 'mtimeNs', 'ctimeNs', 'ino'].some(k => latest[k] !== current[k])) throw new Error('The source file changed. Resume with the original bytes or start a new upload.');
+        return Readable.from(range(offset, length));
+      };
+    } else {
+      if (typeof args.data_base64 !== 'string' || args.data_base64.length > 3 * 1024 * 1024 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(args.data_base64)) throw new Error('Provide canonical base64 for a file up to 2 MiB; use the CLI for larger files.');
+      const bytes = Buffer.from(args.data_base64, 'base64');
+      size = bytes.length;
+      if (!size || size > 2 * 1024 * 1024) throw new Error('Hosted inline uploads support files between 1 byte and 2 MiB. Use the CLI for larger files.');
+      md5 = digest('md5', bytes); sha256 = digest('sha256', bytes); filename = 'asset.bin';
+      source = async (offset, length) => bytes.subarray(offset, offset + length);
+    }
+    const detail = await call('GET', `/api/v1/store-capabilities?operation=${encodeURIComponent(args.operation)}`);
+    const createFields = fields(detail);
+    if (!createFields.fileName || !createFields.fileSize) throw new Error('This operation does not create an uploadable Apple file.');
+    const commitOperation = args.operation.replace(/_createInstance$/, '_updateInstance');
+    const commitDetail = await call('GET', `/api/v1/store-capabilities?operation=${encodeURIComponent(commitOperation)}`);
+    const commitFields = fields(commitDetail);
+    if (!commitFields.uploaded) throw new Error('This asset does not support the standard Apple upload commit operation.');
+    const body = structuredClone(args.body ?? {});
+    if (!body.data || !body.data.relationships) throw new Error('Supply the asset JSON:API body and its parent relationship from get_store_capabilities.');
+    body.data.attributes ??= {};
+    if (body.data.attributes.fileSize !== undefined && body.data.attributes.fileSize !== size) throw new Error('The declared fileSize does not match the source file.');
+    filename = basename(body.data.attributes.fileName || filename).normalize('NFC').replace(/[\r\n]/g, '_');
+    const tag = digest('sha256', `${args.project_id}\n${requestKey}\n${args.operation}\n${sha256}`).slice(0, 32);
+    body.data.attributes.fileName = `nomac-${tag}-${filename}`;
+    body.data.attributes.fileSize = size;
+    const base = `/api/v1/projects/${encodeURIComponent(args.project_id)}/store`;
+    const write = (payload, key) => call('POST', `${base}/write`, { body: payload, idempotencyKey: key });
+    stage = 'reserve';
+    reservation = await write({ operation: args.operation, scope: args.scope, references: args.references, body, ...(args.confirm ? { asset_sha256: sha256 } : {}), confirm: Boolean(args.confirm) }, args.confirm ? requestKey : `${requestKey}:preview`);
+    if (!args.confirm || reservation.state === 'pending') return { ...reservation, request_key: requestKey, stage: 'reserve', file_size: size, sha256 };
+    if (!reservation.resource?.id || !reservation.scope) throw new Error('Apple has not returned an app-owned file reservation. Resume this request key; do not create another file.');
+    const read = async () => call('POST', `${base}/read`, { body: { operation: args.operation.replace(/_createInstance$/, '_getInstance'), scope: reservation.scope } });
+    let state = await read();
+    let attributes = state.data?.attributes;
+    if (!attributes || attributes.fileSize !== size || attributes.fileName !== body.data.attributes.fileName) throw new Error('The reserved Apple file does not match this upload.');
+    stage = 'upload';
+    const completed = ['UPLOAD_COMPLETE', 'COMPLETE', 'FAILED'].includes(attributes.assetDeliveryState?.state);
+    if (!completed) {
+      const operations = attributes.uploadOperations;
+      if (!Array.isArray(operations) || !operations.length) throw new Error('Apple has not exposed upload operations yet. Retry this same upload.');
+      let end = 0;
+      for (const op of [...operations].sort((a, b) => a.offset - b.offset)) {
+        if (op.method !== 'PUT' || !Number.isSafeInteger(op.offset) || !Number.isSafeInteger(op.length) || op.length < 1 || op.offset !== end || op.offset + op.length > size) throw new Error('Apple returned invalid or incomplete upload byte ranges.');
+        const url = new URL(op.url);
+        if (url.protocol !== 'https:' || url.username || url.password || !['apple.com', 'icloud.com', 'mzstatic.com', 'amazonaws.com'].some(domain => url.hostname === domain || url.hostname.endsWith(`.${domain}`))) throw new Error('Apple returned an unexpected upload destination.');
+        end += op.length;
+      }
+      if (end !== size) throw new Error('Apple upload operations do not cover the complete source file.');
+      for (const op of operations) {
+        const headers = new Headers();
+        for (const header of op.requestHeaders ?? []) {
+          if (typeof header.name !== 'string' || typeof header.value !== 'string') throw new Error('Apple returned invalid upload headers.');
+          headers.set(header.name, header.value);
+        }
+        if (headers.has('content-length') && headers.get('content-length') !== String(op.length)) throw new Error('Apple returned a Content-Length that does not match the upload byte range.');
+        // A Readable body otherwise uses chunked transfer encoding, which
+        // Apple's fixed-length upload destinations may reject.
+        headers.set('content-length', String(op.length));
+        const part = await source(op.offset, op.length);
+        try {
+          const response = await fetch(op.url, { method: 'PUT', headers, body: part, duplex: 'half', redirect: 'error', signal: AbortSignal.timeout(120_000) });
+          if (!response.ok) throw new Error(`Apple asset upload returned HTTP ${response.status}. Retry with this same request key to refresh its upload URLs.`);
+          await response.body?.cancel();
+        } finally { if (typeof part.destroy === 'function') part.destroy(); }
+      }
+    }
+    if (handle) {
+      const latest = await handle.stat({ bigint: true });
+      if (['size', 'mtimeNs', 'ctimeNs', 'ino'].some(k => latest[k] !== current[k])) throw new Error('The source file changed during upload; it was not committed.');
+    }
+    stage = 'commit';
+    const committed = await write({ operation: commitOperation, scope: reservation.scope, body: { data: { type: reservation.resource.type, id: reservation.resource.id, attributes: { uploaded: true, ...(commitFields.sourceFileChecksum ? { sourceFileChecksum: md5 } : {}) } } }, confirm: true }, `${requestKey}:commit`);
+    if (committed.state === 'pending') return { ...committed, request_key: requestKey, commit_request_key: `${requestKey}:commit`, stage, resource: reservation.resource, scope: reservation.scope };
+    stage = 'processing';
+    state = await read(); attributes = state.data?.attributes;
+    const deliveryState = attributes?.assetDeliveryState?.state;
+    return { request_key: requestKey, resource: reservation.resource, scope: reservation.scope, file_size: size, sha256, uploaded: true, ready: deliveryState === 'COMPLETE', state: deliveryState === 'COMPLETE' ? 'complete' : deliveryState === 'FAILED' ? 'failed' : 'processing', asset_delivery_state: attributes?.assetDeliveryState, next_steps: 'Poll read_store with this scope until assetDeliveryState is COMPLETE. A committed upload may still be processing or rejected by Apple. This uploaded a new file; existing assets were not replaced.' };
+  } catch (error) {
+    return { state: reservation?.resource ? 'needs_attention' : 'failed', stage, request_key: requestKey, ...(reservation?.resource ? { resource: reservation.resource, scope: reservation.scope } : {}), error: { code: error.code ?? 'store_upload_failed', message: error.friendly ?? error.message }, next_steps: 'Keep the original file and request_key to resume. Completed reservation/commit requests are replayed; upload PUTs may repeat the identical byte ranges. Do not start another reservation for an unconfirmed request.' };
+  } finally { await handle?.close(); }
+}