create-stitchkit 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -4,8 +4,251 @@ All notable changes to **create-stitchkit** are documented here. The scaffolder
 has its own version and release line; the Stitchkit range tested by its template
 is declared in the template root catalog.
 
+A release that changes the generated project in a way an existing project must
+follow leads its entry with a **`### ⚠️ Breaking changes`** section. What else
+has to happen — including the steps that touch a running machine — is in
+[`UPGRADING.md`](./UPGRADING.md), because a changelog entry carrying an operator
+step is overwritten by the next release.
+
 ## [Unreleased]
 
+## [0.4.0] — 2026-08-25
+
+### ⚠️ Breaking changes
+
+- **The repository example's browser talks to its OWN origin by default.** The
+  example is what gets copied, and it was demonstrating the hard case: the
+  browser dialled the API role directly, so the address had to arrive from the
+  server at runtime, the API client could not exist until it did, and every call
+  site paid for that with a lazy accessor — `repositoryApi().read()` — plus a
+  runtime error when something rendered outside `<Providers>`. Somebody copying
+  it inherited that whether or not they were cross-origin at all. The body of
+  the example is now the default shape: a same-origin `/api/…` path forwarded by
+  the web role, and a client that is a module constant.
+  `// before: repositoryApi().read()` → `// after: repositoryApi.read()`
+  The cross-origin form is not lost — it moved to a named file,
+  `packages/frontend/src/lib/api/cross-origin.ts`, with what it costs written
+  next to it, and switching to it is one import in `queries.ts`.
+- **`PUBLIC_REALTIME_ORIGIN` — the socket's address has a name of its own.**
+  `PUBLIC_API_ORIGIN` used to carry both questions and answer only one: it read
+  as a mode switch while in fact nothing but the realtime socket looked at it.
+  The two are genuinely different — HTTP can be forwarded by the web role, and a
+  WebSocket upgrade cannot survive a route handler — so a deployment can be
+  same-origin for HTTP and still have to name the socket's origin. Both are
+  optional; a deployment behind one routing layer sets neither.
+  `// before: PUBLIC_API_ORIGIN=https://api.example  # …which only the socket read` →
+  `// after:  PUBLIC_REALTIME_ORIGIN=https://api.example`
+- **`app.config.json` is now `project.json` — the project *declaration*.** It no
+  longer describes only identity: it states what this repository is, the roles it
+  runs, what it builds, what it needs before it starts, the release steps that
+  must happen once, and the environment variables a deployment must supply.
+  Identity moved under an `identity` key and the file gained a `schemaVersion`,
+  so a reader that does not understand the format refuses the project instead of
+  interpreting it partially.
+  `// before: import { appIdentity } from '@app/config/identity'; appIdentity.name` →
+  `// after:  import { appDeclaration } from '@app/config/declaration'; appDeclaration.identity.name`
+
+  A client component imports `@app/config/app-identity` instead — a generated
+  module carrying identity alone. Importing the whole declaration from the
+  browser would ship role commands, working directories, build artifact paths and
+  the migration lockfile in the bundle.
+  `// before: import { appIdentity } from '@app/config/identity'  // in a 'use client' file` →
+  `// after:  import { appIdentity } from '@app/config/app-identity'`
+
+  The rule the file exists to hold: **it must be complete with no machine in
+  existence.** Ports, hosts, addresses, machine paths, routing shape and
+  supervision policy are named there by variable and never by value — and the
+  schema refuses them by shape rather than by review.
+
+- **The SEO helpers are async, and `siteOrigin` is gone.** They read the public
+  origin from the request instead of a build-time constant, so they cannot be
+  constants themselves. A page that calls them must await them — and TypeScript
+  will *not* catch it inside an inferred object literal, where a `Promise`
+  silently serialises as `{}`.
+  `// before: const url = absoluteSiteUrl('/en'); export const siteOrigin` →
+  `// after:  const url = await absoluteSiteUrl('/en')  // and the component becomes async`
+  `// before: createPageMetadata('home', locale)` →
+  `// after:  await createPageMetadata('home', locale)`
+
+- **A forwarded host must be claimed before it is believed.** The public origin
+  comes from the request, which makes one artifact serve many addresses — and
+  would let any caller choose the canonical URL, the sitemap and the OG metadata
+  if it were trusted blindly. Set `PUBLIC_WEB_ORIGIN` for a single address, or
+  `PUBLIC_WEB_HOSTS` for several; a host outside them is refused. `x-forwarded-proto`
+  is narrowed to `http` or `https`.
+  `// before: (nothing — any x-forwarded-host was honoured)` →
+  `// after:  PUBLIC_WEB_HOSTS=app.example,www.app.example`
+
+- **Environment variables are declared once, and the declaration lists them as
+  `env.variables`.** The server schema, the frontend schema and the tooling
+  schema were three overlapping copies that had already diverged.
+  `packages/config/src/variables.ts` is now the single declaration; `server.ts`
+  and `frontend/src/env.ts` are projections of it, and the declaration's list is
+  *derived* from it rather than restated. An overlay may now **tighten** a
+  variable, not only add one — the repository example requires `INTERNAL_API_URL`,
+  `PUBLIC_API_ORIGIN` and `CORS_ORIGIN` because its frontend dereferences them on
+  every render.
+  `// before: z.url() repeated in three files; env.required with required:false entries` →
+  `// after:  applicationVariables.INTERNAL_API_URL, referenced; env.variables`
+
+- **`NEXT_PUBLIC_API_URL` and `NEXT_PUBLIC_WEB_URL` are gone.** Anything prefixed
+  `NEXT_PUBLIC_` is substituted at BUILD time, so declaring one froze a value of
+  the place into the artifact: the built `robots.txt` and `sitemap.xml` carried
+  one origin inside their bytes, and the server chunk carried
+  `NEXT_PUBLIC_API_URL:"http://…"` as a literal. One build could not serve a
+  second address.
+  `// before: NEXT_PUBLIC_WEB_URL=https://app.example  → baked at build` →
+  `// after:  no variable; the origin is read from the request`
+  **Cost, stated plainly:** `/robots.txt`, `/sitemap.xml` and — because the root
+  layout's `generateMetadata` reads the request — the whole `[locale]` segment
+  are no longer prerendered as static content. Setting `PUBLIC_WEB_ORIGIN`
+  short-circuits the request read and restores static rendering for a deployment
+  that serves exactly one address. Answers are built once per address, not once
+  per request: `cacheByOrigin` memoises them behind a bounded LRU so a forged
+  `Host` cannot grow the cache.
+
+- **`CORS_ORIGIN` is optional.** A frontend that reaches the API through its own
+  routing layer makes same-origin requests, and requiring an origin there was
+  requiring knowledge of the place. Set it only for a genuinely cross-origin
+  browser.
+  `// before: CORS_ORIGIN=https://app.example  # required` →
+  `// after:  unset unless the browser genuinely lives elsewhere`
+
+- **The smoke and e2e addresses are `SMOKE_API_ORIGIN` and `SMOKE_WEB_ORIGIN`.**
+  They are legitimately bound to a place — they name the deployment a check dials —
+  but must not carry a prefix that makes the build substitute them.
+  `// before: NEXT_PUBLIC_API_URL=http://127.0.0.1:3211` →
+  `// after:  SMOKE_API_ORIGIN=http://127.0.0.1:3211`
+
+- **Each role is started by its own PROCESS, in its own directory, and PM2
+  process names follow the declared role names.** A role's command is `executable`
+  plus `args` in the declaration — argv, never a shell string — and the
+  supervision files are rendered from it.
+  `// before: <slug>-backend, <slug>-frontend` → `// after: <slug>-api, <slug>-web`
+  **Before your first `pm2:prod` on the new files**, remove the old processes, or
+  `startOrReload` will start the new pair beside them and both will fight for the
+  same ports under `autorestart`:
+  ```bash
+  pm2 delete <slug>-backend <slug>-frontend <slug>-backend-dev <slug>-frontend-dev
+  ```
+
+- **The web role reads its bindings itself.** The supervisor no longer builds an
+  argv for it; injecting `WEB_PORT` is now sufficient, where before a deployment
+  that set it and stopped there got a web role on the wrong port, silently. There
+  is no default port in the repository any more — a missing variable fails by
+  name.
+  `// before: "start": "next start --port ${WEB_PORT:-3210}"` →
+  `// after:  "start": "bun scripts/serve.ts production"`
+
+### Fixed
+
+- **A supervised backend now actually drains.** The supervision files started the
+  role through a script runner, so the stop signal arrived twice — once from PM2,
+  once forwarded by the launcher — and a shutdown chain treats the second signal
+  as "force it now". Measured on a real PM2 stop: a declared 15 s grace period
+  ended after **1.3 ms** with `outcome: "forced"`, `reason: "signal"`, and the
+  only visible trace was a non-zero exit code. The supervisor now execs the role
+  itself, and the same stop reports `outcome: "clean"` with exit 0.
+  `// before: script: 'bun', args: ['run', 'start']  // an intermediate shape, never released` →
+  `// after:  script: 'bun', args: ['dist/index.js']`
+  A generated project at the previous release ran `script: 'dist/index.js'` with
+  `interpreter: 'bun'`, which had the same property; the defect it *did* ship is
+  the timeout mismatch below.
+- **Supervision no longer kills the backend mid-shutdown.** The application asked
+  for a 30 s drain while PM2 sent `SIGKILL` after `kill_timeout: 15000` in
+  production and 10000 in development — so a drain longer than the supervisor's
+  patience never finished, every time. The check now covers the **whole**
+  termination budget rather than the drain alone: drain floor, plus the force
+  window that follows it, plus cleanup. Comparing against the floor alone let
+  15 s + 5 s meet a 20 s kill timeout exactly, with no margin at all.
+- **The backend says how its shutdown ended.** `onComplete` logs the outcome, the
+  reason, the duration and how many requests completed or were aborted. Without
+  it an operator saw a process that vanished and an exit code, and could not tell
+  a clean drain from one that was cut short — which is exactly how the defect
+  above stayed invisible.
+- **A requested stop of the web role reports success.** Next exits `130` on
+  `SIGINT`; the role passed that upward, so every ordinary supervised stop looked
+  like a failure. A stop the role was asked to perform now exits `0`, while a code
+  from any other cause is still passed on unchanged.
+- **A deployment's environment is no longer overruled by a file.** The production
+  supervision file loaded `.env` with `override: true`, so a value injected into
+  the process lost to a value in the repository. Bindings come from the place; the
+  file fills gaps.
+- **Release steps come from the declaration.** `pm2:prod` hand-carried
+  `db:deploy` and a build preflight as a shell string beside the declaration that
+  already stated them. It now runs `scripts/release.ts`, which checks every
+  artifact `build.artifacts` declares and applies migrations for the engine
+  `release.migrations` declares — refusing an engine it has no command for rather
+  than skipping the step, because silently not migrating is what leaves a machine
+  running against the wrong schema. Both declared migration paths are checked,
+  the lockfile included. Development runs the same step.
+- **`bun run test` passes on a fresh scaffold.** A test read `.env` at module
+  load, before `env:ensure` had created it, so the second gate the README tells a
+  new user to run died with `ENOENT` before a single test executed. Both CI paths
+  write `.env` first, so nothing saw it.
+
+### Changed
+
+- **The generated build declares whether it reads data, and CI proves it does
+  not.** Data read while building is a third kind of input — neither code nor a
+  binding — and a build that reads it undeclared is a function of whichever
+  machine had the database. The template answers it the default way: no route
+  can reach a data source at all (`check-authored` refuses the import and now
+  says why), so the build is a function of the source alone. The packed lane
+  builds against a database address that accepts nothing, which is the only
+  check that covers every transitive path at once. A project that genuinely
+  needs data at build time declares a frozen export in `build.inputs` and
+  `bun scripts/build-inputs.ts` refuses it the moment its digest drifts.
+- **One artifact is now provably portable in CI, within a stated policy.**
+  `runtime:smoke` asks the running web role for `/sitemap.xml` and `/robots.txt`
+  under two different external addresses and requires two different answers —
+  and requires a *third*, unclaimed host to be refused. The first half catches a
+  build-time address creeping back in; the second catches the portability
+  mechanism turning into an open redirect for metadata.
+- **The drain floor has one home.** The backend passed a literal grace period
+  while the declaration stated another — the same two-numbers-in-two-files shape
+  that let a 30 s floor meet a 15 s kill timeout. It now reads
+  `apiRole.drainFloorMs`, the number a supervisor reads too.
+- **Three files are generated from the declaration** — both supervision files and
+  the client-safe identity module — plus the `env.variables` block of the
+  declaration itself. `bun run gen:declaration` renders them and the test suite
+  refuses a stale copy. The example's declaration is generated from the
+  template's in the same way.
+- **The generated application targets Stitchkit `^0.59.0`.** The template's
+  catalog pointed at `^0.52.0`, so a project scaffolded today started seven
+  minors behind the framework — without neutral client-disconnect handling,
+  managed files, composed auth, async operation contracts or the CLI presentation
+  policy. Both the packed target lane and the packed HEAD lane pass on the new
+  target.
+- **The scaffolder prints the addresses the generated project will actually
+  use**, read back from its declaration and example environment rather than
+  restated as constants.
+
+## [0.3.3] — 2026-08-18
+
+### Changed
+
+- **Generated applications bind loopback by default.** Both processes listen on
+  `BIND_HOST` (default `127.0.0.1`) instead of a hardcoded `0.0.0.0` in the
+  backend server and both PM2 configs. Exposing the app to the network is now a
+  single conscious opt-in (`BIND_HOST=0.0.0.0` in `.env`) rather than the state
+  a forgotten edit leaves behind. Reported from a production deployment of a
+  generated app.
+- **The template targets Stitchkit `^0.52.0`** — new applications get
+  `implement.declare`, keyed registries and hook-derived scope maps out of the
+  box. Purely additive relative to 0.50.
+- **`bun run dev` reports honest URLs and fails fast on occupied ports.** The
+  final `Web:`/`API:` lines are rendered from the validated environment instead
+  of hardcoded ports, and before starting fresh PM2 processes the script probes
+  `API_PORT`/`WEB_PORT` and names the offending variable when a foreign process
+  holds one. Reloads of the app's own processes are unaffected.
+- **`start` without a build says what to do.** A missing `dist/index.js` now
+  fails with “run `bun run build` first” (also preflighted in `pm2:prod`)
+  instead of a bare module-resolution error.
+- **README and AGENTS.md pin the Prisma entry point.** Database commands go
+  through the root `bun run db:*` scripts; the `prisma` CLI invoked directly has
+  no datasource URL by design.
+
 ## [0.3.2] — 2026-08-17
 
 ### Changed

package/README.md

@@ -16,7 +16,9 @@ complete production UI system.
 It uses one conventional `packages/*` namespace: `backend`, `frontend`,
 `config`, `db` and `shared`. The destination name becomes the generated slug;
 `--display-name` sets the human title. Both are recorded once in
-`app.config.json` and drive package, process, transport, UI and SEO identity.
+`project.json` — the generated project's **declaration**, the single
+machine-readable statement it makes about itself — and drive package, process,
+transport, UI and SEO identity.
 
 The default scaffold is domain-free. To add the runnable repository example:
 

package/UPGRADING.md

@@ -0,0 +1,225 @@
+# Upgrading a generated project
+
+How to move a project generated by `create-stitchkit` from one scaffolder
+version to another. It is a different move from upgrading the framework: your
+project is a **copy** of the template, not a dependency on it, so nothing here
+happens by installing anything. What a new scaffolder version brings is a set of
+edits you apply to a tree you already own, plus — and this is the part that bites
+— **operator steps**: things a machine has to be told before the new shape will
+start at all.
+
+The framework's own guide is
+[`docs/guide/upgrading.md`](../../docs/guide/upgrading.md); it covers the
+`stitchkit` dependency. This one covers the generated project.
+
+## The one rule that makes this work
+
+A scaffolder release that changes the generated project in a way an existing
+project must follow leads its [`CHANGELOG.md`](./CHANGELOG.md) entry with a
+**`### ⚠️ Breaking changes`** section (exact heading), each item carrying a
+**before → after** snippet. A version with **no** such section changes nothing
+you are obliged to adopt.
+
+The changelog says *what* changed. This file says what else has to happen —
+including the steps that touch a running machine, which have no place in a
+changelog because the next release overwrites the entry that carried them.
+
+## Flow
+
+1. **Find your project's origin.** The scaffolder version that generated it is
+   not recorded in the tree — check the changelog of the version you scaffolded
+   with, or diff your tree against a fresh scaffold of your current target.
+2. **Read every `### ⚠️ Breaking changes` in range** in
+   [`CHANGELOG.md`](./CHANGELOG.md), from the version above yours up to your
+   target.
+3. **Apply the code edits**, then the **`## Released migration: X.Y.Z`** section
+   below for the same versions — that is where the operator steps live.
+
+   > This channel starts at **0.4.0**. Versions below it have breaking changelog
+   > entries and no migration section here, because the file did not exist yet;
+   > for those, the changelog entry is all there is.
+4. **Verify** with your project's own gates: `bun run check`, `bun run test`,
+   `bun run build`, then a real start.
+
+## Where a migration section goes while the version has no number
+
+Write it here as **`## Unreleased migration: <short slug>`**. The slug matters:
+several may sit side by side, and each belongs to whoever wrote it. Do **not**
+reuse another author's heading — that is how a migration gets overwritten before
+anyone promotes it.
+
+At release, the release commit promotes every `Unreleased migration` heading
+into one `## Released migration: X.Y.Z`, each former heading becoming a `###`
+subsection under it — the same move the changelog makes when `[Unreleased]`
+becomes `## [X.Y.Z]`, in the same commit.
+
+A release carrying `### ⚠️ Breaking changes` and no matching
+`## Released migration: X.Y.Z` is refused by `bun scripts/release-plan.ts`, in
+`pre-push` and again in the publishing workflow. The check starts at `0.4.0` —
+the first scaffolder release with a migration channel of its own.
+
+---
+
+## Released migration: 0.4.0
+
+### the project declares itself
+
+Everything in this section is for a project generated **before** the scaffolder
+version that introduces `project.json`.
+
+#### The declaration replaces `app.config.json`
+
+`app.config.json` said who the project was. `project.json` says what it *is*:
+identity, the roles it runs, what it builds, what it needs before it starts,
+what must happen once on release, and the **names** of the variables a
+deployment supplies. Identity moved under an `identity` key, and the file gained
+a `schemaVersion` so a reader that does not understand the format refuses the
+project instead of interpreting half of it.
+
+```ts
+// before
+import { appIdentity } from '@app/config/identity';
+appIdentity.name;
+
+// after
+import { appDeclaration } from '@app/config/declaration';
+appDeclaration.identity.name;
+```
+
+A **client** component imports the generated identity-only module instead —
+importing the whole declaration from the browser ships role commands, working
+directories, artifact paths and the migration lockfile in the bundle:
+
+```ts
+// before, in a 'use client' file
+import { appIdentity } from '@app/config/identity';
+
+// after
+import { appIdentity } from '@app/config/app-identity';
+```
+
+#### Operator step: delete the old supervisor processes FIRST
+
+PM2 process names now follow the declared role names, so the new supervision
+files start a **new pair beside the old one**. Under `autorestart` both then
+fight for the same ports, and the symptom is an `EADDRINUSE` loop rather than a
+clear error.
+
+Before the first `bun run pm2:prod` on the new files:
+
+```bash
+pm2 delete <slug>-backend <slug>-frontend <slug>-backend-dev <slug>-frontend-dev
+```
+
+`<slug>` is your project's slug — `identity.slug` in `project.json`. Check what
+is actually registered with `pm2 list` first; nothing here is safe to run blind.
+
+#### Operator step: the supervisor's patience must cover the whole shutdown
+
+The generated `ecosystem.config.cjs` is now rendered from the declaration, and
+its `kill_timeout` is computed from each role's drain floor plus the force
+window plus cleanup. If you kept a hand-edited supervision file, compare its
+`kill_timeout` against `drainFloorMs` in `project.json`: a timeout shorter than
+the full budget means the drain never finishes, every time, and the only visible
+trace is a non-zero exit code.
+
+Regenerate rather than hand-edit:
+
+```bash
+bun run gen:declaration
+```
+
+#### Environment: three variables changed meaning
+
+```sh
+# before
+NEXT_PUBLIC_API_URL=https://api.example
+NEXT_PUBLIC_WEB_URL=https://app.example
+
+# after — nothing. Both are gone.
+```
+
+Anything prefixed `NEXT_PUBLIC_` is substituted at **build** time, so declaring
+one froze an address into the artifact: the built `robots.txt` and `sitemap.xml`
+carried one origin in their bytes and one build could not serve a second
+address. The public origin now comes from the request.
+
+A forwarded host must be claimed before it is believed. Set **one** of:
+
+```sh
+PUBLIC_WEB_ORIGIN=https://app.example          # a single address
+PUBLIC_WEB_HOSTS=app.example,www.app.example   # several
+```
+
+A host outside them is refused. Setting `PUBLIC_WEB_ORIGIN` also restores static
+rendering for `/robots.txt`, `/sitemap.xml` and the `[locale]` segment, which
+otherwise become request-rendered.
+
+The check and e2e addresses were renamed so no build can substitute them:
+
+```sh
+# before
+NEXT_PUBLIC_API_URL=http://127.0.0.1:3211
+# after
+SMOKE_API_ORIGIN=http://127.0.0.1:3211
+SMOKE_WEB_ORIGIN=http://127.0.0.1:3210
+```
+
+`CORS_ORIGIN` is now optional: a frontend that reaches the API through its own
+routing layer makes same-origin requests, and requiring an origin there was
+requiring knowledge of the place.
+
+#### The repository example: calls lose their parentheses
+
+Only for a project generated with `--example repository`. The browser now talks
+to its own origin, so the API client is a module constant:
+
+```ts
+// before
+repositoryApi().read();
+repositoryUrls().read();
+
+// after
+repositoryApi.read();
+repositoryUrls.read();
+```
+
+The web role forwards `/api/…` to the API role, which needs `INTERNAL_API_URL`
+(already required).
+
+**The socket's address is now its own variable.** If you use the realtime
+socket and have no routing layer forwarding `/socket.io`, rename it:
+
+```sh
+# before — read only by the socket, despite the name
+PUBLIC_API_ORIGIN=https://api.example
+# after
+PUBLIC_REALTIME_ORIGIN=https://api.example
+```
+
+`PUBLIC_API_ORIGIN` still exists and still means HTTP, but it is inert until you
+switch: the import in `packages/frontend/src/lib/api/queries.ts` decides which
+client the browser uses. Both variables are optional; a deployment behind one
+routing layer sets neither, and `CORS_ORIGIN` with them.
+
+The cross-origin form moved to `packages/frontend/src/lib/api/cross-origin.ts`
+(previously `lib/api/origin.ts`); `requirePublicApiOrigin` lives there, beside
+`optionalRealtimeOrigin` and `setPublicOrigins`.
+
+#### The SEO helpers are async
+
+They read the public origin from the request, so they cannot be constants.
+TypeScript will **not** catch a missing `await` inside an inferred object
+literal — a `Promise` serialises there as `{}`.
+
+```ts
+// before
+const url = absoluteSiteUrl('/en');
+createPageMetadata('home', locale);
+
+// after — and the component becomes async
+const url = await absoluteSiteUrl('/en');
+await createPageMetadata('home', locale);
+```
+
+`siteOrigin` is gone.