create-daloy 0.1.16 → 0.1.17

package/README.md

@@ -118,3 +118,12 @@ re-run with `--minimal`, or delete the marked blocks by hand later.
 - 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:
+
+- `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.
+
+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

@@ -221,16 +221,33 @@ async function patchPackageJson(dir, projectName, packageManager) {
   await writeFile(file, JSON.stringify(json, null, 2) + "\n", "utf8");
 }
 
-async function patchReadme(dir, packageManager) {
+async function patchTemplateTextFiles(dir, packageManager) {
   if (packageManager === "pnpm") return;
-  const file = path.join(dir, "README.md");
-  if (!existsSync(file)) return;
-  const raw = await readFile(file, "utf8");
-  const next = raw
+  for (const fileName of ["README.md", "AGENTS.md", "SKILL.md"]) {
+    const file = path.join(dir, fileName);
+    if (!existsSync(file)) continue;
+    const raw = await readFile(file, "utf8");
+    const next = rewritePackageManagerText(raw, packageManager);
+    if (next !== raw) await writeFile(file, next, "utf8");
+  }
+}
+
+function rewritePackageManagerText(raw, packageManager) {
+  return raw
+    .replace(
+      "Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).",
+      `Package manager: ${packageManager}.`,
+    )
     .replace(/\bpnpm install\b/g, `${packageManager} install`)
+    .replace(/\bpnpm gen:openapi\b/g, `${packageManager} run gen:openapi`)
+    .replace(/\bpnpm gen:client\b/g, `${packageManager} run gen:client`)
+    .replace(/\bpnpm typecheck\b/g, `${packageManager} run typecheck`)
+    .replace(/\bpnpm build\b/g, `${packageManager} run build`)
+    .replace(/\bpnpm deploy\b/g, `${packageManager} run deploy`)
     .replace(/\bpnpm dev\b/g, `${packageManager} run dev`)
     .replace(/\bpnpm gen\b/g, `${packageManager} run gen`)
-    .replace(/\bpnpm build\b/g, `${packageManager} run build`)
+    .replace(/\bpnpm test\b/g, `${packageManager} test`)
+    .replace(/\bpnpm audit\b/g, `${packageManager} audit`)
     .replace(
       "- Hardened `.npmrc` for safer installs.",
       `- Package-manager scripts adjusted for ${packageManager}.`,
@@ -238,8 +255,11 @@ async function patchReadme(dir, packageManager) {
     .replace(
       "- Hey API codegen wired to `pnpm gen`.",
       `- Hey API codegen wired to \`${packageManager} run gen\`.`,
+    )
+    .replace(
+      "- Do not add runtime dependencies without checking the hardened `.npmrc` (installs wait 24h after publish by default).",
+      `- Add runtime dependencies with \`${packageManager} install <package>\` and rerun the quality gates after dependency changes.`,
     );
-  await writeFile(file, next, "utf8");
 }
 
 /**
@@ -545,7 +565,7 @@ async function main() {
     if (!skipPackageManager) {
       await patchPackageJson(targetDir, projectName, packageManager);
       logStep("Package metadata written", projectName);
-      await patchReadme(targetDir, packageManager);
+      await patchTemplateTextFiles(targetDir, packageManager);
       await normalizePackageManagerFiles(targetDir, packageManager);
       if (packageManager !== "pnpm") {
         logStep("Package-manager config normalized", packageManager);

package/package.json

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

@@ -0,0 +1,20 @@
+# 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.
+
+- Package manager / runtime: Bun.
+
+## Commands
+
+- `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
+
+## Structure hints
+
+- 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.
+
+For workflows (adding routes, regenerating the SDK, common pitfalls) see [SKILL.md](SKILL.md).

package/templates/bun-basic/SKILL.md

@@ -0,0 +1,68 @@
+# 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/AGENTS.md

@@ -0,0 +1,20 @@
+# 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.
+
+- Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
+- Runtime: Cloudflare Workers (Web Standard `Request`/`Response`).
+
+## Commands
+
+- `pnpm dev` — `wrangler dev` on http://localhost:8787
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm deploy` — `wrangler deploy`
+
+## Structure hints
+
+- 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.
+
+For workflows (adding routes, deploy, common pitfalls) see [SKILL.md](SKILL.md).

package/templates/cloudflare-worker/SKILL.md

@@ -0,0 +1,68 @@
+# 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/cloudflare-worker/package.json

@@ -7,7 +7,7 @@
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test tests/**/*.test.ts"
+    "test": "node --import tsx/esm --test tests/**/*.test.ts"
   },
   "dependencies": {
     "@daloyjs/core": "^0.5.0",

package/templates/deno-basic/AGENTS.md

@@ -0,0 +1,22 @@
+# 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.
+
+- Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` specifiers in `deno.json`.
+
+## Commands
+
+- `deno task dev` — watch-mode server on http://localhost:3000
+- `deno task typecheck`
+- `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.
+
+## Structure hints
+
+- 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.
+
+For workflows (adding routes, regenerating the spec, common pitfalls) see [SKILL.md](SKILL.md).

package/templates/deno-basic/SKILL.md

@@ -0,0 +1,71 @@
+# 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/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+A [DaloyJS](https://daloyjs.dev) Node.js REST API. 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: Node.js >= 20.10.
+
+## Commands
+
+- `pnpm dev` — watch-mode dev server on http://localhost:3000
+- `pnpm typecheck` — `tsc --noEmit`
+- `pnpm test` — Node built-in test runner
+- `pnpm gen` — regenerate `generated/openapi.json` and the typed Hey API client
+- `pnpm build` — emit `dist/`
+
+## Structure hints
+
+- 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/node`.
+- Codegen reads from `buildApp()` only — never import `src/index.ts` from scripts.
+
+For workflows (adding routes, regenerating the SDK, common pitfalls) see [SKILL.md](SKILL.md).

package/templates/node-basic/SKILL.md

@@ -0,0 +1,70 @@
+# 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/node-basic/package.json

@@ -7,12 +7,12 @@
     "node": ">=20.10.0"
   },
   "scripts": {
-    "dev": "node --import tsx --watch src/index.ts",
-    "start": "node --import tsx src/index.ts",
+    "dev": "node --import tsx/esm --watch src/index.ts",
+    "start": "node --import tsx/esm src/index.ts",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test tests/**/*.test.ts",
-    "gen:openapi": "node --import tsx scripts/dump-openapi.ts",
+    "test": "node --import tsx/esm --test tests/**/*.test.ts",
+    "gen:openapi": "node --import tsx/esm scripts/dump-openapi.ts",
     "gen:client": "openapi-ts",
     "gen": "pnpm gen:openapi && pnpm gen:client",
     "audit": "pnpm audit --prod"

package/templates/vercel-edge/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. 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: Vercel Edge (Web Standard `Request`/`Response`).
+
+## Commands
+
+- `pnpm dev` — local Vercel dev server on http://localhost:3000
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm deploy` — deploy to Vercel
+
+## Structure hints
+
+- The Edge entrypoint is `api/[...path].ts` — a catch-all that delegates to DaloyJS via `toEdgeHandler(app)` from `@daloyjs/core/vercel`. Keep it as a catch-all so DaloyJS owns routing.
+- Build the `App` inside that file (or import a factory it uses); the file must export `default toEdgeHandler(app)` and `export const config = { runtime: "edge" }`.
+
+For workflows (adding routes, regenerating the SDK, common pitfalls) see [SKILL.md](SKILL.md).

package/templates/vercel-edge/SKILL.md

@@ -0,0 +1,64 @@
+# 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>

package/templates/vercel-edge/package.json

@@ -7,7 +7,7 @@
     "dev": "vercel dev",
     "deploy": "vercel deploy",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test tests/**/*.test.ts"
+    "test": "node --import tsx/esm --test tests/**/*.test.ts"
   },
   "dependencies": {
     "@daloyjs/core": "^0.5.0",