@nomac/cli 0.2.4 → 0.3.0-beta.1

package/src/lifecycle-schemas.json

@@ -1,4 +1,420 @@
 {
+  "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",

package/src/mac-credits.mjs

@@ -0,0 +1,10 @@
+import { parseArgs } from "node:util";
+import { api, CliError } from "./api.mjs";
+export async function creditsCommand(argv, { request = api, print = console.log } = {}) {
+  const { values, positionals } = parseArgs({ args: argv, options: { plan: { type: "string" }, "request-key": { type: "string" }, json: { type: "boolean" }, help: { type: "boolean" } }, allowPositionals: true });
+  if (values.help) return print("nomac credits [--json]\nnomac credits --plan five|twenty_five --request-key STABLE_KEY\n$5/week for 5 hours or $20/week for 25 hours. Unused hours expire weekly.\nReturns a subscription checkout link; the human reviews and pays. Reuse the key after a lost response.");
+  if (positionals.length) throw new CliError("Unexpected credits argument.");
+  if (!values.plan) return print(JSON.stringify(await request("GET", "/api/v1/mac/credits"), null, 2));
+  if (!["five", "twenty_five"].includes(values.plan) || !/^[A-Za-z0-9_.:-]{8,128}$/.test(values["request-key"] ?? "")) throw new CliError("Choose --plan five or twenty_five and supply a stable --request-key.");
+  return print(JSON.stringify(await request("POST", "/api/v1/mac/credits/checkout", { idempotencyKey: values["request-key"], body: { plan: values.plan } }), null, 2));
+}

package/src/mac-tools.mjs

@@ -0,0 +1,18 @@
+import { api } from "./api.mjs";
+const text = value => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const session = { type: "string", pattern: "^ses_[A-Za-z0-9_-]{1,80}$" };
+const job = { type: "string", pattern: "^job_[a-f0-9]{40}$" };
+const key = { type: "string", pattern: "^[A-Za-z0-9_.:-]{8,128}$" };
+const schema = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+const base = args => `/api/v1/mac/sessions/${encodeURIComponent(args.session_id)}`;
+export const MAC_TOOLS = [
+  { name: "get_mac_checkout", description: "Return a weekly subscription checkout: five is $5/week for 5 hours; twenty_five is $20/week for 25 hours. Renews until canceled; no rollover or overage. The human reviews and subscribes. Reuse request_key after a lost response.", inputSchema: schema({ plan: { type: "string", enum: ["five", "twenty_five"] }, request_key: key }, ["plan", "request_key"]), handler: async ({ plan, request_key }) => text(await api("POST", "/api/v1/mac/credits/checkout", { body: { plan }, idempotencyKey: request_key })) },
+  { name: "get_mac_credits", description: "Read weekly Mac hours, expiry, reservations and concurrency, separate from legacy build subscriptions.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/credits")) },
+  { name: "start_mac", description: "Allocate a full cloud Mac VM. Supply a stable request_key; SSH public_key is optional for HTTPS-only agents; reuse both after a lost response. Inspect the returned offer and limits. Poll get_mac_session until ready. No project pipeline is imposed; stop_mac deletes the VM and files.", inputSchema: schema({ public_key: { type: "string" }, request_key: key, limits: { type: "object", properties: { max_duration_seconds: { type: "integer", minimum: 60, maximum: 86400 }, idle_timeout_seconds: { type: "integer", minimum: 60, maximum: 3600 }, spend_cap_microunits: { type: "string", pattern: "^[1-9][0-9]{0,17}$" } }, additionalProperties: false } }, ["request_key"]), handler: async ({ request_key, ...body }) => text(await api("POST", "/api/v1/mac/sessions", { body, idempotencyKey: request_key })) },
+  { name: "list_mac_sessions", description: "Find existing Mac sessions, including after losing a response. Shows state, cost, limits and cleanup.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/sessions")) },
+  { name: "get_mac_session", description: "Read live Mac allocation state, cost, funded time and cleanup confirmation. queued/provisioning means wait; stopping is not yet confirmed cleanup.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("GET", base(args))) },
+  { name: "stop_mac", description: "Stop billing by shutting down the VM and deleting its files. Retrieve files first. Poll get_mac_session until cleanup_confirmed; stopping only acknowledges the request.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("DELETE", base(args))) },
+  { name: "exec_mac", description: "Run any argv command in your cloud Mac workspace. Returns a durable job ID; poll get_mac_job and read_mac_output. Reuse request_key and identical arguments after lost responses; never submit a new key blindly. Use bash -lc explicitly for shell syntax.", inputSchema: schema({ session_id: session, request_key: key, argv: { type: "array", items: { type: "string" }, minItems: 1 }, timeout_seconds: { type: "integer", minimum: 1, maximum: 600 } }, ["session_id", "request_key", "argv"]), handler: async ({ session_id, request_key, ...body }) => text(await api("POST", `${base({ session_id })}/jobs`, { body, idempotencyKey: request_key })) },
+  { name: "get_mac_job", description: "Inspect the existing command without rerunning it. Retain its job ID until completion and retrieve output before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}`)) },
+  { name: "read_mac_output", description: "Read a bounded stdout/stderr chunk by byte cursor. data_base64 preserves binary output. Resume from next_cursor; retrieve before stopping the VM.", inputSchema: schema({ session_id: session, job_id: job, cursor: { type: "integer", minimum: 0 }, stream: { type: "string", enum: ["stdout", "stderr"] } }, ["session_id", "job_id"]), handler: async args => text(await api("GET", `${base(args)}/jobs/${encodeURIComponent(args.job_id)}/output?${new URLSearchParams({ cursor: String(args.cursor ?? 0), stream: args.stream ?? "stdout" })}`)) },
+];

package/src/mac-transport.mjs

@@ -0,0 +1,118 @@
+import http from "node:http";
+import https from "node:https";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { getProxyForUrl } from "proxy-from-env";
+import WebSocket, { createWebSocketStream } from "ws";
+import { CliError } from "./api.mjs";
+
+export function sessionId(value) {
+  const id = String(value ?? "").replace(/^nomac-/, "");
+  if (!/^ses_[A-Za-z0-9_-]{1,80}$/.test(id)) throw new CliError("Invalid Mac session ID.", undefined, undefined, "invalid_session");
+  return id;
+}
+
+export function transportOptions(options = {}) {
+  let url;
+  try { url = new URL(options.gateway ?? process.env.NOMAC_GATEWAY_URL); }
+  catch { throw new CliError("Set NOMAC_GATEWAY_URL to the HTTPS gateway origin.", undefined, undefined, "gateway_required"); }
+  const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+  if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+    throw new CliError("The gateway must be an HTTPS origin; HTTP is allowed only for a loopback probe.", undefined, undefined, "invalid_gateway");
+  }
+  const token = options.token ?? process.env.NOMAC_SESSION_TOKEN;
+  if (typeof token !== "string" || !/^[A-Za-z0-9_-]{32,2048}$/.test(token)) throw new CliError("Set NOMAC_SESSION_TOKEN to a session-scoped access token.", undefined, undefined, "token_required");
+  const proxy = options.proxy ?? getProxyForUrl(url.href);
+  return { url, token, agent: proxy ? new HttpsProxyAgent(proxy) : undefined, ca: options.ca };
+}
+
+/** Bounded requests deliberately do not require streaming responses or retry mutations. */
+export function macRequest(method, path, { body, raw, requestKey, ...options } = {}) {
+  const { url, token, agent, ca } = transportOptions(options);
+  if (!path.startsWith("/api/v1/mac/") || path.includes("#")) throw new CliError("Invalid Mac API path.");
+  const target = new URL(path, url);
+  if (target.origin !== url.origin) throw new CliError("Invalid Mac API origin.");
+  const payload = raw ?? (body === undefined ? undefined : Buffer.from(JSON.stringify(body)));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (code, message, status) => {
+      if (settled) return;
+      settled = true;
+      reject(new CliError(message, undefined, status, code, requestKey ? { request_key: requestKey } : undefined));
+    };
+    const request = (target.protocol === "https:" ? https : http).request(target, {
+      method, agent, ca, headers: {
+        authorization: `Bearer ${token}`,
+        ...(payload ? { "content-type": raw ? "application/octet-stream" : "application/json", "content-length": payload.length } : {}),
+        ...(requestKey ? { "idempotency-key": requestKey } : {}),
+      },
+    }, response => {
+      const chunks = []; let bytes = 0;
+      response.on("data", chunk => {
+        bytes += chunk.length;
+        if (bytes > 768 * 1024) {
+          fail("response_too_large", "The gateway response exceeded its limit.");
+          response.destroy();
+        } else chunks.push(chunk);
+      });
+      response.on("error", () => fail("outcome_unknown", "Response lost. Inspect the job or retry with the same request key."));
+      response.on("end", () => {
+        if (settled) return;
+        let data;
+        try { data = JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+        catch { return fail("bad_response", "The gateway returned an unreadable response. Reconcile before retrying.", response.statusCode); }
+        if (response.statusCode < 200 || response.statusCode >= 300) return fail(data.error?.code ?? "gateway_error", data.error?.message ?? "The Mac request failed.", response.statusCode);
+        settled = true;
+        resolve(data);
+      });
+    });
+    const deadline = setTimeout(() => request.destroy(new Error("deadline")), 15_000);
+    request.on("close", () => clearTimeout(deadline));
+    request.on("error", () => fail("outcome_unknown", "Connection lost. Inspect the job or retry with the same request key."));
+    request.end(payload);
+  });
+}
+
+/** A ProxyCommand: stdout contains only SSH bytes, never status or cost messages. */
+export function tunnel(value, { input = process.stdin, output = process.stdout, ...options } = {}) {
+  const id = sessionId(value);
+  const { url, token, agent, ca } = transportOptions(options);
+  url.pathname = `/api/v1/mac/sessions/${id}/ssh`;
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url, {
+      agent, ca, headers: { authorization: `Bearer ${token}` },
+      handshakeTimeout: 15_000, perMessageDeflate: false, maxPayload: 1024 * 1024,
+      followRedirects: false,
+    });
+    const stream = createWebSocketStream(ws, { highWaterMark: 64 * 1024 });
+    let failure, closedCode, settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      input.unpipe(stream); stream.unpipe(output); input.pause();
+      input.removeListener("error", fail); output.removeListener("error", fail);
+      if (failure || closedCode !== 1000) reject(failure ?? new CliError("SSH tunnel closed unexpectedly.", undefined, undefined, "tunnel_disconnected"));
+      else resolve();
+    };
+    const fail = () => { failure ??= new CliError("SSH tunnel disconnected. Reconnect explicitly; an existing SSH connection cannot be resumed.", undefined, undefined, "tunnel_disconnected"); stream.destroy(); finish(); };
+    stream.on("error", fail);
+    input.on("error", fail);
+    output.on("error", fail);
+    ws.on("unexpected-response", (_req, response) => {
+      failure = new CliError(`SSH tunnel refused (HTTP ${response.statusCode}).`, undefined, response.statusCode, "tunnel_refused");
+      response.resume();
+      ws.terminate();
+    });
+    ws.on("error", fail);
+    ws.on("close", code => {
+      closedCode = code;
+      input.unpipe(stream); input.pause();
+      if (code !== 1000 || failure) { stream.destroy(); finish(); }
+    });
+    // A close frame can arrive while the consumer is backpressured. Drain all
+    // buffered SSH bytes and the last output write before resolving.
+    stream.on("end", () => output.write(Buffer.alloc(0), error => { if (error) fail(); else finish(); }));
+    stream.pipe(output, { end: false });
+    input.pipe(stream);
+  });
+}

package/src/mcp.mjs

@@ -10,6 +10,8 @@ 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";
+import { MAC_TOOLS } from "./mac-tools.mjs";
 
 const PROTOCOL_FALLBACK = "2025-06-18";
 
@@ -26,6 +28,55 @@ async function resolveProjectId(args) {
 }
 
 export const TOOLS = [
+  ...MAC_TOOLS,
+  {
+    name: "check_project", description: "Free source-readiness check of the latest uploaded snapshot. No Apple credentials or paid compute. Run push_project first or after code changes; this does not prove compilation or TestFlight delivery.",
+    inputSchema: { type: "object", properties: { project_id: { type: "string" } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/check-project", { body: { project_id: await resolveProjectId(args) } })),
+  },
+  {
+    name: "get_billing_status", description: "Read confirmed payment, contracted prices, quota/reset, renewal and first-purchase refund eligibility. After payment, resume a blocked build once with a fresh request_key only if the earlier response said build_started:false. Reconcile unknown outcomes first.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => text(await api("GET", "/api/v1/billing/status")),
+  },
+  {
+    name: "get_checkout_link", description: "Return an org-bound checkout link; the human chooses a plan and pays explicitly. This tool does not charge them. Reuses pending checkout; existing subscribers get billing management instead.",
+    inputSchema: { type: "object", properties: { plan: { type: "string", enum: ["starter", "pro"] } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/billing/checkout", { body: args })),
+  },
+  {
+    name: "request_refund", description: "Preview the first-purchase refund amount and subscription cancellation. Default confirm:false. Present the quote and effect to the customer; only after explicit authorization for both actions call with confirm:true and its request_id. A build failure alone does not authorize a refund. Reason is optional.",
+    inputSchema: { type: "object", properties: { confirm: { type: "boolean", default: false }, request_id: { type: "string" }, reason: { type: "string", maxLength: 1000 } }, additionalProperties: false },
+    handler: async args => text(await api("POST", "/api/v1/billing/refund", { body: args })),
+  },
+  {
+    name: "get_refund_status", description: "Read the saved refund and cancellation progress. Does not submit a refund or cancel anything.",
+    inputSchema: { type: "object", properties: { request_id: { type: "string" } }, required: ["request_id"], additionalProperties: false },
+    handler: async args => text(await api("GET", `/api/v1/billing/refund?request_id=${encodeURIComponent(args.request_id)}`)),
+  },
+  {
+    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:
@@ -90,6 +141,7 @@ export const TOOLS = [
       properties: {
         project_id: { type: "string" },
         workflow: { type: "string", enum: ["release", "smoke"], default: "release" },
+        request_key: { type: "string", description: "Reuse this key to reconcile an unknown response. Use a fresh key after a confirmed build_started:false and payment/setup completion." },
       },
       additionalProperties: false,
     },
@@ -97,7 +149,7 @@ export const TOOLS = [
       const project_id = await resolveProjectId(args);
       const res = await api("POST", "/api/v1/builds", {
         body: { project_id, workflow: args?.workflow ?? "release" },
-        idempotencyKey: `mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+        idempotencyKey: args?.request_key ?? `mcp-${randomUUID()}`,
       });
       let warning;
       try {
@@ -376,7 +428,7 @@ export async function runMcpServer() {
             reply(await tool.handler(params?.arguments ?? {}));
           } catch (err) {
             reply({
-              content: [{ type: "text", text: err?.friendly ?? err?.message ?? String(err) }],
+              content: [{ type: "text", text: err?.details ? JSON.stringify({ error: { ...err.details, message: err.friendly ?? err.message } }, null, 2) : err?.friendly ?? err?.message ?? String(err) }],
               isError: true,
             });
           }