create-daloy 0.1.18 → 0.1.20

package/README.md

@@ -68,6 +68,7 @@ A production-ready Node.js HTTP server using `@daloyjs/core` with:
 A minimal Cloudflare Worker bootstrap using `@daloyjs/core/cloudflare` with:
 
 - `wrangler.toml` ready to deploy.
+- `secureHeaders` and `requestId` enabled by default, with smaller edge-friendly body and timeout limits.
 - Zod-validated route exposed as `fetch`.
 - A sample test that exercises `app.request(...)`.
 
@@ -78,6 +79,7 @@ A Vercel Edge API bootstrap using `@daloyjs/core/vercel` with:
 - `api/[...path].ts` catch-all routing so DaloyJS owns the API surface.
 - `export const config = { runtime: "edge" }` ready for Vercel Edge.
 - `vercel dev` / `vercel deploy` scripts.
+- `secureHeaders` and `requestId` enabled by default, with smaller edge-friendly body and timeout limits.
 - A health route and bookstore route mirroring the Node starter.
 
 ### `bun-basic`
@@ -86,7 +88,7 @@ A [Bun](https://bun.sh) runtime starter using `@daloyjs/core/bun` with:
 
 - `bun --hot src/index.ts` for instant reloads.
 - `bun test` wired to in-process `app.request(...)` checks.
-- The same secure defaults (`secureHeaders`, `requestId`, `rateLimit`).
+- The same starter security middleware as the Node template (`secureHeaders`, `requestId`, `rateLimit`).
 - A health route and contract-first `/books/:id` route with Zod validation.
 - Hey API codegen wired to `bun run gen:openapi` + `bun run gen:client`.
 
@@ -97,6 +99,7 @@ A [Deno](https://deno.com) runtime starter using `@daloyjs/core/deno` with:
 - A `deno.json` with `deno task dev`, `test`, and `gen:openapi` tasks.
 - `@daloyjs/core` and Zod loaded via `npm:` import-map specifiers.
 - Minimum-permissions dev script (`--allow-net --allow-env --allow-read`).
+- The same starter security middleware as the Node template (`secureHeaders`, `requestId`, `rateLimit`).
 - A health route and contract-first `/books/:id` route with Zod validation.
 - The CLI skips Node-style installs for this template (no `package.json`).
 
@@ -120,16 +123,16 @@ re-run with `--minimal`, or delete the marked blocks by hand later.
 - Zero runtime dependencies (uses only Node built-ins) for a clean supply-chain footprint.
 - A modern terminal experience with Unicode/color capability detection and ASCII fallbacks.
 - Templates are copied verbatim from this package's `templates/` directory.
-- Files prefixed with `_` are renamed (`_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`) to survive npm packing.
+- Files and folders prefixed with `_` are renamed on copy (`_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`, `_agents/` → `.agents/`) to survive npm packing.
 - pnpm-specific `.npmrc` hardening is kept only when you choose `pnpm`; other package managers get a clean project without unsupported config warnings.
 - pnpm projects ship with `ignore-scripts=true`, `minimum-release-age=1440`, `verify-store-integrity=true`, `prefer-frozen-lockfile=true`, and `strict-peer-dependencies=true` by default.
 - The CLI never executes template scripts and never makes network calls beyond the package manager you select.
 
 ## AI agent helper files
 
-Every scaffolded project ships with two files at the repo root that help AI coding agents (Copilot, Claude Code, Cursor, Codex, etc.) understand and work in your project:
+Every scaffolded project ships with two files that help AI coding agents (Copilot, Claude Code, Cursor, Codex, etc.) understand and work in your project:
 
-- `AGENTS.md` — a small, top-of-context file (per the open [AGENTS.md](https://agents.md) convention): one-line project description, package manager / runtime, and the few commands an agent needs. It points to `SKILL.md` for the rest.
-- `SKILL.md` — operational guidance for AI agents: when to use the skill, project structure, core workflows (adding routes, regenerating the OpenAPI spec and client), decision rules, and pitfalls to avoid.
+- `AGENTS.md` (repo root) — a small, top-of-context file (per the open [AGENTS.md](https://agents.md) convention): one-line project description, package manager / runtime, project shape, core rules, and the few commands an agent needs. It links to the full skill below.
+- `.agents/skills/daloyjs-best-practices/SKILL.md` — comprehensive operational guidance following the open `agents/skills/<skill-name>/SKILL.md` convention: when to use the skill, project structure, core workflows (adding routes, regenerating the OpenAPI spec and client), schema and validation conventions, error-handling patterns, middleware order, testing best practices (happy and unhappy paths), security best practices, logging and observability notes, configuration and secrets handling, deployment notes, pitfalls and guardrails, and process expectations.
 
 Both files are tailored to the chosen template (Node, Bun, Deno, Vercel Edge, or Cloudflare Workers), and Node-style templates rewrite their commands to match your selected package manager. They follow the "instruction budget" advice — small root file, progressive disclosure for the rest — so they don't waste agent tokens. Edit or delete them freely; the framework does not depend on them at runtime.

package/bin/create-daloy.mjs

@@ -56,6 +56,10 @@ const RENAME_ON_COPY = new Map([
   ["_gitignore", ".gitignore"],
   ["_npmrc", ".npmrc"],
   ["_env.example", ".env.example"],
+  // Directory: holds skill files for AI coding agents under
+  // `.agents/skills/<skill-name>/SKILL.md`. Templates author this as
+  // `_agents/` so npm pack does not drop the dotfolder during publish.
+  ["_agents", ".agents"],
 ]);
 
 // Templates that target a runtime instead of an npm package manager.
@@ -436,7 +440,16 @@ async function patchPackageJson(dir, projectName, packageManager) {
 
 async function patchTemplateTextFiles(dir, packageManager) {
   if (packageManager === "pnpm") return;
-  for (const fileName of ["README.md", "AGENTS.md", "SKILL.md"]) {
+  // README.md and AGENTS.md sit at the repo root; SKILL.md lives under
+  // `.agents/skills/daloyjs-best-practices/` so it follows the open
+  // "agents/skills" convention. After copyTemplate runs, the `_agents`
+  // template folder has already been renamed to `.agents`.
+  const targets = [
+    "README.md",
+    "AGENTS.md",
+    path.join(".agents", "skills", "daloyjs-best-practices", "SKILL.md"),
+  ];
+  for (const fileName of targets) {
     const file = path.join(dir, fileName);
     if (!existsSync(file)) continue;
     const raw = await readFile(file, "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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.