Verifier Web

Web Verifier (Polar)

The handle is the browser. The evidence is screenshots + the resulting DB/backoffice state. This skill is the repo's replay protocol for any change that a user — human or programmatic — meets through the web UI: the dashboard, the checkout, or the backoffice.

Use the local-environment skill for all stack mechanics (start/stop/logs/instances). This skill adds the browser-driving and auth/payment recipe on top.

When to use

• Verifying a dashboard, checkout, or backoffice change.
• Confirming login works, or a flow that requires being logged in.
• Proving a purchase / subscription path end-to-end against live Stripe (test mode).

For CLI/API/library changes, use the built-in /verify surfaces instead — this skill is for pixels.

Tooling

Drive the browser with the Playwright MCP (mcp__playwright__*). Prefer browser_snapshot (accessibility tree, gives refs) over screenshots for acting; use browser_take_screenshot for evidence. Read backend state with dev docker exec db psql and docker logs.

1. Bring up the stack

dev docker ps          # allocates/detects this worktree's instance number N
dev docker up -d       # build + migrate + seed on first run (several minutes)

dev docker up prints the authoritative ports — always read them from its output, do not compute them. They look like:

API:  http://localhost:81NN
Web:  http://localhost:31NN

(N is the instance; e.g. instance 7 → API :8107, Web :3107. Container names are polar-app-<N>-api-1, -web-1, -worker-1; DB is polar_dev_<N>.)

Poll readiness before driving anything:

for i in $(seq 1 60); do
  a=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:81NN/healthz)
  w=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:31NN)
  # web may answer 200/307/308 (Next.js dev redirects/compiles on first hit)
  [ "$a" = 200 ] && [ "$w" -ge 200 ] && [ "$w" -lt 400 ] && break; sleep 5
done

2. Log in (dashboard + backoffice share one cookie)

Log in through the real email-OTP flow. The backoffice at http://localhost:81NN/backoffice/ uses the same user-session cookie, so logging into the dashboard authenticates the backoffice too.

1. browser_navigate → http://localhost:31NN/auth (the nav "Login" link is hidden; go to /auth directly. /login 404s.)
2. Type admin@polar.sh into the Email field, click Sign in with email. The seed account admin@polar.sh owns admin-org (approved, payout account, products) — go straight to checkout testing, no onboarding.
3. The page advances to /auth/email-otp. Read the code from the api logs:

   docker logs --since 60s polar-app-<N>-api-1 2>&1 | grep -A1 "LOGIN CODE"

4. Type the 6-character code (uppercase letters + digits, e.g. C9YLIF) → lands on /dashboard/admin-org.
5. Backoffice: browser_navigate → http://localhost:81NN/backoffice/.

The backoffice needs compiled assets (Tailwind/DaisyUI → static/styles.css + scripts.js). On a clean start these are often not built yet — the backoffice then renders unstyled and /backoffice/static/styles.css + scripts.js 404 (served as application/json). Build them once:

cd server && uv run task backoffice

The output lands in server/polar/backoffice/static/ on the host, which is mounted into the api container — it's picked up live, no recreate needed. (dev docker up has a "Building backoffice assets" step, but don't rely on it having run; check that the backoffice is styled and rebuild if not.)

Login prerequisite — the auth-session cookie domain

Login through the browser requires the auth-session cookie domain to match the host the frontend uses (localhost). This is set in dev/docker/docker-compose.dev.yml:

POLAR_USER_SESSION_COOKIE_DOMAIN: localhost
POLAR_AUTHENTICATION_SESSION_COOKIE_DOMAIN: localhost   # both must be present

If you see POST /v1/auth/email-otp/request → 401 "Invalid or missing authentication session token", the Set-Cookie from /auth/start is being dropped because its Domain= doesn't match the page host. Check:

curl -si -X POST http://localhost:81NN/v1/auth/start \
  -H 'Origin: http://localhost:31NN' -H 'Content-Type: application/json' \
  -d '{"return_to":"/dashboard"}' | grep -i set-cookie

Domain=localhost → good. Domain=127.0.0.1 → the override above is missing; add it, then recreate the api (dev docker up -d api — a restart does NOT reload compose env). Do not fall back to minting/injecting a session cookie.

3. Purchase end-to-end (live Stripe test mode)

A real purchase needs (a) a valid Stripe sandbox key on api and worker, and (b) a webhook listener forwarding to the api. Order creation is async — the api 202s the webhook and the worker creates the order.

3a. Stripe account + keys

Use your own Stripe sandbox (https://dashboard.stripe.com/sandboxes). Never a live account, and never a shared team account — dev stripe refuses both. The Stripe CLI profile is always polar-sandbox.

Secrets are set up once and reused across worktrees. They live centrally in ~/.config/polar/secrets.env and dev/setup-environment propagates them into each worktree's server/.env. So you don't redo Stripe setup per worktree — populate the central file once. The one-step path:

dev stripe --listen --port <api-port>   # <api-port> = the API port from `dev docker up`

This installs/logs-in the Stripe CLI if needed, writes the API keys + webhook secret into the central secrets file, propagates them, and starts the webhook listener (3b). If the CLI is already configured it skips straight to listening.

CLI test keys expire every 90 days. Symptom of an expired key: checkout sticks on "We are processing your order" and the worker/api logs show AuthenticationError: Expired API Key provided. Refresh with dev stripe, which detects the expired key and re-runs the link flow, then recreate services (3c).

If you ever set keys by hand, set them in the central file (or server/.env) and keep them on the same account: POLAR_STRIPE_SECRET_KEY (the secret key), POLAR_STRIPE_PUBLISHABLE_KEY and NEXT_PUBLIC_STRIPE_KEY (the publishable key — the browser tokenizes the card with it). pk and sk must belong to one account or the card tokenizes against one account while the backend charges another.

3b. Webhook listener

dev stripe --listen --port <api-port> starts it for you. To run it directly in the background with its output captured to a log you can grep later:

stripe listen \
  --forward-to http://localhost:81NN/v1/integrations/stripe/webhook \
  --forward-connect-to http://localhost:81NN/v1/integrations/stripe/webhook-connect \
  > /tmp/stripe-listen.log 2>&1 &

(If you started it via dev stripe --listen instead, its events print in that command's terminal — redirect to a file as above if you want to grep them in 3e.)

It prints Your webhook signing secret is whsec_.... Both POLAR_STRIPE_WEBHOOK_SECRET and POLAR_STRIPE_CONNECT_WEBHOOK_SECRET must equal that secret. Leave the listener running in the background. If webhooks come back 400 (signature failure), the configured secret is stale — re-sync it to the value the listener prints.