create-daloy 0.26.0 → 0.34.0

package/templates/_ci/node/_github/workflows/container-scan.yml

@@ -0,0 +1,177 @@
+# Container security scan generated by create-daloy --with-ci.
+#
+# Inspired by the controls in
+# https://snyk.io/blog/scale-container-security-effortlessly/ — but built
+# only from SHA-pinned, free, open-source GitHub Actions:
+#
+#   - hadolint lints the Dockerfile for known anti-patterns and unsafe
+#     instructions (CIS Docker Benchmark coverage).
+#   - Trivy scans the source tree (config + secrets + vulnerable lockfile
+#     entries), then scans the built image for OS + language CVEs.
+#   - SARIF results are uploaded to the Code Scanning tab so findings show
+#     up in the same place as CodeQL.
+#
+# The job is a no-op if the project has no Dockerfile at the repo root, so
+# it is safe to keep enabled for templates that disable the container.
+
+name: Container scan
+
+on:
+  pull_request:
+    paths:
+      - "Dockerfile"
+      - ".dockerignore"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "package-lock.json"
+      - "yarn.lock"
+      - "bun.lock"
+      - ".github/workflows/container-scan.yml"
+  push:
+    branches: [main]
+    paths:
+      - "Dockerfile"
+      - ".dockerignore"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "package-lock.json"
+      - "yarn.lock"
+      - "bun.lock"
+      - ".github/workflows/container-scan.yml"
+  schedule:
+    # Weekly run catches newly-disclosed base-image CVEs even when the
+    # Dockerfile itself hasn't changed.
+    - cron: "17 6 * * 1"
+
+permissions: {}
+
+concurrency:
+  group: container-scan-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  scan:
+    name: Lint + scan container
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2
+        with:
+          egress-policy: audit
+          disable-sudo: true
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+          show-progress: false
+
+      - name: Detect Dockerfile
+        id: detect
+        run: |
+          if [ -f Dockerfile ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No Dockerfile found at the repo root; skipping container scan."
+          fi
+
+      - name: Pin check (FROM @sha256 digest)
+        # Aikido x Root.io ("Harden your containers without the headaches",
+        # 2026) makes the point that a floating tag like `node:24-alpine`
+        # silently re-resolves to a new digest on every build, so a
+        # base-image CVE that lands tomorrow is invisible to today's
+        # scan results. Pinning `FROM <image>@sha256:<digest>` makes the
+        # base reproducible; the `docker` Dependabot ecosystem in
+        # `.github/dependabot.yml` then opens a PR when a fresher digest
+        # is published so the pin stays current instead of stale. This
+        # step surfaces unpinned `FROM` lines as PR annotations without
+        # failing the build, so a brand-new scaffold still goes green.
+        if: steps.detect.outputs.present == 'true'
+        run: |
+          unpinned=0
+          while IFS= read -r line; do
+            ref="${line#FROM }"
+            ref="${ref#from }"
+            ref="${ref%% AS *}"
+            ref="${ref%% as *}"
+            ref="${ref## }"
+            ref="${ref%% }"
+            case "$ref" in
+              scratch|"\${"*|*"@sha256:"*) ;;
+              *)
+                echo "::warning file=Dockerfile::FROM '$ref' is not pinned to a @sha256:<digest> — see Aikido x Root.io 'Harden your containers' (Daloy SECURITY.md → Container base-image hardening)."
+                unpinned=$((unpinned + 1))
+                ;;
+            esac
+          done < <(grep -E '^(FROM|from) ' Dockerfile || true)
+          if [ "$unpinned" -gt 0 ]; then
+            echo "::notice::$unpinned unpinned FROM line(s). Override at build time with --build-arg NODE_IMAGE=node:24-alpine@sha256:<digest> or hard-code the digest in the Dockerfile and let Dependabot keep it fresh."
+          fi
+
+      - name: Lint Dockerfile (hadolint)
+        if: steps.detect.outputs.present == 'true'
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5 # v3.3.0
+        with:
+          dockerfile: Dockerfile
+          format: sarif
+          output-file: hadolint.sarif
+          no-fail: true
+
+      - name: Upload hadolint SARIF
+        if: steps.detect.outputs.present == 'true'
+        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        with:
+          sarif_file: hadolint.sarif
+          category: hadolint
+
+      - name: Trivy filesystem scan (config + secrets + vulns)
+        if: steps.detect.outputs.present == 'true'
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          severity: HIGH,CRITICAL
+          ignore-unfixed: true
+          format: sarif
+          output: trivy-fs.sarif
+          exit-code: "0"
+
+      - name: Upload Trivy filesystem SARIF
+        if: steps.detect.outputs.present == 'true'
+        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        with:
+          sarif_file: trivy-fs.sarif
+          category: trivy-fs
+
+      - name: Build image (no push)
+        if: steps.detect.outputs.present == 'true'
+        run: |
+          # Tag locally so the scan step has something to point at.
+          docker build --pull --load -t local/app:scan .
+
+      - name: Trivy image scan
+        if: steps.detect.outputs.present == 'true'
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          image-ref: local/app:scan
+          severity: HIGH,CRITICAL
+          ignore-unfixed: true
+          format: sarif
+          output: trivy-image.sarif
+          # Block merges only on CRITICAL by default; relax with `severity`
+          # / `exit-code` if it gets noisy in your pipeline.
+          exit-code: "1"
+          vuln-type: os,library
+
+      - name: Upload Trivy image SARIF
+        if: always() && steps.detect.outputs.present == 'true'
+        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        with:
+          sarif_file: trivy-image.sarif
+          category: trivy-image

package/templates/_ci/node/_github/workflows/vuln-scan.yml

@@ -0,0 +1,89 @@
+# Daily vulnerability scan generated by create-daloy --with-ci.
+#
+# Why this exists for a REST API service:
+#   `ci.yml` already runs an audit on every PR and push to main, which
+#   catches CVEs at change time. It does NOT catch CVEs disclosed AFTER
+#   the last change. A long-running service may sit on `main` for weeks
+#   between deploys; a worm published to a transitive dep yesterday is
+#   invisible to that pipeline until the next PR lands.
+#
+#   SOC 2 CC7.1 ("the entity uses detection and monitoring procedures to
+#   identify ... vulnerabilities") and the Aikido write-up "A Guide to
+#   Automating Technical Vulnerability Management for SOC 2" both require
+#   a *continuous* cadence: an auditable, scheduled scan that produces
+#   evidence on a fixed interval regardless of developer activity.
+#
+#   This workflow runs the package manager's audit against the committed
+#   lockfile every day at 06:13 UTC. When the package manager exposes
+#   separate production and full-tree scopes, the production-tree scan is
+#   blocking (it covers what actually ships to your users) and the
+#   full-tree scan is advisory so a low-severity dev-tool advisory does
+#   not page the on-call.
+#
+# Hardening:
+#   * `permissions: {}` at the top level; the single job opts in to
+#     `contents: read` only.
+#   * Third-party actions are SHA-pinned and managed by Dependabot.
+#   * `step-security/harden-runner` runs in audit mode (no need to block
+#     egress on a read-only scan that touches no secret).
+#   * `actions/checkout` runs with `persist-credentials: false`.
+#   * Lifecycle scripts are disabled during install so a malicious dev
+#     dep cannot run a postinstall during the scan itself.
+#   * No GitHub Actions cache — matches `ci.yml` rationale (shared cache
+#     scope between fork PRs and pushes to `main` is a known bridge).
+
+name: Vuln scan
+
+on:
+  schedule:
+    # 06:13 UTC daily — offset from CodeQL (Mon 04:37), Scorecard
+    # (Tue 05:23), and Zizmor (daily 07:00) so the four scheduled
+    # security workflows do not all queue at once.
+    - cron: "13 6 * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: vuln-scan-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    name: Daily SCA
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@ab7a9404c0f3da075243ca237b5fac12c98deaa5 # v2
+        with:
+          egress-policy: audit
+          disable-sudo: true
+          disable-file-monitoring: false
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+          show-progress: false
+
+__SETUP_PACKAGE_MANAGER_STEP__
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: 24
+
+__SETUP_BUN_RUNTIME_STEP__
+
+      - name: Install dependencies (no scripts)
+        run: __INSTALL_COMMAND__
+        env:
+          npm_config_ignore_scripts: "true"
+
+__AUDIT_PROD_STEP__
+
+__AUDIT_FULL_STEP__

package/templates/bun-basic/AGENTS.md

@@ -21,6 +21,16 @@ A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime.
 - `generated/` — machine-written. Do not edit by hand.
 - `tests/` — Bun test files.
 
+## Imports
+
+This project uses TypeScript with `"moduleResolution": "Bundler"` and `"allowImportingTsExtensions": true`. Relative imports use the **`.ts` extension** directly, since Bun executes TypeScript natively:
+
+```ts
+import { buildApp } from "./build-app.ts";
+```
+
+Do not write `.js` here — that's the Node NodeNext convention and will fail to resolve under Bun's setup. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
+
 ## Core rules
 
 1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.

package/templates/bun-basic/README.md

@@ -44,6 +44,16 @@ bun run gen:client
 bun test
 ```
 
+## Imports
+
+This project uses TypeScript with `"moduleResolution": "Bundler"` and `"allowImportingTsExtensions": true`. Relative imports use the **`.ts` extension** directly:
+
+```ts
+import { buildApp } from "./build-app.ts";
+```
+
+Do not use `.js` here — that's the Node NodeNext convention and will not resolve under Bun's setup.
+
 ## What's included
 
 - `@daloyjs/core` with starter security middleware: `secureHeaders`, `requestId`, and `rateLimit`.

package/templates/bun-basic/_Dockerfile

@@ -0,0 +1,57 @@
+# syntax=docker/dockerfile:1.7
+# Container-first defaults for a DaloyJS app running on Bun.
+#
+# Hardening shipped out of the box:
+#   - Non-root runtime user (`bun`, uid 1000 — created by the official
+#     `oven/bun` image).
+#   - Read-only-root-filesystem friendly: no runtime writes outside the
+#     ephemeral working dir. Run with `--read-only --tmpfs /tmp` or set
+#     `readOnlyRootFilesystem: true` in your orchestrator.
+#   - `STOPSIGNAL SIGTERM` so DaloyJS's graceful-shutdown drain fires
+#     when the container is stopped.
+#   - `HEALTHCHECK` wired to the `/healthz` route registered in
+#     `src/build-app.ts`. The healthcheck uses BusyBox `wget` already
+#     present in the alpine base — no `curl`, no extra packages, no
+#     `exec`-ing shell scripts.
+#   - `tini` as PID 1 for proper signal forwarding and zombie reaping
+#     in case the app spawns subprocesses.
+#   - `pnpm install --frozen-lockfile --ignore-scripts` matches the
+#     supply-chain defaults in `.npmrc` (no lifecycle scripts run).
+#   - Base images are consumed through ARGs so production builds can
+#     pin to immutable digests:
+#       docker build --build-arg \
+#         NODE_IMAGE=node:24-alpine@sha256:<digest> \
+#         BUN_IMAGE=oven/bun:1-alpine@sha256:<digest> .
+#     Dependabot's `docker` ecosystem (see `.github/dependabot.yml`)
+#     keeps the digest fresh. The companion `container-scan.yml`
+#     workflow lints this file with hadolint and scans the built image
+#     with Trivy on every PR.
+
+# Override at build time to pin a specific digest.
+ARG NODE_IMAGE=node:24-alpine
+ARG BUN_IMAGE=oven/bun:1-alpine
+
+FROM ${NODE_IMAGE} AS builder
+WORKDIR /app
+# Install deps in a layer that only invalidates when manifests change.
+COPY package.json pnpm-lock.yaml* ./
+RUN corepack enable && corepack prepare pnpm@latest --activate && \
+  pnpm install --frozen-lockfile --ignore-scripts
+COPY . .
+
+FROM ${BUN_IMAGE} AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+# tini only — no curl, no extra packages. BusyBox `wget` (already in
+# alpine) is enough for the HEALTHCHECK below.
+RUN apk add --no-cache tini
+COPY --from=builder --chown=bun:bun /app/node_modules ./node_modules
+COPY --from=builder --chown=bun:bun /app/src ./src
+COPY --from=builder --chown=bun:bun /app/package.json ./package.json
+USER bun
+EXPOSE 3000
+STOPSIGNAL SIGTERM
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -q -O /dev/null --spider http://127.0.0.1:3000/healthz || exit 1
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["bun", "run", "src/index.ts"]

package/templates/bun-basic/_dockerignore

@@ -0,0 +1,11 @@
+node_modules
+coverage
+.git
+.github
+.vscode
+*.log
+.env
+.env.*
+!.env.example
+generated
+otherdocs

package/templates/bun-basic/package.json

@@ -16,7 +16,7 @@
     "gen": "pnpm gen:openapi && pnpm gen:client"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.32.0",
+    "@daloyjs/core": "^0.34.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/cloudflare-worker/_Dockerfile

@@ -0,0 +1,56 @@
+# syntax=docker/dockerfile:1.7
+# Containerized local-dev / CI environment for a DaloyJS Cloudflare Worker.
+#
+# Production deploys go through `wrangler deploy` to Cloudflare's edge —
+# **this Dockerfile is not a production runtime**. Ship the Worker to
+# Cloudflare; use this image for:
+#   - Reproducible local dev (devcontainers, GitHub Codespaces).
+#   - CI smoke tests that exercise the Worker against `wrangler dev`'s
+#     local workerd runtime without installing Node/pnpm on the runner.
+#   - Air-gapped review apps that need to host `wrangler dev` behind a
+#     reverse proxy.
+#
+# Hardening shipped out of the box:
+#   - Non-root runtime user (uid 1001).
+#   - Read-only-root-filesystem friendly: writes are confined to the
+#     working dir; mount `/tmp` as tmpfs (`--read-only --tmpfs /tmp`).
+#   - `STOPSIGNAL SIGTERM` so wrangler's child workerd process gets a
+#     clean shutdown signal.
+#   - Minimal runner surface: no `curl`, no `bash` extras beyond what
+#     `node:*-alpine` already ships. BusyBox `wget` powers the
+#     HEALTHCHECK.
+#   - `tini` as PID 1 for proper signal forwarding and zombie reaping
+#     (important because wrangler spawns workerd as a child process).
+#   - `pnpm install --frozen-lockfile --ignore-scripts` matches the
+#     supply-chain defaults in `.npmrc` (no lifecycle scripts run).
+#   - Base image is consumed through the `NODE_IMAGE` ARG so builds
+#     can pin to an immutable digest:
+#       docker build --build-arg \
+#         NODE_IMAGE=node:24-alpine@sha256:<digest> .
+
+# Override at build time to pin a specific digest.
+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 && \
+    pnpm install --frozen-lockfile --ignore-scripts
+COPY . .
+
+FROM ${NODE_IMAGE} AS runner
+WORKDIR /app
+ENV NODE_ENV=development
+# tini only — no curl, no extra packages.
+RUN apk add --no-cache tini && \
+    addgroup -S app -g 1001 && \
+  adduser -S app -G app -u 1001
+COPY --from=builder --chown=app:app /app /app
+USER app
+EXPOSE 8787
+STOPSIGNAL SIGTERM
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD wget -q -O /dev/null --spider http://127.0.0.1:8787/healthz || exit 1
+ENTRYPOINT ["/sbin/tini", "--"]
+# Bind to 0.0.0.0 so the container can be reached from the host network.
+CMD ["./node_modules/.bin/wrangler", "dev", "--ip", "0.0.0.0", "--port", "8787"]

package/templates/cloudflare-worker/_dockerignore

@@ -0,0 +1,13 @@
+node_modules
+.wrangler
+dist
+coverage
+.git
+.github
+.vscode
+*.log
+.env
+.env.*
+!.env.example
+generated
+otherdocs

package/templates/cloudflare-worker/package.json

@@ -10,7 +10,7 @@
     "test": "node --import tsx/esm --test tests/**/*.test.ts"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.32.0",
+    "@daloyjs/core": "^0.34.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

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

@@ -11,6 +11,23 @@ const app = new App({
 app.use(requestId());
 app.use(secureHeaders());
 
+app.route({
+  method: "GET",
+  path: "/healthz",
+  operationId: "healthz",
+  tags: ["Ops"],
+  responses: {
+    200: {
+      description: "Service is healthy",
+      body: z.object({ ok: z.literal(true), runtime: z.literal("cloudflare-worker") }),
+    },
+  },
+  handler: async () => ({
+    status: 200,
+    body: { ok: true as const, runtime: "cloudflare-worker" as const },
+  }),
+});
+
 // daloy-minimal:strip-start books
 const Book = z.object({ id: z.string(), title: z.string() });
 const books = new Map<string, z.infer<typeof Book>>([

package/templates/deno-basic/_Dockerfile

@@ -0,0 +1,66 @@
+# syntax=docker/dockerfile:1.7
+# Container-first defaults for a DaloyJS app running on Deno.
+#
+# Hardening shipped out of the box:
+#   - Non-root runtime user (`deno`, uid 1993 — created by the official
+#     `denoland/deno` image).
+#   - **Deno's capability-based permission model is the primary
+#     defense.** The runtime CMD passes only `--allow-net`,
+#     `--allow-env`, and scoped `--allow-read` — no `--allow-write`, no
+#     `--allow-run`, no `--allow-ffi`, no `--allow-sys`, no `--allow-all`.
+#     Network and env permissions are constrained to the server port and
+#     expected env vars so a compromised dependency cannot silently open
+#     arbitrary outbound sockets or read every secret in the environment.
+#   - `--cached-only` refuses any module that was not baked into the
+#     image at build time. A malicious republish of a transitive dep
+#     cannot ride in via a runtime `import("https://…")`.
+#   - Read-only-root-filesystem friendly: no runtime writes. Run with
+#     `--read-only --tmpfs /tmp` or set `readOnlyRootFilesystem: true`
+#     in your orchestrator.
+#   - `STOPSIGNAL SIGTERM` so DaloyJS's graceful-shutdown drain fires
+#     when the container is stopped.
+#   - `HEALTHCHECK` uses BusyBox `wget` already present in the alpine
+#     base — no `curl`, no extra packages.
+#   - `tini` as PID 1 for proper signal forwarding and zombie reaping.
+#   - Base image is consumed through the `DENO_IMAGE` ARG so production
+#     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.
+
+# Override at build time to pin a specific digest.
+ARG DENO_IMAGE=denoland/deno:alpine
+
+FROM ${DENO_IMAGE} AS builder
+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
+
+FROM ${DENO_IMAGE} AS runner
+WORKDIR /app
+ENV DENO_DIR=/deno-dir
+ENV DENO_ENV=production
+# tini only — no curl, no extra packages. BusyBox `wget` (already in
+# alpine) is enough for the HEALTHCHECK below.
+USER root
+RUN apk add --no-cache tini
+COPY --from=builder --chown=deno:deno /deno-dir /deno-dir
+COPY --from=builder --chown=deno:deno /app/deno.json /app/deno.json
+COPY --from=builder --chown=deno:deno /app/src /app/src
+USER deno
+EXPOSE 3000
+STOPSIGNAL SIGTERM
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -q -O /dev/null --spider http://127.0.0.1:3000/healthz || exit 1
+ENTRYPOINT ["/sbin/tini", "--"]
+# Minimum permissions for a DaloyJS HTTP server. Add more only if your
+# app genuinely needs them — every flag widens the blast radius of a
+# compromised dependency. If you change `PORT`, update `--allow-net` to
+# match the exposed listen address.
+CMD ["deno", "run", "--cached-only", "--allow-net=0.0.0.0:3000,127.0.0.1:3000,localhost:3000", "--allow-env=PORT,DENO_ENV", "--allow-read=/app/deno.json,/app/src", "src/main.ts"]

package/templates/deno-basic/_dockerignore

@@ -0,0 +1,10 @@
+coverage
+.git
+.github
+.vscode
+*.log
+.env
+.env.*
+!.env.example
+generated
+otherdocs

package/templates/deno-basic/deno.json

@@ -8,8 +8,8 @@
     "gen:openapi": "deno run --allow-net --allow-env --allow-read --allow-write scripts/dump-openapi.ts"
   },
   "imports": {
-    "@daloyjs/core": "npm:@daloyjs/core@^0.32.0",
-    "@daloyjs/core/": "npm:@daloyjs/core@^0.32.0/",
+    "@daloyjs/core": "npm:@daloyjs/core@^0.34.0",
+    "@daloyjs/core/": "npm:@daloyjs/core@^0.34.0/",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/node-basic/AGENTS.md

@@ -25,6 +25,16 @@ When `docs: true` is set in `new App({...})`, three routes are auto-mounted:
 - `generated/` — machine-written by `pnpm gen`. Do not edit by hand.
 - `tests/` — `*.test.ts` files run with `node --test` (via `tsx`).
 
+## Imports
+
+This project uses TypeScript with `"module": "NodeNext"` (ESM). Relative imports **must include a `.js` extension**, even when the source file is `.ts`:
+
+```ts
+import { buildApp } from "./build-app.js"; // resolves to build-app.ts at typecheck, build-app.js at runtime
+```
+
+This is the official Node.js ESM convention — TypeScript rewrites the specifier during typecheck, and the compiled output really is `.js`. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
+
 ## Core rules
 
 1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.

package/templates/node-basic/README.md

@@ -46,6 +46,16 @@ pnpm build
 node dist/index.js
 ```
 
+## Imports
+
+This project uses Node.js **ESM** with `"module": "NodeNext"`. Relative imports must include a `.js` extension, even when the source file is `.ts`:
+
+```ts
+import { buildApp } from "./build-app.js"; // ./build-app.ts on disk
+```
+
+TypeScript resolves the `.js` specifier to the matching `.ts` file at typecheck, and the compiled output really is `.js`. This is the official Node ESM convention — not a typo.
+
 ## What's included
 
 - `@daloyjs/core` with starter security middleware: `secureHeaders`, `requestId`, and `rateLimit`.