Stack Preview

stack-preview

/live-preview tunnels one dev server. The Vicoa dashboard is not one: its browser code calls the REST backend and holds a WebSocket to the agent-facing server, so a tunnel to the web app alone cannot even sign in. This skill runs every piece from the checkout and puts them behind one origin:

browser ──https──▶ tunnel ──▶ proxy :P ─┬─ /ws          → server   (uvicorn, realtime)
                                        ├─ /api/v1/...  → backend  (uvicorn, REST)
                                        └─ everything   → web      (next dev, hot reload)
                   backend + server ──▶ Postgres (throwaway Docker container)

One origin means one link to hand over, no CORS, and realtime works through the tunnel. Everything binds 127.0.0.1; only the tunnel is public.

The script is scripts/stack-preview.sh in this skill's directory. It previews the git checkout of the current directory (a worktree is fine), or --repo DIR.

1. Start

<skill-dir>/scripts/stack-preview.sh up

It creates and migrates the database, opens the tunnel, starts server, backend and web, seeds two accounts, closes sign-up, then checks the page, the API and the WebSocket handshake through the public URL. About 30 s, longer on a first web compile. The result is * key: value lines, the same contract as /live-preview, so the Vicoa app opens the link in Live Preview.

• status: error means one of those public checks failed. Read the log it names under state:, fix the problem, down, up. Don't hand over a link that failed its own check.
• "a next dev server already serves apps/web": that server isn't yours. Don't stop it; ask the user.
• Running up again while the preview is up just prints its status.

Flags:

• --env-file FILE: KEY=value lines for backend and server, e.g. Stripe test keys, or a PYTHONPATH that adds an overlay package. The preview's own database, URLs and auth settings always win. Never pass a file that holds production credentials.
• --allow-signup: leave sign-up open (for reviewing the sign-up flow). By default it closes after seeding, because anyone with the link can reach the server.
• --provider ngrok: by default cloudflared is tried first, then ngrok.
• --auth supabase: only when the user asks to review the mobile app, which can only sign in with Supabase. Everything else uses the default (builtin), and every up without the flag is builtin again. It signs in with a hosted Supabase project instead of seeded accounts. Export SUPABASE_URL and SUPABASE_ANON_KEY first (apps/mobile/env.json has them). Identity only: the data stays in the preview's database. There are no Ada/Bea accounts, so seeds write rows for the person who signs in (find them in users by email after their first sign-in). Point the app at the preview in the debug branch of apps/mobile/lib/custom_code/actions/vicoa_api_config.dart (https://<public_url> and wss://<public_url>/ws), and never commit that file.

2. Seed what the change needs

A fresh database holds only Ada (ada@example.com, owner) and Bea (bea@example.com, a second person for sharing and permissions). The passwords are in the output. An empty dashboard reviews nothing, so read the diff (git diff origin/main...), list the screens and states it touches, and seed those:

• Put seed scripts in the state dir (state: in the output), never in the repo.
• Prefer the API, acting as a real user: curl -H "Authorization: Bearer $OWNER_TOKEN" "$PREVIEW_BACKEND/api/v1/...". This runs the same code the reviewer will use.
• Write rows directly only for things no endpoint creates (agent sessions and their messages, automation runs). A .py seed can import the models from shared.database. On a branch older than the fix that registers AgentProfile there, flushing an Automation or AgentInstance fails with NoReferencedTableError: agent_profiles; add import shared.database.agent_profile_models.
• Session status COMPLETED means archived: default lists and share links hide it. For a session that looks finished, use AWAITING_INPUT.
• Run stack-preview.sh seed FILE. A .py runs in the backend venv with PYTHONPATH set; anything else runs under bash. Seeds get PREVIEW_URL, PREVIEW_BACKEND, DATABASE_URL, OWNER_EMAIL/PASSWORD/TOKEN and the VIEWER_* equivalents. stack-preview.sh env prints the same exports for ad-hoc curl.
• Use invented data only. The link is public.