shotops-mcp 0.8.0 → 0.9.0

package/README.md

@@ -63,7 +63,7 @@ The key is never copied, printed, or sent to ShotOps, and no release tool is ins
 | `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)* |
+| `describe_look` | Five named design presets, three 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)* |
@@ -85,15 +85,15 @@ The key is never copied, printed, or sent to ShotOps, and no release tool is ins
   `text` (and a single caption's `subtitle`) is per-RENDER input (never stored — a look carries
   styling only). Captions auto-layout in a band at the top of the panel, and the device does NOT
   move to make room.
-- **`style.layout`** — the panel **composition** in one word: `"standard"` or `"bleed"`. It settles
-  the headline's reserved region *and* the device size + position together, which is three numbers
-  that are not independent of each other. `standard` (the shipped default) puts the whole device
+- **`style.layout`** — the panel **composition** in one word: `"standard"`, `"bleed"`, or
+  `"top-bleed"`. It settles the headline's reserved region, device placement, camera pose, and
+  roll together. `standard` (the shipped default) puts the whole device
   under a 2-line region — about 36 characters — and crops nothing; `bleed` reserves 4 lines (~72
   characters) and runs the device 10% off the bottom edge. The region is **reserved, not fitted**:
   it is held at full size whether or not the headline fills it, which is what makes every panel in
   a swiped set land on the same line. **Precedence** — the template expands *first*, then any
-  `shotLook.phoneHeight`/`hOffset`/`vOffset` or `captions[].sizePt`/`maxWidth` you also pass
-  **overrides** it (`{ layout: "bleed", shotLook: { vOffset: "45" } }` is "bleed, but a bit lower").
+  explicit `shotLook` composition field or caption layout field you also pass **overrides** it
+  (`{ layout: "bleed", shotLook: { vOffset: "45" } }` is "bleed, but a bit lower").
   A pure macro: nothing stores the template id, so `save_project` persists the expanded values and
   `read_look` returns them unchanged. **The id is not lost, though — it is DERIVED back:**
   `read_project` and `read_look` both return a `layout` report read out of the values themselves, so
@@ -236,7 +236,7 @@ own `error` and never cancels the others — re-import just that one. In ChatGPT
 arrives as the top-level `file` parameter instead of an array entry, because the Apps SDK cannot
 fill a file parameter nested inside an array; you can pass both in the same call.
 
-`{ url }` and `{ file }` need the hosted server (it stores the fetched PNG under your account);
+`{ url }` and `{ file }` need the hosted server (it stores the fetched screenshot as PNG under your account);
 `{ path }` needs the local stdio server (the hosted server never reads a caller-supplied
 filesystem path — that would be an LFI hole). Each refusal names the door that IS open on your
 tier. When the screenshots are only on the user's machine and you are on the hosted server, there
@@ -255,19 +255,22 @@ is no URL to give, so use the signed-slot flow below:
 `screenshots` entries accept these shapes: an inline base64 string (small payloads only —
 inline is capped and returns a clear "payload too large" error above 3MB decoded, pointing
 you back at this flow), `{ ref }` from step 1, `{ url }` (an https URL this server fetches
-itself: image/png, no redirects, ~20MB cap), `{ path }` (local stdio server only — see below),
+itself: PNG or JPEG, converted to PNG when needed, no redirects, ~20MB cap), `{ path }` (local stdio server only — see below),
 or `{ "locales": { "<locale>": <any of those> } }` for per-locale variants (see
 [Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles) above).
 
 Every raw PNG is automatically palette-optimized before rendering (TinyPNG-style, locally inside
 ShotOps): dimensions and transparency are preserved, and an already-smaller PNG is left byte-for-byte
-unchanged. This happens after the input reaches the MCP, so it does **not** raise the inline request
+unchanged. Fetched JPEGs are converted to palette PNGs at the same boundary without changing their
+dimensions. This happens after the input reaches the MCP, so it does **not** raise the inline request
 cap — use the ref/upload flow for a large source file.
 
-**Output** works the same way in reverse: `render_strip`/`emit_bundle` take an `output` field
-— `"inline"` (base64), `"urls"` (uploaded under your own prefix, short-lived signed download
-URLs), or omit for auto (inline under ~200KB total, `urls` above). Use `"urls"` for
-full-resolution work so results never transit your context either.
+**Output** works the same way in reverse: `render_strip`/`render_project` take an `output` field
+— `"inline"` (standard MCP `image` blocks), `"urls"` (uploaded under your own prefix and returned
+as short-lived `resource_link` blocks), or omit for auto (inline under ~200KB total, `urls` above).
+The model-visible `structuredContent.panels` contains ordered delivery descriptors rather than PNG
+base64; ChatGPT receives the complete gallery through widget-only result metadata. Programmatic
+clients read the standard MCP content blocks. Use `"urls"` for full-resolution work.
 
 **Cheap preview, then compose:** `render_strip({ preview: true })` renders at ~25% resolution
 for fast, cheap styling iteration — small enough to always come back inline; don't ship it,
@@ -308,7 +311,7 @@ Deploy the hosted server at a public HTTPS origin, enable Developer Mode in Chat
 an app whose MCP server URL is `https://<your-host>/mcp`. Do not paste a personal `shotops_` token
 into the app definition: ChatGPT discovers the protected-resource metadata from the endpoint and
 runs the server's OAuth + PKCE browser sign-in flow. This is a tool-only app — no widget or UI
-resource is required. User-attached PNGs enter through `import_screenshot`.
+resource is required. User-attached PNGs and JPEGs enter through `import_screenshot`.
 
 For public plugin submission, OpenAI supplies a domain-verification token after the MCP domain
 is entered in the Platform dashboard. Set it on the hosted server as
@@ -368,47 +371,42 @@ since this repo is private.
 
 ### Ops (this repo's maintainer only)
 
-- **Deploy** (from the **repo root** — the Dockerfile needs `../mockup-engine` and
-  `../api/_lib` as build-context siblings):
+`shotops-mcp` serves from its own Vercel project on `https://mcp.shotops.dev` (health:
+`/health`, MCP endpoint: `/mcp`). **`docs/reference/ops-runbook.md` §Deploy owns the procedure**
+— the notes here are only what is specific to this package.
+
+- **Deploy:** run the repo's deploy script from the repo root; deploys run locally, and a push to
+  `main` is a production deploy. Do not hand-run a bare `vercel deploy`. Fly was retired (#68) —
+  `flyctl` is history, not the live procedure.
+- **Runtime env** lives on the `shotops-mcp` **Vercel project**, not in this repo:
+  `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, and `MCP_PUBLIC_URL` (pins the public hostname as
+  the OAuth issuer), plus `OPENAI_APPS_CHALLENGE_TOKEN` while verifying the MCP domain for public
+  ChatGPT submission — nothing Apple-related, ever, by construction. Vercel env applies at the
+  NEXT deployment, never to the running one.
+- **Verify after any deploy** — a green deploy isn't proof the server answers MCP calls:
   ```bash
-  flyctl deploy . --config shotops-mcp/fly.toml --remote-only --ha=false
+  cd shotops-mcp && SHOTOPS_MCP_TOKEN=… node verify-mcp.mjs https://mcp.shotops.dev/mcp
   ```
-- **Secrets** (`fly secrets set -a shotops-mcp KEY=value`): `SUPABASE_URL`,
-  `SUPABASE_SERVICE_ROLE_KEY`, plus `OPENAI_APPS_CHALLENGE_TOKEN` while verifying the MCP
-  domain for public ChatGPT plugin submission — nothing Apple-related, ever, by construction.
-- **Verify after any deploy** — a green `flyctl deploy` isn't proof the server answers MCP
-  calls:
-  ```bash
-  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`.
-- **Logs / status:** `flyctl logs -a shotops-mcp`, `flyctl status -a shotops-mcp`.
-- The Dockerfile is pinned to `mcr.microsoft.com/playwright:v1.61.1-noble` — matching the
-  `playwright` npm version in `package.json`. If you bump one, bump the other.
-- The container builds the browser harness once and serves it through a loopback-only static
-  server at runtime. Vite is build/parity tooling only and is pruned from production
-  dependencies; the Docker build context still includes `mockup-engine` so the harness can
-  bundle the shared engine + GLB.
-- **VM size is `shared-cpu-2x` with 4GB — and BOTH numbers are load-bearing for different
-  reasons.** The **memory** was raised 2gb → 4gb on 2026-07-26 (#134): a grouped multi-panel
-  `render_strip` drove `chrome-headless` to ~1.4gb resident, the kernel OOM-killed it, and the
-  server went unhealthy for minutes — `verify-mcp.mjs` could not run to completion at 2gb and now
-  does. The **2 vCPUs** are the older finding below; don't conflate them, and don't cut either.
-- **Why 2 vCPU and not `shared-cpu-1x`** (found live, Phase 10):
-  Chromium's software WebGL render (no GPU on the hosted tier) is CPU-heavy enough that on
-  a single shared vCPU it can starve the whole process — health checks stop responding,
-  SIGTERM/SIGINT get ignored, and the platform force-kills the machine
-  mid-render. **`Virtual machine exited abruptly` has TWO causes and they look identical in the
-  logs:** on 1 vCPU it is this CPU starvation; on 2 vCPU under load it was the #134 OOM, i.e.
-  MEMORY, fixed by the `4gb` above (`docs/reference/ops-runbook.md` carries that half). Check
-  which resource ran out before reaching for either fix. On 2 vCPUs the same 3-panel real-screenshot render completes in ~8s. Don't
-  drop back to `shared-cpu-1x` to save cost — a render-triggering tool call is expected to
-  occasionally saturate a whole core, and 1x has no second core to keep the process alive
-  while that happens. Client callers (agents, `verify-mcp.mjs`) should still set a generous
-  per-call timeout (≥180s) for `render_strip`/`emit_bundle` — even warm, cold-machine renders
-  can take 60-110s before the CPU fix, and network/Supabase round trips add more on `urls`
-  output.
+  Exercises the exact registered tool set, real render/bundle/project round-trips, signed upload
+  refs, asset deletion, and asserts no-token / bad-token both get `401`. It needs the **Studio**
+  deployment live too (`delete_project` is a control-plane op) and leaves the account as it found
+  it (#333). Add `--artifact-dir <private-dir>` for the ChatGPT portal handoff.
+- **Logs / status:** the `shotops-mcp` project in the Vercel dashboard.
+- **Production builds through Nitro** — `nitro.config.ts` (`preset: 'node-server'`,
+  `vercel: { entryFormat: 'node' }`) compiles the Express graph into `dist-server/`. `Dockerfile`
+  builds the RETIRED Fly image only; it is pinned to `mcr.microsoft.com/playwright:v1.61.1-noble`
+  to match the `playwright` npm version in `package.json`, so if you bump one, bump the other.
+- The build compiles the browser harness once (`build:harness` → `harness-dist/`) and the running
+  server serves it from a loopback-only static server. Vite is build/parity tooling only and is
+  pruned from production dependencies; `mockup-engine` stays reachable at build time so the
+  harness can bundle the shared engine + GLB.
+- **Hosted render capacity is load-bearing and history-rich.** A `render_strip` boots headless
+  Chromium + WebGL for seconds, inline in the request, and full-res multi-panel renders are slow
+  by design — seconds per panel, one panel at a time. The function duration ceiling, the memory
+  findings behind it, and the two distinct failure shapes (CPU starvation vs. OOM) are recorded in
+  `docs/reference/ops-runbook.md` §Deploy. Never cut a memory or duration setting without a green
+  `verify-mcp.mjs` run behind the claim. Client callers (agents, `verify-mcp.mjs`) should set a
+  generous per-call timeout (≥180s) for `render_strip`/`emit_bundle`.
 
 ## Local — `npx shotops-mcp`
 
@@ -579,15 +577,23 @@ npx shotops-mcp release plan \
 
 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.
+baseline. It writes a user-only `release-plan.json` containing every operation as a member of one
+closed, typed vocabulary — each carrying its own target, the precondition it needs, the sealed bytes
+it sends, the postcondition it must reach, and a redacted summary — plus a portable
+`release-review.zip` containing that exact canonical plan and its content-addressed screenshot bytes.
+
+The plan hash-binds the project revision, desired bytes, normalized Fastlane inputs, Apple setup
+identity and policy version, so later approval cannot drift onto different state. Its **approval
+window is 15 minutes**; the plan itself stays readable for as long as its sealed workspace exists.
+Concurrency is per resource rather than one hash of the whole app: an unrelated App Store edit is
+reported without invalidating the plan, while a change to a resource the plan writes — or to the
+app, version or App Store state it targets — blocks before any write.
 
 `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
+step: it carries keyed commitments and digests, never metadata values, review credentials, local
+paths, Apple credentials, or asset bytes. Identifiers are committed under a per-plan key that stays
+on your machine, so the envelope cannot be used to confirm a guess at your Bundle ID, Apple key ID
+or version string. 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
@@ -604,13 +610,14 @@ To review an artifact downloaded from owner-controlled CI, pass it directly:
 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 command verifies the 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, the approval window, complete or partial scope, every
+before/after/clear, build, review, rating, compliance, preview, screenshot order/replacement/omission,
+unchanged operation, 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.
+A plan past its approval window opens read-only and says why; 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
@@ -650,7 +657,8 @@ shotops-mcp/
   vite.harness.config.mjs  the STATIC harness build (local mode's publish prerequisite) → harness-dist/
   build.mjs         esbuild bundle of src/local.ts (+ @engine/@api inlined) → dist/local.js
   Dockerfile        hosted image — Playwright's Chromium base + this repo's 3 npm installs
-  fly.toml          Fly app config — ROLLBACK ONLY since the Vercel cutover; see #68
+  fly.toml          Fly app config — RETIRED (#68), kept only for the cold-deploy recipe;
+                    the running fly.dev machine is NOT a rollback
   verify-mcp.mjs    post-deploy smoke test — real MCP round-trip against a hosted URL
   verify-mcp-local.ts  local stdio smoke test (tsx src/local.ts, in-repo)
   static-parity.ts  pixel-diffs the static-serve render against the Vite-dev render (must be 0)