minshop: Instructions file for Codex

AGENTS.md — working on minshop

A guide for contributors and automated tooling making changes to minshop: a small, full-Cloudflare ecommerce store (Astro 7 SSR on Workers + D1 + R2 + Stripe / Lightning). Read this before editing. It's the map, the rules, the recipes, and the traps.

The loop (run this constantly)

nvm use 22         # REQUIRED — the supported toolchain runs on Node 22
npm run verify     # complete storefront + D1 + MCP green/red gate

npm run verify is the single signal that a change is sound: it runs unit tests, full Astro diagnostics, the production build, the clean-room D1 integration, and the MCP typecheck/deployment dry run. If it's green, the change holds together. Run it after every meaningful edit, not just at the end.

Other commands: npm run dev (astro dev), npm run preview (wrangler dev = production mode, for testing middleware/auth), npm run db:migrate (local D1), npm test.

Inspecting local data: use Local Explorer, not the CLI

Any local dev server (npm run dev, npm run preview) serves Cloudflare's Local Explorer — a UI at /cdn-cgi/explorer and a self-describing REST API at /cdn-cgi/explorer/api covering D1, KV, R2, Durable Objects and Workflows. It reads the same local state the app does, with no setup.

Prefer it over npx wrangler d1 execute --local for reads and fixture setup: that spawns a process each time (~1.2s) where this is an HTTP call (~0.02s) — roughly 70x, which is the difference between checking state freely and avoiding it. GET /cdn-cgi/explorer/api returns the OpenAPI spec, so the endpoints are discoverable rather than memorized. The D1 database id is the binding name:

curl -s localhost:4321/cdn-cgi/explorer/api/d1/database/DB/raw \
  -H 'content-type: application/json' \
  -d '{"sql":"SELECT status, COUNT(*) FROM orders GROUP BY status"}'

Local only, and unauthenticated on the dev origin — it is never exposed on a deployed Worker, but do not bind a dev server to a public interface. Anything touching --remote still goes through wrangler. The API reports itself as version 0.0.1, so use it for working loops, not as the basis of a test gate.