create-daloy 0.1.17 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
   "type": "module",
   "license": "MIT",

package/templates/bun-basic/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime. Contract-first: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
 
 - Package manager / runtime: Bun.
 
@@ -8,13 +8,34 @@ A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime.
 
 - `bun run dev` — hot-reload server on http://localhost:3000
 - `bun run typecheck` — `tsc --noEmit`
-- `bun test` — run tests with Bun's native test runner
-- `bun run gen:openapi` then `bun run gen:client` — regenerate `generated/openapi.json` + the Hey API client
+- `bun test` — Bun's native test runner
+- `bun run gen:openapi` — write `generated/openapi.json`
+- `bun run gen:client` — write the typed Hey API client
+- `bun run build` — produce `dist/`
 
-## Structure hints
+## Project shape
 
-- Route + middleware wiring lives in `src/build-app.ts` (`buildApp()` factory; pure, no side effects).
-- The HTTP listener is started in `src/index.ts` via `@daloyjs/core/bun`.
-- Codegen reads from `buildApp()` only — never import `src/index.ts` from scripts.
+- `src/build-app.ts` — `buildApp()` factory. Routes, schemas, and middleware live here. **Pure, no side effects.**
+- `src/index.ts` — calls `buildApp()` and starts the listener via `@daloyjs/core/bun`. The only file that opens a port.
+- `scripts/dump-openapi.ts` — imports `buildApp()` and writes `generated/openapi.json`. Codegen reads from `buildApp()` only — never import `src/index.ts` from scripts.
+- `generated/` — machine-written. Do not edit by hand.
+- `tests/` — Bun test files.
 
-For workflows (adding routes, regenerating the SDK, common pitfalls) see [SKILL.md](SKILL.md).
+## Core rules
+
+1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
+2. Validate every input with Zod. Use `.strict()` on top-level object schemas to reject unknown keys at the boundary.
+3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields. Codegen depends on these.
+4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core` — never return raw error responses.
+5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled. They are the project's secure defaults.
+6. Every new route ships with a test that covers a happy path and at least one unhappy path.
+7. After any route change: `bun run gen:openapi && bun run gen:client && bun run typecheck && bun test`.
+
+## Process expectations
+
+- Quality gates must pass before declaring work done: `bun run typecheck` and `bun test`.
+- Regenerate the OpenAPI spec and typed client whenever route shapes change.
+- Bug fixes include a regression test.
+- Never bypass safety checks without a clear reason.
+
+For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/bun-basic/README.md

@@ -40,7 +40,7 @@ bun test
 
 ## What's included
 
-- `@daloyjs/core` with `secureHeaders`, `requestId`, and `rateLimit` enabled.
+- `@daloyjs/core` with starter security middleware: `secureHeaders`, `requestId`, and `rateLimit`.
 <!-- daloy-minimal:strip-start books -->
 - A health route and contract-first `/books/:id` route with Zod validation.
 <!-- daloy-minimal:strip-end books -->

package/templates/bun-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -0,0 +1,233 @@
+# SKILL.md — DaloyJS best practices (Bun)
+
+Operational guidance and best practices for AI coding agents working in this
+DaloyJS [Bun](https://bun.sh) project. This is the project's **single source
+of truth** for how to add routes, write tests, ship secure defaults, and run
+the quality gates. Read this in full before making non-trivial changes.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- Add, modify, or remove HTTP routes in this project.
+- Regenerate the OpenAPI spec or the typed Hey API SDK in `generated/`.
+- Wire up new middleware, validation, or error handling.
+- Add or update tests, run typecheck, or build the project.
+- Harden the API (auth, CORS, rate limits, secrets, dependency hygiene).
+
+Do **not** use this skill for tasks unrelated to the API itself.
+
+## Core principles
+
+DaloyJS is a **contract-first** framework. Internalize these rules — every
+recommendation below follows from them:
+
+1. **The route definition is the contract.** Method, path, request schemas,
+   and response schemas live in one place (`app.route({...})`). The OpenAPI
+   spec, the typed client, and the runtime validation are all derived from
+   it.
+2. **Zod schemas validate at every boundary.** Body, params, query, and
+   headers go through Zod.
+3. **Preserve literal types.** Return `status: 200 as const` and use
+   `z.literal(...)` / `as const` on discriminator fields so the typed
+   client can narrow responses.
+4. **`buildApp()` is pure.** Construction never opens sockets. The HTTP
+   listener lives in `src/index.ts` via `@daloyjs/core/bun`. This lets
+   codegen and tests import `buildApp()` without side effects.
+5. **Secure by default.** `requestId()`, `secureHeaders()`, and
+   `rateLimit()` are registered before route definitions.
+
+## Project shape
+
+- `src/build-app.ts` — exports `buildApp()`. All routes and middleware
+  registered here. **Pure factory.**
+- `src/index.ts` — calls `buildApp()` and starts the Bun HTTP listener via
+  `@daloyjs/core/bun`. The only file allowed to open a port.
+- `scripts/dump-openapi.ts` — imports `buildApp()` and writes
+  `generated/openapi.json`.
+- `openapi-ts.config.ts` — Hey API config; reads `generated/openapi.json`
+  and writes `generated/client/`.
+- `tests/` — Bun test files (`*.test.ts`).
+- `generated/` — **machine-written**. Never edit by hand.
+
+## Commands cheat-sheet
+
+```bash
+bun run dev           # hot-reload server on http://localhost:3000
+bun run typecheck     # tsc --noEmit
+bun test              # Bun's native test runner
+bun run gen:openapi   # write generated/openapi.json
+bun run gen:client    # write generated/client/
+bun run build         # produce dist/
+```
+
+Always run `bun run typecheck` and `bun test` before declaring a task done.
+If a change touches route shapes, also rerun `bun run gen:openapi && bun
+run gen:client` so the client stays in sync.
+
+## Workflow: add a new route
+
+1. **Open `src/build-app.ts`.**
+2. **Design schemas first.** Define request body/params/query/headers and a
+   response body per status code. Prefer `z.object({...}).strict()` for
+   inputs so unknown keys are rejected at the boundary.
+3. **Call `app.route({...})`** with `method`, `path`, `operationId`, `tags`,
+   `responses`, `handler` (plus `request` when accepting input).
+4. **Return `{ status, body, headers? }` from the handler.** Always use
+   `status: 200 as const` so the typed client can narrow.
+5. **Throw typed errors**, do not return raw error responses. Use
+   `NotFoundError`, `BadRequestError`, `UnauthorizedError`,
+   `ForbiddenError`, `ConflictError`, etc.
+6. **Add a test in `tests/<route>.test.ts`** using `app.request(...)` for
+   in-process testing — no port needed.
+7. **Regenerate the contract**: `bun run gen:openapi && bun run gen:client`.
+   Inspect `generated/openapi.json` to confirm the operation shows up.
+8. **Run the quality gates**: `bun run typecheck && bun test`.
+
+### Example: a typed route
+
+```ts
+import { z } from "zod";
+import { NotFoundError } from "@daloyjs/core";
+
+const Book = z.object({ id: z.string(), title: z.string() }).strict();
+const BookParams = z.object({ id: z.string().min(1) }).strict();
+
+app.route({
+  method: "GET",
+  path: "/books/:id",
+  operationId: "getBookById",
+  tags: ["Books"],
+  request: { params: BookParams },
+  responses: {
+    200: { description: "Found", body: Book },
+    404: { description: "Not found" },
+  },
+  handler: async ({ params }) => {
+    const book = await store.find(params.id);
+    if (!book) throw new NotFoundError(`Book ${params.id} not found`);
+    return { status: 200 as const, body: book };
+  },
+});
+```
+
+## Validation & schema conventions
+
+- **Inputs**: use `.strict()` on top-level object schemas to reject unknown
+  keys at the API boundary.
+- **IDs**: prefer `z.string().min(1)`; use `z.string().uuid()` or
+  `z.string().regex(...)` when the shape is known.
+- **Numbers from query strings**: use `z.coerce.number().int().min(...)`.
+- **Optional vs nullable**: `.optional()` for "may be absent",
+  `.nullable()` for "explicitly null". They differ in OpenAPI output.
+- **Pagination**: standardize on `{ items, nextCursor }` cursor pagination.
+- **Discriminated unions**: use `z.discriminatedUnion("kind", [...])`.
+- **Never** call `JSON.parse` or read `req.body` directly. Let the
+  framework validate and pass the typed object to your handler.
+
+## Error handling
+
+- Throw typed errors from `@daloyjs/core` — they serialize to RFC 7807
+  problem responses.
+- Add a `responses[code]` entry for every error you throw.
+- Do not swallow errors. Log via `ctx.log.error(err, "context")` and
+  rethrow if recovery is impossible.
+
+## Middleware
+
+Register middleware **before** route definitions. Order matters.
+
+Keep the secure baseline:
+
+```ts
+app.use(requestId());      // x-request-id for log correlation
+app.use(secureHeaders());  // strict security headers
+app.use(rateLimit({ windowMs: 60_000, max: 120 }));
+```
+
+Add CORS only when needed, with an explicit `origin` allowlist.
+
+## Testing best practices
+
+Tests run with `bun test`. Use **in-process** requests through
+`app.request()` — no HTTP server, no port flakiness.
+
+```ts
+import { test, expect } from "bun:test";
+import { buildApp } from "../src/build-app";
+
+test("GET /healthz returns ok", async () => {
+  const app = buildApp();
+  const res = await app.request("/healthz");
+  expect(res.status).toBe(200);
+  const body = await res.json();
+  expect(body.ok).toBe(true);
+  expect(typeof body.uptime).toBe("number");
+});
+```
+
+Cover both **happy paths and unhappy paths** for every route: valid input,
+validation failures (400), auth failures (401/403), not-found (404),
+conflicts (409), rate limiting (429). For external services, inject an
+in-memory fake via `buildApp({ store })` rather than mocking `fetch`.
+
+Aim for **100% line and function coverage** on routes you add.
+
+## Security best practices
+
+- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled.
+- Never log secrets — filter `authorization`, `cookie`, and any
+  token-bearing fields.
+- Validate secrets from `process.env` (or `Bun.env`) through a Zod schema
+  at boot. Fail fast on missing config.
+- For auth, verify JWT signatures against an allowlist of keys, never
+  trust the `alg` header, always check `exp` / `nbf`.
+- Validate redirects against an allowlist.
+- Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
+  mitigate DoS.
+- Use parameterized queries for database access — never interpolate user
+  input into SQL.
+- Bun ships its own audit story; check `bun pm audit` periodically and
+  pin versions in `bun.lockb`.
+
+## Logging & observability
+
+- Use the framework logger via `ctx.log` — it carries the request id
+  automatically.
+- Avoid `console.log` in production code paths; the structured logger
+  emits JSON for log aggregators.
+
+## Configuration & secrets
+
+- Centralize config parsing in `src/config.ts`, validated by Zod.
+- `.env.example` documents required variables; `.env` is gitignored.
+- Treat config as immutable at runtime.
+
+## Pitfalls and guardrails
+
+- Never import `@daloyjs/core/bun` from `src/build-app.ts` or any script
+  under `scripts/`. That would boot an HTTP listener during codegen.
+- Do not edit files under `generated/` by hand — they are overwritten.
+- Do not weaken response literal types (`as const`); the typed client
+  depends on them.
+- Do not return errors as `{ status: 4xx, body: {...} }`. Throw a typed
+  error.
+- Do not add runtime dependencies without checking the hardened `.npmrc` (installs wait 24h after publish by default).
+- Avoid Node-only APIs in code that may also run on the Cloudflare/Vercel
+  templates; the Bun runtime is web-standard friendly but check before
+  reaching for `node:fs` etc.
+
+## Process expectations
+
+- Every new feature ships with happy-path and unhappy-path tests.
+- Bug fixes include a regression test.
+- `bun run typecheck` and `bun test` must pass before completion.
+- Run `bun run gen:openapi && bun run gen:client` when route shapes
+  change; commit the updated artifacts.
+- Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent with the
+  code.
+
+## More
+
+- Framework docs: <https://daloyjs.dev/docs>
+- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/cloudflare-worker/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. Contract-first: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Cloudflare Workers (Web Standard `Request`/`Response`).
@@ -8,13 +8,35 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. Co
 ## Commands
 
 - `pnpm dev` — `wrangler dev` on http://localhost:8787
-- `pnpm typecheck`
-- `pnpm test`
+- `pnpm typecheck` — `tsc --noEmit`
+- `pnpm test` — run test suite
 - `pnpm deploy` — `wrangler deploy`
+- `pnpm audit` — supply-chain audit
 
-## Structure hints
+## Project shape
 
-- Worker entrypoint: `src/index.ts`. Builds the `App`, registers routes/middleware, and exports `default { fetch: toFetchHandler(app) }` from `@daloyjs/core/cloudflare`.
-- `wrangler.toml` controls runtime config, bindings, and deploy targets.
+- `src/index.ts` — Worker entrypoint. Builds the `App`, registers routes/middleware, and exports `default { fetch: toFetchHandler(app) }` from `@daloyjs/core/cloudflare`.
+- `wrangler.toml` — Worker configuration (name, compatibility date, bindings, routes).
+- `tests/` — test files.
 
-For workflows (adding routes, deploy, common pitfalls) see [SKILL.md](SKILL.md).
+## Core rules
+
+1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
+2. Validate every input with Zod. Use `.strict()` on top-level object schemas to reject unknown keys at the boundary.
+3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields.
+4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core`.
+5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled. For high-traffic routes, attach Cloudflare's native rate-limit binding (the in-memory limiter resets per isolate).
+6. Stay on the Workers runtime: only Web Standards APIs + Cloudflare bindings. No `node:` modules unless `nodejs_compat` is enabled and required.
+7. Bindings flow through `env`. Read KV/D1/R2/secrets from the `env` argument; never read them via globals.
+8. Long-running work belongs in `ctx.waitUntil(...)`, not blocking the response.
+9. Every new route ships with a test that covers a happy path and at least one unhappy path.
+
+## Process expectations
+
+- Quality gates must pass before declaring work done: `pnpm typecheck` and `pnpm test`.
+- Bug fixes include a regression test.
+- Pin `compatibility_date` in `wrangler.toml`; only bump it deliberately.
+- For deploys, ensure the user has run `wrangler login`; do not authenticate on their behalf.
+- Never bypass safety checks without a clear reason.
+
+For the full workflow — adding routes step-by-step, bindings, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/cloudflare-worker/README.md

@@ -16,3 +16,9 @@ pnpm deploy
 ```
 
 `@daloyjs/core/cloudflare` exposes `toFetchHandler(app)`, so the same `App` you would use on Node also runs on Workers.
+
+## What's included
+
+- `@daloyjs/core/cloudflare` with starter security middleware: `secureHeaders` and `requestId`.
+- Smaller edge-friendly body and timeout limits in the generated app.
+- `wrangler.toml` ready for local development and deploys.

package/templates/cloudflare-worker/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -0,0 +1,236 @@
+# SKILL.md — DaloyJS best practices (Cloudflare Workers)
+
+Operational guidance and best practices for AI coding agents working in this
+DaloyJS **Cloudflare Workers** project. This is the project's **single
+source of truth** for how to add routes, write tests, ship secure defaults,
+and run the quality gates. Read this in full before making non-trivial
+changes.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- Add, modify, or remove HTTP routes in this Worker.
+- Adjust middleware, validation, or error handling.
+- Change Worker bindings (KV, D1, R2, Queues, env vars) in `wrangler.toml`.
+- Run tests/typecheck or deploy the Worker.
+- Harden the API (auth, CORS, rate limits, secrets, dependency hygiene).
+
+Do **not** use this skill for tasks unrelated to the API itself.
+
+## Core principles
+
+DaloyJS is a **contract-first** framework. On Workers, additionally:
+
+1. **Stay on the Workers runtime.** Only Web Standards APIs and
+   Cloudflare-specific bindings. No `node:` modules unless
+   `nodejs_compat` is enabled in `wrangler.toml` and the user explicitly
+   opts in.
+2. **The route definition is the contract.** Method, path, request
+   schemas, and response schemas live in one place (`app.route({...})`).
+3. **Zod schemas validate at every boundary.**
+4. **Preserve literal types.** Return `status: 200 as const`.
+5. **Secure by default.** `requestId()`, `secureHeaders()`, and
+   `rateLimit()` are registered. Note: the in-memory rate limiter resets
+   per isolate — for production traffic, prefer Cloudflare's native
+   rate-limit binding.
+6. **Bindings flow through `env`.** Read KV/D1/R2/secrets from the
+   `env` argument to `fetch`, never from globals.
+
+## Project shape
+
+- `src/index.ts` — the Worker entrypoint. Builds the `App`, registers
+  routes/middleware, and exports `default { fetch: toFetchHandler(app) }`
+  from `@daloyjs/core/cloudflare`.
+- `wrangler.toml` — Worker config (name, compatibility date, bindings,
+  routes).
+- `tests/` — test files using Workers-compatible test runners (e.g.
+  `vitest` + `@cloudflare/vitest-pool-workers`) or in-process
+  `app.request(...)` for pure logic.
+
+## Commands cheat-sheet
+
+```bash
+pnpm dev          # wrangler dev on http://localhost:8787
+pnpm typecheck    # tsc --noEmit
+pnpm test         # run test suite
+pnpm deploy       # wrangler deploy
+pnpm audit        # supply-chain audit
+```
+
+Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
+
+## Workflow: add a new route
+
+1. **Open `src/index.ts`.**
+2. **Design schemas first.** Use `z.object({...}).strict()` for inputs.
+3. **Call `app.route({...})`** with `method`, `path`, `operationId`,
+   `tags`, `responses`, `handler` (plus `request` when accepting input).
+4. **Return `{ status, body, headers? }`** with `status: 200 as const`.
+5. **Throw typed errors** (`NotFoundError`, `BadRequestError`, etc.).
+6. **Add a test** under `tests/`. Use `app.request(...)` for pure logic;
+   use `unstable_dev` (Wrangler) or `@cloudflare/vitest-pool-workers`
+   when you need bindings.
+7. **Run the quality gates**: `pnpm typecheck && pnpm test`.
+
+### Example: a typed route with bindings
+
+```ts
+import { z } from "zod";
+import { App, NotFoundError, rateLimit, requestId, secureHeaders } from "@daloyjs/core";
+import { toFetchHandler } from "@daloyjs/core/cloudflare";
+
+interface Env {
+  BOOKS: KVNamespace;
+  JWT_SECRET: string;
+}
+
+const Book = z.object({ id: z.string(), title: z.string() }).strict();
+
+function buildApp(env: Env) {
+  const app = new App({ bodyLimitBytes: 1024 * 1024, requestTimeoutMs: 5_000 });
+  app.use(requestId());
+  app.use(secureHeaders());
+  app.use(rateLimit({ windowMs: 60_000, max: 120 }));
+
+  app.route({
+    method: "GET",
+    path: "/books/:id",
+    operationId: "getBookById",
+    tags: ["Books"],
+    request: { params: z.object({ id: z.string().min(1) }).strict() },
+    responses: {
+      200: { description: "Found", body: Book },
+      404: { description: "Not found" },
+    },
+    handler: async ({ params }) => {
+      const raw = await env.BOOKS.get(params.id, "json");
+      if (!raw) throw new NotFoundError(`Book ${params.id} not found`);
+      return { status: 200 as const, body: Book.parse(raw) };
+    },
+  });
+
+  return app;
+}
+
+export default {
+  fetch: (req: Request, env: Env, ctx: ExecutionContext) =>
+    toFetchHandler(buildApp(env))(req, env, ctx),
+};
+```
+
+## Validation & schema conventions
+
+- **Inputs**: use `.strict()` on top-level object schemas.
+- **IDs**: prefer `z.string().min(1)`; use `z.string().uuid()` when
+  applicable.
+- **Numbers from query strings**: `z.coerce.number().int().min(...)`.
+- **Optional vs nullable**: differ in OpenAPI output.
+- **Pagination**: standardize on `{ items, nextCursor }` cursor
+  pagination.
+- **Discriminated unions**: `z.discriminatedUnion("kind", [...])`.
+
+## Error handling
+
+- Throw typed errors from `@daloyjs/core` — they serialize to RFC 7807
+  problem responses.
+- Add a `responses[code]` entry for every error you throw.
+- For unexpected errors, let them bubble. The framework's error
+  middleware converts them to a 500 problem response.
+
+## Middleware
+
+Register middleware **before** route definitions. Order matters.
+
+Keep the secure baseline (`requestId`, `secureHeaders`, `rateLimit`).
+Add CORS only when needed, with an explicit `origin` allowlist.
+
+## Working with bindings
+
+1. Add the binding (`[[kv_namespaces]]`, `[[d1_databases]]`, `[vars]`,
+   etc.) to `wrangler.toml`.
+2. Type the binding in the `Env` interface inside `src/index.ts`.
+3. Pass `env` into `buildApp(env)` so handlers receive bindings via
+   closure or factory argument. **Never read bindings via globals.**
+4. Store secrets via `wrangler secret put` — they appear on `env` but
+   are not committed to `wrangler.toml`.
+
+## Testing best practices
+
+Two patterns:
+
+- **In-process** with `app.request(...)` for pure logic that does not
+  need bindings.
+- **Workers-aware** runners (`@cloudflare/vitest-pool-workers` or
+  Wrangler `unstable_dev`) when KV/D1/etc. are involved.
+
+Cover **happy paths and unhappy paths** for every route: valid input,
+validation failures (400), auth failures (401/403), not-found (404),
+conflict (409), rate limiting (429). For external services, inject an
+in-memory fake into `buildApp(env)` during tests.
+
+Aim for **100% line and function coverage** on the routes you add.
+
+## Security best practices
+
+- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled. For
+  high-traffic routes, attach Cloudflare's native rate-limit binding so
+  limits are shared across isolates.
+- Never log secrets — filter `authorization`, `cookie`, etc.
+- Read secrets via `wrangler secret put`, never via plain `[vars]` in
+  `wrangler.toml`.
+- For auth, verify JWT signatures with the Web Crypto API
+  (`crypto.subtle`). Never trust the `alg` header from the token.
+- Validate redirects against an allowlist.
+- Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
+  mitigate DoS.
+- Workers have CPU and bundle-size limits; be cautious about adding
+  heavy dependencies. Run `wrangler deploy --dry-run --outdir=dist` to
+  inspect bundle size.
+- Use `ctx.waitUntil(...)` for fire-and-forget work so the response
+  returns promptly.
+- Pin a `compatibility_date` in `wrangler.toml` and only bump it
+  deliberately. New compat flags can change runtime semantics.
+
+## Logging & observability
+
+- Use `ctx.log` — it carries the request id.
+- `console.log` in Workers shows up in `wrangler tail`. Prefer
+  structured logs through the framework logger.
+- For tracing, the `tracing()` middleware emits OpenTelemetry-compatible
+  spans; wire up a Workers-friendly exporter when needed.
+
+## Configuration & secrets
+
+- Centralize env shape in an `Env` interface.
+- Validate env via Zod once per request (cheap with Workers) or on first
+  access via a memoized helper.
+- Treat env as immutable during a request.
+
+## Pitfalls and guardrails
+
+- Use `toFetchHandler(app)` from `@daloyjs/core/cloudflare` — never
+  hand-roll a `fetch(req, env, ctx)` adapter.
+- Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only
+  `@daloyjs/core` and `@daloyjs/core/cloudflare`.
+- Avoid Node-only APIs (`Buffer`, `fs`, `process` beyond
+  `process.env`) unless `nodejs_compat` is enabled and required.
+- Do not weaken response literal types (`as const`).
+- Do not return errors as `{ status: 4xx, body }`. Throw a typed error.
+- Do not add runtime dependencies without checking the hardened `.npmrc` (installs wait 24h after publish by default).
+- Long-running work belongs in `ctx.waitUntil(...)`, not blocking the
+  response.
+
+## Process expectations
+
+- Every new feature ships with happy-path and unhappy-path tests.
+- Bug fixes include a regression test.
+- `pnpm typecheck` and `pnpm test` must pass before completion.
+- For deploys, ask the user to run `wrangler login` first if needed —
+  do not attempt to authenticate on their behalf.
+- Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent.
+
+## More
+
+- Framework docs: <https://daloyjs.dev/docs>
+- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/deno-basic/AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runtime. Contract-first: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runtime. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
 
-- Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` specifiers in `deno.json`.
+- Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` and `jsr:` specifiers in `deno.json`.
 
 ## Commands
 
@@ -11,12 +11,33 @@ A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runti
 - `deno task test`
 - `deno task gen:openapi` — write `generated/openapi.json`
 
-The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint yet). Run `npx @hey-api/openapi-ts` against `generated/openapi.json` if you need the client.
+The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint yet). Run `npx @hey-api/openapi-ts -i generated/openapi.json -o generated/client` if you need the client.
 
-## Structure hints
+## Project shape
 
-- Route + middleware wiring lives in `src/build-app.ts` (`buildApp()` factory; pure, no side effects).
-- The HTTP listener is started in `src/main.ts` via `@daloyjs/core/deno`.
-- Codegen reads from `buildApp()` only — never import `src/main.ts` from scripts.
+- `src/build-app.ts` — `buildApp()` factory. Routes, schemas, and middleware live here. **Pure, no side effects.**
+- `src/main.ts` — calls `buildApp()` and starts the listener via `@daloyjs/core/deno`. The only file that opens a port.
+- `scripts/dump-openapi.ts` — imports `buildApp()` and writes `generated/openapi.json`. Codegen reads from `buildApp()` only — never import `src/main.ts` from scripts.
+- `deno.json` — tasks, import map, and `npm:` specifiers. There is no `package.json` in this project.
+- `generated/` — machine-written. Do not edit by hand.
+- `tests/` — Deno test files.
 
-For workflows (adding routes, regenerating the spec, common pitfalls) see [SKILL.md](SKILL.md).
+## Core rules
+
+1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
+2. Validate every input with Zod. Use `.strict()` on top-level object schemas to reject unknown keys at the boundary.
+3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields.
+4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core`.
+5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled.
+6. Deno permissions are part of the contract — keep `--allow-net --allow-env --allow-read` narrow; never use `--allow-all`.
+7. Every new route ships with a test that covers a happy path and at least one unhappy path.
+8. After any route change: `deno task gen:openapi && deno task typecheck && deno task test`.
+
+## Process expectations
+
+- Quality gates must pass before declaring work done: `deno task typecheck` and `deno task test`.
+- Regenerate the OpenAPI spec whenever route shapes change.
+- Bug fixes include a regression test.
+- Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json` here.
+
+For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/deno-basic/README.md

@@ -44,7 +44,7 @@ deno task test
 ## What's included
 
 - `@daloyjs/core` (loaded via `npm:` specifiers in `deno.json`).
-- `secureHeaders`, `requestId`, and `rateLimit` enabled by default.
+- Starter security middleware: `secureHeaders`, `requestId`, and `rateLimit`.
 <!-- daloy-minimal:strip-start books -->
 - A health route and contract-first `/books/:id` route with Zod validation.
 <!-- daloy-minimal:strip-end books -->