create-daloy 1.3.7 → 1.4.1

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

@@ -83,7 +83,7 @@ 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 run deploy   # wrangler deploy (`pnpm deploy` is pnpm's own command)
 pnpm audit        # supply-chain audit
 ```
 
@@ -138,56 +138,63 @@ when it helps consumers understand or safely automate the route:
 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.
+   use `@cloudflare/vitest-pool-workers` when you need bindings
+   (Wrangler's `unstable_dev` is deprecated).
 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
 
 ```ts
+import { env } from "cloudflare:workers";
 import { z } from "zod";
 import { App, NotFoundError, rateLimit, requestId, secureHeaders } from "@daloyjs/core";
 import { toFetchHandler } from "@daloyjs/core/cloudflare";
 
-interface Env {
-  BOOKS: KVNamespace;
-  JWT_SECRET: string;
+// Type your bindings once; `env` from "cloudflare:workers" is typed from this.
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      BOOKS: KVNamespace;
+      JWT_SECRET: string;
+    }
+  }
 }
 
 const Book = z.object({ id: z.string(), title: z.string() }).strict();
 
-function buildApp(env: Env) {
-  const app = new App({ bodyLimitBytes: 1024 * 1024, requestTimeoutMs: 5_000 });
-  app.use(requestId());
-  app.use(secureHeaders());
-  app.use(rateLimit({ windowMs: 60_000, max: 120 }));
-
-  app.get(
-    "/books/:id",
-    {
-      operationId: "getBookById",
-      tags: ["Books"],
-      request: { params: z.object({ id: z.string().min(1) }).strict() },
-      responses: {
-        200: { description: "Found", body: Book },
-        404: { description: "Not found" },
-      },
+// Build the App ONCE at module scope. Creating it per request would give every
+// request a fresh rateLimit() store, so the limit could never trigger.
+const app = new App({
+  bodyLimitBytes: 1024 * 1024,
+  requestTimeoutMs: 5_000,
+  production: true,
+  behindProxy: { hops: 1 },
+});
+app.use(requestId());
+app.use(secureHeaders());
+app.use(rateLimit({ windowMs: 60_000, max: 120 }));
+
+app.get(
+  "/books/:id",
+  {
+    operationId: "getBookById",
+    tags: ["Books"],
+    request: { params: z.object({ id: z.string().min(1) }).strict() },
+    responses: {
+      200: { description: "Found", body: Book },
+      404: { description: "Not found" },
     },
-    async ({ params }) => {
-      const raw = await env.BOOKS.get(params.id, "json");
-      if (!raw) throw new NotFoundError(`Book ${params.id} not found`);
-      return { status: 200 as const, body: Book.parse(raw) };
-    }
-  );
-
-  return app;
-}
-
-export default {
-  fetch: (req: Request, env: Env, ctx: ExecutionContext) =>
-    toFetchHandler<Env>(buildApp(env)).fetch(req, env, ctx),
-};
+  },
+  async ({ params }) => {
+    // Bindings are read per request, inside the handler.
+    const raw = await env.BOOKS.get(params.id, "json");
+    if (!raw) throw new NotFoundError(`Book ${params.id} not found`);
+    return { status: 200 as const, body: Book.parse(raw) };
+  }
+);
+
+export default toFetchHandler(app);
 ```
 
 ## Validation & schema conventions
@@ -222,9 +229,11 @@ Add CORS only when needed, with an explicit `origin` allowlist.
 
 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`.
-3. Pass `env` into `buildApp(env)` so handlers receive bindings via
-   closure or factory argument. **Never read bindings via globals.**
+2. Type the binding on the `Cloudflare.Env` interface (see the example
+   above).
+3. Read bindings inside handlers with `import { env } from "cloudflare:workers"`.
+   Build the `App` once at module scope; **never create it per request**
+   (that resets the rateLimit store and re-compiles every route).
 4. Store secrets via `wrangler secret put` — they appear on `env` but
    are not committed to `wrangler.toml`.
 
@@ -277,13 +286,15 @@ Two patterns:
 
 - **In-process** with `app.request(...)` for pure logic that does not
   need bindings.
-- **Workers-aware** runners (`@cloudflare/vitest-pool-workers` or
-  Wrangler `unstable_dev`) when KV/D1/etc. are involved.
+- **Workers-aware** runner (`@cloudflare/vitest-pool-workers`) when
+  KV/D1/etc. are involved.
 
 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.
+conflict (409), rate limiting (429). For external services, run under
+`@cloudflare/vitest-pool-workers` with test bindings, or keep the call behind
+a small module that tests replace. Do not rebuild the App per request to
+inject fakes.
 For user-owned or tenant-owned resources, use at least two principals and
 prove that Alice's valid token cannot list, read, update, or delete Bob's
 record.
@@ -339,10 +350,10 @@ reference. Skip that file for ordinary route work.
 
 ## Logging & observability
 
-- Use `ctx.log` — it carries the request id.
+- Use `ctx.state.log` — it carries the request id.
 - `console.log` in Workers shows up in `wrangler tail`. Prefer
   structured logs through the framework logger.
-- For tracing, the `tracing()` middleware emits OpenTelemetry-compatible
+- For tracing, the `otelTracing(opts)` middleware emits OpenTelemetry-compatible
   spans; wire up a Workers-friendly exporter when needed.
 
 ## Configuration & secrets

package/templates/cloudflare-worker/_dockerignore

@@ -10,5 +10,10 @@ coverage
 .env
 .env.*
 !.env.example
+# Wrangler's local secrets file.
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+*.pem
+*.key
 generated
-otherdocs

package/templates/cloudflare-worker/_gitignore

@@ -14,3 +14,8 @@ dist/
 # consumer's lockfile and can pin transitives to unsigned tarballs.
 # See https://socket.dev/blog/understanding-the-security-concerns-of-npm-shrinkwrap
 npm-shrinkwrap.json
+
+# Private keys and certificates (keep them in a secret manager, not git).
+*.pem
+*.key
+*.p12

package/templates/cloudflare-worker/_npmrc

@@ -1,4 +1,7 @@
 # DaloyJS supply-chain hardening defaults — see the "Supply chain" docs.
+#
+# pnpm 11+ reads its settings from pnpm-workspace.yaml, not from this file,
+# so the same values are set there. They stay here for npm and older tooling.
 
 auto-install-peers=true
 strict-peer-dependencies=true

package/templates/cloudflare-worker/package.json

@@ -10,17 +10,17 @@
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/**/*.test.ts",
+    "test": "node --test \"tests/**/*.test.ts\"",
     "contract": "daloy inspect --check src/index.ts",
     "audit": "pnpm audit --prod",
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.3.7",
+    "@daloyjs/core": "^1.4.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20240909.0",
+    "@cloudflare/workers-types": "^5.20260926.1",
     "typescript": "^7.0.2",
     "wrangler": "^4.0.0"
   }

package/templates/cloudflare-worker/pnpm-workspace.yaml

@@ -22,3 +22,19 @@ minimumReleaseAge: 1440
 # Transitive deps must resolve from the configured registry, which makes
 # typosquatted-tarball and compromised-fork attacks much harder to land.
 blockExoticSubdeps: true
+
+# pnpm 11+ ignores these keys in `.npmrc`, so they live here. `.npmrc` keeps
+# the same values for older tooling.
+#
+# Never run dependency lifecycle scripts (postinstall / preinstall / prepare):
+# the main execution channel of the chalk/debug, node-ipc and Shai-Hulud
+# malware. If you later need a build step, allowlist that one package with
+# `allowBuilds` instead of turning this off.
+ignoreScripts: true
+# Fail on unmet or incompatible peer dependencies instead of warning.
+strictPeerDependencies: true
+# Re-verify package integrity hashes against the lockfile on install.
+verifyStoreIntegrity: true
+# Use the lockfile as-is whenever it satisfies package.json.
+preferFrozenLockfile: true
+autoInstallPeers: true

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

@@ -6,11 +6,12 @@ const app = new App({
   bodyLimitBytes: 256 * 1024,
   requestTimeoutMs: 5_000,
   production: true,
-  // Cloudflare Workers always run behind Cloudflare's edge, which sets
-  // X-Forwarded-For. Declare that single trusted hop so DaloyJS reads the real
-  // client IP instead of refusing the (otherwise spoofable) header and
-  // returning 500 in production. Increase the hop count if you put an
-  // additional proxy in front of the Worker.
+  // Cloudflare Workers always run behind Cloudflare's edge, which appends the
+  // real client IP as the right-most X-Forwarded-For entry. Declaring that
+  // single trusted hop stops production from refusing the header with a 500,
+  // and rateLimit() below follows it, so each client gets its own bucket
+  // instead of every caller sharing one. Increase the hop count only if you
+  // put an additional proxy in front of the Worker.
   behindProxy: { hops: 1 },
   // daloy-minimal:strip-start docs
   // `docs: "auto"` mounts GET /openapi.json, /openapi.yaml and /docs (Scalar
@@ -28,8 +29,8 @@ const app = new App({
 
 app.use(requestId());
 app.use(secureHeaders());
-// The in-memory limiter resets per Worker isolate, so treat it as a
-// per-isolate abuse brake, not a global quota. For high-traffic routes, attach
+// Keyed per client (via behindProxy above). The in-memory store resets per
+// Worker isolate, so treat it as a per-isolate abuse brake, not a global quota. For high-traffic routes, attach
 // Cloudflare's native rate-limit binding in addition to — not instead of —
 // this baseline. Do not remove it to make a test pass; raise `max` per route.
 app.use(rateLimit({ windowMs: 60_000, max: 120 }));

package/templates/deno-basic/AGENTS.md

@@ -38,7 +38,7 @@ The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint
 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`.
+6. Deno permissions are part of the contract — keep `--allow-net` and the `--allow-env` allowlist narrow; never use `--allow-all`.
 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`.

package/templates/deno-basic/README.md

@@ -72,7 +72,7 @@ deno task hooks:install   # points core.hooksPath at .githooks
 
 <!-- daloy-minimal:strip-end books -->
 
-- Minimal permissions: `--allow-net --allow-env --allow-read` for `dev`.
+- Minimal permissions: `--allow-net` plus an `--allow-env` allowlist (`PORT`, `DENO_ENV`, `TRUST_PROXY_HOPS`, `PUBLIC_URL`) for `dev` and `start`; add a variable there when you read a new one.
 
 ## Authentication (OAuth2 / OpenID Connect)
 

package/templates/deno-basic/_Dockerfile

@@ -30,8 +30,10 @@
 #     builds can pin to an immutable digest:
 #       docker build --build-arg \
 #         DENO_IMAGE=denoland/deno:alpine@sha256:<digest> .
-#     Dependabot's `docker` ecosystem (see `.github/dependabot.yml`)
-#     keeps the digest fresh.
+#     The default is a floating tag, and Dependabot's `docker` ecosystem
+#     cannot update a `FROM ${ARG}` line. For automatic digest updates,
+#     write the digest into the ARG default below (for example
+#     `ARG DENO_IMAGE=denoland/deno:alpine@sha256:<digest>`).
 
 # Override at build time to pin a specific digest.
 ARG DENO_IMAGE=denoland/deno:alpine
@@ -41,10 +43,12 @@ WORKDIR /app
 # Cache deps in a layer that only invalidates when imports change.
 COPY deno.json deno.lock* ./
 COPY src ./src
-# `deno cache` resolves and verifies every import against the lockfile
-# and bakes them into Deno's module cache. The resulting image cannot
-# resolve any module that was not present at build time.
-RUN deno cache --lock=deno.lock src/main.ts || deno cache src/main.ts
+# `deno install --frozen=true` resolves every import from the committed
+# lockfile and bakes it into Deno's module cache. It fails the build when a
+# dependency does not match deno.lock, instead of silently resolving
+# something newer (there is deliberately no unlocked fallback). The resulting
+# image cannot resolve any module that was not present at build time.
+RUN deno install --frozen=true --entrypoint src/main.ts
 
 FROM ${DENO_IMAGE} AS runner
 WORKDIR /app

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

@@ -74,7 +74,7 @@ DaloyJS is a **contract-first** framework. Internalize these rules:
   `generated/openapi.json`.
 - `deno.json` — tasks, import map, and JSR-first dependency specifiers. **There is no
   `package.json`** in this project — do not add one.
-- `tests/` — Deno test files (`*.test.ts`).
+- `tests/` — Deno test files (`*_test.ts`).
 - `generated/` — **machine-written**. Never edit by hand.
 
 ## Commands cheat-sheet
@@ -199,7 +199,7 @@ app.get(
 - Throw typed errors from `@daloyjs/core` — they serialize to RFC 9457
   problem responses.
 - Add a `responses[code]` entry for every error you throw.
-- Do not swallow errors. Log via `ctx.log.error(...)` and rethrow.
+- Do not swallow errors. Log via `ctx.state.log.error(...)` and rethrow.
 
 ## Middleware
 
@@ -299,7 +299,7 @@ Aim for complete happy- and unhappy-path test coverage of the routes you 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.
-- Validate env via Zod at boot (`Deno.env.toObject()`). Fail fast on
+- Validate env via Zod at boot (build the object from explicit `Deno.env.get("NAME")` calls; `Deno.env.toObject()` needs unscoped `--allow-env` and fails under the Dockerfile's allowlist). Fail fast on
   missing config.
 - For auth, verify JWT signatures against an allowlist of keys, never
   trust the `alg` header, always check `exp` / `nbf`.
@@ -331,7 +331,7 @@ Skip that file for ordinary route work.
 
 ## Logging & observability
 
-- Use `ctx.log` — it carries the request id.
+- Use `ctx.state.log` — it carries the request id.
 - Avoid `console.log` in production code paths.
 
 ## Configuration & secrets

package/templates/deno-basic/_dockerignore

@@ -8,4 +8,7 @@ coverage
 .env.*
 !.env.example
 generated
-otherdocs
+# Private keys and certificates never belong in an image.
+*.pem
+*.key
+*.p12

package/templates/deno-basic/_gitignore

@@ -10,3 +10,8 @@ generated/
 # consumer's lockfile and can pin transitives to unsigned tarballs.
 # See https://socket.dev/blog/understanding-the-security-concerns-of-npm-shrinkwrap
 npm-shrinkwrap.json
+
+# Private keys and certificates (keep them in a secret manager, not git).
+*.pem
+*.key
+*.p12

package/templates/deno-basic/deno.json

@@ -1,20 +1,20 @@
 {
   "name": "my-daloy-deno-app",
   "tasks": {
-    "dev": "deno run --allow-net --allow-env --allow-read --watch src/main.ts",
-    "start": "deno run --allow-net --allow-env --allow-read src/main.ts",
-    "typecheck": "deno check src/main.ts",
+    "dev": "deno run --allow-net --allow-env=PORT,DENO_ENV,TRUST_PROXY_HOPS,PUBLIC_URL --watch src/main.ts",
+    "start": "deno run --allow-net --allow-env=PORT,DENO_ENV,TRUST_PROXY_HOPS,PUBLIC_URL src/main.ts",
+    "typecheck": "deno check src/ tests/ scripts/",
     "test": "deno test --allow-net --allow-env tests/",
     "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@^1.3.7",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^1.3.7/banner",
-    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^1.3.7/contract",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^1.3.7/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^1.3.7/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^1.4.0",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^1.4.0/banner",
+    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^1.4.0/contract",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^1.4.0/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^1.4.0/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/deno-basic/deno.lock

@@ -1,14 +1,14 @@
 {
   "version": "5",
   "specifiers": {
-    "jsr:@daloyjs/daloy@^1.0.0-rc.5": "1.0.0-rc.5",
+    "jsr:@daloyjs/daloy@^1.4.0": "1.4.0",
     "jsr:@std/assert@1": "1.0.19",
     "jsr:@std/internal@^1.0.12": "1.0.14",
     "npm:zod@^4.4.3": "4.4.3"
   },
   "jsr": {
-    "@daloyjs/daloy@1.0.0-rc.5": {
-      "integrity": "30d4d04baae914d7edaaf827d144e28caa41fda6bf77817840b8863d345378e6"
+    "@daloyjs/daloy@1.4.0": {
+      "integrity": "95c4a18e8e1b134a5c4038134fe0c2c862ce1c48d0b56d5b7ae0f1800945ebed"
     },
     "@std/assert@1.0.19": {
       "integrity": "eaada96ee120cb980bc47e040f82814d786fe8162ecc53c91d8df60b8755991e",
@@ -27,7 +27,7 @@
   },
   "workspace": {
     "dependencies": [
-      "jsr:@daloyjs/daloy@^1.0.0-rc.5",
+      "jsr:@daloyjs/daloy@^1.4.0",
       "npm:zod@^4.4.3"
     ]
   }

package/templates/node-basic/README.md

@@ -18,6 +18,11 @@ curl http://localhost:3000/books/1
 <!-- daloy-minimal:strip-end books -->
 ```
 
+> **Install refused right after a DaloyJS release?** New installs wait 24 hours
+> before using a freshly published version (`minimumReleaseAge` in
+> `pnpm-workspace.yaml`), a supply-chain safeguard. If `@daloyjs/core` was just
+> released, retry a few hours later rather than turning the safeguard off.
+
 <!-- daloy-minimal:strip-start docs -->
 
 ## API documentation

package/templates/node-basic/_Dockerfile

@@ -16,8 +16,11 @@
 #     pin to an immutable digest (recommended for production):
 #       docker build --build-arg \
 #         NODE_IMAGE=node:24-alpine@sha256:<digest> .
-#     Dependabot's `docker` ecosystem (see `.github/dependabot.yml`)
-#     keeps the digest fresh. The companion `container-scan.yml`
+#     The default is a floating tag, and Dependabot's `docker` ecosystem
+#     cannot update a `FROM ${ARG}` line. For automatic digest updates,
+#     write the digest into the ARG default below (for example
+#     `ARG NODE_IMAGE=node:24-alpine@sha256:<digest>`).
+#     The companion `container-scan.yml`
 #     workflow lints this file with hadolint and scans the built
 #     image with Trivy on every PR.
 
@@ -28,7 +31,7 @@ ARG NODE_IMAGE=node:24-alpine
 FROM ${NODE_IMAGE} AS builder
 WORKDIR /app
 COPY package.json pnpm-lock.yaml* ./
-RUN corepack enable && corepack prepare pnpm@latest --activate && \
+RUN corepack enable && corepack prepare pnpm@11.1.3 --activate && \
     pnpm install --frozen-lockfile --ignore-scripts
 COPY . .
 RUN pnpm build

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

@@ -231,7 +231,7 @@ app.get(
 - Add a `responses[code]` entry for every error you throw, so the OpenAPI
   spec and the typed client know it can happen.
 - Do not swallow errors in handlers. If you need to log and rethrow, use
-  `ctx.log.error(err, "context")` and rethrow.
+  `ctx.state.log.error({ err }, "context")` and rethrow.
 - For unexpected errors, let them bubble. The framework's error middleware
   will convert them into a generic 500 problem response and log them with
   the request ID for correlation.
@@ -315,7 +315,7 @@ test("GET /healthz returns ok", async () => {
   const app = buildApp();
   const res = await app.request("/healthz");
   assert.equal(res.status, 200);
-  const body = await res.json();
+  const body = (await res.json()) as { ok: boolean; uptime: number };
   assert.equal(body.ok, true);
   assert.ok(typeof body.uptime === "number");
 });
@@ -392,14 +392,14 @@ reference. Skip that file for ordinary route work.
 
 ## Logging & observability
 
-- The default logger emits structured JSON in production and pretty logs
-  in development. Use it via the handler context: `await handler(ctx)` →
-  `ctx.log.info({ userId }, "message")`.
+- The default logger emits structured JSON (it is silent under
+  `NODE_ENV=test`). Use it via the handler context:
+  `ctx.state.log.info({ userId }, "message")`.
 - Always include the request id in log lines automatically emitted by
   the framework. When you add your own logs, the request id is on
-  `ctx.requestId` and on the bound child logger.
-- For tracing, the `tracing()` middleware (from `@daloyjs/core`) emits
-  OpenTelemetry-compatible spans. Enable it once the user wires up an
+  `ctx.state.requestId` and on the bound child logger (`ctx.state.log`).
+- For tracing, the `otelTracing(opts)` middleware (from `@daloyjs/core`)
+  emits OpenTelemetry-compatible spans. Enable it once the user wires up an
   exporter.
 
 ## Configuration & secrets

package/templates/node-basic/_dockerignore

@@ -10,4 +10,7 @@ coverage
 .env.*
 !.env.example
 generated
-otherdocs
+# Private keys and certificates never belong in an image.
+*.pem
+*.key
+*.p12

package/templates/node-basic/_env.example

@@ -1 +1,12 @@
+# Copy to .env for local use. Real secrets belong in your platform's secret
+# store, never in git (.env is git-ignored).
 PORT=3000
+
+# Number of reverse-proxy hops in front of the app (load balancer, PaaS edge,
+# CDN). Required in production behind any proxy: without it DaloyJS refuses
+# forwarded headers and answers 500. rateLimit() also uses it to key each
+# client instead of the proxy. Leave unset when clients connect directly.
+# TRUST_PROXY_HOPS=1
+
+# Public base URL, used as the OpenAPI `servers` entry (no localhost default).
+# PUBLIC_URL=https://api.example.com

package/templates/node-basic/_gitignore

@@ -12,3 +12,8 @@ generated/
 # consumer's lockfile and can pin transitives to unsigned tarballs.
 # See https://socket.dev/blog/understanding-the-security-concerns-of-npm-shrinkwrap
 npm-shrinkwrap.json
+
+# Private keys and certificates (keep them in a secret manager, not git).
+*.pem
+*.key
+*.p12

package/templates/node-basic/_npmrc

@@ -3,6 +3,9 @@
 # See the DaloyJS "Supply chain" docs and the 2026-05-11 TanStack incident
 # postmortem (https://tanstack.com/blog/npm-supply-chain-compromise-postmortem)
 # for context on why every line below is on by default.
+#
+# pnpm 11+ reads its settings from pnpm-workspace.yaml, not from this file,
+# so the same values are set there. They stay here for npm and older tooling.
 
 auto-install-peers=true
 strict-peer-dependencies=true

package/templates/node-basic/package.json

@@ -11,7 +11,7 @@
     "start": "node dist/index.js",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/**/*.test.ts",
+    "test": "node --test \"tests/**/*.test.ts\"",
     "contract": "daloy inspect --check src/build-app.ts",
     "gen:openapi": "node scripts/dump-openapi.ts",
     "gen:client": "openapi-ts",
@@ -20,7 +20,7 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.3.7",
+    "@daloyjs/core": "^1.4.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/node-basic/pnpm-workspace.yaml

@@ -22,3 +22,19 @@ minimumReleaseAge: 1440
 # Transitive deps must resolve from the configured registry, which makes
 # typosquatted-tarball and compromised-fork attacks much harder to land.
 blockExoticSubdeps: true
+
+# pnpm 11+ ignores these keys in `.npmrc`, so they live here. `.npmrc` keeps
+# the same values for older tooling.
+#
+# Never run dependency lifecycle scripts (postinstall / preinstall / prepare):
+# the main execution channel of the chalk/debug, node-ipc and Shai-Hulud
+# malware. If you later need a build step, allowlist that one package with
+# `allowBuilds` instead of turning this off.
+ignoreScripts: true
+# Fail on unmet or incompatible peer dependencies instead of warning.
+strictPeerDependencies: true
+# Re-verify package integrity hashes against the lockfile on install.
+verifyStoreIntegrity: true
+# Use the lockfile as-is whenever it satisfies package.json.
+preferFrozenLockfile: true
+autoInstallPeers: true

package/templates/vercel/AGENTS.md

@@ -19,7 +19,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.j
 - `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 run deploy` — deploy to Vercel
 - `pnpm audit` — supply-chain audit
 
 ## Project shape

package/templates/vercel/README.md

@@ -18,6 +18,11 @@ curl http://localhost:3000/books/1
 <!-- daloy-minimal:strip-end books -->
 ```
 
+> **Install refused right after a DaloyJS release?** New installs wait 24 hours
+> before using a freshly published version (`minimumReleaseAge` in
+> `pnpm-workspace.yaml`), a supply-chain safeguard. If `@daloyjs/core` was just
+> released, retry a few hours later rather than turning the safeguard off.
+
 <!-- daloy-minimal:strip-start docs -->
 
 ## API documentation
@@ -48,9 +53,21 @@ pnpm hooks:install   # points core.hooksPath at .githooks
 ## Deploy
 
 ```bash
-pnpm deploy
+pnpm run deploy
 ```
 
+One-time Vercel project setting: add the environment variable
+`ENABLE_EXPERIMENTAL_COREPACK=1` (Project → Settings → Environment Variables).
+With it, Vercel builds with the pnpm pinned in `package.json#packageManager`
+(the same version as CI). Without it, Vercel guesses pnpm 9 from the lockfile,
+which fails this project's `engines.pnpm >= 11` check and aborts the build.
+
+This template uses TypeScript 5.9 on purpose: Vercel's Node builder loads the
+project's `typescript` package through its JavaScript API, which TypeScript 7
+(the native compiler) no longer provides, and the Vercel CLI's own tooling
+declares `typescript ^4 || ^5` as a peer. Move up once Vercel supports newer
+TypeScript.
+
 The API entry lives at `api/index.ts` and uses `@daloyjs/core/vercel`:
 
 ```ts
@@ -81,7 +98,7 @@ export default toWebHandler(app);
 
 So DaloyJS owns all routing and the app's routes are served at the **site root**
 (`/healthz`, `/docs`, `/openapi.json`, …) rather than under `/api/*`. Without
-this rewrite the function only answers `/api/*` and the root domain returns a
+this rewrite the function only answers `/api` and the root domain returns a
 Vercel 404. (The demo defines no `/` route, so the bare root returns the app's
 problem+json 404 — visit `/docs` or `/healthz`.)