Random-prompt endpoint

Generated from the grilling session at /grilling-transcripts/random-prompt. This is the smallest possible TDD demo on this site — one function, one observable contract, three tests.

Problem

The site exposes many prompts. A visitor who wants to “just see one” shouldn’t have to pick. The endpoint also gives the talk a clean backend slice to TDD live on stage: no UI to debate, no design choices to grill, just one function whose contract fits on a slide.

User stories

• As a visitor, hitting /api/random-prompt returns one prompt encoded as JSON.
• As a visitor, refreshing the endpoint usually returns a different prompt — the response is not cached.
• As a visitor, the response is self-sufficient: it contains the prompt’s title, description, body, tags and demo association without needing a second request.

Non-goals

• A UI on top of the endpoint in this slice. Backend only.
• Weighting, recency bias, or per-visitor randomness.
• Authentication or rate limiting. Vercel handles the latter and the former isn’t required.

Acceptance

• GET /api/random-prompt → 200, content-type: application/json, body contains a top-level prompt object.
• 50 sequential calls return at least 5 distinct prompt ids when the corpus contains ≥ 5 prompts.
• Empty corpus → 503 with body { "error": "no prompts indexed" }.
• Every response includes cache-control: no-store.

Tracer bullets

1. Endpoint stub returning a constant prompt — red → green on the shape test (status, content-type, presence of prompt).
2. Random selection over the bundled corpus — red → green on the randomness test (50 calls, ≥ 5 distinct).
3. Empty-corpus handling — red → green on the 503 edge case.

Each bullet is one commit, ready to demo as a clean red/green/refactor cycle in /tdd.