@next-friday/create-app 0.0.0-stage → 1.0.0

package/templates/nodejs/.github/workflows/ci.yml

@@ -0,0 +1,179 @@
+name: Verify
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, converted_to_draft]
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "0 3 * * 1"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read # Needed by paths-filter to inspect pull request changes.
+    outputs:
+      heavy: ${{ steps.filter.outputs.heavy }}
+      ci_policy: ${{ steps.filter.outputs.ci_policy }}
+      full_verification: ${{ steps.mode.outputs.full_verification }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Detect relevant changes
+        id: filter
+        if: github.event_name == 'pull_request'
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        with:
+          predicate-quantifier: some-with-excludes
+          filters: .github/file-filters.yml
+      - name: Select verification mode
+        id: mode
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          DRAFT: ${{ github.event.pull_request.draft }}
+          HEAVY: ${{ steps.filter.outputs.heavy }}
+          CI_POLICY: ${{ steps.filter.outputs.ci_policy }}
+        run: |
+          full_verification=false
+          if [[ "$EVENT_NAME" == "push" || ( "$EVENT_NAME" == "pull_request" && "$DRAFT" != "true" && ( "$HEAVY" == "true" || "$CI_POLICY" == "true" ) ) ]]; then
+            full_verification=true
+          fi
+
+          echo "full_verification=$full_verification" >> "$GITHUB_OUTPUT"
+
+  checks:
+    name: Static Checks, Tests & Build
+    needs: changes
+    if: needs.changes.outputs.full_verification == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Node.js and pnpm
+        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+        with:
+          cache: true
+          require-lockfile: true
+      - name: Reject suppression directives
+        run: pnpm suppressions:check
+      - name: Check Cursor rules match .agents/rules
+        run: pnpm rules:check
+      - name: Check agent gates
+        run: pnpm gates:check
+      - name: Check lint
+        run: pnpm lint:check
+      - name: Check formatting
+        run: pnpm format:check
+        env:
+          GITHUB_TOKEN: ${{ github.token }} # editorconfig-checker downloads its binary from GitHub releases; the token avoids the anonymous rate limit.
+      - name: Check package.json ordering
+        run: pnpm sort-package-json:check
+      - name: Validate peer dependency contracts
+        run: pnpm peers:check
+      - name: Check types
+        run: pnpm typecheck
+      - name: Run Knip
+        run: pnpm knip
+      - name: Check dependency graph
+        run: pnpm depcruise
+      - name: Run tests with coverage
+        run: pnpm test:coverage
+      - name: Build
+        run: pnpm build
+      - name: Check patch coverage
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          python3 -m venv "$RUNNER_TEMP/diff-cover"
+          "$RUNNER_TEMP/diff-cover/bin/pip" install --quiet --require-hashes --only-binary=:all: -r .github/requirements/diff-cover.txt
+          "$RUNNER_TEMP/diff-cover/bin/diff-cover" coverage/cobertura-coverage.xml --compare-branch "origin/$BASE_REF" --fail-under 95
+
+  image:
+    name: Container Image
+    needs: changes
+    if: needs.changes.outputs.full_verification == 'true' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      HADOLINT_VERSION: 2.15.1
+      HADOLINT_SHA256: c7187db94eeeeca956519a6af171adc31453941a1e777961f6e680f697c8c507
+      TRIVY_VERSION: 0.76.1
+      TRIVY_SHA256: c7cbe3137fb8a48a17574bede3dd6beb16742d1e9772929940fc90082c39d9c0
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Lint Dockerfile
+        run: |
+          curl --silent --show-error --fail --location --output hadolint \
+            "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-linux-x86_64"
+          echo "${HADOLINT_SHA256}  hadolint" | sha256sum --check --strict
+          chmod +x hadolint
+          ./hadolint Dockerfile
+      - name: Build image
+        run: docker build --tag app:ci .
+      - name: Smoke test image
+        id: smoke
+        run: |
+          docker run --detach --name app --env PORT=3000 --publish 3000:3000 app:ci
+          curl --silent --show-error --fail --retry 15 --retry-delay 1 --retry-all-errors --output /dev/null http://localhost:3000/health
+      - name: Show container logs
+        if: failure() && steps.smoke.outcome == 'failure'
+        run: docker logs app
+      - name: Scan image for vulnerabilities
+        run: |
+          archive="trivy_${TRIVY_VERSION}_Linux-64bit.tar.gz"
+          curl --silent --show-error --fail --location --output "$archive" \
+            "https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}/${archive}"
+          echo "${TRIVY_SHA256}  ${archive}" | sha256sum --check --strict
+          tar --extract --gzip --file "$archive" trivy
+          ./trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed --no-progress app:ci
+
+  deploy-dev:
+    name: Deploy to dev
+    needs:
+      - checks
+      - image
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_ENABLED == 'true'
+    permissions:
+      contents: read
+      actions: read # Needed by deploy.yml to find the CI run of the deployed commit.
+    uses: ./.github/workflows/deploy.yml
+    with:
+      environment: dev
+      commit_sha: ${{ github.sha }}
+
+  ci:
+    name: All Checks
+    if: always()
+    timeout-minutes: 5
+    needs:
+      - changes
+      - checks
+      - image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require all verification jobs
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

package/templates/nodejs/.github/workflows/sast.yml

@@ -0,0 +1,45 @@
+name: SAST
+
+on:
+  pull_request: {}
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "**/*.md"
+      - ".agents/**"
+      - ".claude/**"
+      - ".cursor/**"
+  schedule:
+    - cron: "17 2 * * 1"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  semgrep:
+    name: Semgrep (OWASP)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    container:
+      image: semgrep/semgrep:1.179.0@sha256:93963d9295a366f59e4850127b1550400ee7b388f04fe144e4a1f6325d96e01b
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Scan source
+        run: >-
+          semgrep scan
+          --config p/owasp-top-ten
+          --config p/typescript
+          --config p/nodejsscan
+          --severity ERROR --severity WARNING
+          --error --metrics=off
+          --timeout 60 --timeout-threshold 0
+          .

package/templates/nodejs/.lintstagedrc.json

@@ -0,0 +1,10 @@
+{
+  "*.{ts,tsx,js,jsx,mjs,cjs}": [
+    "pnpm exec eslint --fix --cache --max-warnings=0 --no-warn-ignored --no-inline-config",
+    "prettier --write --cache"
+  ],
+  "!(package).json": ["prettier --write --cache"],
+  "*.{md,yml,yaml}": ["prettier --write --cache"],
+  "package.json": ["sort-package-json", "prettier --write --cache"],
+  ".husky/{commit-msg,pre-commit,pre-merge-commit,pre-push}": ["prettier --write --cache"]
+}

package/templates/nodejs/.prettierignore

@@ -0,0 +1,2 @@
+.husky/_
+pnpm-lock.yaml

package/templates/nodejs/.prettierrc.json

@@ -0,0 +1 @@
+"@next-friday/prettier-config-friday"

package/templates/nodejs/AGENTS.md

@@ -0,0 +1,8 @@
+# Agent guide
+
+Node.js HTTP service on pnpm, without a framework. Source lives in `src/`.
+
+- Follow the rules in `.agents/rules/`; `.agents/rules.json` gives each rule's scope. Claude Code and Cursor load them automatically.
+- Rule files, agent hooks, and agent settings are company policy: propose a change to the user, who edits them.
+- Put tests next to the code as `*.test.ts`.
+- Read configuration from environment variables and fail when one is missing; document each variable in `.env.example`.

package/templates/nodejs/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Use this guide to prepare changes to this repository.
+
+## Prerequisites
+
+- Use the Node.js version declared by `.nvmrc` and `package.json#engines`.
+- Change the Node.js version in `.nvmrc` and the `Dockerfile` together. Dependabot updates only the `Dockerfile`.
+- Install pnpm once with `npm install --global pnpm`. It switches to the version declared by `package.json#packageManager` automatically.
+- Use Claude Code v2.1.295 or later. It reads `AGENTS.md` directly and supports the `onFailure` field the agent hooks use.
+- Install gitleaks 8.19 or later, which the `pre-commit` hook runs, and jq, which the agent hooks and the `pre-push` hook (`pnpm gates:check`) need: `brew install gitleaks jq` on macOS, or install them from each project's releases on Linux.
+
+From the repository root:
+
+```sh
+npm install --global pnpm
+pnpm install
+```
+
+## Quality standards
+
+- Fix lint, type, and test failures at their root cause.
+- Put tests next to the code as `*.test.ts`.
+- Treat `coverage/` as generated output.
+- Do not commit `.env` files or credentials.
+
+## Verification
+
+Run the narrowest check that covers the change while you work. Git hooks run these checks:
+
+| Hook               | Checks                                                                                                                                                |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pre-commit`       | blocks commits on `main` except the first commit of a new repository, gitleaks on staged changes, `pnpm rules:check`, and lint-staged on staged files |
+| `commit-msg`       | commitlint                                                                                                                                            |
+| `pre-merge-commit` | blocks merge commits on `main`                                                                                                                        |
+| `pre-push`         | blocks pushes to `main` except the push that creates it, then `pnpm check`: the static checks and the unit tests related to your changes              |
+
+- **Scans:** CI also runs coverage, the build, the container image, and the secret, SAST, and OSV scans. Dependabot and OSV-Scanner report vulnerable dependencies.
+- **Coverage:** CI requires 95% line coverage on changed lines in `src/`, except `main.ts`, which holds only wiring. Keep logic out of it, as `src/port.ts` and `src/server.ts` do.
+
+Run `pnpm verify` for repository changes.
+
+Agent rules live in `.agents/rules/` with their scope in `.agents/rules.json`. After you change either, run `pnpm rules:sync` to regenerate `.claude/rules/` and `.cursor/rules/`.
+
+## Pull requests
+
+We use trunk-based development. `main` is the only long-lived branch, and every deploy promotes a commit from `main` (see the Deploy section in the README).
+
+- Branch from `main` and merge back within a day or two. Do not create `develop` or release branches.
+- Merge unfinished work behind a feature flag or keep it unreachable instead of holding a long-lived branch.
+- Pull requests are squash-merged, so the pull request title becomes the commit on `main`.
+- Write commit messages in the format that `@next-friday/commitlint-config-friday` defines. Pull request titles use `<type>(<scope>): <subject>`, which `.github/workflows/validate-pr-title.yml` checks.
+- Keep each pull request focused on one cohesive change.
+- Describe observable endpoint, request or response, or configuration effects.
+- Report only checks that actually ran and include their results.
+- Add or update tests only when they protect a distinct observable contract.

package/templates/nodejs/Dockerfile

@@ -0,0 +1,27 @@
+# Runs on any OCI platform (Railway, Fly.io, Cloud Run). The platform sets `PORT`.
+FROM node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53 AS base
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN npm install --global "pnpm@$(node --print 'require("./package.json").packageManager.split("+")[0].split("@")[1]')"
+
+FROM base AS build
+RUN pnpm install --frozen-lockfile --ignore-scripts
+COPY tsconfig.json tsconfig.build.json ./
+COPY src ./src
+RUN pnpm build
+
+FROM base AS prod-deps
+RUN pnpm install --frozen-lockfile --ignore-scripts --prod
+
+FROM node:24.22.1-alpine@sha256:06d7adf3e0ef61a13f1d28682726366f97a15aa1888c934d3ecec86c33918b53
+ENV NODE_ENV=production
+WORKDIR /app
+# Apply Alpine security fixes released after the base image, and drop npm, corepack, and yarn: the app never runs them, and their bundled dependencies carry their own CVEs.
+RUN apk upgrade --no-cache \
+  && rm -rf /usr/local/lib/node_modules /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack /usr/local/bin/yarn /usr/local/bin/yarnpkg /opt/yarn-*
+COPY package.json ./
+COPY --from=prod-deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+USER 1000
+HEALTHCHECK --interval=30s --timeout=5s CMD ["node", "-e", "fetch('http://127.0.0.1:' + (process.env.PORT || 3000) + '/health').then(response => process.exit(response.ok ? 0 : 1), () => process.exit(1))"]
+CMD ["node", "dist/main.js"]

package/templates/nodejs/README.md

@@ -0,0 +1,74 @@
+# next-friday-template-nodejs
+
+Next Friday starter for Node.js HTTP services without a framework.
+
+## Getting started
+
+```sh
+npm install --global pnpm
+pnpm install
+pnpm start:dev
+```
+
+The server listens on the port set by `PORT` in `.env`, which the CLI created from `.env.example`.
+
+## After creating a project from this template
+
+1. Install gitleaks and jq (see [CONTRIBUTING.md](CONTRIBUTING.md)). Make the first commit on `main` and push it. The Git hooks allow only this first commit and push on `main`; work on branches after that.
+
+   ```sh
+   git add --all
+   git commit -m "chore(repo): start from template"
+   git push --set-upstream origin main
+   ```
+
+2. Add your team as the owner of every file in `.github/CODEOWNERS`, and replace the owner placeholder in `.github/zizmor.yml`.
+3. Replace the template's description and owner: `package.json#description`, `repository.url`, and `author`. Change `license` from `UNLICENSED` if the project is open source.
+4. In the repository settings:
+   - **Actions → General → Workflow permissions:** select **Read repository contents and packages permissions**. Every workflow requests the extra permissions it needs.
+   - **Advanced Security:** enable private vulnerability reporting, Dependabot alerts, Dependabot security updates, secret scanning, and push protection. `SECURITY.md` sends reporters to private vulnerability reporting.
+   - **Cursor Bugbot:** enable the repository at [Bugbot](https://cursor.com/automations/from-cursor/bugbot). Bugbot reviews pull requests against the rules linked from `.cursor/BUGBOT.md`.
+   - **Rules → Rulesets:** protect `main` with squash merges only, a linear history, no force pushes or deletion, and the required checks `All Checks` and `Validate pull request title`. Rulesets in a private repository need GitHub Pro, Team, or Enterprise; on GitHub Free, make the repository public or upgrade.
+   - Create the `needs triage` label, which the issue forms apply: `gh label create "needs triage"`.
+
+## Scripts
+
+| Script            | Purpose                                                                    |
+| :---------------- | :------------------------------------------------------------------------- |
+| `pnpm start:dev`  | Start in watch mode from `src/main.ts`; loads `.env` when present          |
+| `pnpm build`      | Compile to `dist/`                                                         |
+| `pnpm start`      | Run `dist/main.js`; loads `.env` when present                              |
+| `pnpm start:prod` | Run `dist/main.js`; the environment sets `PORT`                            |
+| `pnpm test`       | Run tests (`src/**/*.test.ts`)                                             |
+| `pnpm check`      | Run the static checks and the tests for changed code (the `pre-push` hook) |
+| `pnpm verify`     | Run the static checks and all tests with coverage                          |
+
+CI also runs the build, the container image scan, and the security scans.
+
+## Container
+
+The `Dockerfile` builds a production image that runs as the `node` user. The platform must set `PORT`; Railway sets it automatically.
+
+```sh
+docker build -t app .
+docker run --env PORT=3000 --publish 3000:3000 app
+```
+
+## Deploy
+
+`.github/workflows/deploy.yml` deploys the `Dockerfile` to Railway and promotes one commit through `dev`, `uat`, and `prod`. `railway.json` sets the Railway health check to `/health`. The workflow stays off until you configure it:
+
+1. In Railway, create a project with one service for this repository and the environments `dev`, `uat`, and `prod`. The workflow passes these names to `railway up --environment`. Create one project token per environment under **Project Settings → Tokens**.
+2. In GitHub, create the `dev`, `uat`, and `prod` environments under **Settings → Environments**, and add to each:
+   - the `RAILWAY_TOKEN` secret: that environment's project token;
+   - the `RAILWAY_SERVICE` variable: the service name;
+   - the `APP_URL` variable: the public `https://` URL.
+
+   Limit `prod` to the `main` branch and add required reviewers. Environment secrets and variables in a private repository need GitHub Pro, Team, or Enterprise; required reviewers in a private repository need GitHub Enterprise.
+
+3. Set the repository variable `DEPLOY_ENABLED` to `true`. Each push to `main` that passes CI then deploys to `dev`.
+4. Promote with **Actions → Deploy → Run workflow**, giving the environment and the full commit SHA. The workflow requires a successful CI run on `main` for that commit and a successful deployment to the previous environment, then waits for `/health`.
+
+Remove the workflow, `railway.json`, and the `deploy-dev` job in `ci.yml` if the project deploys elsewhere.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/templates/nodejs/_gitignore

@@ -0,0 +1,47 @@
+node_modules
+.pnpm-store
+
+coverage
+*.tsbuildinfo
+
+.cache
+
+*.pem
+
+npm-debug.log*
+pnpm-debug.log*
+*.log
+
+**/.env*
+!.env.example
+
+.eslintcache
+
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+/.idea
+
+logs
+.temp
+.tmp
+
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+**/.DS_Store
+
+*.key
+*.p12
+*.pfx
+id_rsa*
+id_ed25519*
+
+/.claude/settings.local.json
+/.claude/worktrees/
+
+/dist

package/templates/nodejs/eslint.config.ts

@@ -0,0 +1,7 @@
+import {defineConfig, globalIgnores} from "eslint/config";
+import friday from "@next-friday/eslint-config-friday";
+
+export default defineConfig(
+  globalIgnores([".agents/**", ".claude/**", ".cursor/**", "coverage/**", "dist/**"]),
+  friday(),
+);

package/templates/nodejs/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "next-friday-template-nodejs",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Next Friday Node.js template.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/next-friday/next-friday-template-nodejs.git"
+  },
+  "license": "UNLICENSED",
+  "author": "Next Friday",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "pnpm verify:static && pnpm test:changed",
+    "clean": "rm -rf dist coverage *.tsbuildinfo .eslintcache node_modules/.cache",
+    "depcruise": "depcruise --config .dependency-cruiser.json src eslint.config.ts vitest.config.ts",
+    "format": "prettier --write --cache .",
+    "format:check": "prettier --check --cache . && editorconfig-checker",
+    "gates:check": "node scripts/check-agent-gates.ts",
+    "knip": "knip",
+    "lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
+    "lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
+    "peers:check": "pnpm peers check",
+    "prepare": "husky",
+    "rules:check": "node scripts/sync-agent-rules.ts --check",
+    "rules:sync": "node scripts/sync-agent-rules.ts",
+    "sort-package-json": "sort-package-json package.json",
+    "sort-package-json:check": "sort-package-json --check package.json",
+    "start": "node --env-file-if-exists=.env dist/main.js",
+    "start:dev": "node --env-file-if-exists=.env --watch src/main.ts",
+    "start:prod": "node dist/main.js",
+    "suppressions:check": "bash .agents/hooks/agent-suppression-gate.sh --repo",
+    "test": "vitest run --passWithNoTests",
+    "test:changed": "if git rev-parse --quiet --verify origin/main > /dev/null && git diff --quiet \"$(git merge-base origin/main HEAD)\" -- pnpm-lock.yaml pnpm-workspace.yaml \"*package.json\" \"*tsconfig.json\" .husky; then vitest run --changed origin/main --passWithNoTests; else vitest run --passWithNoTests; fi",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify": "pnpm verify:static && pnpm test:coverage",
+    "verify:static": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm peers:check && pnpm typecheck && pnpm knip && pnpm depcruise"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "21.2.4",
+    "@next-friday/commitlint-config-friday": "4.0.0",
+    "@next-friday/eslint-config-friday": "5.1.0",
+    "@next-friday/prettier-config-friday": "4.0.0",
+    "@types/node": "26.6.5",
+    "@vitest/coverage-v8": "5.0.5",
+    "dependency-cruiser": "18.7.0",
+    "editorconfig-checker": "7.0.0",
+    "eslint": "10.13.0",
+    "fast-check": "4.10.2",
+    "husky": "9.1.7",
+    "jiti": "2.7.0",
+    "knip": "6.43.0",
+    "lint-staged": "17.6.0",
+    "prettier": "3.9.10",
+    "sort-package-json": "4.1.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "packageManager": "pnpm@12.6.0+sha512.3ef68f951cb111ac204b4a5a16f0b2ddf0da56a96e0413e81d855d9f0b55ef926714709028e1cd00c405c2c5fb7b9e8ec4dc46777c805d0373c2f2ff00fd20ec",
+  "engines": {
+    "node": ">=24.15.0 <25"
+  }
+}

package/templates/nodejs/src/main.ts

@@ -0,0 +1,22 @@
+import {createAppServer} from "./server.ts";
+import {parsePort} from "./port.ts";
+
+const shutdownTimeoutMs = 10_000;
+const server = createAppServer();
+
+server.listen(parsePort(process.env.PORT));
+
+/**
+ * Stop accepting connections and let in-flight requests finish, closing any left after the timeout.
+ */
+function shutdown(): void {
+  server.close();
+  server.closeIdleConnections();
+
+  setTimeout(() => {
+    server.closeAllConnections();
+  }, shutdownTimeoutMs).unref();
+}
+
+process.once("SIGTERM", shutdown);
+process.once("SIGINT", shutdown);

package/templates/nodejs/src/port.test.ts

@@ -0,0 +1,30 @@
+import {assert, integer, property} from "fast-check";
+import {describe, expect, it} from "vitest";
+
+import {parsePort} from "./port.ts";
+
+describe("parsePort", () => {
+  it("reads every port from 1 to 65535", () => {
+    assert(
+      property(
+        integer({
+          min: 1,
+          max: 65_535,
+        }),
+        port => {
+          expect(parsePort(String(port))).toBe(port);
+        },
+      ),
+    );
+  });
+
+  it.each([undefined, ""])("requires a value, rejecting %j", value => {
+    expect(() => parsePort(value)).toThrow("PORT environment variable is required");
+  });
+
+  it.each(["abc", "0", "65536", "3000.5", "-1", " 3000", "0x10"])("rejects %j", value => {
+    expect(() => parsePort(value)).toThrow(
+      `PORT must be an integer from 1 to 65535, got "${value}"`,
+    );
+  });
+});

package/templates/nodejs/src/port.ts

@@ -0,0 +1,20 @@
+const maxPort = 65_535;
+
+/**
+ * Read the TCP port the server listens on.
+ * @param value - The raw `PORT` environment variable.
+ * @returns The port as an integer from 1 to 65535.
+ */
+export function parsePort(value: string | undefined): number {
+  if (value === undefined || value === "") {
+    throw new Error("PORT environment variable is required");
+  }
+
+  const port = Number(value);
+
+  if (!/^\d+$/.test(value) || port < 1 || port > maxPort) {
+    throw new Error(`PORT must be an integer from 1 to ${maxPort}, got "${value}"`);
+  }
+
+  return port;
+}

package/templates/nodejs/src/server.test.ts

@@ -0,0 +1,60 @@
+import {describe, expect, it} from "vitest";
+import {once} from "node:events";
+import type {AddressInfo} from "node:net";
+
+import {createAppServer} from "./server.ts";
+
+/**
+ * Run a request against the server on a free port, then close it.
+ * @param pathname - Path to request.
+ * @param method - HTTP method.
+ * @returns The response.
+ */
+async function request(pathname: string, method = "GET"): Promise<Response> {
+  const server = createAppServer();
+
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+
+  const {port} = server.address() as AddressInfo;
+
+  try {
+    return await fetch(`http://127.0.0.1:${port}${pathname}`, {
+      method,
+    });
+  } finally {
+    server.close();
+    await once(server, "close");
+  }
+}
+
+describe("createAppServer", () => {
+  it("reports ok on GET /health", async () => {
+    const response = await request("/health");
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+
+    await expect(response.json()).resolves.toStrictEqual({
+      status: "ok",
+    });
+  });
+
+  it("reports ok when /health has a query string", async () => {
+    const response = await request("/health?probe=1");
+
+    expect(response.status).toBe(200);
+  });
+
+  it("reports ok on HEAD /health", async () => {
+    const response = await request("/health", "HEAD");
+
+    expect(response.status).toBe(200);
+  });
+
+  it("returns 404 for other paths", async () => {
+    const response = await request("/missing");
+
+    expect(response.status).toBe(404);
+  });
+});