create-daloy 0.39.1 → 0.42.0

package/bin/create-daloy.mjs

@@ -4,7 +4,7 @@
 
 import { spawn } from "node:child_process";
 import { existsSync, openSync } from "node:fs";
-import { mkdir, readdir, readFile, writeFile, copyFile, rm } from "node:fs/promises";
+import { mkdir, readdir, readFile, writeFile, copyFile, rm, stat, chmod } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { ReadStream as TtyReadStream } from "node:tty";
@@ -79,6 +79,10 @@ const RENAME_ON_COPY = new Map([
   // Templates author this as `_vscode/` so npm pack does not drop the
   // dotfolder during publish.
   ["_vscode", ".vscode"],
+  // Directory: holds the opt-in `pre-push` contract gate. `core.hooksPath`
+  // points here once the user runs the `hooks:install` script. Authored as
+  // `_githooks/` so npm pack does not drop the dotfolder during publish.
+  ["_githooks", ".githooks"],
 ]);
 
 // Templates that target a runtime instead of an npm package manager.
@@ -499,6 +503,12 @@ async function copyTemplate(src, dest) {
       await copyTemplate(from, to);
     } else if (entry.isFile()) {
       await copyFile(from, to);
+      // Preserve the source file's mode so executable templates (e.g.
+      // `.githooks/pre-push`, the localhost contract gate) stay executable in
+      // the scaffold. `fs.copyFile` does not guarantee mode preservation on
+      // every platform (notably Linux `copy_file_range`), so set it explicitly.
+      const { mode } = await stat(from);
+      await chmod(to, mode);
     }
   }
 }
@@ -549,6 +559,8 @@ function rewritePackageManagerText(raw, packageManager) {
     .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 contract\b/g, `${packageManager} run contract`)
+    .replace(/\bpnpm hooks:install\b/g, `${packageManager} run hooks:install`)
     .replace(/\bpnpm test\b/g, `${packageManager} test`)
     .replace(/\bpnpm audit\b/g, `${packageManager} audit`)
     .replace(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.39.1",
+  "version": "0.42.0",
   "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/sbom.cdx.json

@@ -1,25 +1,25 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:695a28ef-e70f-5825-96bc-ac3607a61156",
+  "serialNumber": "urn:uuid:d2c825aa-a918-58f1-9fed-b01fd3b46439",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-17T18:34:51.003Z",
+    "timestamp": "2026-06-19T08:56:45.353Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.39.1"
+        "version": "0.42.0"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@0.39.1",
+      "bom-ref": "pkg:npm/create-daloy@0.42.0",
       "name": "create-daloy",
-      "version": "0.39.1",
+      "version": "0.42.0",
       "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
-      "purl": "pkg:npm/create-daloy@0.39.1",
+      "purl": "pkg:npm/create-daloy@0.42.0",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-0.39.1",
+        "tagId": "swidtag-create-daloy-0.42.0",
         "name": "create-daloy",
-        "version": "0.39.1",
+        "version": "0.42.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@0.39.1",
+      "ref": "pkg:npm/create-daloy@0.42.0",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-0.39.1",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.39.1-695a28ef-e70f-5825-96bc-ac3607a61156",
+  "name": "create-daloy-0.42.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.42.0-d2c825aa-a918-58f1-9fed-b01fd3b46439",
   "creationInfo": {
-    "created": "2026-06-17T18:34:51.003Z",
+    "created": "2026-06-19T08:56:45.353Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "0.39.1",
+      "versionInfo": "0.42.0",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/create-daloy@0.39.1"
+          "referenceLocator": "pkg:npm/create-daloy@0.42.0"
         }
       ]
     }

package/templates/bun-basic/README.md

@@ -44,6 +44,20 @@ bun run gen:client
 bun test
 ```
 
+## Contract gate
+
+Check that your OpenAPI contract is internally consistent (operationIds present and unique, response examples matching their schemas, no dead routes). It ships as `tests/contract.test.ts` (run under `bun test`) and as a focused script:
+
+```bash
+bun run contract     # bun test tests/contract.test.ts
+```
+
+For a localhost-only gate that runs before code leaves your machine, enable the bundled pre-push hook (opt-in; bypass once with `git push --no-verify`):
+
+```bash
+bun run hooks:install   # points core.hooksPath at .githooks
+```
+
 ## Imports
 
 This project uses TypeScript with `"moduleResolution": "Bundler"` and `"allowImportingTsExtensions": true`. Relative imports use the **`.ts` extension** directly:

package/templates/bun-basic/_githooks/pre-push

@@ -0,0 +1,16 @@
+#!/bin/sh
+# daloyjs-pre-push-contract-hook v1
+#
+# Localhost-only contract gate. Rejects a push whose OpenAPI contract has
+# error-level issues: missing or duplicate operationIds, response examples that
+# don't match their schema, accidental body schemas on safe methods, or routes
+# with no declared responses. Catches the class of drift `tsc` can't see before
+# it leaves your machine, with CI as the backstop.
+#
+# Enable once per clone:  bun run hooks:install   (sets core.hooksPath here)
+# Bypass once:            git push --no-verify
+if ! command -v bun >/dev/null 2>&1; then
+  echo "pre-push: bun not found on PATH. Skipping contract gate." >&2
+  exit 0
+fi
+exec bun test tests/contract.test.ts

package/templates/bun-basic/package.json

@@ -11,13 +11,15 @@
     "start": "bun src/index.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "contract": "bun test tests/contract.test.ts",
     "gen:openapi": "bun run scripts/dump-openapi.ts",
     "gen:client": "openapi-ts",
     "gen": "pnpm gen:openapi && pnpm gen:client",
-    "audit": "pnpm audit --prod"
+    "audit": "pnpm audit --prod",
+    "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.39.1",
+    "@daloyjs/core": "^0.42.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/bun-basic/tests/contract.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { App } from "@daloyjs/core";
+import { runContractTests } from "@daloyjs/core/contract";
+import { buildApp } from "../src/build-app.ts";
+
+// Contract gate. `runContractTests` re-derives the OpenAPI contract from the
+// live route table and fails on the defects `tsc` can't see: missing or
+// duplicate operationIds, response examples that don't match their schema, and
+// routes that declare no responses. Running it under `bun test` means a broken
+// contract fails CI before it can ship a misleading OpenAPI spec or generate a
+// wrong typed client.
+describe("contract", () => {
+  test("the app's OpenAPI contract is internally consistent", async () => {
+    const report = await runContractTests(buildApp());
+    expect(report.ok).toBe(true);
+  });
+
+  // Unhappy path: prove the gate actually rejects a broken contract. A route
+  // without an operationId can't generate a stable client method name, so the
+  // runner reports an error (operationId is required by default).
+  test("the contract gate rejects a route missing its operationId", async () => {
+    const broken = new App();
+    broken.route({
+      method: "GET",
+      path: "/missing-op-id",
+      responses: { 200: { description: "ok", body: z.object({ ok: z.boolean() }) } },
+      handler: async () => ({ status: 200 as const, body: { ok: true } }),
+    });
+    const report = await runContractTests(broken);
+    expect(report.ok).toBe(false);
+  });
+});

package/templates/bun-basic/tests/healthz.test.ts

@@ -10,4 +10,11 @@ describe("buildApp", () => {
     expect(body.ok).toBe(true);
     expect(body.runtime).toBe("bun");
   });
+
+  // Unhappy path: an unregistered route is rejected with 404 (problem+json).
+  test("unknown route returns 404", async () => {
+    const app = buildApp();
+    const res = await app.request("/__not_a_route__");
+    expect(res.status).toBe(404);
+  });
 });

package/templates/cloudflare-worker/README.md

@@ -17,6 +17,20 @@ pnpm deploy
 
 `@daloyjs/core/cloudflare` exposes `toFetchHandler(app)`, so the same `App` you would use on Node also runs on Workers.
 
+## Contract gate
+
+Check that your OpenAPI contract is internally consistent (operationIds present and unique, response examples matching their schemas, no dead routes). It ships as `tests/contract.test.ts` (run under `pnpm test`) and as a focused script:
+
+```bash
+pnpm contract        # daloy inspect --check src/index.ts
+```
+
+For a localhost-only gate that runs before code leaves your machine, enable the bundled pre-push hook (opt-in; bypass once with `git push --no-verify`):
+
+```bash
+pnpm hooks:install   # points core.hooksPath at .githooks
+```
+
 ## What's included
 
 - `@daloyjs/core/cloudflare` with starter security middleware: `secureHeaders` and `requestId`.

package/templates/cloudflare-worker/_githooks/pre-push

@@ -0,0 +1,17 @@
+#!/bin/sh
+# daloyjs-pre-push-contract-hook v1
+#
+# Localhost-only contract gate. Rejects a push whose OpenAPI contract has
+# error-level issues: missing or duplicate operationIds, response examples that
+# don't match their schema, accidental body schemas on safe methods, or routes
+# with no declared responses. Catches the class of drift `tsc` can't see before
+# it leaves your machine, with CI as the backstop.
+#
+# Enable once per clone:  npm run hooks:install   (sets core.hooksPath here)
+# Bypass once:            git push --no-verify
+DALOY="./node_modules/.bin/daloy"
+if [ ! -x "$DALOY" ]; then
+  echo "pre-push: daloy CLI not found — run your package manager's install. Skipping contract gate." >&2
+  exit 0
+fi
+exec "$DALOY" inspect --check src/index.ts

package/templates/cloudflare-worker/package.json

@@ -8,10 +8,12 @@
     "deploy": "wrangler deploy",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test tests/**/*.test.ts",
-    "audit": "pnpm audit --prod"
+    "contract": "daloy inspect --check src/index.ts",
+    "audit": "pnpm audit --prod",
+    "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.39.1",
+    "@daloyjs/core": "^0.42.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/cloudflare-worker/src/index.ts

@@ -68,4 +68,9 @@ app.route({
 });
 // daloy-minimal:strip-end books
 
+// Cloudflare invokes the default export's `fetch`. The `app` instance is also
+// exported (a no-op for the Worker runtime) so `tests/contract.test.ts` can
+// contract-check the route table in-process without booting the handler.
+export { app };
+
 export default toFetchHandler(app);

package/templates/cloudflare-worker/tests/app.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import handler from "../src/index.ts";
+
+// Cloudflare Workers invoke the default export's `fetch(request, env?, ctx?)`.
+// env / ctx are optional, so a plain Request is enough for in-process tests.
+test("GET /healthz returns 200", async () => {
+  const res = await handler.fetch(new Request("https://example.test/healthz"));
+  assert.equal(res.status, 200);
+  const body = (await res.json()) as { ok: boolean; runtime: string };
+  assert.equal(body.ok, true);
+  assert.equal(body.runtime, "cloudflare-worker");
+});
+
+// Unhappy path: an unregistered route is rejected with 404 (problem+json).
+test("unknown route returns 404", async () => {
+  const res = await handler.fetch(new Request("https://example.test/__not_a_route__"));
+  assert.equal(res.status, 404);
+});

package/templates/cloudflare-worker/tests/contract.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { z } from "zod";
+import { App } from "@daloyjs/core";
+import { runContractTests } from "@daloyjs/core/contract";
+import { app } from "../src/index.ts";
+
+// Contract gate. `runContractTests` re-derives the OpenAPI contract from the
+// live route table and fails on the defects `tsc` can't see: missing or
+// duplicate operationIds, response examples that don't match their schema, and
+// routes that declare no responses. Running it under `pnpm test` means a broken
+// contract fails CI before it can ship a misleading OpenAPI spec or generate a
+// wrong typed client.
+test("the app's OpenAPI contract is internally consistent", async () => {
+  const report = await runContractTests(app);
+  assert.equal(
+    report.ok,
+    true,
+    `contract issues:\n${report.issues
+      .map((i) => `  [${i.level}] ${i.route}: ${i.message}`)
+      .join("\n")}`,
+  );
+});
+
+// Unhappy path: prove the gate actually rejects a broken contract. A route
+// without an operationId can't generate a stable client method name, so the
+// runner reports an error (operationId is required by default).
+test("the contract gate rejects a route missing its operationId", async () => {
+  const broken = new App();
+  broken.route({
+    method: "GET",
+    path: "/missing-op-id",
+    responses: { 200: { description: "ok", body: z.object({ ok: z.boolean() }) } },
+    handler: async () => ({ status: 200 as const, body: { ok: true } }),
+  });
+  const report = await runContractTests(broken);
+  assert.equal(report.ok, false);
+});

package/templates/deno-basic/README.md

@@ -47,6 +47,20 @@ first-class Deno entry point.
 deno task test
 ```
 
+## Contract gate
+
+Check that your OpenAPI contract is internally consistent (operationIds present and unique, response examples matching their schemas, no dead routes). It ships as `tests/contract_test.ts` (run under `deno task test`) and as a focused task:
+
+```bash
+deno task contract        # deno test --allow-net --allow-env tests/contract_test.ts
+```
+
+For a localhost-only gate that runs before code leaves your machine, enable the bundled pre-push hook (opt-in; bypass once with `git push --no-verify`):
+
+```bash
+deno task hooks:install   # points core.hooksPath at .githooks
+```
+
 ## What's included
 
 - `@daloyjs/core` (loaded via `jsr:` specifiers in `deno.json`).

package/templates/deno-basic/_githooks/pre-push

@@ -0,0 +1,16 @@
+#!/bin/sh
+# daloyjs-pre-push-contract-hook v1
+#
+# Localhost-only contract gate. Rejects a push whose OpenAPI contract has
+# error-level issues: missing or duplicate operationIds, response examples that
+# don't match their schema, accidental body schemas on safe methods, or routes
+# with no declared responses. Catches the class of drift the type-checker can't
+# see before it leaves your machine, with CI as the backstop.
+#
+# Enable once per clone:  deno task hooks:install   (sets core.hooksPath here)
+# Bypass once:            git push --no-verify
+if ! command -v deno >/dev/null 2>&1; then
+  echo "pre-push: deno not found on PATH. Skipping contract gate." >&2
+  exit 0
+fi
+exec deno test --allow-net --allow-env tests/contract_test.ts

package/templates/deno-basic/deno.json

@@ -5,13 +5,16 @@
     "start": "deno run --allow-net --allow-env --allow-read src/main.ts",
     "typecheck": "deno check src/main.ts",
     "test": "deno test --allow-net --allow-env tests/",
-    "gen:openapi": "deno run --allow-net --allow-env --allow-read --allow-write scripts/dump-openapi.ts"
+    "contract": "deno test --allow-net --allow-env tests/contract_test.ts",
+    "gen:openapi": "deno run --allow-net --allow-env --allow-read --allow-write scripts/dump-openapi.ts",
+    "hooks:install": "git config core.hooksPath .githooks"
   },
   "imports": {
-    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.39.1",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.39.1/banner",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.39.1/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.39.1/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.42.0",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.42.0/banner",
+    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^0.42.0/contract",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.42.0/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.42.0/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/deno-basic/tests/contract_test.ts

@@ -0,0 +1,37 @@
+import { assertEquals } from "jsr:@std/assert@^1.0.0";
+import { z } from "zod";
+import { App } from "@daloyjs/core";
+import { runContractTests } from "@daloyjs/core/contract";
+import { buildApp } from "../src/build-app.ts";
+
+// Contract gate. `runContractTests` re-derives the OpenAPI contract from the
+// live route table and fails on the defects the type-checker can't see: missing
+// or duplicate operationIds, response examples that don't match their schema,
+// and routes that declare no responses. Running it under `deno task test` means
+// a broken contract fails CI before it can ship a misleading OpenAPI spec or
+// generate a wrong typed client.
+Deno.test("the app's OpenAPI contract is internally consistent", async () => {
+  const report = await runContractTests(buildApp());
+  assertEquals(
+    report.ok,
+    true,
+    `contract issues:\n${report.issues
+      .map((i) => `  [${i.level}] ${i.route}: ${i.message}`)
+      .join("\n")}`,
+  );
+});
+
+// Unhappy path: prove the gate actually rejects a broken contract. A route
+// without an operationId can't generate a stable client method name, so the
+// runner reports an error (operationId is required by default).
+Deno.test("the contract gate rejects a route missing its operationId", async () => {
+  const broken = new App();
+  broken.route({
+    method: "GET",
+    path: "/missing-op-id",
+    responses: { 200: { description: "ok", body: z.object({ ok: z.boolean() }) } },
+    handler: async () => ({ status: 200 as const, body: { ok: true } }),
+  });
+  const report = await runContractTests(broken);
+  assertEquals(report.ok, false);
+});

package/templates/deno-basic/tests/healthz_test.ts

@@ -9,3 +9,10 @@ Deno.test("GET /healthz returns 200", async () => {
   assertEquals(body.ok, true);
   assertEquals(body.runtime, "deno");
 });
+
+// Unhappy path: an unregistered route is rejected with 404 (problem+json).
+Deno.test("unknown route returns 404", async () => {
+  const app = buildApp();
+  const res = await app.request("/__not_a_route__");
+  assertEquals(res.status, 404);
+});

package/templates/node-basic/README.md

@@ -39,6 +39,20 @@ pnpm gen
 # → generated/client/  (typed Hey API client)
 ```
 
+## Contract gate
+
+Check that your OpenAPI contract is internally consistent (operationIds present and unique, response examples matching their schemas, no dead routes):
+
+```bash
+pnpm contract        # daloy inspect --check src/build-app.ts
+```
+
+It also runs as `tests/contract.test.ts` under `pnpm test`. For a localhost-only gate that runs before code leaves your machine, enable the bundled pre-push hook (opt-in; bypass once with `git push --no-verify`):
+
+```bash
+pnpm hooks:install   # points core.hooksPath at .githooks
+```
+
 ## Build
 
 ```bash

package/templates/node-basic/_githooks/pre-push

@@ -0,0 +1,17 @@
+#!/bin/sh
+# daloyjs-pre-push-contract-hook v1
+#
+# Localhost-only contract gate. Rejects a push whose OpenAPI contract has
+# error-level issues: missing or duplicate operationIds, response examples that
+# don't match their schema, accidental body schemas on safe methods, or routes
+# with no declared responses. Catches the class of drift `tsc` can't see before
+# it leaves your machine, with CI as the backstop.
+#
+# Enable once per clone:  npm run hooks:install   (sets core.hooksPath here)
+# Bypass once:            git push --no-verify
+DALOY="./node_modules/.bin/daloy"
+if [ ! -x "$DALOY" ]; then
+  echo "pre-push: daloy CLI not found — run your package manager's install. Skipping contract gate." >&2
+  exit 0
+fi
+exec "$DALOY" inspect --check src/build-app.ts

package/templates/node-basic/package.json

@@ -12,13 +12,15 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test tests/**/*.test.ts",
+    "contract": "daloy inspect --check src/build-app.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"
+    "audit": "pnpm audit --prod",
+    "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.39.1",
+    "@daloyjs/core": "^0.42.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/node-basic/tests/contract.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { z } from "zod";
+import { App } from "@daloyjs/core";
+import { runContractTests } from "@daloyjs/core/contract";
+import { buildApp } from "../src/build-app.ts";
+
+// Contract gate. `runContractTests` re-derives the OpenAPI contract from the
+// live route table and fails on the defects `tsc` can't see: missing or
+// duplicate operationIds, response examples that don't match their schema, and
+// routes that declare no responses. Running it under `pnpm test` means a broken
+// contract fails CI before it can ship a misleading OpenAPI spec or generate a
+// wrong typed client.
+test("the app's OpenAPI contract is internally consistent", async () => {
+  const report = await runContractTests(buildApp());
+  assert.equal(
+    report.ok,
+    true,
+    `contract issues:\n${report.issues
+      .map((i) => `  [${i.level}] ${i.route}: ${i.message}`)
+      .join("\n")}`,
+  );
+});
+
+// Unhappy path: prove the gate actually rejects a broken contract. A route
+// without an operationId can't generate a stable client method name, so the
+// runner reports an error (operationId is required by default).
+test("the contract gate rejects a route missing its operationId", async () => {
+  const broken = new App();
+  broken.route({
+    method: "GET",
+    path: "/missing-op-id",
+    responses: { 200: { description: "ok", body: z.object({ ok: z.boolean() }) } },
+    handler: async () => ({ status: 200 as const, body: { ok: true } }),
+  });
+  const report = await runContractTests(broken);
+  assert.equal(report.ok, false);
+});

package/templates/node-basic/tests/healthz.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildApp } from "../src/build-app.ts";
+
+// In-process tests via `app.request(...)` — no port, no network.
+test("GET /healthz returns 200", async () => {
+  const app = buildApp();
+  const res = await app.request("/healthz");
+  assert.equal(res.status, 200);
+  const body = (await res.json()) as { ok: boolean };
+  assert.equal(body.ok, true);
+});
+
+// Unhappy path: an unregistered route is rejected with 404 (problem+json).
+test("unknown route returns 404", async () => {
+  const app = buildApp();
+  const res = await app.request("/__not_a_route__");
+  assert.equal(res.status, 404);
+});

package/templates/vercel/README.md

@@ -31,6 +31,20 @@ To brand Scalar, change `docs: true` in `api/index.ts` to `docs: { scalar: { the
 
 <!-- daloy-minimal:strip-end docs -->
 
+## Contract gate
+
+Check that your OpenAPI contract is internally consistent (operationIds present and unique, response examples matching their schemas, no dead routes). It ships as `tests/contract.test.ts` (run under `pnpm test`) and as a focused script:
+
+```bash
+pnpm contract        # daloy inspect --check api/index.ts
+```
+
+For a localhost-only gate that runs before code leaves your machine, enable the bundled pre-push hook (opt-in; bypass once with `git push --no-verify`):
+
+```bash
+pnpm hooks:install   # points core.hooksPath at .githooks
+```
+
 ## Deploy
 
 ```bash

package/templates/vercel/_githooks/pre-push

@@ -0,0 +1,17 @@
+#!/bin/sh
+# daloyjs-pre-push-contract-hook v1
+#
+# Localhost-only contract gate. Rejects a push whose OpenAPI contract has
+# error-level issues: missing or duplicate operationIds, response examples that
+# don't match their schema, accidental body schemas on safe methods, or routes
+# with no declared responses. Catches the class of drift `tsc` can't see before
+# it leaves your machine, with CI as the backstop.
+#
+# Enable once per clone:  npm run hooks:install   (sets core.hooksPath here)
+# Bypass once:            git push --no-verify
+DALOY="./node_modules/.bin/daloy"
+if [ ! -x "$DALOY" ]; then
+  echo "pre-push: daloy CLI not found — run your package manager's install. Skipping contract gate." >&2
+  exit 0
+fi
+exec "$DALOY" inspect --check api/index.ts

package/templates/vercel/package.json

@@ -8,10 +8,12 @@
     "deploy": "vercel deploy",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test tests/**/*.test.ts",
-    "audit": "pnpm audit --prod"
+    "contract": "daloy inspect --check api/index.ts",
+    "audit": "pnpm audit --prod",
+    "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.39.1",
+    "@daloyjs/core": "^0.42.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/vercel/tests/app.test.ts

@@ -8,3 +8,9 @@ test("Vercel Node.js handler responds through DaloyJS", async () => {
   assert.equal(response.status, 200);
   assert.equal((await response.json()).runtime, "vercel");
 });
+
+// Unhappy path: an unregistered route is rejected with 404 (problem+json).
+test("unknown route returns 404", async () => {
+  const response = await handler.fetch(new Request("https://example.test/__not_a_route__"));
+  assert.equal(response.status, 404);
+});

package/templates/vercel/tests/contract.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { z } from "zod";
+import { App } from "@daloyjs/core";
+import { runContractTests } from "@daloyjs/core/contract";
+import { app } from "../api/index.ts";
+
+// Contract gate. `runContractTests` re-derives the OpenAPI contract from the
+// live route table and fails on the defects `tsc` can't see: missing or
+// duplicate operationIds, response examples that don't match their schema, and
+// routes that declare no responses. Running it under `pnpm test` means a broken
+// contract fails CI before it can ship a misleading OpenAPI spec or generate a
+// wrong typed client.
+test("the app's OpenAPI contract is internally consistent", async () => {
+  const report = await runContractTests(app);
+  assert.equal(
+    report.ok,
+    true,
+    `contract issues:\n${report.issues
+      .map((i) => `  [${i.level}] ${i.route}: ${i.message}`)
+      .join("\n")}`,
+  );
+});
+
+// Unhappy path: prove the gate actually rejects a broken contract. A route
+// without an operationId can't generate a stable client method name, so the
+// runner reports an error (operationId is required by default).
+test("the contract gate rejects a route missing its operationId", async () => {
+  const broken = new App();
+  broken.route({
+    method: "GET",
+    path: "/missing-op-id",
+    responses: { 200: { description: "ok", body: z.object({ ok: z.boolean() }) } },
+    handler: async () => ({ status: 200 as const, body: { ok: true } }),
+  });
+  const report = await runContractTests(broken);
+  assert.equal(report.ok, false);
+});