create-daloy 1.0.0-beta.4 → 1.0.0-beta.6

package/templates/vercel/AGENTS.md

@@ -1,23 +1,33 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.js runtime** (Vercel's recommended runtime for standalone functions, running on Fluid Compute). **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.js runtime**. **Contract-first**: routes use validation schemas (Zod here; DaloyJS also supports Standard Schema-compatible validators) and generate OpenAPI 3.1. With `docs: true`, DaloyJS auto-mounts `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Vercel Node.js Functions on Fluid Compute (Web Standard `Request`/`Response`).
 
+## Agent guidance
+
+- Treat this file as the short, durable project contract for AI coding agents.
+- Use `.agents/skills/daloyjs-best-practices/SKILL.md` for the detailed DaloyJS workflow; keep this file concise and do not duplicate that skill.
+- If instructions conflict, follow the user's latest prompt first, then the nearest `AGENTS.md`, then the skill.
+- Change route definitions, schemas, metadata, and tests first; regenerate generated files instead of hand-editing OpenAPI output.
+
 ## Commands
 
 - `pnpm dev` — local Node dev server (`src/dev.ts`) on http://localhost:3000 (no `vercel dev` / login needed; serves the same app the Vercel Function runs)
 - `pnpm typecheck` — `tsc --noEmit`
 - `pnpm test` — run test suite
+- `pnpm contract` — run `daloy inspect --check api/index.ts`
+- `pnpm hooks:install` — enable the optional pre-push contract gate
 - `pnpm deploy` — deploy to Vercel
 - `pnpm audit` — supply-chain audit
 
 ## Project shape
 
-- `api/index.ts` — the single Vercel Node.js Functions entrypoint. Builds the `App`, registers routes/middleware, and exports `default toFetchHandler(app)` from `@daloyjs/core/vercel` (Node.js Functions expect a default export with a `fetch` method; Node.js is the default runtime, so no `runtime` export is needed). `vercel.json` rewrites every path (`/(.*)` → `/api`) to this one function, so DaloyJS owns all routing and the app's routes are served at the site root (`/healthz`, `/docs`, …), not under `/api/*`. If you specifically need the Edge runtime, add `export const runtime = "edge"` and switch to `default toWebHandler(app)`.
-- `vercel.json` — Vercel config. The `rewrites` rule routing all paths to `/api` is **required** for root routing; do not remove it. (`functions` sets memory / maxDuration.)
-- `src/dev.ts` — local Node dev server (`pnpm dev`). Imports the `app` exported from `api/index.ts` and serves it via `@daloyjs/core/node` at the root, so you get fast local iteration without `vercel dev`. Dev-only; it is not under `api/`, so Vercel never deploys it.
+- `api/index.ts` — the single Vercel Node.js Functions entrypoint. Export `default toFetchHandler(app)` from `@daloyjs/core/vercel`; add `runtime = "edge"` and switch to `toWebHandler(app)` only when the user asks for Edge.
+- This template is not a Next.js App Router project. Do not add `app/api` routes, `next.config.*`, or Next-specific file structure unless the user asks to convert or embed the API in a Next.js app.
+- `vercel.json` — routes all paths to `/api` so DaloyJS owns root routing; do not remove this rewrite.
+- `src/dev.ts` — local Node dev server (`pnpm dev`) for fast iteration without `vercel dev`. Dev-only; Vercel does not deploy it.
 - `tests/` — test files.
 
 ## Imports
@@ -28,34 +38,36 @@ This project uses TypeScript with `"allowImportingTsExtensions"`, so relative im
 import handler from "../api/index.ts";
 ```
 
-You import the file you see. Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly, and the test runner (tsx) does too. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
+You import the file you see. Vercel and tsx resolve `.ts` directly. Bare package imports (`@daloyjs/core`, `zod`, ...) need no extension.
 
 ## 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.
+2. Validate every input with Zod or another Standard Schema-compatible validator. For Zod object schemas, use `.strict()` 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 production traffic, back rate-limiting with Vercel KV or another shared store (the in-memory limiter resets per instance).
-6. On the Node.js runtime the full Node API is available (`node:*`, `Buffer`, `fs`), but prefer Web Standards (`Request`/`Response`, `fetch`, Web Crypto) so the same app can also run on the Edge runtime or another adapter unchanged. If you opt into the Edge runtime, drop `node:` modules entirely.
+6. Prefer Web Standards (`Request`/`Response`, `fetch`, `Web Crypto`) even though Node APIs are available; Edge runtime code must avoid `node:` modules.
 7. Keep a single `api/index.ts` entry and the `vercel.json` `/(.*)` → `/api` rewrite so DaloyJS handles all routing at the site root.
-8. Every new route ships with a test that covers a happy path and at least one unhappy path.
+8. Keep operation IDs stable and examples schema-valid; `pnpm contract` must pass after route, metadata, or OpenAPI-facing changes.
+9. Every new route ships with a test that covers a happy path and at least one unhappy path.
 
 ## Secure-by-default (do not let an AI strip these)
 
-Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/blog/supabase-approach-to-secure-by-default-development): *"If you tell an AI to make something work, it might remove the very security checks that protect you."* When a guard rejects a request, **satisfy it, do not delete it.**
+Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/blog/supabase-approach-to-secure-by-default-development): _"If you tell an AI to make something work, it might remove the very security checks that protect you."_ When a guard rejects a request, **satisfy it, do not delete it.**
 
-- Keep `secureHeaders()`, `requestId()`, `rateLimit()` registered, and `bodyLimitBytes` / `requestTimeoutMs` set on `new App({...})`. For production, back the limiter with Vercel KV **in addition to** the in-memory limiter (which resets per instance).
-- Keep Zod `.strict()` on top-level request objects; do not switch to `.passthrough()`. Keep `responses[N].body` schemas tight; never widen to `z.any()` to let a privileged field escape.
-- Every protected route attaches an auth `beforeHandle` and ships an unhappy-path test proving an unauthenticated request returns `401` (and wrong scope returns `403`) — the HTTP-boundary equivalent of Supabase's pgTAP policy tests.
+- Keep `secureHeaders()`, `requestId()`, `rateLimit()`, `bodyLimitBytes`, and `requestTimeoutMs`. For production, back rate limits with Vercel KV or another shared store.
+- Keep Zod `.strict()` on top-level request objects; do not switch to `.passthrough()`. For other validators, use the strict / no-extra-keys equivalent. Keep `responses[N].body` schemas tight; never widen to `z.any()` to let a privileged field escape.
+- Every protected route attaches auth `beforeHandle` and tests unauthenticated `401` plus wrong-scope `403`.
 - JWT verifiers keep an explicit `algorithms` allowlist; never trust the token's `alg` header, never allow `none`, always check `exp` / `nbf`.
-- Credential / HMAC comparisons use a constant-time comparison (the framework's `timingSafeEqual`), never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
+- Credential / HMAC comparisons use constant-time comparison, never `===`. Throw typed errors so problem+json redacts in prod.
 - Keep the single `api/index.ts` entry and the `vercel.json` rewrite so DaloyJS owns routing — do not split into per-path files that bypass the middleware chain, and do not remove the rewrite (the root domain would 404).
 - `.env`, `.env.local`, secrets, private keys: never commit. Use `vercel env` for production secrets.
 
 ## Process expectations
 
 - Quality gates must pass before declaring work done: `pnpm typecheck` and `pnpm test`.
+- Run the contract gate (`pnpm contract`) whenever route shapes, examples, operation IDs, or OpenAPI metadata change.
 - Bug fixes include a regression test.
 - For deploys, ensure the user has run `vercel login`; do not authenticate on their behalf.
 - Never bypass safety checks without a clear reason.

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

@@ -2,11 +2,11 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  Vercel (Node.js runtime). Use when adding or changing HTTP routes, Zod
-  schemas, middleware, or error handling; regenerating the OpenAPI spec or the
-  typed Hey API client; keeping the single Vercel Functions entrypoint and
-  Web-Standard handler; or working on auth, rate limits, secrets, and the
-  project's quality gates.
+  Vercel (Node.js runtime). Use when adding or changing HTTP routes,
+  Zod/Standard Schema validation schemas, middleware, route metadata, or error
+  handling; regenerating the OpenAPI spec or typed Hey API client; keeping the
+  single Vercel Functions entrypoint and Web-Standard handler; running contract
+  gates; or working on auth, rate limits, secrets, and security defaults.
 license: MIT
 ---
 
@@ -42,7 +42,8 @@ DaloyJS is a **contract-first** framework. On Vercel, additionally:
    then drop `node:` modules.
 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.**
+3. **Validation schemas protect every boundary.** This template uses Zod,
+   and Daloy accepts any Standard Schema-compatible library.
 4. **Preserve literal types.** Return `status: 200 as const`.
 5. **Secure by default.** `requestId()`, `secureHeaders()`, and
    `rateLimit()` are registered before route definitions. Note the
@@ -53,6 +54,9 @@ DaloyJS is a **contract-first** framework. On Vercel, additionally:
    and `vercel.json` rewrites every path (`/(.*)` → `/api`) to it, so
    DaloyJS owns all routing at the site root and generates a unified
    OpenAPI spec. Removing the rewrite makes the root domain 404.
+7. **Contract gates are part of done.** Keep `operationId` values stable,
+   examples schema-valid, declared error responses accurate, and the
+   generated OpenAPI contract in sync with the live route table.
 
 ## Project shape
 
@@ -73,11 +77,14 @@ DaloyJS is a **contract-first** framework. On Vercel, additionally:
 pnpm dev          # local Node dev server (src/dev.ts) on http://localhost:3000
 pnpm typecheck    # tsc --noEmit
 pnpm test         # run test suite
+pnpm contract     # daloy inspect --check api/index.ts
 pnpm deploy       # deploy to Vercel
 pnpm audit        # supply-chain audit
 ```
 
 Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
+`pnpm test` includes the contract gate; if you need a focused contract
+check, run `pnpm contract`.
 
 ## OpenAPI & docs routes
 
@@ -97,17 +104,32 @@ On Vercel the YAML serializer is pure-string (no extra deps) and adds
 <1KB to the bundle. For hand-rolled mounting, `openapiToYAML` is exported
 from `@daloyjs/core/openapi`.
 
+## AI-ready contract metadata
+
+Daloy can expose route metadata to OpenAPI and agent tooling. Add metadata
+when it helps consumers understand or safely automate the route:
+
+- Use `summary`, `description`, and `tags` for concise human-facing docs.
+- Use `meta.examples` for realistic happy-path and unhappy-path examples.
+  Examples must match the declared schemas; the contract gate rejects drift.
+- Use `meta.extensions` for stable `x-*` fields consumed by internal tools.
+- Use `deprecated` and `sunset` when changing API lifecycle. Do not remove
+  a route or response shape silently if generated clients may depend on it.
+
 ## Workflow: add a new route
 
 1. **Open `api/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).
+   Add `meta` examples / descriptions when the route is user-facing or
+   consumed by agents.
 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`.
+7. **Run the contract gate**: `pnpm contract` or `pnpm test`.
+8. **Run the quality gates**: `pnpm typecheck && pnpm test`.
 
 ### Example: a typed route
 
@@ -146,6 +168,8 @@ app.route({
 - **Pagination**: standardize on `{ items, nextCursor }` cursor
   pagination.
 - **Discriminated unions**: `z.discriminatedUnion("kind", [...])`.
+- Keep response examples close to the route definition and schema-valid.
+  The contract test intentionally fails invalid examples.
 
 ## Error handling
 
@@ -183,6 +207,8 @@ 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.
+The shipped contract test should fail invalid examples, duplicate/missing
+`operationId`, or missing responses.
 
 Aim for **100% line and function coverage** on the routes you add.
 
@@ -191,6 +217,10 @@ Aim for **100% line and function coverage** on the routes you add.
 - 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 make a failing test pass by deleting or weakening a security guard.
+  If a guard blocks a legitimate route, add the narrowest per-route
+  override or configuration knob and cover both the allowed and rejected
+  paths in tests.
 - Never log secrets — filter `authorization`, `cookie`, etc.
 - Read secrets from `process.env` (available on Node.js Functions).
   Validate via Zod at module load.
@@ -200,6 +230,9 @@ Aim for **100% line and function coverage** on the routes you add.
 - Validate redirects against an allowlist.
 - Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
   mitigate DoS.
+- For outbound HTTP, prefer `fetchGuard()` or a transport layered on top
+  of it when URLs can be influenced by users or tenants. SSRF protections
+  should fail closed for private ranges and cloud metadata endpoints.
 - Serverless functions still have bundle-size and cold-start costs; be
   cautious about adding heavy dependencies. Inspect bundle size during
   deploy.
@@ -229,6 +262,8 @@ Aim for **100% line and function coverage** on the routes you add.
   Edge runtime, use `toWebHandler(app)` with `export const runtime = "edge"`.
 - Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only
   `@daloyjs/core` and `@daloyjs/core/vercel`.
+- Do not hand-edit OpenAPI paths or client types. Fix the route definition,
+  schema, or metadata and regenerate.
 - Node APIs (`Buffer`, `fs`, full `process`) are available on the Node.js
   runtime, but keep handlers Web-Standard where practical so the app can
   also run on the Edge runtime unchanged.
@@ -241,6 +276,8 @@ Aim for **100% line and function coverage** on the routes you add.
 - 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.
+- When route metadata, examples, lifecycle flags, or operation IDs change,
+  run the contract gate and inspect the relevant generated OpenAPI diff.
 - 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.

package/templates/vercel/package.json

@@ -13,7 +13,7 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.0.0-beta.4",
+    "@daloyjs/core": "^1.0.0-beta.6",
     "zod": "^4.4.3"
   },
   "devDependencies": {