AGENTS.md for Cloudflare Workers

An AGENTS.md for a Hono Worker with D1 + KV: workerd runtime constraints, binding types, isolate-safety rules, and dry-run deploy gates.

# edge-api (Cloudflare Workers)

## Project Overview
Hono API on the Workers runtime. Storage: D1 (SQL) + KV (cache/flags).
TypeScript strict, Vitest with the Workers pool, deployed via wrangler.
This is the Workers runtime, not Node - that constraint shapes everything below.

## Setup & Commands
```bash
pnpm install                    # pnpm only; lockfile is pnpm-lock.yaml
pnpm dev                        # wrangler dev on :8787 (local D1/KV emulation)
pnpm vitest run                 # unit tests in workerd via @cloudflare/vitest-pool-workers
pnpm exec wrangler deploy --dry-run   # validates the bundle without deploying
pnpm exec wrangler d1 migrations apply edge-api --local   # apply migrations locally
```

## Structure
- `src/index.ts` - Hono app + route registration only
- `src/routes/` - one file per resource; `src/lib/` - shared helpers
- `migrations/` - D1 SQL migrations, numbered
- `wrangler.jsonc` - bindings (DB, KV, vars); the deploy contract

## Runtime rules
- No Node-only APIs: no `fs`, no `Buffer` without the compat flag, no
  long-lived globals. Use `crypto.subtle`, `fetch`, Web Streams.
- Bindings come typed from `worker-configuration.d.ts` - regenerate with
  `pnpm exec wrangler types` after editing wrangler.jsonc.
- Per-request state only; module scope survives across requests on the same
  isolate and will leak data between users if you cache carelessly.

## Code Style
- Handlers validate input with Zod at the edge of every route.
- D1 access through prepared statements in `src/lib/db.ts`; no string-built SQL.
- KV values get an explicit `expirationTtl`; unbounded cache keys are a bug.

## Testing
- Tests run inside workerd with real binding emulation - test against the
  binding, don't mock `fetch` to your own routes.

## Boundaries
- Secrets via `wrangler secret put`, never in wrangler.jsonc `vars` or code.
- Never edit an applied D1 migration; add the next numbered file.
- Response streaming: don't buffer whole bodies to transform them; pipe streams.

## PR Guidelines
- The dry-run deploy must pass; include `wrangler.jsonc` changes in the PR
  description since they alter production bindings.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.