feat(onboarding): add a demo mode that runs without an API key

[mangit955]

Why

Woopcode's first screen demanded an API key. onboarding/setupWizard.tsx walked welcome → select provider → key URL → paste, and nothing ran until a key was stored. Users who wanted to try the tool before handing over a credential stopped there.

The obvious fix — ship a free-tier Gemini key for people to copy — does not work, for three reasons that have nothing to do with cost:

Shared quota	Free-tier limits attach to the project, not the caller (rate limits). One Woopcode turn is up to 40 provider requests, and free-tier Flash-Lite sits around 15 RPM. Two demo users at once means 429s for everyone — the first impression becomes "this is broken," which is worse than the key prompt.
Revocation	A key printed in a TUI reaches screenshots and blog posts, gets scraped, and is revoked. Every demo user breaks at once and there is no way to push a replacement.
Terms	Unpaid-tier content is used to improve Google's models and may be read by human reviewers; the terms say outright not to send confidential information. A coding agent sends the user's repository.

So the key stays server-side and the client holds a token instead.

What

A demo session stores { type: "demo", apiKey: <token>, baseUrl, demoExpiresAt }. The token is worthless to Google — it authenticates to Woopcode's proxy, which applies the quota and forwards under the real key. That makes the demo revocable, rationable and switchable off without a client release.

Mechanically it is one line. @google/genai takes a full-URL override, so a demo session is an ordinary Gemini client pointed elsewhere:

new GoogleGenAI({ apiKey, ...(baseUrl ? { httpOptions: { baseUrl } } : {}) })

The wire format, the streaming, runtime/loop.ts and the Message type are untouched. baseUrl is honoured only by Google — forwarding it would point the Anthropic or OpenAI SDK at a proxy that answers neither.

The proxy's two refusals were chosen to land on rules runtime/retry.ts already has, so that file needed no change:

Status	Meaning	Existing behaviour
429 + Retry-After	proxy busy	already retryable — the loop backs off, which is how load shedding works
403	daily allowance spent	already fatal — fails immediately instead of spending three attempts on a fixed answer

config/demoAccount.ts owns the lifecycle so nothing else knows the endpoint: a random install id to ration by, session requests with a 10s deadline, expiry helpers, and the exhaustion-message mapping. WOOPCODE_DEMO_URL points it at a local proxy for development.

The disclosure is mandatory and deliberate. The proxy runs a free-tier key, so demo traffic falls under the training and human-review terms above. The wizard states that plainly and requires an explicit y rather than any keypress — a screen dismissed by whatever someone pressed next is not a notice anyone read. Moving to a paid-tier key later is a server-side change needing no client release.

Two pre-existing defects this turned up

Both were found by reading the diff, not by the suite:

• Every path that stored a user's key spread over the previous entry (/login, providers login, the wizard). Upgrading out of demo mode would keep type: "demo", the proxy URL and the old expiry underneath the new key — sending a real Google credential to Woopcode's proxy and expiring it on the demo's schedule. All three now build the entry fresh via apiProviderEntry().
• normalizeConfig rebuilds provider entries field by field, so a field it does not name is dropped on the next read. The docstring claimed extra keys were preserved; that is true at the top level only. A demo entry would have kept its token and lost the URL it is only valid against.

setProvider has the same hazard at runtime and now assigns baseUrl unconditionally, unlike model.

Verified

bun run verify --staged   →  docs lint ok, docs surface ok, type check ok, tests ok — 4 gate(s) passed
                             (re-run by .githooks/pre-commit at commit time, passed again)
bun test $(git ls-files '*.test.ts' '*.test.tsx' | sort -r)
                          →  1698 pass, 0 fail across 105 files

Both regression tests were proven by reverting their fix and confirming the revert applied:

• removing the two lines from normalizeConfig turned 2 tests red, and revealed a cascade worth knowing about — a live demo session resolves as null, because the expiry is dropped alongside the URL;
• removing the httpOptions line turned 3 of the 5 diversion tests red, correctly leaving the two negative ones green.

The baseUrl tests run against a real Bun.serve on a real port, because the failure being guarded is silent: a request that still goes to Google carries a demo token as if it were a Google key. Two of them initially made live calls to Google, Anthropic and OpenAI; those now stub the global fetch, which took the file from 1.72s to 114ms and removed a network dependency from CI.

Not verified, and outside the suite's reach: every wizard screen, including the disclosure keypress, since none of it is rendered in a test; a real 403 or 429 from an actual proxy; and the exhaustion message end to end — the DEMO_EXHAUSTED_MARKER contract is tested as a pure function only.

This is inert until the proxy exists. The default endpoint does not resolve, so no user can reach demo mode; the wizard reports the service as unavailable and falls through to provider selection. The server is a separate private repo and is not in this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
woop-code	Ready	Preview	Aug 10, 2026 2:55am