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

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

@@ -2,10 +2,10 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  Cloudflare Workers. Use when adding or changing HTTP routes, Zod schemas,
-  middleware, or error handling; wiring Worker bindings (KV, D1, R2, Queues,
-  env, secrets); or working on auth, rate limits, and the project's quality
-  gates.
+  Cloudflare Workers. Use when adding or changing HTTP routes, Zod/Standard
+  Schema validation schemas, middleware, route metadata, or error handling;
+  wiring Worker bindings (KV, D1, R2, Queues, env, secrets); running contract
+  gates; or working on auth, rate limits, and security defaults.
 license: MIT
 ---
 
@@ -34,11 +34,12 @@ Do **not** use this skill for tasks unrelated to the API itself.
 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 the user
-  explicitly adds `nodejs_compat` to `wrangler.toml` and opts in.
+   Cloudflare-specific bindings. No `node:` modules unless the user
+   explicitly adds `nodejs_compat` to `wrangler.toml` and 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.**
+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. Note: the in-memory rate limiter resets
@@ -46,6 +47,9 @@ DaloyJS is a **contract-first** framework. On Workers, additionally:
    rate-limit binding.
 6. **Bindings flow through `env`.** Read KV/D1/R2/secrets from the
    `env` argument to `fetch`, never from globals.
+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
 
@@ -64,11 +68,14 @@ DaloyJS is a **contract-first** framework. On Workers, additionally:
 pnpm dev          # wrangler dev on http://localhost:8787
 pnpm typecheck    # tsc --noEmit
 pnpm test         # run test suite
+pnpm contract     # daloy inspect --check src/index.ts
 pnpm deploy       # wrangler deploy
 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
 
@@ -89,18 +96,33 @@ On Workers the Scalar UI adds the most weight; consider
 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 `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).
+   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.).
 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`.
+7. **Run the contract gate**: `pnpm contract` or `pnpm test`.
+8. **Run the quality gates**: `pnpm typecheck && pnpm test`.
 
 ### Example: a typed route with bindings
 
@@ -158,6 +180,8 @@ export default {
 - **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
 
@@ -197,6 +221,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 into `buildApp(env)` 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.
 
@@ -205,6 +231,10 @@ Aim for **100% line and function coverage** on the routes you add.
 - Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled. For
   high-traffic routes, attach Cloudflare's native rate-limit binding so
   limits are shared across isolates.
+- 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 via `wrangler secret put`, never via plain `[vars]` in
   `wrangler.toml`.
@@ -213,6 +243,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.
 - Workers have CPU and bundle-size limits; be cautious about adding
   heavy dependencies. Run `wrangler deploy --dry-run --outdir=dist` to
   inspect bundle size.
@@ -242,6 +275,8 @@ Aim for **100% line and function coverage** on the routes you add.
   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`.
+- Do not hand-edit OpenAPI paths or client types. Fix the route definition,
+  schema, or metadata and regenerate.
 - 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`).
@@ -255,6 +290,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, 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.

package/templates/cloudflare-worker/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": {

package/templates/deno-basic/AGENTS.md

@@ -1,15 +1,24 @@
 # 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. 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 for the [Deno](https://deno.com) runtime. **Contract-first**: routes are defined with validation schemas (Zod in this template; DaloyJS also supports Standard Schema-compatible validators) 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).
 
 - Runtime: Deno (no Node package manager). DaloyJS loads from `jsr:` and third-party packages such as Zod load from `npm:` in `deno.json`.
 
+## 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
 
 - `deno task dev` — watch-mode server on http://localhost:3000
 - `deno task typecheck`
 - `deno task test`
 - `deno task gen:openapi` — write `generated/openapi.json`
+- `deno task contract` — run the focused OpenAPI contract test
+- `deno task hooks:install` — enable the optional pre-push contract gate
 
 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.
 
@@ -25,21 +34,22 @@ The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint
 ## 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.
 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`.
+7. Keep operation IDs stable and examples schema-valid; `deno task contract` must pass after route, metadata, or OpenAPI-facing changes.
+8. Every new route ships with a test that covers a happy path and at least one unhappy path.
+9. After any route change: `deno task gen:openapi && deno task contract && deno task typecheck && deno task test`.
 
 ## 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({...})`. Tighten per-route; never raise globally to pass a test.
 - Keep Deno permissions narrow. Never add `--allow-all`; never broaden `--allow-net` / `--allow-read` / `--allow-env` to silence a prompt — add the specific host / path / var.
-- 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.
+- 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 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.
 - 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, never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
@@ -48,7 +58,7 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 ## 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.
+- Regenerate the OpenAPI spec whenever route shapes change, then run `deno task contract`.
 - Bug fixes include a regression test.
 - Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json` here.
 

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

@@ -2,10 +2,11 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  the Deno runtime. Use when adding or changing HTTP routes, Zod schemas,
-  middleware, or error handling; regenerating the OpenAPI spec; managing Deno
-  permissions and tasks; or working on auth, rate limits, secrets, and the
-  project's quality gates.
+  the Deno runtime. Use when adding or changing HTTP routes, Zod/Standard
+  Schema validation schemas, middleware, route metadata, or error handling;
+  regenerating the OpenAPI spec; running contract gates; managing Deno
+  permissions and tasks; or working on auth, rate limits, secrets, and
+  security defaults.
 license: MIT
 ---
 
@@ -35,7 +36,8 @@ DaloyJS is a **contract-first** framework. Internalize these rules:
 
 1. **The route definition is the contract.** Method, path, request schemas,
    and response schemas live in one place (`app.route({...})`).
-2. **Zod schemas validate at every boundary.**
+2. **Validation schemas protect every boundary.** This template uses Zod,
+   and Daloy accepts any Standard Schema-compatible library.
 3. **Preserve literal types.** Return `status: 200 as const`; use
    `z.literal(...)` / `as const` on discriminator fields.
 4. **`buildApp()` is pure.** Construction never opens sockets. The HTTP
@@ -45,6 +47,9 @@ DaloyJS is a **contract-first** framework. Internalize these rules:
 6. **Deno permissions are part of the contract.** Tasks declare exactly
    the permissions they need (`--allow-net`, `--allow-env`, `--allow-read`).
    Do not broaden them casually.
+7. **Contract gates are part of done.** Keep `operationId` values stable,
+   examples schema-valid, declared error responses accurate, and generated
+   OpenAPI artifacts in sync with the live route table.
 
 ## Project shape
 
@@ -65,6 +70,7 @@ DaloyJS is a **contract-first** framework. Internalize these rules:
 deno task dev           # watch-mode server on http://localhost:3000
 deno task typecheck     # deno check
 deno task test          # deno test
+deno task contract      # run the focused contract test
 deno task gen:openapi   # write generated/openapi.json
 ```
 
@@ -76,7 +82,8 @@ npx @hey-api/openapi-ts -i generated/openapi.json -o generated/client
 ```
 
 Always run `deno task typecheck` and `deno task test` before declaring a
-task done.
+task done. `deno task test` includes the contract gate; if you need a
+focused contract check, run `deno task contract`.
 
 ## OpenAPI & docs routes
 
@@ -95,6 +102,18 @@ mount only outside production, or `docs: false` to disable all three.
 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 `src/build-app.ts`.**
@@ -103,14 +122,17 @@ For hand-rolled mounting, `openapiToYAML` is exported from
    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? }` from the handler.** Always
    `status: 200 as const`.
 5. **Throw typed errors** (`NotFoundError`, `BadRequestError`, etc.) from
    `@daloyjs/core`.
 6. **Add a test in `tests/<route>.test.ts`** using `app.request(...)` for
    in-process tests.
-7. **Regenerate the contract**: `deno task gen:openapi`.
-8. **Run the quality gates**: `deno task typecheck && deno task test`.
+7. **Run the contract gate**: `deno task contract` or `deno task test`.
+8. **Regenerate the contract artifacts**: `deno task gen:openapi`.
+9. **Run the quality gates**: `deno task typecheck && deno task test`.
 
 ### Example: a typed route
 
@@ -149,6 +171,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.
 - **Never** parse `req.body` directly — let the framework validate.
 
 ## Error handling
@@ -194,14 +218,20 @@ Cover **happy paths and unhappy paths**: 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 via
 `buildApp({ store })`.
+The shipped contract test should fail invalid examples, duplicate/missing
+`operationId`, or missing responses.
 
 Aim for **100% line and function coverage** on routes you add.
 
 ## Security best practices
 
 - Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled.
+- 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.
 - Permissions for the `dev` task are intentionally narrow: `--allow-net
-  --allow-env --allow-read`. If a change requires more permissions, add
+--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 — never `--allow-all`.
 - Never log secrets — filter `authorization`, `cookie`, etc.
@@ -212,6 +242,9 @@ Aim for **100% line and function coverage** on 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.
 - Pin `npm:` and `jsr:` specifiers in `deno.json` to exact or
   caret-locked versions; review changes in `deno.lock` before committing.
 
@@ -231,6 +264,8 @@ Aim for **100% line and function coverage** on routes you add.
 - Never import `@daloyjs/core/deno` from `src/build-app.ts` or any
   script under `scripts/`. That would boot a listener during codegen.
 - Do not edit files under `generated/` by hand.
+- Do not hand-edit OpenAPI paths or client types. Fix the route definition,
+  schema, or metadata and regenerate.
 - Do not weaken response literal types (`as const`).
 - Do not return errors as `{ status: 4xx, body }`. Throw a typed error.
 - Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json`.
@@ -244,6 +279,8 @@ Aim for **100% line and function coverage** on routes you add.
 - `deno task typecheck` and `deno task test` must pass before completion.
 - Run `deno task gen:openapi` when route shapes change; commit the
   updated `generated/openapi.json`.
+- When route metadata, examples, lifecycle flags, or operation IDs change,
+  run the contract gate and inspect the relevant generated OpenAPI diff.
 - Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent with the
   code.
 

package/templates/deno-basic/deno.json

@@ -10,11 +10,11 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "imports": {
-    "@daloyjs/core": "jsr:@daloyjs/daloy@^1.0.0-beta.4",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^1.0.0-beta.4/banner",
-    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^1.0.0-beta.4/contract",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^1.0.0-beta.4/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^1.0.0-beta.4/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^1.0.0-beta.6",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^1.0.0-beta.6/banner",
+    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^1.0.0-beta.6/contract",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^1.0.0-beta.6/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^1.0.0-beta.6/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/node-basic/AGENTS.md

@@ -1,12 +1,21 @@
 # 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.
+routes are defined with validation schemas (Zod in this template; DaloyJS also
+supports Standard Schema-compatible validators) 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).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
-- Runtime: Node.js >= 24.0.0 (active LTS).
+- Runtime: Node.js 24 LTS or Node.js 26+ (`^24.0.0 || >=26.0.0`).
+
+## 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 or typed-client output.
 
 ## Commands
 
@@ -14,6 +23,8 @@ When `docs: true` is set in `new App({...})`, three routes are auto-mounted:
 - `pnpm typecheck` — `tsc --noEmit`
 - `pnpm test` — Node built-in test runner
 - `pnpm gen` — regenerate `generated/openapi.json` and the typed Hey API client
+- `pnpm contract` — run `daloy inspect --check src/build-app.ts`
+- `pnpm hooks:install` — enable the optional pre-push contract gate
 - `pnpm build` — emit `dist/`
 - `pnpm audit` — supply-chain audit (respects the hardened `.npmrc`)
 
@@ -38,19 +49,20 @@ You import the file you see. On `pnpm build`, TypeScript rewrites the `.ts` spec
 ## 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. 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: `pnpm gen && pnpm typecheck && pnpm test`.
+6. Keep operation IDs stable and examples schema-valid; `pnpm contract` must pass after route, metadata, or OpenAPI-facing changes.
+7. Every new route ships with a test that covers a happy path and at least one unhappy path.
+8. After any route change: `pnpm gen && pnpm contract && pnpm typecheck && pnpm test`.
 
 ## 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({...})`. Tighten per-route; never raise globally to pass a test.
-- 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.
+- 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 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.
 - 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 `timingSafeEqual`, never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
@@ -60,7 +72,7 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 ## Process expectations
 
 - Quality gates must pass before declaring work done: `pnpm typecheck` and `pnpm test`.
-- Update the OpenAPI spec and typed client whenever route shapes change (`pnpm gen`).
+- Update the OpenAPI spec and typed client whenever route shapes change (`pnpm gen`) and run the contract gate (`pnpm contract`).
 - Bug fixes include a regression test.
 - Never bypass safety checks (`--no-verify`, `--ignore-scripts=false`) without a clear reason.
 

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

@@ -2,9 +2,10 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  Node.js. Use when adding or changing HTTP routes, Zod schemas, middleware, or
-  error handling; regenerating the OpenAPI spec or the typed Hey API client; or
-  working on auth, rate limits, secrets, and the project's quality gates.
+  Node.js. 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; running contract
+  gates; or working on auth, rate limits, secrets, and security defaults.
 license: MIT
 ---
 
@@ -38,9 +39,10 @@ recommendation below follows from them:
    spec, the typed client, and the runtime validation are all derived from
    it. Never duplicate that information by hand-writing fetch calls, types,
    or `openapi.json` entries.
-2. **Zod schemas validate at every boundary.** Body, params, query, and
-   headers go through Zod. If a field is not in the schema, it is not part
-   of the contract.
+2. **Validation schemas protect every boundary.** This template uses Zod,
+   and Daloy accepts any Standard Schema-compatible library. Body, params,
+   query, and headers go through the declared schema. If a field is not in
+   the schema, it is not part of the contract.
 3. **Preserve literal types.** Return `status: 200 as const` and use
    `z.literal(...)` / `as const` on discriminator fields. The typed client
    needs narrow types to do useful response narrowing.
@@ -51,6 +53,9 @@ recommendation below follows from them:
 5. **Secure by default.** `requestId()`, `secureHeaders()`, and
    `rateLimit()` are registered before route definitions. Do not remove
    them unless the user explicitly asks.
+6. **Contract gates are part of done.** Keep `operationId` values stable,
+   examples schema-valid, declared error responses accurate, and generated
+   OpenAPI / client artifacts in sync with the live route table.
 
 ## Project shape
 
@@ -74,13 +79,15 @@ pnpm test         # Node built-in test runner
 pnpm gen          # gen:openapi + gen:client
 pnpm gen:openapi  # write generated/openapi.json
 pnpm gen:client   # write generated/client/
+pnpm contract     # daloy inspect --check src/build-app.ts
 pnpm build        # emit dist/
 pnpm audit        # supply-chain audit
 ```
 
 Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
-If a change touches route shapes, also run `pnpm gen` so the client stays
-in sync.
+`pnpm test` includes the contract gate; if you need a focused contract
+check, run `pnpm contract`. If a change touches route shapes, also run
+`pnpm gen` so the OpenAPI spec and client stay in sync.
 
 ## OpenAPI & docs routes
 
@@ -104,6 +111,18 @@ exported from the openapi subpath:
 import { generateOpenAPI, openapiToYAML } 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
 
 Follow these steps in order. Skipping any of them is a common source of
@@ -118,7 +137,8 @@ bugs (drifted client SDK, missing test, broken codegen).
    keys are rejected at the boundary.
 3. **Call `app.route({...})`.** Required keys: `method`, `path`,
    `operationId`, `tags`, `responses`, `handler`. Add `request` when the
-   route accepts input.
+   route accepts input, and add `meta` examples / descriptions when the
+   route is user-facing or consumed by agents.
 4. **Return `{ status, body, headers? }` from the handler.** Always use
    `status: 200 as const` (or whatever code) so the typed client can
    narrow. For literal discriminators in `body`, use `as const` or
@@ -129,10 +149,12 @@ bugs (drifted client SDK, missing test, broken codegen).
    framework maps them to RFC 7807 problem responses.
 6. **Add a test in `tests/<route>.test.ts`.** Use `app.request(...)` for
    in-process tests — no port needed (see "Testing best practices").
-7. **Regenerate the contract.** Run `pnpm gen`. Inspect
+7. **Run the contract gate.** Run `pnpm contract` or `pnpm test` before
+   trusting the OpenAPI output.
+8. **Regenerate the contract artifacts.** Run `pnpm gen`. Inspect
    `generated/openapi.json` to confirm the operation shows up with the
    expected schemas and status codes.
-8. **Run the quality gates.** `pnpm typecheck && pnpm test`.
+9. **Run the quality gates.** `pnpm typecheck && pnpm test`.
 
 ### Example: a typed route
 
@@ -178,6 +200,8 @@ app.route({
 - **Discriminated unions** (e.g. for response variants): use
   `z.discriminatedUnion("kind", [...])` and tag each branch with
   `z.literal("...")` so codegen produces a narrow TypeScript union.
+- Keep response examples close to the route definition and schema-valid.
+  The contract test intentionally fails invalid examples.
 - **Never** call `JSON.parse` or `req.body` directly in a handler. Let the
   framework validate via the schema and read the typed object passed to
   the handler.
@@ -202,8 +226,8 @@ Order matters — earlier middleware wraps later middleware and routes.
 Keep these as the secure baseline:
 
 ```ts
-app.use(requestId());      // x-request-id for log correlation
-app.use(secureHeaders());  // strict security headers
+app.use(requestId()); // x-request-id for log correlation
+app.use(secureHeaders()); // strict security headers
 app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 ```
 
@@ -245,6 +269,8 @@ Cover both **happy paths** and **unhappy paths** for every route:
 - Not found: unknown id → `404`.
 - Conflict: duplicate create → `409`.
 - Rate limit: hammer the route → `429` after the configured threshold.
+- Contract failure: invalid examples, duplicate/missing `operationId`, or
+  missing responses should fail through the shipped contract test.
 
 For routes that touch external services, write a thin in-memory fake
 inside the test and inject it via the factory pattern (`buildApp({ store })`).
@@ -259,6 +285,10 @@ honor them.
 
 - Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled. They
   ship the OWASP-recommended baseline.
+- 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`, and any header /
   body field that may contain tokens before logging.
 - Read secrets from `process.env`, validated through a Zod schema at
@@ -273,6 +303,9 @@ honor them.
 - Set `requestTimeoutMs` so slow clients cannot tie up workers.
 - For database access, use parameterized queries / a query builder. Never
   interpolate user input into SQL strings.
+- 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.
 - Review `pnpm audit` output before releases. Avoid lowering the
   install cooldown without reason; new package versions can be malicious.
 
@@ -303,6 +336,8 @@ honor them.
   start an HTTP listener as a side effect of codegen.
 - Do not edit files under `generated/` by hand — they are overwritten by
   `pnpm gen`.
+- Do not hand-edit OpenAPI paths or client types. Fix the route definition,
+  schema, or metadata and regenerate.
 - 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
@@ -321,6 +356,8 @@ honor them.
   declaring the task complete.
 - When route shapes change, also run `pnpm gen` and commit the updated
   `generated/openapi.json` + client.
+- When route metadata, examples, lifecycle flags, or operation IDs change,
+  run the contract gate and inspect the relevant generated OpenAPI diff.
 - Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent with the
   code. If you add a workflow, document it here.
 

package/templates/node-basic/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24.0.0"
+    "node": "^24.0.0 || >=26.0.0"
   },
   "scripts": {
     "dev": "daloy dev",
@@ -20,7 +20,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": {