chore: modernize setup, dependencies, and project docs

AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md
+
+This file gives coding agents fast context for working in this repository.
+
+## Project summary
+
+Email-to-RSS is a Cloudflare Worker that ingests newsletters from ForwardEmail and exposes them as RSS feeds.
+
+Core goals:
+
+- Self-hosted and private
+- Free-tier-friendly (Cloudflare + ForwardEmail)
+- Minimal operational overhead
+
+## Runtime and stack
+
+- Runtime: Cloudflare Workers
+- Framework: Hono (`src/index.ts` + `src/routes/*`)
+- Storage: Cloudflare KV (`EMAIL_STORAGE` binding)
+- Typescript + Vitest for development/testing
+
+## Important files
+
+- `setup.sh`: bootstraps local setup, KV namespaces, secrets, and local Wrangler config
+- `wrangler-example.toml`: template used by setup
+- `src/index.ts`: app boot + CORS + inbound IP allowlist middleware
+- `src/routes/inbound.ts`: email ingestion endpoint
+- `src/routes/rss.ts`: RSS rendering endpoint
+- `src/routes/admin.ts`: admin UI and feed/email management
+- `src/test/setup.ts`: test runtime mocks (KV + Cache)
+
+## KV data model
+
+Current keys used by routes:
+
+- `feeds:list` -> `{ feeds: Array<{ id, title }> }`
+- `feed:<feedId>:config` -> feed config object
+- `feed:<feedId>:metadata` -> `{ emails: Array<{ key, subject, receivedAt }> }`
+- `feed:<feedId>:<timestamp>` -> stored email body/metadata
+
+Notes:
+
+- Some utility files contain alternate key helpers not used by routes (`src/utils/storage.ts`).
+- Keep route behavior and key schema consistent when refactoring.
+
+## Setup/deploy workflow
+
+1. `npx wrangler login`
+2. `bash setup.sh`
+3. Configure ForwardEmail DNS records in Cloudflare
+4. `npm run deploy`
+
+`setup.sh` assumes Wrangler v4 command syntax (`wrangler kv namespace ...`).
+
+## Development workflow
+
+- Install: `npm install`
+- Test: `npm test`
+- Build (dry-run deploy bundle): `npm run build`
+- Dev server: `npm run dev`
+
+## Testing notes
+
+- Tests run in Node environment (`vitest.config.ts`), not DOM.
+- Hono v4 test requests pass env as the 3rd arg: `app.request(path, init, env)`.
+- Some tests intentionally hit validation errors; stderr logs are expected.
+
+## Security assumptions
+
+- Inbound endpoint only accepts requests from ForwardEmail source IPs.
+- Admin access uses cookie gate and password stored in Worker secret (`ADMIN_PASSWORD`).
+- Do not hardcode credentials or domain-specific secrets into tracked files.
+
+## Cloudflare/Wrangler conventions
+
+- `wrangler.toml` is generated locally from `wrangler-example.toml`.
+- Keep `compatibility_date` current on meaningful runtime upgrades.
+- Prefer explicit `--env production` for deploy/secret commands.
+
+## If you change behavior
+
+Update all of the following together:
+
+- `README.md`
+- `setup.sh` (if setup/deploy assumptions changed)
+- tests under `src/routes/*.test.ts` and `src/test/setup.ts`