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.

Estes exemplos são publicados sob CC0. Use livremente, sem atribuição. São fornecidos como estão, sem garantia de qualquer tipo: revise e adapte ao seu projeto antes de usar, pois você é responsável pelo resultado de aplicá-los.