shotops-mcp 0.7.0 → 0.8.0

package/README.md

@@ -11,20 +11,43 @@ reusable **looks** and editable **projects**, so the next release matches the la
 Built for agents (ChatGPT / Claude Code / Cursor / CI). It runs over the same `@engine` render
 spine the Studio web app and the `mockup-mcp` CLI use, driving headless Chromium (Playwright).
 
-Ships as **two tiers, one engine**: a free `npx shotops-mcp` **local stdio server** that
-renders on your own machine with no account (see [Local (free tier)](#local-free-tier---npx-shotops-mcp)
-below), and a **hosted** server on Vercel with an account, saved looks, and share links (see
-[Hosted](#hosted) below, or the public
-[`/connect`](https://shotops.dev/connect) page in the studio app).
+Ships as **two doors, one engine**: an `npx shotops-mcp` **local stdio server** that renders on
+your own machine, no account needed to preview (see [Local](#local--npx-shotops-mcp) below), and a
+**hosted** server on Vercel with an account, saved looks, and share links (see [Hosted](#hosted)
+below, or the public [`/connect`](https://shotops.dev/connect) page in the studio app).
+
+## Preview free, export store-ready with Pro
+
+Composing and previewing a strip is free through either door — every device, caption and locale, no
+watermark, and locally without an account at all. **Store-ready output needs an active trial or
+Pro:** a full-resolution `render_strip`/`render_project`, and every `emit_bundle` form, including
+one that only re-zips panels you already rendered. That holds wherever the render happens; local
+compute being free is not the same as local output being free.
+
+The two limits are independent and neither substitutes for the other:
+
+- **Entitlement** is permission to create store-ready files. One server-owned decision answers it
+  for Studio, hosted and local alike, so no door can be talked into a different answer. Free and
+  anonymous callers are refused before a credit is reserved, a screenshot is read or a file is
+  written — a refused call costs nothing and leaves nothing behind.
+- **Credits** price compute ShotOps supplies: 0.5 per hosted preview panel, 2 per hosted
+  full-resolution panel, plus AI. Rendering on your own machine spends none, on any plan. More
+  credits never unlock store-ready output on Free.
+
+Free accounts get 40 credits a month and 2 synced projects. Every new account starts with a 7-day
+Pro trial; after that Pro is €9/month or €90/year. Without any account, the hosted server allows 3
+preview strips per rolling 30 days, at most 5 panels each. Call `account_status` to see exactly
+where this connection stands — it spends no credits and none of that anonymous allowance.
 
 ## Zero-custody
 
-This server **never touches a store-signing credential.** There is no tool input, env var,
-or code path that accepts, stores, or forwards one. `emit_bundle` hands you a zip; **you**
-upload it with **your own** `fastlane`, signed in as yourself. The generated `Deliverfile`
-is screenshots-only and **never submits for review**. The only secrets this process holds
-are Supabase service credentials (to resolve your API token, read your saved look, and back
-share links) — nothing that could reach a store on your behalf.
+The hosted server and every MCP tool **never touch a store-signing credential.** `emit_bundle`
+hands you a zip; **you** upload it with **your own** `fastlane`, signed in as yourself. The
+generated `Deliverfile` is screenshots-only and **never submits for review**.
+
+The one explicit exception is the local `release setup` CLI below. It validates an existing `.p8`
+on your machine directly with Fastlane and Apple, then stores only its path and public identifiers.
+The key is never copied, printed, or sent to ShotOps, and no release tool is installed or upgraded.
 
 ## Tools
 
@@ -36,12 +59,15 @@ share links) — nothing that could reach a store on your behalf.
 | `read_look` | Return a project's saved ShotOps look (styling only), with its latest version, the held version, the `versions` history, and the `layout` template it is composed on (derived from its values, never stored) | `project?` (default: your most recently edited project) |
 | `read_project` | Return a project's FULL current state as an opaque `ProjectFile` — frame order, per-locale caption words, locale list, styling — plus the derived `layout` and a `screenshots.cells` report for every shot × target-family × locale. Each cell says whether pixels resolve, where they resolved from, and which axes inherited | `project?` (default: your most recently edited project) |
 | `render_project` | Render a SAVED project. By default it renders the screenshots **the project already holds** — pass none at all, no upload needed — into **every supported device the project targets**. Pixels resolve independently for each device family + locale through the shared manifest; genuine fallback is reported in `shots[].inherited` and `note` | `project?`, `screenshots?` (**optional** — omit to use what the project holds; else a FLAT list matched by original `name`, with optional `variant: { family?, locale? }` per cell), `outputs?` (override the project's saved devices for this call), `locale?`, `preview?`, `output?` |
+| `refine_project` | Run one bounded Agent turn against a saved project. A supported request commits once and returns the actual diff; ambiguity, missing input, unsupported intent, conflict, and failure return a typed no-write outcome | `project?`, `instruction`, `focus?` |
 | `save_look` | Persist a composed look on a project (styling only — appends a new version) | `look`, `project?`, `sourceName?` |
 | `hold_look` | Hold which saved version agents render by default (replaces pinning) — the version must exist (`read_look` `versions`) | `version`, `project?` |
 | `release_look` | Clear the held version — agents Follow latest (render the newest saved look) | `project?` |
 | `describe_look` | Five named design presets, two named layout templates, the user-intake script, and the full styling field catalog + defaults | *(none)* |
 | `request_screenshot_upload` | Mint signed upload slots for real screenshots; every returned slot carries its semantic screenshot `variant` | `count` (1–10), `names?`, `family?`, `locale?` |
 | `import_screenshot` | Get screenshots INTO ShotOps — several per call, each from one named source (`{ url }`, `{ file }`, or local-stdio `{ path }`), returning a render-ready ref per entry in input order | `screenshots` (1–10 source entries), `file?` (the ChatGPT top-level attachment), `name?`, `locale?` |
+| `account_status` | What THIS connection may do, for free: signed-in account, plan, trial, remaining ShotOps credits, what a preview costs here, and whether store-ready output (full-resolution renders, any `emit_bundle`) is allowed — with a machine-readable `nextStep`. Spends no credits, uses none of the free anonymous preview allowance, uploads and writes nothing | *(none)* |
+| `production_operation` | Reconnect to one durable paid Hosted render or rendering bundle, report persisted progress, request cooperative cancellation, or mint fresh result download grants without rerendering or charging again | `action` (`get`, `cancel`, or `result`), `operationId` |
 | `delete_assets` | Permanently delete private uploaded screenshots, rendered panels, or generated bundles owned by the signed-in account | `refs` (1–50 ShotOps refs) |
 
 - **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1290×2796), `r65`, `r55`.
@@ -50,7 +76,9 @@ share links) — nothing that could reach a store on your behalf.
   accepted set is `RENDERABLE_PANEL_PRESET_IDS` in `shotops-mcp/src/panelCatalog.ts`, a subset of
   the hand-kept `PANEL_PRESET_IDS` copy of `mockup-engine/appstore.ts`'s `PANEL_PRESETS` — when
   Apple revises required sizes, add the preset in the engine first, then mirror it here.
-- **`style`** — the structured styling input (call `describe_look` for the full catalog):
+- **`style`** — the structured styling input. On both the hosted MCP and the local
+  `npx shotops-mcp` stdio server, call `describe_look` for the authoritative complete field
+  catalog and defaults:
   `{ layout?, shotLook?, background?, captions? }`. `shotLook` is **one device for every phone**;
   `captions` is one entry PER PANEL in slot order — each entry is EITHER a single caption object OR
   an **array of caption layers** stacked on that panel (headline + subline + …). Each layer's
@@ -93,10 +121,10 @@ share links) — nothing that could reach a store on your behalf.
   background, `style.captions` supplies the words, in one render. (Alone, `style` styles every
   phone identically. If you pass `style.shotLook`/`style.background` *alongside* a `look`, the look
   wins and the result carries a note.) Also composes with `useSavedLook`/`version`.
-- **`clip`** — `"strip"` (default) renders one continuous canvas, so a wide/offset device can
-  straddle the seam into the next panel (swipe-through scenes). `"panel"` clips each phone to its
-  own panel so it can't bleed a foreign edge into the neighbouring App Store screenshot. A render
-  option, not part of the saved look.
+- **Clipping** — set `look.shots[].look.clipToFrame: true` to clip one device's complete composite
+  (body, screen, shadow, and reflection) to its own panel; omit it or use `false` for overflow.
+  Pass top-level `clip: "panel"` to clip every device, or `clip: "strip"` to force continuous
+  overflow. Call `describe_look` for the complete Look contract on either MCP tier.
 - **`version`** — render a specific saved look version (implies the saved look). Without it,
   a project with a PINNED version renders the pin; otherwise the latest saved look.
 - **`emit_bundle` output** — a zip (`README.md`, `fastlane/Deliverfile`,
@@ -256,7 +284,7 @@ screenshot unavailable; public privacy disclosures must accurately state this re
 ## Prerequisites
 
 1. **A ShotOps API token.** Sign in at the Studio app → account menu → **API tokens** →
-   create one. It looks like `shotops_9Zq3Xr7Tp0Vn6Lk2Wd8Yb4Mf1Hc5Ju3Rs9Ea7Gt0Nz1` and is
+   create one. It looks like `shotops_9Zq3Xr7T…` and is
    shown once — copy it then.
 2. **Supabase service env** (already in the repo's `.env.local` for local dev): `SUPABASE_URL`
    and `SUPABASE_SERVICE_ROLE_KEY`. The server loads `../.env.local` automatically.
@@ -294,7 +322,7 @@ tests without private fixture data or third-party hosting.
 
 ```bash
 claude mcp add --transport http shotops http://localhost:8788/mcp \
-  --header "Authorization: Bearer shotops_9Zq3Xr7Tp0Vn6Lk2Wd8Yb4Mf1Hc5Ju3Rs9Ea7Gt0Nz1"
+  --header "Authorization: Bearer shotops_…"
 ```
 
 Then ask the agent to, e.g., *"render these two screenshots into a 6.9″ App Store strip and
@@ -322,14 +350,14 @@ fastlane deliver        # signs in as YOU, previews, uploads screenshots to a dr
 The server also runs hosted, 24/7-reachable (scale-to-zero when idle), at:
 
 ```
-https://shotops.dev/mcp
+https://mcp.shotops.dev/mcp
 ```
 
 Nothing to install — point any MCP client at that URL with your `Authorization: Bearer
 shotops_…` header, same as local dev, just swap the base URL:
 
 ```bash
-claude mcp add --transport http shotops https://shotops.dev/mcp \
+claude mcp add --transport http shotops https://mcp.shotops.dev/mcp \
   --header "Authorization: Bearer shotops_…"
 ```
 
@@ -351,7 +379,7 @@ since this repo is private.
 - **Verify after any deploy** — a green `flyctl deploy` isn't proof the server answers MCP
   calls:
   ```bash
-  node verify-mcp.mjs https://shotops.dev/mcp <a-real-shotops_-token>
+  node verify-mcp.mjs https://mcp.shotops.dev/mcp <a-real-shotops_-token>
   ```
   Exercises `tools/list`, `read_look`, `emit_bundle` (asserts the zip unzips to
   README/Deliverfile/screenshots), and asserts no-token / bad-token both get `401`.
@@ -382,12 +410,12 @@ since this repo is private.
   can take 60-110s before the CPU fix, and network/Supabase round trips add more on `urls`
   output.
 
-## Local (free tier) — `npx shotops-mcp`
+## Local — `npx shotops-mcp`
 
 The SAME server also runs as a **local stdio MCP**, entirely on your own machine — no URL, no
-account, no hosted cost, and no render-timeout ceiling (the hosted server's one real limit — see
-"Ops" above). It's the same `registerTools`/render engine as the hosted server; only the
-transport and a few account-shaped tools differ.
+hosted cost, and no render-timeout ceiling (the hosted server's one real limit — see "Ops" above).
+Previewing needs no account. It's the same `registerTools`/render engine as the hosted server; only
+the transport and a few account-shaped tools differ.
 
 ```bash
 claude mcp add shotops -- npx -y shotops-mcp
@@ -410,14 +438,19 @@ instead of `{ ref }`/`{ url }`:
 (`{ "path": ... }` only works over this LOCAL server — the hosted server rejects it, since
 reading an arbitrary server-side path there would be a local-file-inclusion hole.)
 
-**`emit_bundle` reads local panels off disk too** — the free tier has no account, so it can't
-produce `output: "urls"` refs. After rendering, pass the on-disk PNGs straight to `emit_bundle`
-(same local-only `{ path }` door as screenshots) to package a `fastlane deliver` zip with no upload:
+**`emit_bundle` reads local panels off disk too** — an unsigned local server has no account, so it
+can't produce `output: "urls"` refs. Once you are signed in on a trial or Pro, pass the on-disk PNGs
+straight to `emit_bundle` (same local-only `{ path }` door as screenshots) to package a
+`fastlane deliver` zip with no upload and no credits:
 
 ```json
 { "bundleId": "com.acme.app", "panels": [{ "path": "/abs/panel-01.png" }, { "path": "/abs/panel-02.png" }] }
 ```
 
+`emit_bundle` and full-resolution renders are the store-ready half of the offer, so they need that
+trial or Pro even here, where the compute is yours. Preview renders need neither an account nor
+credits. `account_status` reports which side of the line this process is on.
+
 **Saving without a token:** a new `save_project` made from local `{ path }` PNGs creates a private
 **pending claim**. It uploads only that saved project's byte-free record and raw source PNGs,
 returns `status: "pending_claim"` plus `claimId` and `openUrl`, and deliberately returns no
@@ -425,22 +458,26 @@ returns `status: "pending_claim"` plus `claimId` and `openUrl`, and deliberately
 with its screenshots, and the link expires after 7 days. An existing `project` cannot be updated
 without the token that owns it. Non-path inputs are refused rather than creating a blank claim.
 
-Ordinary `render_strip` / `emit_bundle` calls still upload **nothing** and work fully. Other
+Ordinary `render_strip` / `emit_bundle` calls still upload **nothing** — pixels and zips are written
+straight to your disk, and no screenshot leaves the machine. Other
 account reads/writes (`read_look`, `save_look`, `read_project`, `render_project`, share links)
 still need a token or hosted connection. A token-backed local `render_project` reads the cloud
 manifest through the Studio control plane, downloads only the resolved cells, and renders locally:
 
-| | Local (free, `npx shotops-mcp`) | Hosted (`shotops_…` token) |
+| | Local (`npx shotops-mcp`) | Hosted (`shotops_…` token) |
 |---|---|---|
-| Render compute | **your machine** ($0, no timeout) | our servers — spends your ShotOps credits: 1,000 per preview panel, 4,000 per full-resolution panel |
-| Auth | none (the process runs as you) | account + API token |
+| Render compute | **your machine** ($0, no timeout, no credits on any plan) | our servers — spends your ShotOps credits: 0.5 per preview panel, 2 per full-resolution panel |
+| Preview render | free, no account | free on an account; 3 per 30 days, ≤5 panels, without one |
+| Full-resolution render, any `emit_bundle` | trial or Pro (costs no credits) | trial or Pro, and spends credits |
+| Auth | none to preview; a token for account state and store-ready output | account + API token |
 | Saved looks / editable projects / project read+re-render / share links | new project: pending claim; existing/account state: token (below); share links: hosted | ✅ |
 | Screenshot input | local `{ path }` off disk | `request_screenshot_upload` → `{ ref }` |
 
 ### Optional: bridge a local render into your hosted account
 
 Connect your account and `save_project` / `read_look` / `save_look` / `read_project` /
-`render_project` start working too — **rendering still happens locally and for free.** A
+`render_project` start working too — **rendering still happens locally and spends no credits**, and
+a trial or Pro account unlocks full-resolution output and `emit_bundle` on this machine. A
 deliberate save also uploads its local source PNGs privately so the project reopens with
 screenshots on another device; normal renders and exports never upload.
 
@@ -466,6 +503,115 @@ SHOTOPS_TOKEN=shotops_… claude mcp add shotops -- npx -y shotops-mcp
 `--token` wins over `SHOTOPS_TOKEN`, which wins over a saved browser login — so a token in the
 environment is never quietly shadowed by whoever last signed in on that machine.
 
+### Local Apple release setup
+
+Before preparing an App Store release, validate the Apple tooling and API key already on this
+machine:
+
+```bash
+npx shotops-mcp release setup
+# non-interactive form:
+npx shotops-mcp release setup \
+  --issuer-id "$APP_STORE_CONNECT_ISSUER_ID" \
+  --key-id "$APP_STORE_CONNECT_KEY_ID" \
+  --key-path /secure/AuthKey_ABC123DEFG.p8
+```
+
+The command requires an owner-only `.p8`, Fastlane, and Apple Transporter; parses the key through
+Fastlane; and makes read-only App Store Connect app-list requests to prove the key's real access.
+It does not install or upgrade anything. Only Issuer ID, Key ID, and the canonical key path are
+saved in `~/.shotops/release.json` (or `$SHOTOPS_CONFIG_DIR/release.json`); a failed rerun leaves the
+last valid setup untouched.
+
+For CI, create secret inputs named `APP_STORE_CONNECT_ISSUER_ID`,
+`APP_STORE_CONNECT_KEY_ID`, and `APP_STORE_CONNECT_PRIVATE_KEY`. The setup command names these
+inputs but never prints their values.
+
+### Prepare a deterministic desired release
+
+Once signed in to ShotOps, assemble the saved owner project and repository into one local,
+content-addressed workspace — before reading or changing App Store Connect:
+
+```bash
+npx shotops-mcp release prepare --project "My project"
+
+# Optional signed build and an explicit partial scope:
+npx shotops-mcp release prepare \
+  --project proj_123 \
+  --build build/MyApp.ipa \
+  --locales en-US,de-DE \
+  --outputs iphone-6-9
+```
+
+The command renders every authored locale and selected output by default with the same engine as
+Studio and the MCP. `--locales` or `--outputs` deliberately narrows the run and records every
+omission as a **partial** scope. It writes `desired-release.json` plus the rendered PNGs under
+`~/.shotops/release-workspaces/<desired-id>/` (or `--output <directory>`), with user-only
+permissions. Identical project, repository, scope, and build inputs produce the same manifest ID
+and pixels.
+
+Repository input conventions are explicit so no Ruby is ever evaluated:
+
+- `fastlane/metadata/<locale>/*.txt` — supported localized Deliver metadata;
+- `fastlane/metadata/*.txt` and `review_information/*.txt` — app and review metadata;
+- `fastlane/metadata/app_store_rating_config.json` — Fastlane's current age-rating shape;
+- `fastlane/metadata/submission_information.json` — export/content compliance fields;
+- `fastlane/metadata/app_review_attachment_file.txt` — empty clears the attachment; otherwise it
+  names a repository-relative supported attachment;
+- `fastlane/app-previews/<locale>/*` — `.mov`, `.mp4`, or `.m4v`, with the ASC device token in
+  each filename (for example `APP_IPHONE_67_01_demo.mp4`).
+
+Missing files mean **unchanged**; an existing supported empty text file means **clear**. Unknown
+files, fields, locales, outputs, unreadable artifacts, and Bundle ID disagreements fail closed.
+Fastfile and Deliverfile are never executed. Optional `.ipa`/supported `.pkg` bytes are hashed and
+referenced, never copied into ShotOps state. This step performs no ASC request, upload, version
+creation, signing, submission, or release.
+
+### Create the exact App Store Connect plan
+
+Read the editable App Store version and bind it to the prepared workspace without changing Apple:
+
+```bash
+npx shotops-mcp release plan \
+  --workspace ~/.shotops/release-workspaces/<desired-id> \
+  --repo .
+```
+
+The command resolves the Bundle ID to one accessible app and one editable iOS version, then reads
+the supported metadata, review, age-rating, compliance, build, screenshot, and App Preview
+baseline. It writes a user-only `release-plan.json` containing every create, update, clear,
+replacement, upload, attachment, and no-op, plus a portable `release-review.zip` containing that
+exact canonical plan and its content-addressed screenshot bytes. The plan expires after 15 minutes
+and hash-binds the project revision, desired bytes, normalized Fastlane inputs, Apple setup identity,
+policy version, and the complete remote snapshot so later approval cannot drift onto different state.
+
+`release-plan-envelope.json` is the separate redacted form safe for a later ShotOps coordination
+step: it carries identifiers and value hashes, never metadata values, review credentials, local
+paths, Apple credentials, or asset bytes. This command talks directly to Apple with GET requests
+only; it never uploads, creates a version, commits, submits, or sends the private key to ShotOps.
+
+### Review the exact plan locally
+
+From the plan directory, open its read-only local browser review:
+
+```bash
+npx shotops-mcp release review
+```
+
+To review an artifact downloaded from owner-controlled CI, pass it directly:
+
+```bash
+npx shotops-mcp release review release-review.zip
+```
+
+The command verifies the unexpired exact plan hash, artifact manifest, and every embedded screenshot
+before opening a nonce-protected URL on `127.0.0.1` with a random port. The page shows target app and
+team fingerprint, Bundle ID, version, expiry, complete or partial scope, every before/after/clear,
+build, review, rating, compliance, preview, screenshot order/replacement/omission, no-op, and the
+operations excluded by the plan. Partial-scope and no-build warnings cannot be dismissed. It loads
+no remote resource, sends nothing, and has no edit or approval action; expired, corrupt, edited, or
+content-mismatched inputs fail before a server is started.
+
 The saved project remembers the exact on-disk folder your screenshots came from (not just their
 filenames), so re-opening it on the SAME machine can point right back at it. Share links aren't
 bridged yet — they'd need a hosted rendering step, which would defeat local rendering's whole
@@ -496,7 +642,7 @@ shotops-mcp/
     uploads.ts      Phase 10 — upload slots, ref ownership check, output:'urls' storage
     screenshotInput.ts  Phase 10 — resolves screenshots[] (inline/ref/url/path) to base64
     env.ts          loads ../.env.local; MCP_PORT / STUDIO_ORIGIN / MCP_PUBLIC_URL
-    local.ts        the LOCAL (free tier) npx entry point — stdio transport, no auth
+    local.ts        the LOCAL npx entry point — stdio transport, no auth required to preview
     localDeps.ts     the local ToolDeps fork — static-serve renderer, no-op/bridged persistence
     hostedBridge.ts  local→hosted bridge (a real MCP client using your shotops_ token)
   harness/          the browser render page Chromium loads (render.js exposes window.renderStrip)

package/THIRD_PARTY_NOTICES

@@ -71,6 +71,7 @@ Space Grotesk
 Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
 
 Each font is licensed under the SIL Open Font License, Version 1.1:
+https://openfontlicense.org/open-font-license-official-text/
 
 -----------------------------------------------------------
 SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007