@nomac/cli 0.1.0

package/bin/nomac.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err?.friendly ?? err?.message ?? String(err));
+  process.exit(err?.exitCode ?? 1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nomac/cli",
+  "version": "0.1.0",
+  "description": "Ship iOS apps to TestFlight and the App Store without a Mac — built for agents.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "nomac": "./bin/nomac.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ignore": "^7.0.0",
+    "tar": "^7.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: nomac
+description: >
+  Ship iOS apps to TestFlight and the App Store without a Mac. Use when the
+  user asks to build, test on a phone, publish, or submit an iOS app for
+  review — or mentions TestFlight, App Store Connect, signing, provisioning,
+  screenshots/metadata for the App Store, or app review rejections. Works from
+  any directory containing an Xcode project (SwiftUI vibe-code exports
+  included).
+---
+
+# 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 —
+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 whoami`. If not logged in, ask the human for an API
+   key from nomac.app → API keys, then `npx nomac login <nmk_…>` and
+   `claude mcp add nomac -- npx nomac 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.
+
+## Ship to TestFlight
+
+```
+push_project                    # after every code change
+build workflow=release         # ~3 min; smoke = fast compile-only check
+status                         # poll ~30s until ready | failed
+```
+
+- `ready` → tell the human: "open TestFlight on your phone." Their taps are
+  the test run; read `get_feedback` for crashes/comments afterwards.
+- `failed` → `get_failure`: kind=project means you fix source and re-push;
+  kind=account means relay the link to the human. Don't burn release builds
+  debugging compile errors — use `build workflow=smoke`.
+
+## Submit for App Store review
+
+1. `review_lint` → fix every red. Apply returned patches (e.g. generated
+   `PrivacyInfo.xcprivacy`) directly to the source. Yellow "signals"
+   (4.3 distinctiveness, thin listing) are yours to judge and improve.
+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.
+
+## When stuck
+
+`report_issue` with the failing `ref_id` files a support ticket with full
+context auto-attached (deduped, so safe to call). Read replies with the same
+tool. Never retry-loop an identical failure more than twice.

package/src/api.mjs

@@ -0,0 +1,66 @@
+import { loadApiKey, loadApiUrl } from "./config.mjs";
+
+export class CliError extends Error {
+  constructor(message, friendly) {
+    super(message);
+    this.friendly = friendly ?? message;
+    this.exitCode = 1;
+  }
+}
+
+/** Unauthenticated request — for the device-login endpoints, which take no key. */
+export async function apiPublic(method, path, body) {
+  const url = `${loadApiUrl()}${path}`;
+  const res = await fetch(url, {
+    method,
+    headers: body !== undefined ? { "content-type": "application/json" } : {},
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
+  }
+  return { status: res.status, ok: res.ok, json };
+}
+
+export async function api(method, path, { body, raw, idempotencyKey } = {}) {
+  const key = loadApiKey();
+  if (!key) {
+    throw new CliError(
+      "not logged in",
+      "Not logged in. Run `nomac login <api-key>` (create a key in the dashboard) or set NOMAC_API_KEY.",
+    );
+  }
+  const url = `${loadApiUrl()}${path}`;
+  const res = await fetch(url, {
+    method,
+    headers: {
+      authorization: `Bearer ${key}`,
+      ...(raw
+        ? { "content-type": "application/gzip" }
+        : body !== undefined
+          ? { "content-type": "application/json" }
+          : {}),
+      ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+    },
+    body: raw ?? (body !== undefined ? JSON.stringify(body) : undefined),
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    throw new CliError(`API returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`);
+  }
+  if (!res.ok) {
+    const err = json?.error ?? {};
+    throw new CliError(
+      `HTTP ${res.status} ${err.code ?? ""}`,
+      err.message ?? `API error (HTTP ${res.status})`,
+    );
+  }
+  return json;
+}

package/src/cli.mjs

@@ -0,0 +1,172 @@
+import { basename } from "node:path";
+import { api, CliError } from "./api.mjs";
+import { loadProjectState, saveApiKey, saveProjectState } from "./config.mjs";
+import { packTarball } from "./pack.mjs";
+
+const HELP = `nomac — ship iOS apps without a Mac (agent-first)
+
+Usage:
+  nomac login                  connect this device (approve in the browser)
+  nomac login <api-key>        store an nmk_ key directly (CI / power users)
+  nomac push                   pack this directory and upload a snapshot
+  nomac build [--smoke]        start a release (or smoke) build
+  nomac build --testflight     release build; waits until TestFlight-ready
+  nomac status [build-id]      show latest (or given) build status
+  nomac logs <build-id>        show build logs
+  nomac mcp                    run the stdio MCP server (for agents)
+  nomac whoami                 show org + usage
+
+Environment: NOMAC_API_KEY, NOMAC_API_URL`;
+
+export async function main(argv) {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case "login": {
+      const key = rest[0];
+      if (key) {
+        // direct-key path for CI / power users
+        if (!key.startsWith("nmk_")) {
+          throw new CliError("bad key", "Usage: nomac login nmk_…  (or just `nomac login` to approve in the browser)");
+        }
+        saveApiKey(key);
+        const me = await api("GET", "/api/v1/me");
+        console.log(`✅ logged in — org "${me.org.name}" (${me.org.id})`);
+        return;
+      }
+      const { deviceLogin } = await import("./login.mjs");
+      return deviceLogin();
+    }
+    case "push":
+      return push();
+    case "build":
+      return build(rest);
+    case "status":
+      return status(rest[0]);
+    case "logs":
+      return logs(rest[0]);
+    case "mcp": {
+      const { runMcpServer } = await import("./mcp.mjs");
+      return runMcpServer();
+    }
+    case "whoami": {
+      const me = await api("GET", "/api/v1/me");
+      console.log(JSON.stringify(me, null, 2));
+      return;
+    }
+    case undefined:
+    case "help":
+    case "--help":
+      console.log(HELP);
+      return;
+    default:
+      throw new CliError(`unknown command: ${cmd}`, `Unknown command "${cmd}".\n\n${HELP}`);
+  }
+}
+
+async function ensureProject() {
+  const state = loadProjectState();
+  if (state.project_id) return state;
+  const name = basename(process.cwd());
+  const created = await api("POST", "/api/v1/projects", { body: { name } });
+  const next = { project_id: created.id, name };
+  saveProjectState(next);
+  console.log(`created project ${created.id} ("${name}")`);
+  return next;
+}
+
+async function push() {
+  const state = await ensureProject();
+  console.log("packing working tree (respecting .gitignore, secrets excluded)…");
+  const { tarball, files } = await packTarball(process.cwd());
+  console.log(`${files.length} files, ${(tarball.length / 1024).toFixed(0)} KB compressed`);
+  const res = await api("POST", `/api/v1/projects/${state.project_id}/snapshots`, {
+    raw: tarball,
+  });
+  console.log(`✅ snapshot ${res.snapshot_id} (commit ${res.commit.slice(0, 8)})`);
+  const d = res.detected ?? {};
+  console.log(
+    `   detected: ${d.xcodeproj ?? "?"} · scheme ${d.scheme ?? "?"} · ${d.bundle_id ?? "no bundle id"}${d.marketing_version ? ` · v${d.marketing_version}` : ""}`,
+  );
+  if (res.warning) console.log(`⚠  ${res.warning}`);
+  saveProjectState({ ...state, last_snapshot: res.snapshot_id });
+}
+
+async function build(rest) {
+  const state = loadProjectState();
+  if (!state.project_id) {
+    throw new CliError("no project", "No project here — run `nomac push` first.");
+  }
+  const smoke = rest.includes("--smoke");
+  const wait = rest.includes("--testflight") || rest.includes("--wait");
+  const res = await api("POST", "/api/v1/builds", {
+    body: { project_id: state.project_id, workflow: smoke ? "smoke" : "release" },
+    idempotencyKey: `cli-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  });
+  console.log(`✅ build ${res.id} started (${res.workflow}, #${res.build_number})`);
+  saveProjectState({ ...state, last_build: res.id });
+  if (!wait) {
+    console.log(`   follow with: nomac status ${res.id}`);
+    return;
+  }
+  await waitForBuild(res.id);
+}
+
+const SPINNER_STATES = {
+  queued: "queued",
+  mirrored: "mirrored",
+  dispatched: "runner starting",
+  building: "building on macOS",
+  uploading: "uploading to Apple",
+  processing: "Apple is processing",
+};
+
+async function waitForBuild(id) {
+  const started = Date.now();
+  let last = "";
+  for (;;) {
+    const b = await api("GET", `/api/v1/builds/${id}`);
+    if (b.state !== last) {
+      const t = Math.round((Date.now() - started) / 1000);
+      console.log(`   [${t}s] ${SPINNER_STATES[b.state] ?? b.state}`);
+      last = b.state;
+    }
+    if (b.state === "ready") {
+      console.log(
+        b.workflow === "smoke"
+          ? "\n🎉 smoke build passed — the project compiles clean on macOS."
+          : "\n🎉 build ready — open TestFlight on your phone, the new build is live.",
+      );
+      return;
+    }
+    if (b.state === "failed") {
+      const err = b.error ?? {};
+      console.log(`\n❌ build failed (${err.code ?? "unknown"})`);
+      if (err.raw) console.log(`   ${err.raw}`);
+      console.log(`   details: nomac logs ${id}`);
+      const e = new CliError("build failed", "");
+      e.friendly = "";
+      throw e;
+    }
+    await new Promise((r) => setTimeout(r, 10_000));
+  }
+}
+
+async function status(buildId) {
+  const state = loadProjectState();
+  const id = buildId ?? state.last_build;
+  if (!id) throw new CliError("no build", "No build id. Usage: nomac status <build-id>");
+  const b = await api("GET", `/api/v1/builds/${id}`);
+  console.log(JSON.stringify(b, null, 2));
+}
+
+async function logs(buildId) {
+  const state = loadProjectState();
+  const id = buildId ?? state.last_build;
+  if (!id) throw new CliError("no build", "No build id. Usage: nomac logs <build-id>");
+  const res = await api("GET", `/api/v1/builds/${id}/logs`);
+  for (const step of res.steps ?? []) {
+    console.log(`\n═══ ${step.name} [${step.status ?? "?"}] ═══`);
+    if (step.log) console.log(step.log);
+  }
+  if (res.excerpt) console.log(`\n═══ failure excerpt ═══\n${res.excerpt}`);
+}

package/src/config.mjs

@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_API_URL =
+  process.env.NOMAC_API_URL ?? "https://www.nomac.app";
+
+const CONFIG_DIR = join(homedir(), ".nomac");
+const CREDENTIALS = join(CONFIG_DIR, "credentials.json");
+
+export function loadApiKey() {
+  if (process.env.NOMAC_API_KEY) return process.env.NOMAC_API_KEY;
+  try {
+    const creds = JSON.parse(readFileSync(CREDENTIALS, "utf8"));
+    return creds.api_key;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveApiKey(apiKey, apiUrl) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(
+    CREDENTIALS,
+    JSON.stringify({ api_key: apiKey, ...(apiUrl ? { api_url: apiUrl } : {}) }, null, 2),
+    { mode: 0o600 },
+  );
+}
+
+export function loadApiUrl() {
+  if (process.env.NOMAC_API_URL) return process.env.NOMAC_API_URL;
+  try {
+    const creds = JSON.parse(readFileSync(CREDENTIALS, "utf8"));
+    if (creds.api_url) return creds.api_url;
+  } catch {
+    // fall through
+  }
+  return DEFAULT_API_URL;
+}
+
+/** Per-project state (project id), stored next to the code. */
+export function loadProjectState(dir = process.cwd()) {
+  const p = join(dir, ".nomac.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveProjectState(state, dir = process.cwd()) {
+  writeFileSync(join(dir, ".nomac.json"), JSON.stringify(state, null, 2) + "\n");
+}

package/src/login.mjs

@@ -0,0 +1,48 @@
+import { hostname } from "node:os";
+import { api, apiPublic, CliError } from "./api.mjs";
+import { saveApiKey } from "./config.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Device-authorization login: no key is ever pasted into the agent. The CLI
+ * gets a short code, the human approves it in the browser, and the CLI polls
+ * until it can claim a freshly-minted API key.
+ */
+export async function deviceLogin() {
+  const start = await apiPublic("POST", "/api/v1/device/start", { client_name: hostname() });
+  if (!start.ok) {
+    throw new CliError("device start failed", start.json?.error?.message ?? "Couldn't start login.");
+  }
+  const { device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in } =
+    start.json;
+
+  console.log(`\n  To connect this device, open:\n`);
+  console.log(`    ${verification_uri_complete || verification_uri}\n`);
+  console.log(`  and confirm this code:  ${user_code}\n`);
+  console.log("  Waiting for approval…");
+
+  const deadline = Date.now() + (expires_in ?? 900) * 1000;
+  const pollMs = Math.max(2, interval ?? 5) * 1000;
+
+  for (;;) {
+    if (Date.now() > deadline) {
+      throw new CliError("expired", "Login timed out. Run `nomac login` again.");
+    }
+    await sleep(pollMs);
+    const r = await apiPublic("POST", "/api/v1/device/token", { device_code });
+    const status = r.json?.status;
+    if (status === "approved" && r.json.api_key) {
+      saveApiKey(r.json.api_key);
+      const me = await api("GET", "/api/v1/me");
+      console.log(`\n✅ connected — org "${me.org.name}" (${me.org.id})`);
+      return;
+    }
+    if (status === "denied") throw new CliError("denied", "Login was denied in the dashboard.");
+    if (status === "expired") throw new CliError("expired", "Login expired. Run `nomac login` again.");
+    if (status === "claimed") {
+      throw new CliError("claimed", "That login was already completed. Run `nomac login` again.");
+    }
+    // "pending" / "slow_down" → keep polling
+  }
+}

package/src/mcp.mjs

@@ -0,0 +1,311 @@
+// nomac mcp — stdio MCP server (JSON-RPC 2.0, newline-delimited).
+// Thin wrappers over the nomac REST API; API-key auth (nomac login / env).
+// Works in every MCP client day one; the hosted transport is mcp.nomac.app.
+
+import { createInterface } from "node:readline";
+import { api } from "./api.mjs";
+import { loadProjectState, saveProjectState } from "./config.mjs";
+import { packTarball } from "./pack.mjs";
+
+const PROTOCOL_FALLBACK = "2025-06-18";
+
+const text = (obj) => ({
+  content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }],
+});
+const errText = (msg) => ({ ...text(msg), isError: true });
+
+async function resolveProjectId(args) {
+  if (args?.project_id) return args.project_id;
+  const state = loadProjectState(args?.directory ?? process.cwd());
+  if (state.project_id) return state.project_id;
+  throw new Error("no project here — run push_project first (or pass project_id)");
+}
+
+export const TOOLS = [
+  {
+    name: "connect_status",
+    description:
+      "Check the org's Apple connection health (API key validity, cert expiry, webhook). Start here if anything store-related fails.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => {
+      const me = await api("GET", "/api/v1/me");
+      const conns = await api("GET", "/api/v1/connections");
+      if (conns.connections.length === 0) {
+        return text({
+          org: me.org,
+          connections: [],
+          next_step:
+            "No Apple connection. The human connects once with an App Store Connect API key (dashboard → Connections, ~60s).",
+        });
+      }
+      const detail = await api("GET", `/api/v1/connections/${conns.connections[0].id}`);
+      return text({ org: me.org, connection: detail });
+    },
+  },
+  {
+    name: "push_project",
+    description:
+      "Pack the project directory (respects .gitignore; secrets never leave the machine) and upload a snapshot. Auto-detects the Xcode project, scheme and bundle id, runs source-level review lint, and links the App Store Connect app record. Run after every code change, before build.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        directory: { type: "string", description: "project directory (default: cwd)" },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const dir = args?.directory ?? process.cwd();
+      let state = loadProjectState(dir);
+      if (!state.project_id) {
+        const name = dir.split("/").filter(Boolean).pop() ?? "app";
+        const created = await api("POST", "/api/v1/projects", { body: { name } });
+        state = { project_id: created.id, name };
+        saveProjectState(state, dir);
+      }
+      const { tarball, files } = await packTarball(dir);
+      const res = await api("POST", `/api/v1/projects/${state.project_id}/snapshots`, {
+        raw: tarball,
+      });
+      saveProjectState({ ...state, last_snapshot: res.snapshot_id }, dir);
+      return text({ project_id: state.project_id, files_packed: files.length, ...res });
+    },
+  },
+  {
+    name: "build",
+    description:
+      "Start a build. workflow=release (signed, uploads to TestFlight; costs one build from the plan quota) or smoke (unsigned compile check, fastest way to verify the project builds on macOS). Returns a build_id — poll with status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string" },
+        workflow: { type: "string", enum: ["release", "smoke"], default: "release" },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      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)}`,
+      });
+      return text({
+        ...res,
+        note: "poll `status` every ~30s; a release build reaching `ready` means the phone can install it from TestFlight",
+      });
+    },
+  },
+  {
+    name: "status",
+    description: "Build status (state machine position). States: queued→mirrored→dispatched→building→uploading→processing→ready|failed.",
+    inputSchema: {
+      type: "object",
+      properties: { build_id: { type: "string", description: "defaults to the last build started here" } },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const id = args?.build_id ?? loadProjectState().last_build;
+      if (!id) return errText("no build_id given and no build started from this directory");
+      return text(await api("GET", `/api/v1/builds/${id}`));
+    },
+  },
+  {
+    name: "get_failure",
+    description:
+      "Structured failure detail for a failed build: {stage, code, kind, error_lines, hints, raw_excerpt}. kind=project → you fix the source and re-push; kind=account → relay the deep link to your human.",
+    inputSchema: {
+      type: "object",
+      properties: { build_id: { type: "string" } },
+      required: ["build_id"],
+      additionalProperties: false,
+    },
+    handler: async (args) => text(await api("GET", `/api/v1/builds/${args.build_id}/failure`)),
+  },
+  {
+    name: "review_lint",
+    description:
+      "Review-readiness report (deterministic checks, graded green/yellow/red). Red findings block publish. Findings carry evidence + fix hints; some include ready-to-apply source patches (e.g. a generated PrivacyInfo.xcprivacy). Signals for fuzzy rules (4.3 distinctiveness) are evidence for YOU to judge.",
+    inputSchema: {
+      type: "object",
+      properties: { project_id: { type: "string" } },
+      additionalProperties: false,
+    },
+    handler: async (args) =>
+      text(await api("POST", "/api/v1/review-lint", { body: { project_id: await resolveProjectId(args) } })),
+  },
+  {
+    name: "get_metadata_schema",
+    description: "Field list, char limits, locales and exact screenshot dimensions for set_metadata / upload_screenshots.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => text(await api("GET", "/api/v1/metadata-schema")),
+  },
+  {
+    name: "get_metadata",
+    description: "Current App Store metadata (app + latest version localizations) from App Store Connect.",
+    inputSchema: {
+      type: "object",
+      properties: { project_id: { type: "string" } },
+      additionalProperties: false,
+    },
+    handler: async (args) =>
+      text(await api("GET", `/api/v1/projects/${await resolveProjectId(args)}/metadata`)),
+  },
+  {
+    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'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string" },
+        locale: { type: "string", default: "en-US" },
+        fields: { type: "object" },
+        primary_category: { type: "string" },
+        age_rating: { type: "object" },
+        content_rights: { type: "string" },
+        copyright: { type: "string" },
+        review_contact: { type: "object" },
+        price: { type: "string", enum: ["FREE"] },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const { project_id: _p, ...rest } = args ?? {};
+      const project_id = await resolveProjectId(args);
+      return text(await api("PUT", `/api/v1/projects/${project_id}/metadata`, { body: rest }));
+    },
+  },
+  {
+    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}].",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string" },
+        display_type: { type: "string" },
+        locale: { type: "string", default: "en-US" },
+        images: { type: "array", items: { type: "object" } },
+      },
+      required: ["display_type", "images"],
+      additionalProperties: false,
+    },
+    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 }));
+    },
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string" },
+        confirm: { type: "boolean", default: false },
+        force: { type: "boolean", default: false, description: "override a red lint gate (not recommended)" },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const project_id = await resolveProjectId(args);
+      return text(
+        await api("POST", "/api/v1/publish", {
+          body: { project_id, confirm: args?.confirm ?? false, force: args?.force ?? false },
+          idempotencyKey: `mcp-pub-${project_id}-${args?.confirm ? "confirm" : "stage"}`,
+        }),
+      );
+    },
+  },
+  {
+    name: "get_feedback",
+    description:
+      "TestFlight crashes + tester feedback (the human-on-a-real-device return channel). Read after the human has tried the build; crashes include device/os and a crash log URL.",
+    inputSchema: {
+      type: "object",
+      properties: { project_id: { type: "string" } },
+      additionalProperties: false,
+    },
+    handler: async (args) =>
+      text(await api("GET", `/api/v1/projects/${await resolveProjectId(args)}/feedback`)),
+  },
+  {
+    name: "report_issue",
+    description:
+      "File an unknown/unfixable error with nomac support. Auto-attaches build error, logs (redacted) and lint state when you pass ref_id (a bld_… id). Deduped by error fingerprint. Read replies by calling with no description.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string", description: "what went wrong + what you tried (≥10 chars). Omit to read existing tickets/replies." },
+        ref_id: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      if (!args?.description) return text(await api("GET", "/api/v1/report-issue"));
+      return text(await api("POST", "/api/v1/report-issue", { body: args }));
+    },
+  },
+];
+
+export async function runMcpServer() {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      return; // ignore garbage
+    }
+    const { id, method, params } = req;
+    const reply = (result) => id !== undefined && send({ jsonrpc: "2.0", id, result });
+    const fail = (code, message) => id !== undefined && send({ jsonrpc: "2.0", id, error: { code, message } });
+
+    try {
+      switch (method) {
+        case "initialize":
+          reply({
+            protocolVersion: params?.protocolVersion ?? PROTOCOL_FALLBACK,
+            capabilities: { tools: {} },
+            serverInfo: { name: "nomac", version: "0.1.0" },
+          });
+          break;
+        case "notifications/initialized":
+        case "initialized":
+          break; // notification, no reply
+        case "ping":
+          reply({});
+          break;
+        case "tools/list":
+          reply({
+            tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+          });
+          break;
+        case "tools/call": {
+          const tool = TOOLS.find((t) => t.name === params?.name);
+          if (!tool) return fail(-32602, `unknown tool: ${params?.name}`);
+          try {
+            reply(await tool.handler(params?.arguments ?? {}));
+          } catch (err) {
+            reply({
+              content: [{ type: "text", text: err?.friendly ?? err?.message ?? String(err) }],
+              isError: true,
+            });
+          }
+          break;
+        }
+        default:
+          if (id !== undefined) fail(-32601, `method not found: ${method}`);
+      }
+    } catch (err) {
+      fail(-32603, err?.message ?? "internal error");
+    }
+  });
+
+  // keep the process alive until stdin closes
+  await new Promise((resolve) => rl.on("close", resolve));
+}

package/src/pack.mjs

@@ -0,0 +1,67 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import ignoreFactory from "ignore";
+import * as tar from "tar";
+
+// Pack the working tree: respect .gitignore, always exclude the deny-list
+// (secrets never leave the machine), gzip in memory.
+
+const ALWAYS_IGNORE = [
+  ".git/",
+  "node_modules/",
+  ".nomac.json",
+  "*.p8",
+  "*.p12",
+  "*.mobileprovision",
+  "*.pem",
+  ".env",
+  ".env.*",
+  ".DS_Store",
+  "build/",
+  "DerivedData/",
+  "*.ipa",
+  "*.xcarchive",
+];
+
+export function collectFiles(dir) {
+  const ig = ignoreFactory().add(ALWAYS_IGNORE);
+  try {
+    ig.add(readFileSync(join(dir, ".gitignore"), "utf8"));
+  } catch {
+    // no .gitignore — fine
+  }
+
+  const files = [];
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      const rel = relative(dir, full);
+      const relForIgnore = entry.isDirectory() ? `${rel}/` : rel;
+      if (ig.ignores(relForIgnore)) continue;
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) files.push(rel);
+    }
+  };
+  walk(dir);
+  return files.sort();
+}
+
+export async function packTarball(dir) {
+  const files = collectFiles(dir);
+  if (files.length === 0) {
+    throw new Error("nothing to pack (is this the right directory?)");
+  }
+  const chunks = [];
+  await new Promise((resolve, reject) => {
+    tar
+      .create({ gzip: true, cwd: dir, portable: true }, files)
+      .on("data", (c) => chunks.push(c))
+      .on("end", resolve)
+      .on("error", reject);
+  });
+  return { tarball: Buffer.concat(chunks), files };
+}
+
+export function totalSize(dir, files) {
+  return files.reduce((n, f) => n + statSync(join(dir, f)).size, 0);
+}