create-stitchkit 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -12,6 +12,147 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.4.2] — 2026-08-25
+
+### Fixed
+
+- **A freshly scaffolded project resolves the framework release that exists.**
+  The template ships a lockfile so a scaffold is reproducible, and that lockfile
+  still pinned the previous Stitchkit patch — so `create-stitchkit` published
+  minutes after a framework release produced a project on the older one, inside
+  a range that already allowed the newer. The range and the lock move together
+  now: `catalog.stitchkit` targets `^0.60.1` and the lockfile resolves it, which
+  is also what the packed target lane then tests against.
+
+## [0.4.1] — 2026-08-25
+
+### Fixed
+
+- **The `Gates` list can be run top to bottom, and it never deploys.** It
+  presented five commands in a row, two of which check a *running* deployment —
+  with nothing in the list that starts one, so on a fresh project `bun run
+  runtime:smoke` failed with a connection reset from inside a check. The answer
+  is not a deploy command: `bun run pm2:prod` applies the declared migrations
+  and reloads the PM2 daemon the developer is running, so a gate list carrying
+  it quietly means "deploy". The runtime gates now run under `bun run
+  acceptance:local`, which creates a deployment of its own — separate
+  `PM2_HOME`, ephemeral ports, its own public-host allowlist, its own
+  database — and destroys it by naming the declared roles. Neither guide says
+  `pm2 delete all` any more: it empties whichever daemon it is pointed at,
+  including applications that have nothing to do with the project.
+- **The acceptance gate writes only to a database of its own.** It inherited
+  `DATABASE_URL`, and the runtime gates write — the repository example's smoke
+  posts `/api/repository/refresh` twice, which upserts. So a command a developer
+  is told to run before handing work off wrote rows into whatever `.env` named.
+  It runs against `ACCEPTANCE_DATABASE_URL`, applies the declared migrations
+  there, and refuses to start when that variable is unset or reuses the
+  deployment's database **name** — with the line to paste in the refusal. The
+  name alone decides, because a hostname is not proof of a different server:
+  `localhost` and `127.0.0.1` are one, and so are two DNS names for the same
+  PostgreSQL. The deployment's URL is not in the harness's child environment at
+  all.
+- **A release will not start an artifact that is not this source's.**
+  `assertBuildArtifacts()` checked that the declared paths exist, and existence
+  is not freshness: `pm2:prod` run without a build applied this source's
+  migrations and started the previous source's `dist` and `.next`, moving the
+  schema ahead of the code in the one direction a code rollback does not undo.
+  `bun run build` now leaves a digest of the source it read, and the release
+  refuses when the tree no longer hashes to it — a digest rather than a
+  timestamp, because a checkout rewrites every mtime and a formatter rewrites
+  some for no change at all. Everything is source unless something names it
+  otherwise, and the something is the **declaration**: the digest skips
+  `build.artifacts`, `node_modules`/`.git`, and runtime state. It no longer
+  skips by kind — every `.md`, every test file, every directory called
+  `generated` — because a project that imports MDX or keeps checked-in source in
+  a directory of that name would have changed its content, kept its digest, and
+  been told a stale artifact was current. `.env` stays out on purpose: a binding
+  is not an input to this build, and hashing it would refuse a correct artifact
+  whenever a deployment edited its own environment.
+- **The shutdown budget is an upper bound again.** `terminationBudgetMs` adds a
+  fixed cleanup allowance to the drain floor and refuses a supervision policy
+  that allows less — but the closes that run after the drain (the MCP session,
+  the database pool) had no deadline of their own, so a hung close ran past the
+  very kill timeout the budget had approved and turned an orderly shutdown into
+  the SIGKILL that runs no cleanup at all. The role's cleanup now shares one
+  bounded budget with the generator, from one constant both read, and names
+  whatever it stopped waiting for — and then **ends the process**. Setting
+  `process.exitCode` only decides the code a process reports when it exits, and
+  a step that ran out of time is usually still holding the handle that stops it
+  from exiting; a close that *threw* is reported with its cause and is no longer
+  counted as a clean shutdown. The shared deadline is measured with
+  `performance.now()` and the clock can no longer be injected: a wall clock
+  stepped backwards widens the very upper bound the supervisor's kill timeout
+  was derived from, and a frozen injected clock hands every step a full budget.
+- **The project declaration stays out of the browser bundle.**
+  `lib/seo/pages.ts` imported `appDeclaration` for one field, and a client
+  component imports that module — so role commands, working directories,
+  artifact and migration paths and every environment variable name travelled
+  into the client graph along with the Zod parser. It reads `appIdentity` now,
+  and a test walks every `'use client'` graph and fails if one reaches the
+  declaration — by resolving each specifier to a file rather than matching a
+  string, so a barrel re-export, a relative path into the config package and a
+  double-quoted import are all caught.
+- **A duplicated host is one address.** The portability check counted the
+  entries of `PUBLIC_WEB_HOSTS` without deduplicating them, so the same host
+  written twice passed as two addresses and the proof compared the deployment
+  with itself.
+- **Every dial in the runtime smoke is bounded.** An endpoint that accepts the
+  connection and never answers used to hang the gate with no output and no
+  deadline instead of failing it.
+- **A build output cannot be published inside the template.** What the scaffolder
+  copies and what npm publishes were two lists that had to agree, and only one of
+  them was consulted when a name was excluded. The exclusions are data now, and a
+  test fails until the package manifest carries the same negation.
+- **A role bound to an IPv6 address gets a readiness URL that parses.**
+  `BIND_HOST=::1` produced `http://::1:3211/health`, which is not an address
+  with a port and which `fetch` refuses — so the wait failed on the spelling
+  rather than on the role. The literal is bracketed.
+- **`bun run dev` and `bun run pm2:prod` report the roles as running only once
+  they answer.** A supervisor returns at the spawn, seconds before a role
+  listens, so both printed their address at a moment when nothing was there and
+  every command after them raced the application they had just started. Both now
+  wait on each role's declared `readinessPath`.
+- **`runtime:smoke` asks the deployment on the addresses it claims.** The
+  portability check carried two fixture hosts of its own, so it only ever passed
+  where somebody had put those exact names into `PUBLIC_WEB_HOSTS` — which only
+  the packed lane had. Everyone else got a bare 500 from a policy working as
+  designed. It now reads `PUBLIC_WEB_HOSTS`, and a deployment with too few
+  addresses to compare is told which line to add instead of being refused a
+  request.
+- **A closed deployment is diagnosed, not reset.** `runtime:smoke` says what is
+  not listening and which command starts it, before the first check runs.
+- **The theme value the toaster reads narrows again.** `@wrksz/themes` 1.2
+  changed `useThemeValue`'s type parameter to describe the map rather than the
+  value, and it now infers `const` — so naming the value union at the call site
+  widened the result to every member of `string` and the generated project
+  stopped type-checking. The call site lets inference do it.
+- **A green `runtime:smoke` prints one line.** The MCP surface check asked the
+  server to list tools even when it advertised no tool capability, which made
+  the vendor client log a debug warning on every successful run. It reads the
+  advertised capability instead.
+
+### Changed
+
+- **Every dependency of the generated project is on its latest release.**
+  Next 16.3.2, `next-intl` 4.13.7, `@tanstack/react-query` 5.102.3,
+  `@tanstack/react-table` 9.1.2, `framer-motion` 13.1.1, `@wrksz/themes` 1.2.0,
+  `shiki` 4.4.3, `sonner` 2.0.8, `ai` 7.0.78, `pg` 8.23.0, Playwright 1.62.1,
+  Biome 2.5.10 and the `@types/*` that go with them. No major crossed; the
+  Stitchkit range is unchanged and still declared once, in the catalog.
+- **The generated project imports the declaration schema instead of mirroring
+  it.** `packages/config/src/declaration.ts` now reads
+  `parseProjectDeclaration` from `stitchkit/declaration`, and the 611-line
+  generated copy — `packages/config/src/project-declaration.generated.ts` — is
+  gone with the script that maintained it. The copy existed only because the
+  entrypoint was not on npm yet; the template's catalog targets `^0.60.0`,
+  which publishes it, so "one schema, three readers" is now literally true.
+  Adopting it is one import and one deletion — see
+  [`UPGRADING.md`](./UPGRADING.md).
+- **`scripts/local-env.ts` reads the identity module, not the declaration.** It
+  needs one slug, and a project scaffolded with `--no-install` renders its
+  `.env` before anything is installed — a script that reaches for the
+  framework's schema to read a name cannot run in that window.
+
 ## [0.4.0] — 2026-08-25
 
 ### ⚠️ Breaking changes

package/UPGRADING.md

@@ -60,6 +60,123 @@ the first scaffolder release with a migration channel of its own.
 
 ---
 
+## Released migration: 0.4.1
+
+### a release refuses a stale artifact, and cleanup is bounded
+
+Two changes an existing project should take, both about a shutdown or a start
+that looked safe and was not.
+
+1. **Stamp the build.** Copy `scripts/build-stamp.ts` from a fresh scaffold,
+   append `&& bun scripts/build-stamp.ts` to your root `build` script, add
+   `.build-stamp.json` to `.gitignore`, and call `assertArtifactMatchesSource()`
+   at the end of `assertBuildArtifacts()` in `scripts/release-steps.ts`. Until
+   you do, `bun run pm2:prod` without a build applies your migrations and starts
+   the previous build.
+
+2. **Bound the cleanup, and let it end the process.** Copy
+   `packages/config/src/shutdown.ts` and `packages/backend/src/cleanup.ts`, add
+   the `./shutdown` export to `packages/config/package.json`, and replace the
+   bare `await mcp.close(); await prisma.$disconnect();` in your API role's
+   `onComplete` with `closeWithinBudget([...])` followed by
+   `concludeShutdown(cleanup, result.outcome === 'clean')`. Then have
+   `scripts/declaration.ts` import `FORCE_BUDGET_MS` and `CLEANUP_BUDGET_MS`
+   from the new module instead of declaring its own copies — the number a
+   supervisor is told to allow and the number the role enforces have to be one
+   number. `concludeShutdown` is the half that makes the budget real: setting
+   `process.exitCode` decides the code a process reports *when it exits*, and a
+   step that ran out of time is usually still holding the handle that stops it
+   from exiting at all.
+
+No operator step: nothing about a running machine changes.
+
+### the gate list runs, and never deploys
+
+The `Gates` list in the generated guides presented five commands in a row, two
+of which check a **running** deployment — with nothing in the list that starts
+one. The fix is not to add a deploy command: `bun run pm2:prod` applies your
+declared migrations and reloads the deployment you are running, so a list that
+contains it means "run these before handing work off" quietly says "deploy".
+
+1. **Take `pm2:prod` out of your gate list**, in `README.md` and `AGENTS.md`
+   alike, and delete any advice to run `pm2 delete all` — that empties whichever
+   daemon it is pointed at, including applications with nothing to do with this
+   project.
+
+2. **Add the harness that brings up a deployment of its own.** Copy
+   `scripts/acceptance-local.ts` and `scripts/acceptance-database.ts` from a
+   fresh scaffold and add `"acceptance:local": "bun scripts/acceptance-local.ts"`
+   to your root scripts. It creates and destroys its own deployment — separate
+   `PM2_HOME`, ephemeral ports, its own public-host allowlist — and runs
+   `runtime:smoke` and `e2e` against that.
+
+3. **Give it a database of its own.** Add `ACCEPTANCE_DATABASE_URL` to `.env`
+   and `.env.example`, naming a throwaway database — not the one `DATABASE_URL`
+   names. The runtime gates WRITE (the repository example's smoke posts a
+   refresh, and that upserts), so a harness borrowing `DATABASE_URL` writes rows
+   into whatever your `.env` points at. The harness refuses to start when the
+   variable is unset or names the same database, and prints the line to add.
+
+4. **Wait for readiness before reporting it.** Copy `scripts/readiness.ts` from
+   a fresh scaffold, then in `scripts/dev.ts` and `scripts/release.ts` await
+   `awaitRolesAnswering(declaredRoleReadiness(appDeclaration, environment))`
+   before printing that the roles are running. Until you do, anything you run
+   after `bun run dev` or `bun run pm2:prod` races the roles they started.
+
+5. **Let the smoke read your allowlist.** In `scripts/web-surface-smoke.ts` the
+   portability check named two hosts of its own; take the version that reads
+   `PUBLIC_WEB_HOSTS` and pass it from `scripts/runtime-smoke.ts`. If you kept
+   the old one, your `.env` must claim `alpha.example` and `beta.example:8443`
+   or the check fails on a host your deployment correctly refuses. With the new
+   one, `_env.example` drops those example hosts — the harness supplies its own.
+
+6. **Keep the declaration out of the browser.**
+   `packages/frontend/src/lib/seo/pages.ts` must import `appIdentity` from
+   `@app/config/app-identity` rather than `appDeclaration`: a client component
+   reaches that module, so the whole declaration was going into your browser
+   bundle.
+
+No operator step: nothing about a running machine changes.
+
+### the declaration schema is imported
+
+For a project generated **before** the scaffolder version that drops the schema
+mirror. Nothing in your tree stops working if you skip this — the copy keeps
+parsing. What you lose by skipping is the guarantee: your copy no longer moves
+when the framework's schema does, and nothing tells you.
+
+1. **Point the config package at the framework.** In
+   `packages/config/src/declaration.ts`:
+
+   ```ts
+   // before
+   import { findProjectRole, parseProjectDeclaration } from './project-declaration.generated';
+   // after
+   import { findProjectRole, parseProjectDeclaration } from 'stitchkit/declaration';
+   ```
+
+   Then the same for every `import type { ProjectDeclaration, … }` in
+   `scripts/` — they pointed at the same file.
+
+2. **Declare the dependency.** `packages/config/package.json` gains
+   `"stitchkit": "catalog:"`, and `bun install` refreshes the lockfile.
+
+3. **Delete `packages/config/src/project-declaration.generated.ts`.**
+
+4. **Check your `stitchkit` range.** The entrypoint ships from **0.60.0**. If
+   your catalog targets less than that, raise it first — otherwise the import
+   resolves to nothing.
+
+5. **Read `.env` without the schema.** If your `scripts/local-env.ts` imports
+   `appDeclaration`, switch it to `appIdentity` from
+   `packages/config/src/app-identity.generated`. It needs only the slug, and a
+   project scaffolded with `--no-install` renders `.env` before anything is
+   installed — in that window the framework is not there to import.
+
+No operator step: nothing about a running machine changes.
+
+---
+
 ## Released migration: 0.4.0
 
 ### the project declares itself

package/dist/cli.js

@@ -292,6 +292,8 @@ var IGNORED_DIRECTORIES = new Set([
   "playwright-report",
   "test-results"
 ]);
+var IGNORED_FILE_NAMES = new Set([".env", ".build-stamp.json", "next-env.d.ts"]);
+var IGNORED_FILE_SUFFIXES = [".log", ".tsbuildinfo"];
 function isTemplateSourcePathIncluded(sourcePath) {
   const normalized = sourcePath.replaceAll("\\", "/").replace(/^\.\//, "");
   if (!normalized)
@@ -302,7 +304,9 @@ function isTemplateSourcePathIncluded(sourcePath) {
   if (normalized === "packages/db/src/generated" || normalized.startsWith("packages/db/src/generated/"))
     return false;
   const name = basename2(normalized);
-  return name !== ".env" && name !== "next-env.d.ts" && !name.endsWith(".log") && !name.endsWith(".tsbuildinfo");
+  if (IGNORED_FILE_NAMES.has(name))
+    return false;
+  return !IGNORED_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix));
 }
 function shouldIncludeTemplatePath(templateDirectory, sourcePath) {
   return isTemplateSourcePathIncluded(relative(templateDirectory, sourcePath));

package/examples/repository/scripts/runtime-smoke.ts

@@ -1,6 +1,7 @@
 import { RepositorySnapshotSchema, repositoryRealtimeContract } from '@app/shared';
 import { createRealtimeClient, defineRealtimeContract } from 'stitchkit';
 import { z } from 'zod';
+import { assertDeploymentIsAnswering } from './deployment-preflight';
 import { defineSurfaceProbe, runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
 import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-surface-smoke';
@@ -8,8 +9,16 @@ import { assertArtifactIsPlacementFree, assertPublicWebSurface } from './web-sur
 const toolingEnv = loadToolingEnv();
 const apiOrigin = toolingEnv.SMOKE_API_ORIGIN;
 
+await assertDeploymentIsAnswering({
+  'the API role': apiOrigin,
+  'the web role': toolingEnv.SMOKE_WEB_ORIGIN,
+});
+
 async function json(path: string, init?: RequestInit): Promise<unknown> {
-  const response = await fetch(`${apiOrigin}${path}`, init);
+  const response = await fetch(`${apiOrigin}${path}`, {
+    ...init,
+    signal: AbortSignal.timeout(30_000),
+  });
   if (!response.ok)
     throw new Error(`${init?.method ?? 'GET'} ${path} returned ${response.status}`);
   return response.json();
@@ -185,7 +194,10 @@ await runSurfaceConformance({
 }
 
 await assertPublicWebSurface(toolingEnv.SMOKE_WEB_ORIGIN);
-await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN);
+await assertArtifactIsPlacementFree(toolingEnv.SMOKE_WEB_ORIGIN, {
+  origin: toolingEnv.PUBLIC_WEB_ORIGIN,
+  hosts: toolingEnv.PUBLIC_WEB_HOSTS,
+});
 
 console.log(
   'Runtime HTTP (same-origin and direct), OpenAPI, Socket.IO, MCP and public web smoke passed',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -18,6 +18,7 @@
     "template/**/*",
     "examples/**/*",
     "!template/**/.env",
+    "!template/**/.build-stamp.json",
     "!template/**/node_modules/**",
     "!template/**/.next/**",
     "!template/**/dist/**",
@@ -29,6 +30,7 @@
     "!template/**/*.tsbuildinfo",
     "!template/**/coverage/**",
     "!examples/**/.env",
+    "!examples/**/.build-stamp.json",
     "!examples/**/node_modules/**",
     "!examples/**/.next/**",
     "!examples/**/dist/**",
@@ -57,7 +59,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/AGENTS.md

@@ -19,10 +19,11 @@ framework source repository.
   by machine — the scaffolder stamps the identity, `bun run gen:declaration`
   derives `env.variables` — so the formatter leaves it alone and
   `scripts/declaration.test.ts` is what checks it.
-- Three files are generated from it and must not be hand-edited:
-  `ecosystem.config.cjs`, `ecosystem.dev.config.cjs` and the `env.variables`
-  block of `project.json`. Run `bun run gen:declaration` after changing a role. It holds
-  nothing that differs between two deployments; those are named there by
+- Four things are generated from it and must not be hand-edited:
+  `ecosystem.config.cjs`, `ecosystem.dev.config.cjs`,
+  `packages/config/src/app-identity.generated.ts` and the `env.variables` block
+  of `project.json`. Run `bun run gen:declaration` after changing a role. It
+  holds nothing that differs between two deployments; those are named there by
   variable and supplied by the place.
 
 Dependencies point inward: frontend/backend → shared; backend → db/config.
@@ -58,6 +59,15 @@ vertical path. Before handing work off, run:
 bun run check
 bun run test
 bun run build
-bun run runtime:smoke
+bun run acceptance:local
 ```
 
+`acceptance:local` is part of the list because `runtime:smoke` and `e2e` check a
+running deployment: it creates one of its own — separate PM2 home, ephemeral
+ports, and its own database from `ACCEPTANCE_DATABASE_URL` — runs both against
+it, and destroys it. The separate database is not tidiness: the gates write, so
+one borrowing `DATABASE_URL` writes rows wherever `.env` points. **Never put
+`pm2:prod` in this list.** It applies the declared migrations to *your* database
+and reloads the running deployment; deploying is its own command, asked for on
+purpose, and no gate performs it.
+

package/template/README.md

@@ -9,14 +9,17 @@ before it starts, and the environment variables a deployment must supply.
 The declaration is true **with no machine in existence**. A field you cannot
 fill in without knowing where the code will run is a *binding*, not a
 declaration: ports, hosts, addresses, machine paths and supervision policy are
-named there by variable and never by value, and the schema has nowhere to put
-them. Change the slug, display name, version or description there and package
+named there by variable and never by value. The schema has no field that asks
+for one, so nothing in it ever requires a value of the place; where a value
+could still be written into a free-text field, a filter refuses the known
+shapes of a machine name. Change the slug, display name, version or description there and package
 names, process names, MCP/OpenAPI identity, UI copy and SEO follow.
 
-Three files are **generated** from it — `ecosystem.config.cjs`,
-`ecosystem.dev.config.cjs` and the `env.variables` block of the declaration
-itself. Run `bun run gen:declaration` after changing a role; the test suite
-refuses a stale copy.
+Four things are **generated** from it — `ecosystem.config.cjs`,
+`ecosystem.dev.config.cjs`, `packages/config/src/app-identity.generated.ts` and
+the `env.variables` block of the declaration itself. Run
+`bun run gen:declaration` after changing a role; the test suite refuses a stale
+copy.
 
 ## Start
 
@@ -87,10 +90,45 @@ Unsupported browsers and users requesting reduced motion switch immediately.
 bun run check
 bun run test
 bun run build
-bun run runtime:smoke
-bun run e2e
+bun run acceptance:local
 ```
 
+Top to bottom, in one terminal, and none of it touches a deployment. They
+assume your development database is already set up — see [Start](#start).
+
+`acceptance:local` is the last one because `runtime:smoke` and `e2e` check a
+**running** deployment rather than a source tree — so it creates one and
+destroys it: its own PM2 home, ephemeral ports, its own public-host allowlist,
+and a stop that names the roles the declaration declares. It reloads nothing
+you are running.
+
+It also brings its own database, `ACCEPTANCE_DATABASE_URL`, and applies this
+project's migrations to that — not to yours. The gates WRITE (the repository
+example's smoke posts a refresh, and that upserts), so borrowing `DATABASE_URL`
+would make a gate a writer in whatever database your `.env` names. It refuses to
+start when the variable is unset or names the same database, and says what to
+add. It needs `pm2` (see [Requirements](#requirements)).
+
+Deploying is a separate, deliberate command — `bun run pm2:prod` under
+[Production](#production) — and it is not a gate.
+
+To run the two runtime gates against a deployment that already exists somewhere,
+point `SMOKE_API_ORIGIN` / `SMOKE_WEB_ORIGIN` at it and call `bun run
+runtime:smoke` / `bun run e2e` directly. `runtime:smoke` asks the web role to
+answer as two of the addresses `PUBLIC_WEB_HOSTS` claims, to prove one artifact
+serves many; a deployment claiming fewer than two addresses besides the one
+being dialled is told exactly what to add rather than failing on a refused host.
+
+## Requirements
+
+- **Bun** and **Node ≥ 22**.
+- **PostgreSQL** — external infrastructure, in development and production
+  alike. This project owns its schema and migrations, never the database
+  process.
+- **PM2** on `PATH` (`bun add --global pm2`) for `bun run dev`,
+  `bun run acceptance:local` and `bun run pm2:prod`.
+- **Playwright browsers** (`bunx playwright install`) for `bun run e2e`.
+
 ## Production
 
 Provide a production `.env`, then:

package/template/_env.example

@@ -1,5 +1,9 @@
 NODE_ENV=development
 DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
+# The throwaway database `bun run acceptance:local` creates and writes to. The
+# runtime gates WRITE, so they get one of their own: the harness refuses to
+# start if this is unset or names the database above.
+ACCEPTANCE_DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter_acceptance
 # 0.0.0.0 exposes the app to every network interface — opt in consciously.
 BIND_HOST=127.0.0.1
 API_PORT=3211
@@ -9,6 +13,10 @@ SMOKE_WEB_ORIGIN=http://127.0.0.1:3210
 # Hosts this deployment answers for, comma-separated. One built artifact can
 # serve several addresses; a forwarded host outside this list is refused rather
 # than believed. Leave unset and set PUBLIC_WEB_ORIGIN instead for a single one.
+#
+# `bun run acceptance:local` supplies its own list to the deployment it creates,
+# so the addresses the portability check needs are not policy this project
+# carries. List here only the hosts this deployment really answers for.
 PUBLIC_WEB_HOSTS=127.0.0.1:3210
 LOG_FORMAT=pretty
 # CORS_ORIGIN is only needed for a genuinely cross-origin browser.

package/template/_gitignore

@@ -3,6 +3,7 @@ dist/
 .next/
 next-env.d.ts
 .env
+.build-stamp.json
 coverage/
 *.log
 packages/db/src/generated/

package/template/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.7/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
   "files": {
     "includes": [
       "**",