@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.2

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@polardbx/pxbaas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.2",
+  "description": "PolarDB-X BaaS CLI application",
+  "keywords": [
+    "polardbx",
+    "baas",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polardbx/mysql-supabase.git",
+    "directory": "cli/apps/baas"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "bin": {
+    "pxbaas": "./bin/pxbaas.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "templates"
+  ],
+  "dependencies": {
+    "axios": "^1.6.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "inquirer": "^9.2.0",
+    "jsonwebtoken": "^9.0.0",
+    "keytar": "^7.9.0",
+    "@polardbx/pxbaas-client": "0.1.0-beta.2"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.0",
+    "@types/jsonwebtoken": "^9.0.0",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.56.0",
+    "msw": "^2.2.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --watch",
+    "start": "node ./bin/pxbaas.js",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/skills/pxbaas-app-spec/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: pxbaas-app-spec
+description: Author and review PolarDB-X BaaS (MySQL-Supabase) apps in both legacy Edge Function modes and schemaVersion 2 Webapp mode. Covers prebuilt static frontends, React + Vite + HashRouter, optional Deno/Hono backends, App capabilities, immutable candidates, generation-CAS publish/rollback/unpublish, artifact guardrails, and legacy /functions/v1 behavior. This is the authoritative app spec enforced by `pxbaas app deploy`.
+---
+
+# pxbaas-app-spec
+
+How to write apps for **PolarDB-X BaaS**, including legacy Edge Function demos and schemaVersion 2 Webapps with a static frontend plus an optional Deno/Hono backend.
+
+This is an **authoring spec**. For exact CLI syntax, see the `pxbaas-cli` skill (`references/app-deploy.md`). Legacy raw Management API and Studio deployment remain documented for Edge Functions; Webapp lifecycle operations should use `pxbaas app`.
+
+> **This spec is enforced, not just advised.** `pxbaas app deploy` runs static spec-lint before upload. In Webapp mode it checks the built frontend, project routing/build configuration, backend source, manifest policy, capability limits, and exact Hono version. Violations are blockers.
+
+## When to use this skill
+
+- Writing a static, React/Vite, Deno, or Hono Webapp for an App mount
+- Writing or maintaining a legacy `spa`/`api`/`mpa` Edge Function demo
+- Reviewing routing, build output, backend imports, Secrets, or egress policy
+- Diagnosing capability blocks, CAS conflicts, 503/blank pages, or broken asset paths
+
+## Mental model: two compatible delivery modes
+
+**Manifest v2 Webapp:** the stable mount serves a prebuilt frontend and optionally routes `/api/*` to a Deno backend. The CLI uploads an immutable candidate and atomically changes the mount generation.
+
+```
+{appEndpoint}/apps/{mount}/
+{appEndpoint}/apps/{mount}/api/*
+```
+
+The public classification is capability-driven. Only `originMode=isolated`, `hostEnforced=true`, and `publicExposureAllowed=true` produce a Public URL; all other mounts are Preview.
+
+**Legacy Edge Function:** one Deno worker remains available for `spa`/`api`/`mpa` compatibility.
+
+```
+{endpoint}/functions/v1/{slug}
+```
+
+## Runtime and artifact contract (must satisfy)
+
+- **Frontend:** upload build output only. Vite uses `base: "./"` and source maps off. React uses `HashRouter`, not browser-history routing. No `.env`, source maps, `node_modules`, `src/`, Service Workers, root-absolute references, or binary assets.
+- **Backend:** Deno only, with top-level `Deno.serve(...)`; no Node APIs, arbitrary remote/npm/jsr imports, Secrets, or outbound egress. `Deno.env` is limited to the platform public three-key whitelist `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL` (any other variable or `Deno.env.toObject()` fails spec-lint with `deno-env-not-allowed`); use `SUPABASE_INTERNAL_URL` as the only worker-side data-plane fetch base — `SUPABASE_URL` is render-only. The first release requires `secrets: []` and `egressPolicy: "deny"`.
+- **Hono:** import exactly `npm:hono@{{HONO_VERSION}}` in scaffold source. Deploy replaces the placeholder with the capability's exact offline-ready version.
+- **SSR renderers:** a worker may also import the curated server-side renderers reported by capability `ssrLibs` (e.g. `npm:react-dom@18.3.1/server`, `npm:@vue/server-renderer@3.5.13`, `npm:preact-render-to-string@6.5.11`, `npm:solid-js@1.9.3/web`). Use the exact `name@version` from `ssrLibs` (a `/subpath` such as `/server` or `/web` is allowed); off-list or version-drifted imports fail spec-lint (`ssr-lib-not-allowed`). `pxbaas app capabilities` lists what the instance actually pre-cached.
+- **Legacy modes:** continue to return `Response` objects, set content types, and avoid binding a port.
+- Full details + limits: `references/runtime-contract.md`.
+
+## Minimal skeleton
+
+```ts
+function cors(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+Deno.serve((req: Request) => {
+  const url = new URL(req.url);
+  if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: cors() });
+
+  if (url.searchParams.get("action") === "time") {
+    return new Response(JSON.stringify({ ok: true, now: new Date().toISOString() }),
+      { headers: { "Content-Type": "application/json", ...cors() } });
+  }
+
+  const html = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Demo</title></head><body>
+<h1>Demo</h1><button onclick="p()">time</button><pre id="o"></pre>
+<script>async function p(){const r=await fetch(location.pathname+"?action=time");document.getElementById("o").textContent=JSON.stringify(await r.json());}</script>
+</body></html>`;
+  return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8", ...cors() } });
+});
+```
+
+## Guardrails (the rules that make it actually work)
+
+**MUST**
+- Serve page(s) + API under the ONE prefix `/functions/v1/{slug}`. Single-file (`spa`/`api`): one `Deno.serve` split by `?action=`/method. Multi-page (`mpa`): the proxy serves real static files by path and the worker handles `?action=`.
+- Use **relative URLs** client-side: `location.pathname + "?action=..."` (in `mpa`, call the directory base `./?action=...` so sub-pages don't capture the query).
+- **Assets**: inline all CSS/JS in single-file mode; in `mpa` deploy real files, link them **relatively** and list them in `app.json` `pages`/`assets`. **Escape reflected input** (the URL is public); set **CORS** + handle `OPTIONS`.
+- Keep it small/fast: ~150MB memory, CPU ~10s soft / 20s hard, ~5min wall; one sandbox shared per tenant; `mpa` static files ≤256KB each.
+- **Webapp publish contract**: `app.json` must be `schemaVersion: 2` and its `name` must equal the mount's `appName` (not the candidate slug); upload statics with an explicit nested `filename=frontend/dist/<name>`. A heavy `npm:` import graph makes the first request slow (up to ~60s with four SSR renderers) and can fail the publish-time SSR probe — warm that tenant's sandbox first and retry, don't rewrite a worker that already returns 200 (see `references/deploy-options.md`).
+
+**MUST NOT**
+- **No root-absolute paths** (`href="/x"`, `src="/x"`, `fetch("/x")`, `url(/x)`) — they escape `/functions/v1/` onto Studio and break the share URL.
+- **No external CDN `<script>`/`<link>`** for core assets — inline them. (Legacy edge functions may `fetch()` public APIs at runtime; **Webapp backends are `egressPolicy="deny"`** — public egress is blocked and only the platform-internal base `SUPABASE_INTERNAL_URL` is reachable.)
+- **No Node.js APIs, heavy build output, large binaries, base64 blobs.**
+- **No secrets in a `verify_jwt=false` function** (publicly reachable, slug enumerable).
+- **No DDL / long jobs** in the request path.
+- **No worker-side cookie sessions on `/apps/{mount}/`** — the proxy strips client cookies on that entry. For signed-in SSR declare `backend.session:"proxy-injected"` and read the injected `X-App-User-*` headers; never read `cookie`, never send `Set-Cookie`, never put tokens in URLs. See `references/ssr-session.md`.
+
+Details, pitfalls and fixes: `references/guardrails-pitfalls.md`.
+
+## App / template organization
+
+SchemaVersion 2 Webapp:
+
+```
+apps/<name>/
+├── frontend/              # source project or vanilla static source
+│   └── dist/              # canonical React/Vite deployment root
+├── backend/index.ts       # optional Deno/Hono API
+└── app.json               # mode=webapp, frontend/backend contracts, deployment state
+```
+
+Legacy modes retain `index.ts` plus optional `mpa` static files.
+
+- Webapp templates: `vanilla-static`, `react-vite`, `react-vite-hono`, `ssr-hono`, `ssr-auth` (signed-in SSR via proxy-injected session headers). Reference application templates (ship `db/schema.sql` + README + a DEPLOY CONFIG block to fill before deploy): `ssr-blog` (full-site SSR + proxy-injected session), `csr-bff` (front/back-separated CSR + BFF), `ssr-shop` (React SSR shop, browser-side session), `ssr-frameworks` (four-framework SSR showcase). `pxbaas app templates` is the authoritative list.
+- Legacy templates: `spa`, `api`, `mpa`.
+- Start from `pxbaas app new --template <id>` instead of hand-rolling the manifest. Full structures: `references/templates-examples.md`.
+
+## Deploy paths (pick one)
+
+| Path | When | How |
+|---|---|---|
+| **`pxbaas app`** (recommended and required for Webapp lifecycle) | you have the CLI + a profile | capability check, candidate upload, CAS publish/rollback/unpublish |
+| **Management API (`curl`)** | legacy Edge Function scripting | `POST {endpoint}/v1/projects/default/functions/deploy?slug=<slug>` (multipart) |
+| **Studio** | legacy manual deployment | Functions editor in the Dashboard |
+
+Use `pxbaas app capabilities --json` before a Webapp deploy. Full commands + gotchas: `references/deploy-options.md`.
+
+## Constraints & limits (state these to the user)
+
+- **Fits:** bounded prebuilt static frontends with optional small Deno/Hono APIs, plus legacy lightweight demos.
+- **Does not fit:** server-side Node frameworks, browser-history fallback routing, Service Workers, arbitrary egress, Secrets, large/binary bundles, or heavy/long-running jobs.
+- Capability limits (`maxFiles`, `maxFileBytes`, `maxBundleBytes`) are authoritative.
+- Legacy functions retain cold-start and function-quota behavior.
+
+## Workflow
+
+```
+1. pxbaas app capabilities --json
+2. pxbaas app new <name> --template react-vite|react-vite-hono|vanilla-static
+3. build the frontend when required (npm ci && npm run build)
+4. pxbaas app deploy <name> --json
+5. pxbaas app verify <name> --json
+6. use publish / rollback / unpublish for later generation changes
+```
+
+## What NOT to do
+
+- Do NOT use root-absolute asset/links/fetch paths — the #1 cause of a broken share URL.
+- Do NOT deploy React/Vite source; run the pinned lockfile build and upload `dist`.
+- Do NOT use `BrowserRouter`, a Service Worker, source maps, `.env`, or root-absolute URLs.
+- Do NOT use Node APIs, arbitrary remote imports, Secrets, or non-deny egress in a Webapp backend. `Deno.env` is allowed ONLY for the three-key whitelist (`SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL`); any other variable or `Deno.env.toObject()` is blocked.
+- Do NOT use `--skip-spec-check` to force a bundled template or a failing artifact through — it bypasses the deployment/security contract. Only bypass when the user explicitly asks, after you have listed every blocker and its impact.
+- Do NOT bypass capability checks or retry a generation conflict with a guessed generation.
+- Do NOT put large/binary assets in an App candidate; use Storage/CDN.
+- For legacy modes, do NOT assume first-hit success or exceed the function quota.
+
+## Reference guide
+
+| Topic | Reference |
+|---|---|
+| Deno runtime contract, worker limits, lifecycle | references/runtime-contract.md |
+| Guardrails, common pitfalls & fixes | references/guardrails-pitfalls.md |
+| Legacy and Manifest v2 template/app structures | references/templates-examples.md |
+| Deploy and Webapp lifecycle options | references/deploy-options.md |
+| SSR webapp sessions (proxy-injected identity headers) | references/ssr-session.md |
+| Multi-tenant provisioning, credentials, RLS placement, acceptance | ../pxbaas-cli/references/multi-tenant-apps.md |

package/skills/pxbaas-app-spec/references/deploy-options.md

@@ -0,0 +1,157 @@
+# Deploy Options
+
+Use `pxbaas app` for schemaVersion 2 Webapps. Legacy Edge Function apps may also use the raw Management API or Studio. Deployment requires the **service_role** key.
+
+## Path 1 — `pxbaas app` (recommended)
+
+Requires the pxbaas CLI with an active profile (`pxbaas provision` or `pxbaas login`). It handles capability gating, artifact lint, immutable candidate upload, generation CAS, and verification.
+
+```bash
+pxbaas app capabilities --json
+pxbaas app new <name> --template react-vite-hono --json
+(cd apps/<name>/frontend && npm ci && npm run build)
+pxbaas app deploy <name> \
+  --frontend apps/<name>/frontend/dist \
+  --backend apps/<name>/backend \
+  --backend-framework hono \
+  --json
+pxbaas app verify <name> --json
+pxbaas app url <name> --json
+
+# Explicit lifecycle operations use local mount/candidate/generation state:
+pxbaas app publish <name> --json
+pxbaas app rollback <name> --json
+pxbaas app unpublish <name> --json
+```
+
+- `vanilla-static` needs no build; React templates use their committed lockfile and fixed versions.
+- `--frontend` must point to prebuilt output. `--backend` points to Deno source.
+- Deploy automatically publishes. `app publish` is useful when a prior publish failed after candidate upload.
+- Confirm deploy/publish/rollback/unpublish with the user first.
+- JSON failures consistently contain `code` and `message`.
+- See the `pxbaas-cli` skill `references/app-deploy.md` for the full command surface.
+
+## Path 2 — Legacy Management API (`curl`), no CLI
+
+Deploy is a **multipart** POST. Critical: the `metadata` field must be a **plain form field WITHOUT a filename** (sending it as a file part causes a 400/parse error). The code file is sent as `file=@index.ts` with a filename matching `entrypoint_path`.
+
+```bash
+BASE="http://<public-endpoint>:8000"     # the instance Kong URL
+SLUG="shop-demo"
+SVC_KEY="<SERVICE_ROLE_KEY>"
+# multi-tenant only:
+TENANT="-H X-Tenant-Id:<TENANT_ID>"
+
+curl -sS -X POST "${BASE}/v1/projects/default/functions/deploy?slug=${SLUG}" \
+  -H "Authorization: Bearer ${SVC_KEY}" \
+  ${TENANT} \
+  -F "metadata={\"slug\":\"${SLUG}\",\"name\":\"${SLUG}\",\"entrypoint_path\":\"index.ts\",\"verify_jwt\":false};type=application/json" \
+  -F "file=@./index.ts;type=application/typescript" \
+  -w "\nHTTP_STATUS=%{http_code}\n"
+```
+
+- Share URL: `${BASE}/functions/v1/${SLUG}`.
+- Some deployments also require Studio basic-auth (`-u <DASHBOARD_USERNAME>:<DASHBOARD_PASSWORD>`) on `/v1/projects/*`; if you get 401, add `-u`.
+- Do not echo the service_role key into logs; prefer an env var.
+
+## Path 3 — Legacy Studio (Dashboard), manual
+
+Open the instance Dashboard (`{endpoint}/`, basic-auth user `supabase`), go to **Edge Functions**, create/paste the function, set **Verify JWT = off** for a public demo, and deploy. Studio then notifies the proxy to create/sync the sandbox. Good for one-off manual demos; not scriptable.
+
+## Verify & share (legacy paths)
+
+A paused sandbox 503s on first hit, so verify with retries:
+
+```bash
+URL="${BASE}/functions/v1/${SLUG}"
+for i in $(seq 1 12); do
+  code=$(curl -sS -o /dev/null -w '%{http_code}' "$URL" || echo 000)
+  ct=$(curl -sS -o /dev/null -w '%{content_type}' "$URL" || echo -)
+  echo "attempt#$i HTTP $code content-type=$ct"
+  [ "$code" = "200" ] && break
+  sleep 5
+done
+curl -sS "${URL}?action=time"        # built-in API ping (spa template)
+```
+
+- Expect `HTTP 200` and `content-type: text/html...` for the page; the `?action=` ping returns JSON.
+- **Cross-machine sharing** works only if `{endpoint}` is a public address (not localhost/private) and the caller's IP is within the instance whitelist (Zero instances whitelist your egress IP).
+- Send the `{endpoint}/functions/v1/{slug}` URL — never the internal sandbox URL.
+
+## Webapp publish contract (schemaVersion 2)
+
+`publish` re-validates the candidate's `app.json` against the mount, so these are hard
+requirements — violating any of them fails at publish time (after the upload succeeded),
+which is the most confusing place to discover them:
+
+- **`name` MUST equal the mount's `appName`** (not the candidate slug). A mismatch returns
+  `409 APP_MANIFEST_INVALID: Candidate app.json does not match the schemaVersion 2 webapp
+  contract` — the message does not name the field, so check `name` first.
+- **`schemaVersion: 2` is required.** Instances report the accepted set in
+  `pxbaas app capabilities --json` → `schemaVersions`; an instance reporting `[2]` rejects
+  legacy v1 manifests (`mode: "mpa"` + `pages[]`/`assets[]`).
+- **Re-publishing the already-active candidate** returns
+  `409 APP_ARTIFACT_INVALID: Candidate is already active`. Treat it as success (idempotent
+  re-run), not as a failure.
+
+### Migrating a legacy v1 `mpa` manifest to v2
+
+| v1 (`mode: "mpa"`) | v2 (`mode: "webapp"`) |
+|---|---|
+| `slug`, `template`, `entrypoint`, `verifyJwt` (top level) | dropped / moved under `backend` |
+| `pages: ["index.html", ...]`, `assets: ["style.css", ...]` | real files uploaded under `frontend.root` (e.g. `frontend/dist/`); `frontend.index` = first page |
+| — | `frontend: { root, routing: "files", index, fallback: null \| "worker" }` |
+| `entrypoint: "index.ts"` | `backend: { entrypoint: "backend/index.ts", framework: "deno" \| "hono", pathMode: "strip-app-api-prefix", verifyJwt, secrets, egressPolicy }` |
+
+Upload each static file with an explicit nested `filename=frontend/dist/<name>` (multipart
+path flattening otherwise collapses them into the bundle root and publish then reports a
+missing `frontend/dist/index.html`).
+
+## SSR probe and cold-start budget (platform-side)
+
+When the manifest declares `ssrProbePath`, publish **fetches that path once through the
+worker before activating the candidate**. If the probe does not answer in time, publish fails
+with `409 APP_SSR_PROBE_FAILED` — first as `SSR probe unreachable: ... aborted due to
+timeout`, then (once the sandbox half-initialises) as `SSR probe failed: http_500`.
+
+This is a **cold-start budget problem, not an app defect**. Measured first-request cost of a
+cold tenant sandbox scales with how many npm modules the worker imports:
+
+| Worker shape | First request (cold) | Warm |
+|---|---|---|
+| Deno stdlib only, no `npm:` imports | a few seconds | < 0.2 s |
+| Hono + React + react-dom/server | tens of seconds | < 0.2 s |
+| Hono + React + Vue + Preact + Solid (4 renderers) | ~60 s | < 0.2 s |
+
+Standard recovery procedure (sandboxes are reused **per tenant**, so warming once helps every
+function of that tenant, including the mount candidate):
+
+1. Deploy the same worker as a legacy function in the same tenant
+   (`functions deploy`, tenant service key + `X-Tenant-Id`).
+2. `GET` it until it returns 200 — the first call may take a minute; this lands the module
+   resolution/compile results in that tenant's sandbox cache.
+3. Re-run `publish`. On `APP_SSR_PROBE_FAILED`, wait 10–20 s and retry (3–5 attempts): each
+   failed probe attempt continues to warm the sandbox.
+
+To decide between "broken code" and "cold start", compare the legacy function's first-call
+latency and final status: slow-then-200 means cold start; immediate 500 with a stack means the
+worker itself. Note `capabilities.ssrLibs` lists only the curated build-time allow-list and
+may **under-report** what the sandbox can actually resolve — treat it as a hint, and verify by
+running the worker.
+
+## Deploy troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| 400 / parse error on deploy | `metadata` sent as a file part | send `metadata` as a plain field, no filename |
+| 401 on `/v1/projects/*` | missing service_role or Studio basic-auth | add `Authorization: Bearer <svc>` (and `-u` if required) |
+| 403 in multi-tenant | missing/incorrect `X-Tenant-Id`, or non-platform key | send the tenant header; use the right key |
+| 429 on deploy | function quota (5/tenant) reached | remove a function or request a higher quota; do not loop |
+| 503 after deploy | sandbox cold start / not READY | retry up to ~60s (verify loop above) |
+| 404 on share URL | wrong slug, or function not deployed | check slug regex and `pxbaas app list` / `functions list` |
+| `APP_CAPABILITY_UNSUPPORTED` | required Webapp/static/Deno/Hono capability is disabled | inspect `pxbaas app capabilities --json`; stop before upload |
+| `APP_ARTIFACT_INVALID` | frontend/backend violates the v2 artifact contract | fix every spec-lint blocker; do not use `--skip-spec-check` as a workaround |
+| `APP_ARTIFACT_INVALID: Candidate is already active` | re-publishing the active candidate | idempotent no-op — treat as success |
+| `APP_MANIFEST_INVALID` | `app.json` `name` ≠ mount `appName`, or manifest is not schemaVersion 2 | align `name` with `appName`; migrate v1 `mpa` manifests (table above) |
+| `APP_SSR_PROBE_FAILED` (timeout, then `http_500`) | cold tenant sandbox cannot resolve/compile the worker's npm imports within the probe budget | warm the sandbox via a legacy function, then retry publish (procedure above) — platform-side, not an app defect |
+| `APP_PUBLISH_CONFLICT` | `expectedGeneration` is stale | reconcile mount state and retry with the returned current generation |

package/skills/pxbaas-app-spec/references/guardrails-pitfalls.md

@@ -0,0 +1,89 @@
+# Guardrails, Pitfalls & Fixes
+
+The enforced rules for schemaVersion 2 Webapps and legacy Edge Function apps, plus common failure modes and fixes.
+
+## Why these rules exist
+
+Webapp static files are served from a stable `/apps/{mount}/` prefix and an optional backend receives `/apps/{mount}/api/*` with that prefix stripped. Legacy apps remain under `/functions/v1/{slug}`. Prefix safety, immutable deployment, and a deliberately restricted backend capability set drive these guardrails.
+
+## Manifest v2 Webapp MUST
+
+1. Check `pxbaas app capabilities --json` before deploy; do not infer App support from the gateway URL.
+2. Upload prebuilt frontend output only. Vite uses `base: "./"` and `build.sourcemap: false`; React uses `HashRouter`.
+3. Use relative asset and API URLs. The backend API is under relative `./api/*` from the mounted frontend.
+4. Keep `frontend.routing="files"` and `frontend.index="index.html"`. Static-only apps use `frontend.fallback=null`; SSR apps use `frontend.fallback="worker"` **and must declare `ssrProbePath`** (see the Worker SSR section) — `fallback=null` is NOT universal.
+5. Backend entrypoints call `Deno.serve`; Hono imports `npm:hono@{{HONO_VERSION}}` in source and the exact capability version in the staged candidate. SSR workers may additionally import only the capability `ssrLibs` renderers at their exact `name@version` (a `/subpath` is allowed); off-list or version-drifted imports fail `ssr-lib-not-allowed`.
+6. Keep backend `secrets=[]` and `egressPolicy="deny"` for the first release.
+
+## Manifest v2 Webapp MUST NOT
+
+1. Do not stage `.env*`, source maps, `node_modules`, `src`, Service Workers, or binary assets.
+2. Do not use `BrowserRouter`, root-absolute URLs, Node APIs, or arbitrary `http:`/`https:`/`npm:`/`jsr:` imports. `Deno.env` is allowed only for the platform public three-key whitelist (`SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL`); any other variable or `Deno.env.toObject()` is a `deno-env-not-allowed` blocker, and custom Secrets are a `custom-secrets-not-supported` blocker. Fetch the data plane through `SUPABASE_INTERNAL_URL` only — `SUPABASE_URL` is render-only.
+3. Do not publish, rollback, or unpublish without the locally recorded `expectedGeneration`; a conflict requires state reconciliation.
+4. Do not label a URL Public unless capabilities report isolated origin, enforced host, and public exposure.
+
+## Legacy modes MUST
+
+1. **One function, one prefix.** Serve the page(s) and the JSON API under the same `/functions/v1/{slug}` prefix. In single-file mode one `Deno.serve` handles both (branch on `?action=`); in `mpa` mode the proxy serves static pages/assets by path and the worker handles `?action=`.
+2. **Relative URLs for client calls.** Use `location.pathname + "?action=time"` (or `new URL("?action=time", location.href)`), never `fetch("/action")`. In `mpa`, call the API from the *directory base* (`./?action=time` or a computed base ending in `/`) so a sub-page like `about.html` does not turn the call into `about.html?action=time`.
+3. **Assets: inline (single-file) or real files (mpa).** `spa`/`api` must inline all CSS/JS in the one file. `mpa` deploys real **text** files (`.html`/`.css`/`.js`/`.svg`/`.json`), flat or in **nested subdirs** (`assets/`, `pages/`) — reference them with **relative** links and list every page/asset in `app.json` `pages`/`assets` so spec-lint (`mpa-assets-exist`) and the proxy static branch can find them.
+4. **Escape reflected input.** Anything from the request echoed into HTML must be escaped (`&`,`<`,`>`,`"`) — the URL is public, so this is an XSS guard.
+5. **CORS + OPTIONS.** Return `Access-Control-Allow-*` headers and answer `OPTIONS` with 204 when the page calls the API.
+6. **Stay small and fast.** ~150MB memory, CPU ~10s soft/20s hard, ~5min wall; one sandbox shared per tenant. In `mpa` each static file must be ≤ `STATIC_MAX_BYTES` (default 256 KB) or the proxy falls through to the worker.
+
+## Legacy modes MUST NOT
+
+1. **No root-absolute paths.** `href="/x"`, `src="/x"`, `fetch("/x")`, `url(/x)`, `<base href="/">` — these resolve against the site root, escape `/functions/v1/`, and land on Studio → broken page/assets. This is the #1 bug.
+2. **No external CDN `<script>`/`<link>` for core assets.** Inline them. (Legacy edge functions may `fetch()` public APIs at runtime, though the page must not depend on a CDN to render. This does **not** apply to Webapp backends: they are `egressPolicy="deny"` — public egress is blocked and only the platform-internal base `SUPABASE_INTERNAL_URL` is reachable.)
+3. **No Node.js APIs / build output / large binaries / base64 blobs.** It is Deno; single-file mode is memory-capped, and `mpa` static files are capped at `STATIC_MAX_BYTES` (256 KB). **Binary assets (png/jpg/gif/webp/ico/woff/woff2/ttf/…) are BLOCKED at deploy** (`no-binary-assets`): the utf-8 upload pipeline silently corrupts them. Put images/fonts/video on **Storage/OSS** (`pxbaas storage cp`) and reference them by URL, never as function files.
+4. **No secrets in a `verify_jwt=false` function.** It is public and the slug is enumerable. Put secrets/private logic behind `--verify-jwt` or a separate function; keep DB keys server-side, never in client HTML.
+5. **No DDL / long jobs in the request path** (CPU/wall limits; DDL implicitly commits and is often blocked for tenant users).
+
+## Common pitfalls → diagnosis → fix
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Webapp deploy is blocked before upload | schema v2, App endpoint, static, Deno, or Hono capability is unavailable | inspect `pxbaas app capabilities --json`; do not bypass the gate |
+| React page loads but route refresh/navigation fails | `BrowserRouter` or Vite root base | use `HashRouter` and `base: "./"` |
+| Frontend artifact is rejected | `.env`, source map, source tree, `node_modules`, Service Worker, or binary file was staged | build cleanly and upload only bounded static output; move binaries to Storage/OSS |
+| Backend artifact is rejected | missing `Deno.serve`, Node API, remote import, Secrets, or non-deny egress | use the Deno/Hono template and first-release policy |
+| Publish returns `APP_PUBLISH_CONFLICT` | local generation is stale | fetch/reconcile mount state; never retry with a guessed generation |
+| Output says Preview instead of Public | origin isolation/host enforcement/public exposure is incomplete | treat it as Preview; do not present it as publicly isolated |
+| Page loads but CSS/JS missing, or you land on Studio/404 | root-absolute asset path (`/x`) | use inline assets or relative paths; never `/`-rooted refs |
+| Button click does nothing / API 404 | client used `fetch("/api")` (absolute) | use `fetch(location.pathname + "?action=...")` |
+| First visit blank or 503, later visits fine | sandbox cold start (paused → resume) | retry with backoff (~60s); optionally warm-up ping; tell the user |
+| CORS error in browser | missing CORS/OPTIONS handling | return `Access-Control-Allow-*` and 204 on OPTIONS |
+| Reflected text breaks layout / XSS risk | unescaped input in HTML | escape with an `esc()` helper |
+| Deploy 400 / parse error | multipart `metadata` sent as a file part | send `metadata` as a plain form field WITHOUT filename (see deploy-options.md) |
+| Deploy 429 | function quota (5/tenant) reached | remove an unused function or request a higher quota; do NOT loop |
+| Share URL works for you, not others | endpoint is localhost/private, or sandbox-internal URL | share only `{public endpoint}/functions/v1/{slug}`; check the instance is publicly reachable + IP whitelist |
+| `Deno.serve` never invoked / worker error | used Node APIs or bound a port | use top-level `Deno.serve(handler)`, no `listen()` |
+| Function runs but data calls 401 | used service_role in client, or wrong key | call REST with the anon key server-side; never expose service_role |
+| mpa: `style.css`/`about.html` 404 or served by the worker | file not listed in `app.json` `pages`/`assets`, missing on disk, or `app.json` `mode` is not `mpa` | add the real file, list it under `pages`/`assets`, keep `"mode": "mpa"`; `pxbaas app verify` probes each |
+| mpa: page loads but unstyled / assets land on Studio | asset linked root-absolute (`/style.css`) | link relatively (`style.css`, `./app.js`) |
+| mpa: API button 404 / returns HTML | called `?action=` from a sub-page (resolved to `about.html?action=`) | call the directory base: `./?action=time` or computed base ending in `/` |
+| mpa: large image/font not served | file > `STATIC_MAX_BYTES` (256 KB) falls through to worker | host large binaries on Storage/OSS and reference by URL |
+| mpa: deploy blocked with `no-binary-assets` | a png/jpg/woff/… is in the app dir | binary files corrupt under utf-8 upload — move them to Storage/OSS and link by URL |
+| mpa: image renders as garbage | a binary was uploaded as a function file (older build) | never upload binaries as function files; use Storage/OSS |
+| webapp: publish returns `APP_MANIFEST_INVALID` | candidate `app.json` `name` ≠ the mount's `appName`, or the manifest is legacy v1 while the instance only accepts schemaVersion 2 | set `name` = `appName`; migrate v1→v2 (deploy-options.md) — the error text does not name the offending field |
+| webapp: publish returns `APP_SSR_PROBE_FAILED` (timeouts, then `http_500`) | **platform-side**: a cold tenant sandbox cannot resolve/compile the worker's npm imports within the probe budget | warm that tenant's sandbox with a legacy function, then retry publish 3–5× — do NOT rewrite a worker that already returns 200 when called directly |
+| webapp: publish returns `APP_ARTIFACT_INVALID: Candidate is already active` | idempotent re-run of the same candidate | treat as success |
+| webapp: static pages 404 but the worker API works | multipart upload flattened nested paths into the bundle root | upload each file with an explicit `filename=frontend/dist/<name>` |
+| webapp: worker sees no user identity under `/apps/{mount}/` | `TRUSTED_INTERNAL` strips client `Authorization`/`Cookie` before the worker | read the proxy-injected `X-App-User-*` headers; establish the session via `./_session/login` (ssr-session.md) |
+| multi-tenant: RLS policies silently do not apply | policies written with `table_schema='public'`, or into the tenant DB's unread `_mysqlrest_rls_*` copies | write to the central `supabase._mysqlrest_rls_*` with `table_schema='<tenant db>'` — see pxbaas-cli `references/multi-tenant-apps.md` |
+
+## Prefix-safety quick check (before deploy)
+
+Scan the source for root-absolute references:
+- `href="/…"`, `src="/…"`, `action="/…"`, `fetch("/…"`, `url(/…)` → replace with relative/inline.
+- Protocol-relative `//cdn/…` for core assets → inline instead.
+- Any hardcoded absolute instance URL in client code → use `location.origin + location.pathname`.
+
+`pxbaas app deploy` runs this scan as part of spec-lint. In Manifest v2 it is a blocking artifact error; fix it before deploying.
+
+## Public-safety checklist (verify_jwt=false)
+
+- No API keys, DB passwords, or tokens anywhere in the returned HTML/JS.
+- No private/admin actions reachable without auth (the function is public).
+- Escape all reflected input.
+- If the demo needs protected logic, split it: a public `verify_jwt=false` front function + a separate `verify_jwt=true` function for privileged actions.