create-daloy 0.1.17 → 0.1.19

package/templates/vercel-edge/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -0,0 +1,204 @@
+# SKILL.md — DaloyJS best practices (Vercel Edge)
+
+Operational guidance and best practices for AI coding agents working in this
+DaloyJS **Vercel Edge** 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.
+- Adjust middleware, validation, or error handling.
+- Run tests or typecheck the project.
+- Deploy or troubleshoot the Edge runtime entrypoint.
+- 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 Vercel Edge, additionally:
+
+1. **Stay on the Edge runtime.** Only Web Standards APIs (no `node:`
+   modules, no `fs`, no `Buffer`). If a feature requires Node APIs, the
+   user must switch to a Node template.
+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 before route definitions. Note the
+   in-memory rate limiter resets per instance — for high-traffic
+   deployments, prefer Vercel's native rate-limiting (e.g.
+   `@vercel/edge` + KV) or an external store.
+6. **One catch-all entrypoint.** `api/[...path].ts` owns all routing so
+   DaloyJS can generate a unified OpenAPI spec.
+
+## Project shape
+
+- `api/[...path].ts` — the Edge entrypoint. Builds the `App`, registers
+  routes/middleware, and exports `default toEdgeHandler(app)` plus
+  `export const config = { runtime: "edge" }`.
+- `vercel.json` — Vercel build/runtime configuration.
+- `tests/` — test files (`*.test.ts`).
+
+## Commands cheat-sheet
+
+```bash
+pnpm dev          # local Vercel dev server on http://localhost:3000
+pnpm typecheck    # tsc --noEmit
+pnpm test         # run test suite
+pnpm deploy       # deploy to Vercel
+pnpm audit        # supply-chain audit
+```
+
+Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
+
+## Workflow: add a new route
+
+1. **Open `api/[...path].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.)
+   from `@daloyjs/core`.
+6. **Add a test** under `tests/` using in-process `app.request(...)`.
+7. **Run the quality gates**: `pnpm typecheck && pnpm 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.
+- **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.
+
+## 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.
+
+## Testing best practices
+
+Tests use in-process `app.request(...)` — no port, no Edge runtime
+needed for unit tests.
+
+```ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import handler from "../api/[...path].ts";
+
+// Either import the underlying app, or test via the Edge handler's
+// fetch interface by passing a Web Request.
+test("GET /healthz returns ok", async () => {
+  const res = await handler(new Request("http://local/healthz"));
+  assert.equal(res.status, 200);
+});
+```
+
+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 during tests.
+
+Aim for **100% line and function coverage** on the routes you add.
+
+## Security best practices
+
+- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled. For
+  production traffic, back rate-limiting with Vercel KV or another
+  shared store so limits apply across instances.
+- Never log secrets — filter `authorization`, `cookie`, etc.
+- Read secrets from `process.env` (available on Edge). Validate via Zod
+  at module load.
+- 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.
+- Edge functions have small bundle and CPU limits; be cautious about
+  adding heavy dependencies. Inspect bundle size during deploy.
+- Pin Vercel project settings (regions, runtime version) explicitly in
+  `vercel.json` rather than relying on dashboard defaults.
+
+## Logging & observability
+
+- Use `ctx.log` — it carries the request id.
+- `console.log` on Edge shows up in Vercel's runtime logs; the framework
+  logger emits structured JSON for log aggregators.
+
+## Configuration & secrets
+
+- Use Vercel project env vars; mirror required names in `.env.example`.
+- Validate `process.env` via a Zod schema at module load.
+
+## Pitfalls and guardrails
+
+- The catch-all `api/[...path].ts` must remain a catch-all so DaloyJS
+  handles routing. Do not split routes into multiple Vercel API files
+  unless the user explicitly asks (it disables shared middleware and a
+  unified OpenAPI).
+- Use `toEdgeHandler(app)` from `@daloyjs/core/vercel` — never hand-roll
+  a `fetch(req)` adapter.
+- Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only
+  `@daloyjs/core` and `@daloyjs/core/vercel`.
+- Avoid Node-only APIs (`Buffer`, `fs`, full `process` API). If a
+  feature needs Node, switch to a Node-runtime template.
+- 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).
+
+## 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, ensure the user is logged in via `vercel login`; do not
+  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/bun-basic/SKILL.md

@@ -1,68 +0,0 @@
-# SKILL.md
-
-Operational guidance for AI coding agents working in this DaloyJS Bun project.
-
-## 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.
-- Run tests or typecheck the project under Bun.
-
-Do **not** use this skill for tasks unrelated to the API itself.
-
-## Project shape
-
-- `src/build-app.ts` — exports `buildApp()`. All routes and middleware are registered here. **Pure function, no side effects.**
-- `src/index.ts` — calls `buildApp()` and starts the Bun HTTP listener via `@daloyjs/core/bun`.
-- `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`).
-
-## Core workflows
-
-### Add a new route
-
-1. Open `src/build-app.ts`.
-2. Define request/response Zod schemas.
-3. Call `app.route({ method, path, request, response, handler })`. Return `{ status, body }`; preserve literal types (`status: 200 as const`, `ok: true as const`) so codegen sees narrow types.
-4. Add a test under `tests/`.
-5. Regenerate the spec + client: `bun run gen:openapi && bun run gen:client`.
-
-### Regenerate the OpenAPI spec and SDK
-
-```bash
-bun run gen:openapi   # → generated/openapi.json
-bun run gen:client    # → generated/client/
-```
-
-If `gen:openapi` fails with a "server already listening" error, you imported `src/index.ts` (or `@daloyjs/core/bun`) from a place that codegen pulls in. Codegen must only touch `buildApp()`.
-
-### Run quality gates
-
-```bash
-bun run typecheck
-bun test
-```
-
-Both must pass before considering a change done.
-
-## Decision rules
-
-- If the user asks to **change API behavior**, edit `src/build-app.ts`, then regenerate and run `bun test`.
-- If the user asks to **consume the API from a client**, import from `generated/client/` — do not handwrite fetch calls.
-- If the user asks for **new middleware**, register it on `app` inside `buildApp()` before route definitions so it applies globally.
-
-## Pitfalls and guardrails
-
-- Never import `@daloyjs/core/bun` from `src/build-app.ts` or any script under `scripts/`. That would start an HTTP listener as a side effect of codegen.
-- Do not edit files under `generated/` by hand — they are overwritten by codegen.
-- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled in `buildApp()` unless the user explicitly asks to remove them.
-- Do not weaken response literal types (`as const`); the typed client depends on them.
-
-## More
-
-- Framework docs: <https://daloyjs.dev/docs>
-- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/cloudflare-worker/SKILL.md

@@ -1,68 +0,0 @@
-# SKILL.md
-
-Operational guidance for AI coding agents working in this DaloyJS Cloudflare Workers project.
-
-## 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, env vars) in `wrangler.toml`.
-- Run tests/typecheck or deploy the Worker.
-
-Do **not** use this skill for tasks unrelated to the API itself.
-
-## 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 configuration (name, compatibility date, bindings, routes).
-
-## Core workflows
-
-### Add a new route
-
-1. Open `src/index.ts`.
-2. Define request/response Zod schemas.
-3. Call `app.route({ method, path, request, response, handler })`. Return `{ status, body }`; preserve literal types (`status: 200 as const`, `ok: true as const`) so codegen sees narrow types.
-
-### Run quality gates
-
-```bash
-pnpm typecheck
-pnpm test
-```
-
-Both must pass before considering a change done.
-
-### Deploy
-
-```bash
-pnpm deploy
-```
-
-Wrangler will use the account/zone config from `wrangler.toml`. If the user has not run `wrangler login`, ask them to do so first — do not attempt to authenticate on their behalf.
-
-### Add a binding
-
-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` so handlers can read it from the second `fetch` argument.
-3. Pass `env` into `buildApp(env)` if your factory needs it; never read bindings via globals.
-
-## Decision rules
-
-- Use `toFetchHandler(app)` from `@daloyjs/core/cloudflare` — never hand-roll a `fetch(req, env, ctx)` adapter.
-- 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.
-- Long-running work belongs in `ctx.waitUntil(...)`, not blocking the response.
-
-## Pitfalls and guardrails
-
-- Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only `@daloyjs/core` and `@daloyjs/core/cloudflare`.
-- Do not weaken response literal types (`as const`).
-- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled unless the user explicitly asks to remove them. (For `rateLimit`, prefer Cloudflare's native rate-limit binding for high traffic; the in-memory limiter resets per isolate.)
-- Workers have CPU and bundle-size limits — be cautious about adding heavy dependencies.
-
-## More
-
-- Framework docs: <https://daloyjs.dev/docs>
-- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/deno-basic/SKILL.md

@@ -1,71 +0,0 @@
-# SKILL.md
-
-Operational guidance for AI coding agents working in this DaloyJS Deno project.
-
-## 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.
-- Wire up new middleware, validation, or error handling.
-- Run tests or typecheck the project under Deno.
-
-Do **not** use this skill for tasks unrelated to the API itself.
-
-## Project shape
-
-- `src/build-app.ts` — exports `buildApp()`. All routes and middleware are registered here. **Pure function, no side effects.**
-- `src/main.ts` — calls `buildApp()` and starts the Deno HTTP listener via `@daloyjs/core/deno`.
-- `scripts/dump-openapi.ts` — imports `buildApp()` and writes `generated/openapi.json`.
-- `deno.json` — tasks, import map, and `npm:` specifiers (no `package.json`).
-- `tests/` — Deno test files (`*.test.ts`).
-
-## Core workflows
-
-### Add a new route
-
-1. Open `src/build-app.ts`.
-2. Define request/response Zod schemas.
-3. Call `app.route({ method, path, request, response, handler })`. Return `{ status, body }`; preserve literal types (`status: 200 as const`, `ok: true as const`) so codegen sees narrow types.
-4. Add a test under `tests/`.
-5. Regenerate: `deno task gen:openapi`.
-
-### Regenerate the OpenAPI spec
-
-```bash
-deno task gen:openapi   # → generated/openapi.json
-```
-
-To produce the typed client, run Hey API via Node tooling against the generated spec — Hey API does not yet ship a Deno entrypoint:
-
-```bash
-npx @hey-api/openapi-ts -i generated/openapi.json -o generated/client
-```
-
-### Run quality gates
-
-```bash
-deno task typecheck
-deno task test
-```
-
-Both must pass before considering a change done.
-
-## Decision rules
-
-- Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json` here.
-- Permissions for `dev` are intentionally narrow: `--allow-net --allow-env --allow-read`. If a change requires more permissions, add them explicitly to the relevant task in `deno.json` and call it out to the user.
-- If you need a new dependency, add it to `imports` in `deno.json` using a `npm:` or `jsr:` specifier; do not introduce a `package.json`.
-
-## Pitfalls and guardrails
-
-- Never import `@daloyjs/core/deno` from `src/build-app.ts` or any script under `scripts/`. That would start an HTTP listener as a side effect of codegen.
-- Do not edit files under `generated/` by hand.
-- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled in `buildApp()` unless the user explicitly asks to remove them.
-- Do not weaken response literal types (`as const`).
-
-## More
-
-- Framework docs: <https://daloyjs.dev/docs>
-- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/node-basic/SKILL.md

@@ -1,70 +0,0 @@
-# SKILL.md
-
-Operational guidance for AI coding agents working in this DaloyJS Node.js project.
-
-## 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.
-- Run tests, typecheck, or build the project.
-
-Do **not** use this skill for tasks unrelated to the API itself (e.g. infra, CI workflows, unrelated docs sites).
-
-## Project shape
-
-- `src/build-app.ts` — exports `buildApp()`. All routes and middleware are registered here. **Pure function, no side effects.**
-- `src/index.ts` — calls `buildApp()` and starts the Node HTTP listener via `@daloyjs/core/node`.
-- `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/` — Node test runner files (`*.test.ts`).
-
-## Core workflows
-
-### Add a new route
-
-1. Open `src/build-app.ts`.
-2. Define request/response Zod schemas inline or in a sibling module.
-3. Call `app.route({ method, path, request, response, handler })`. Always return `{ status, body }`; preserve literal types (`status: 200 as const`, `ok: true as const`) so codegen sees narrow types.
-4. Add a test under `tests/`.
-5. Regenerate the spec + client: `pnpm gen`.
-
-### Regenerate the OpenAPI spec and SDK
-
-```bash
-pnpm gen
-# = pnpm gen:openapi  → generated/openapi.json
-#   pnpm gen:client   → generated/client/
-```
-
-If `pnpm gen:openapi` fails with a "server already listening" error, you imported `src/index.ts` (or `@daloyjs/core/node`) from somewhere it shouldn't be. Codegen must only touch `buildApp()`.
-
-### Run quality gates
-
-```bash
-pnpm typecheck
-pnpm test
-```
-
-Both must pass before considering a change done.
-
-## Decision rules
-
-- If the user asks to **change API behavior**, edit `src/build-app.ts`, then run `pnpm gen` and `pnpm test`.
-- If the user asks to **consume the API from a client**, import from `generated/client/` — do not handwrite fetch calls.
-- If the user asks for **new middleware**, register it on `app` inside `buildApp()` before route definitions so it applies globally.
-
-## Pitfalls and guardrails
-
-- Never import `@daloyjs/core/node` (or any adapter that boots a server) from `src/build-app.ts` or any script under `scripts/`. That would start an HTTP listener as a side effect of codegen.
-- Do not edit files under `generated/` by hand — they are overwritten by `pnpm gen`.
-- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled in `buildApp()` unless the user explicitly asks to remove them; they are the project's secure defaults.
-- Do not weaken response literal types (`as const`); the typed client depends on them.
-- Do not add runtime dependencies without checking the hardened `.npmrc` (installs wait 24h after publish by default).
-
-## More
-
-- Framework docs: <https://daloyjs.dev/docs>
-- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/vercel-edge/SKILL.md

@@ -1,64 +0,0 @@
-# SKILL.md
-
-Operational guidance for AI coding agents working in this DaloyJS Vercel Edge project.
-
-## When to use this skill
-
-Use this skill when you need to:
-
-- Add, modify, or remove HTTP routes in this project.
-- Adjust middleware, validation, or error handling.
-- Run tests or typecheck the project.
-- Deploy or troubleshoot the Edge runtime entrypoint.
-
-Do **not** use this skill for tasks unrelated to the API itself.
-
-## Project shape
-
-- `api/[...path].ts` — the Edge entrypoint. Builds the `App`, registers routes/middleware, and exports `default toEdgeHandler(app)` plus `export const config = { runtime: "edge" }`.
-- `vercel.json` — Vercel build/runtime configuration.
-- `tests/` — test files (`*.test.ts`).
-
-## Core workflows
-
-### Add a new route
-
-1. Open `api/[...path].ts`.
-2. Define request/response Zod schemas.
-3. Call `app.route({ method, path, request, response, handler })`. Return `{ status, body }`; preserve literal types (`status: 200 as const`, `ok: true as const`) so codegen sees narrow types.
-4. Add a test under `tests/`.
-
-### Run quality gates
-
-```bash
-pnpm typecheck
-pnpm test
-```
-
-Both must pass before considering a change done.
-
-### Deploy
-
-```bash
-pnpm deploy
-```
-
-The `/docs` and `/openapi.json` routes registered in `api/[...path].ts` will be live at the deployed URL.
-
-## Decision rules
-
-- The catch-all `api/[...path].ts` must remain a catch-all so DaloyJS handles routing. Do not split routes into multiple Vercel API files unless the user explicitly asks for that pattern (it disables shared middleware and unified OpenAPI).
-- Stay on the Edge runtime: only use APIs available in Web Standards (no `node:` modules, no `fs`, no `Buffer` reliance). If a feature requires Node, the user must choose a Node-runtime template instead.
-- Use `toEdgeHandler(app)` from `@daloyjs/core/vercel` — never hand-roll a `fetch(req)` adapter.
-
-## Pitfalls and guardrails
-
-- Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only `@daloyjs/core` and `@daloyjs/core/vercel`.
-- Do not weaken response literal types (`as const`).
-- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled unless the user explicitly asks to remove them.
-- Edge functions have small bundle and CPU limits; be cautious about adding heavy dependencies.
-
-## More
-
-- Framework docs: <https://daloyjs.dev/docs>
-- Issues: <https://github.com/daloyjs/daloy/issues>