Cloudflare Workers rules

# AGENTS.md: Cloudflare Workers

TypeScript Worker deployed with Wrangler. Config is in `wrangler.jsonc` (or `wrangler.toml` in older projects).

## Commands
- Local dev: `npx wrangler dev`. Logs from a deployed Worker: `npx wrangler tail`.
- After changing bindings or config: `npx wrangler types` to regenerate the `Env` types, then `npx tsc --noEmit`.
- Tests: `npx vitest run` with `@cloudflare/vitest-pool-workers` if configured.
- Done means: types regenerated if bindings changed, type-check and tests pass, and the route works under `wrangler dev`.

## Never without the human asking in this session
- `npx wrangler deploy`, `wrangler versions deploy` or any command with `--remote` against production data.
- `wrangler d1 migrations apply <db> --remote`, `wrangler kv` writes or `wrangler r2 object` writes on production namespaces.
- Changing `compatibility_date`, routes, custom domains or account settings.

## Runtime rules
- No request data in module scope. Isolates are reused across requests; globals leak between users.
- Use bindings (KV, D1, R2, Queues, Durable Objects, service bindings) from `env`, not the REST API with a token.
- Background work after the response goes in `ctx.waitUntil(promise)`. Never leave a promise floating.
- D1: always `env.DB.prepare(sql).bind(...)`; never interpolate values into SQL. Schema changes are migration files
  (`npx wrangler d1 migrations create <db> <name>`), applied with `--local` first.
- Large bodies: stream them; do not buffer whole files in memory.
- Node APIs need the `nodejs_compat` compatibility flag. Check before importing `node:*` modules.
- Validate input and return proper status codes and `Content-Type`. Set CORS headers only for listed origins.

## Secrets
- Secrets with `npx wrangler secret put <NAME>`; local values in `.dev.vars`, which stays gitignored.
- Never put secrets in `vars` in `wrangler.jsonc`, in code or in test fixtures.

## Docs
- The Cloudflare docs MCP server (`cloudflare-docs`) searches current Workers, D1, R2 and Wrangler docs. Check APIs
  and limits there instead of relying on memory. New endpoints: use the `worker-endpoint` skill.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `worker-endpoint`. Use them when their description matches the task.
- MCP servers for this project are in `.mcp.json`. If a server is not connected, tell the human rather than working around it.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Cloudflare Workers rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/cloudflare-workers/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `worker-endpoint`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Cloudflare Workers rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/cloudflare-workers/ -->

---
name: worker-endpoint
description: Add an endpoint to a Cloudflare Worker using bindings from env, validated input, parameterised D1 queries, waitUntil for background work and a local check. Use when adding or changing a Worker route.
---

# Worker endpoint

1. Read `wrangler.jsonc` for bindings and flags, and the Worker's router or `fetch` handler.
2. If you need a new binding, add it to `wrangler.jsonc` and run `npx wrangler types`. Ask before creating remote
   resources (`wrangler d1 create`, `wrangler kv namespace create`).
3. Write the handler like `references/index.ts`: parse and validate input, use `env` bindings, prepared D1 statements,
   JSON responses with the right status, and `ctx.waitUntil` for work that can finish after the response.
4. If the schema changes: `npx wrangler d1 migrations create <db> <name>`, write the SQL, apply with `--local`.
5. Run `npx tsc --noEmit` and the tests. Start `npx wrangler dev` and call the route once with curl or the test client.
6. Report the route, bindings used, migrations added and check results. Do not deploy.

// Example Worker: bindings from env, validated input, prepared D1 statements, waitUntil for background work.
// The Env interface is what `npx wrangler types` generates for these bindings.

export interface Env {
  DB: D1Database;
  CACHE: KVNamespace;
  ALLOWED_ORIGIN: string;
}

type Note = { id: number; text: string; created_at: string };

const json = (data: unknown, status = 200, origin?: string): Response =>
  new Response(JSON.stringify(data), {
    status,
    headers: {
      "Content-Type": "application/json; charset=utf-8",
      ...(origin ? { "Access-Control-Allow-Origin": origin, Vary: "Origin" } : {}),
    },
  });

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);
    const origin = request.headers.get("Origin") === env.ALLOWED_ORIGIN ? env.ALLOWED_ORIGIN : undefined;

    if (request.method === "GET" && url.pathname.startsWith("/notes/")) {
      const id = Number(url.pathname.slice("/notes/".length));
      if (!Number.isInteger(id) || id < 1) return json({ error: "id must be a positive integer" }, 400, origin);
      const cached = await env.CACHE.get<Note>(`note:${id}`, "json");
      if (cached) return json(cached, 200, origin);
      const note = await env.DB.prepare("SELECT id, text, created_at FROM notes WHERE id = ?").bind(id).first<Note>();
      if (!note) return json({ error: "not found" }, 404, origin);
      ctx.waitUntil(env.CACHE.put(`note:${id}`, JSON.stringify(note), { expirationTtl: 300 }));
      return json(note, 200, origin);
    }

    if (request.method === "POST" && url.pathname === "/notes") {
      let body: unknown;
      try {
        body = await request.json();
      } catch {
        return json({ error: "invalid JSON" }, 400, origin);
      }
      const text = typeof body === "object" && body !== null && "text" in body ? (body as { text: unknown }).text : undefined;
      if (typeof text !== "string" || text.length === 0 || text.length > 2000) {
        return json({ error: "text must be 1 to 2000 characters" }, 400, origin);
      }
      const row = await env.DB.prepare("INSERT INTO notes (text) VALUES (?) RETURNING id, text, created_at")
        .bind(text)
        .first<Note>();
      return json(row, 201, origin);
    }

    return json({ error: "not found" }, 404, origin);
  },
} satisfies ExportedHandler<Env>;

{
  "mcpServers": {
    "cloudflare-docs": {
      "type": "http",
      "url": "https://docs.mcp.cloudflare.com/mcp"
    }
  }
}