create-stitchkit 0.3.3 → 0.4.1

package/template/e2e/starter.spec.ts

@@ -1,4 +1,4 @@
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { systemContract } from '@app/shared';
 import AxeBuilder from '@axe-core/playwright';
 import { expect, test } from '@playwright/test';
@@ -21,7 +21,7 @@ test('calls the live backend through the typed contract client', async () => {
   const client = createClient(
     systemContract,
     createHttpClient({
-      baseUrl: `${toolingEnv.NEXT_PUBLIC_API_URL}/api`,
+      baseUrl: `${toolingEnv.SMOKE_API_ORIGIN}/api`,
       credentials: 'omit',
     }),
   );
@@ -31,7 +31,7 @@ test('calls the live backend through the typed contract client', async () => {
 
 test('publishes complete page metadata', async ({ page }) => {
   await page.goto('/en/ui/themes');
-  await expect(page).toHaveTitle(`Theme system · ${appIdentity.name}`);
+  await expect(page).toHaveTitle(`Theme system · ${appDeclaration.identity.name}`);
   await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
     'href',
     /\/en\/ui\/themes$/,
@@ -42,9 +42,7 @@ test('publishes complete page metadata', async ({ page }) => {
   );
 
   const imageUrl = await page.locator('meta[property="og:image"]').getAttribute('content');
-  expect(imageUrl).toBe(
-    new URL('/api/og/en/themes', toolingEnv.NEXT_PUBLIC_WEB_URL).toString(),
-  );
+  expect(imageUrl).toBe(new URL('/api/og/en/themes', toolingEnv.SMOKE_WEB_ORIGIN).toString());
 });
 
 test('switches catalogue sections and component tabs', async ({ page }) => {
@@ -217,7 +215,7 @@ test('provides a server-first synchronized theme system', async ({
   await page.getByRole('button', { name: 'System', exact: true }).click();
   await expect(page.getByTestId('theme-state-selected')).toContainText('system');
   const themeCookie = (await context.cookies()).find(
-    (cookie) => cookie.name === `${appIdentity.slug}-theme`,
+    (cookie) => cookie.name === `${appDeclaration.identity.slug}-theme`,
   );
   expect(themeCookie?.value).toBe('system');
   await page.reload();

package/template/ecosystem.config.cjs

@@ -1,34 +1,57 @@
+// GENERATED FILE — do not edit.
+//
+// Rendered from `project.json` by `scripts/declaration.ts`; run
+// `bun run gen:declaration` after changing a role. Roles, commands and the
+// drain floor come from the declaration because they are true of the code;
+// restart policy and the kill timeout are this machine's, and the generator
+// refuses a timeout shorter than any role's full shutdown budget.
 const path = require('node:path');
 const { config } = require('dotenv');
-const identity = require('./app.config.json');
+const declaration = require('./project.json');
 
-config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
+// NOT `override`: an environment a deployment injected into this process must
+// win over a file in the repository. The file fills gaps; it does not overrule
+// the place.
+config({ path: path.join(__dirname, '.env'), quiet: true });
 
 module.exports = {
   apps: [
     {
-      name: `${identity.slug}-backend`,
-      cwd: path.join(__dirname, 'packages/backend'),
-      script: 'dist/index.js',
-      interpreter: 'bun',
+      name: `${declaration.identity.slug}-api`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/backend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `API_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["dist/index.js"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 15000,
+      // >= this role's full shutdown budget of 25000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'production' },
     },
     {
-      name: `${identity.slug}-frontend`,
-      cwd: path.join(__dirname, 'packages/frontend'),
-      script: 'node_modules/.bin/next',
-      args: [
-        'start',
-        '--port',
-        process.env.WEB_PORT,
-        '--hostname',
-        process.env.BIND_HOST ?? '127.0.0.1',
-      ],
-      interpreter: 'bun',
+      name: `${declaration.identity.slug}-web`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/frontend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `WEB_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["scripts/serve.ts","production"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 15000,
+      // >= this role's full shutdown budget of 15000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'production' },
     },
   ],

package/template/ecosystem.dev.config.cjs

@@ -1,37 +1,57 @@
+// GENERATED FILE — do not edit.
+//
+// Rendered from `project.json` by `scripts/declaration.ts`; run
+// `bun run gen:declaration` after changing a role. Roles, commands and the
+// drain floor come from the declaration because they are true of the code;
+// restart policy and the kill timeout are this machine's, and the generator
+// refuses a timeout shorter than any role's full shutdown budget.
 const path = require('node:path');
 const { config } = require('dotenv');
-const identity = require('./app.config.json');
+const declaration = require('./project.json');
 
+// NOT `override`: an environment a deployment injected into this process must
+// win over a file in the repository. The file fills gaps; it does not overrule
+// the place.
 config({ path: path.join(__dirname, '.env'), quiet: true });
 
-const frontendArgs = [
-  'dev',
-  '--port',
-  process.env.WEB_PORT,
-  '--hostname',
-  process.env.BIND_HOST ?? '127.0.0.1',
-];
-
 module.exports = {
   apps: [
     {
-      name: `${identity.slug}-backend-dev`,
-      cwd: path.join(__dirname, 'packages/backend'),
-      script: 'src/index.ts',
-      interpreter: 'bun',
-      interpreter_args: '--watch',
+      name: `${declaration.identity.slug}-api-dev`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/backend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `API_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["--watch","src/index.ts"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 10000,
+      // >= this role's full shutdown budget of 25000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'development' },
     },
     {
-      name: `${identity.slug}-frontend-dev`,
-      cwd: path.join(__dirname, 'packages/frontend'),
-      script: 'node_modules/.bin/next',
-      args: frontendArgs,
-      interpreter: 'bun',
+      name: `${declaration.identity.slug}-web-dev`,
+      // The role's OWN process, in its OWN directory — no launcher in between.
+      // Measured: a launcher makes the role see the stop signal twice (once from
+      // the supervisor, once forwarded), the second press forces the shutdown,
+      // and a declared drain of seconds collapses to milliseconds. A workspace
+      // filter is worse: the signal never arrives at all.
+      cwd: path.join(__dirname, "packages/frontend"),
+      script: "bun",
+      // No argv invented here: the deployment injects `WEB_PORT` and the command
+      // reads it. Serialised rather than concatenated — an argument with a space
+      // or a quote has to survive this file intact.
+      args: ["scripts/serve.ts","development"],
+      interpreter: 'none',
       autorestart: true,
-      kill_timeout: 10000,
+      // >= this role's full shutdown budget of 15000ms.
+      kill_timeout: 30000,
       env: { NODE_ENV: 'development' },
     },
   ],

package/template/package.json

@@ -7,14 +7,14 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.52.0"
+    "stitchkit": "^0.60.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
     "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
-    "test": "bun run --filter '*' test",
-    "build": "bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
+    "test": "bun test scripts && bun run --filter '*' test",
+    "build": "bun scripts/build-inputs.ts && bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build && bun scripts/build-stamp.ts",
     "start:api": "bun --filter @app/backend start",
     "start:web": "bun --filter @app/frontend start",
     "env:ensure": "bun scripts/local-env.ts",
@@ -28,10 +28,12 @@
     "runtime:smoke": "bun scripts/runtime-smoke.ts",
     "surface:snapshot": "bun scripts/surface-snapshot.ts",
     "e2e": "playwright test",
+    "acceptance:local": "bun scripts/acceptance-local.ts",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
     "pm2:dev": "bun scripts/dev.ts",
-    "pm2:prod": "bun run db:deploy && bun packages/backend/scripts/ensure-built.ts && pm2 startOrReload ecosystem.config.cjs --update-env"
+    "pm2:prod": "bun scripts/release.ts",
+    "gen:declaration": "bun scripts/declaration.ts"
   },
   "dependencies": {
     "dotenv": "^17.4.2"
@@ -39,13 +41,13 @@
   "devDependencies": {
     "@app/config": "workspace:*",
     "@app/shared": "workspace:*",
-    "@axe-core/playwright": "^4.11.0",
-    "@biomejs/biome": "^2.5.7",
+    "@axe-core/playwright": "^4.13.0",
+    "@biomejs/biome": "^2.5.10",
     "@modelcontextprotocol/client": "^2.0.0",
-    "@playwright/test": "^1.55.0",
-    "@types/bun": "^1.3.14",
-    "@types/node": "^26.2.0",
-    "oxc-parser": "^0.143.0",
+    "@playwright/test": "^1.62.1",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26.3.0",
+    "oxc-parser": "^0.147.0",
     "socket.io-client": "^4.8.3",
     "stitchkit": "catalog:",
     "typescript": "^7.0.2",

package/template/packages/backend/package.json

@@ -19,13 +19,13 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "@prisma/adapter-pg": "^7.9.1",
     "@socket.io/bun-engine": "^0.1.1",
-    "ai": "^7.0.58",
+    "ai": "^7.0.78",
     "socket.io": "^4.8.3",
     "stitchkit": "catalog:",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "typescript": "^7.0.2"
   }
 }

package/template/packages/backend/src/cleanup.ts

@@ -0,0 +1,121 @@
+import { CLEANUP_BUDGET_MS } from '@app/config/shutdown';
+
+export interface CleanupStep {
+  name: string;
+  close: () => Promise<unknown>;
+}
+
+export interface CleanupFailure {
+  name: string;
+  cause: unknown;
+}
+
+export interface CleanupResult {
+  /** Steps that did not finish inside the budget, in order. */
+  unfinished: string[];
+  /** Steps that finished by throwing, with what they threw. */
+  failed: CleanupFailure[];
+  durationMs: number;
+}
+
+/** How one step ended: in time, in time but throwing, or not in time. */
+type StepOutcome =
+  | { kind: 'finished' }
+  | { kind: 'threw'; cause: unknown }
+  | { kind: 'expired' };
+
+/**
+ * Close what the role owns, and stop waiting when the budget is spent.
+ *
+ * Waiting forever is not the safe option it looks like: the supervisor's kill
+ * timeout is derived from this budget, so a close that hangs past it turns an
+ * orderly shutdown into a SIGKILL — which is the one ending that runs no
+ * cleanup at all. Better to leave one connection to the operating system and
+ * exit, saying which.
+ *
+ * The steps run in order and share one deadline, because they are one budget:
+ * a slow first close must not hand the second one a full budget of its own.
+ *
+ * The two ways a step can end are kept apart. Running out of time and throwing
+ * are different facts about a shutdown — one says a resource is still held, the
+ * other says closing it is broken — and collapsing them (this used to discard
+ * the rejection entirely) turned a failed shutdown into a clean exit with the
+ * reason gone.
+ *
+ * The clock is `performance.now()` and cannot be replaced. It used to be
+ * `Date.now()` behind an injectable parameter, and both halves of that were
+ * wrong for a deadline: a wall clock stepped backwards widens the very upper
+ * bound a supervisor's kill timeout was derived from, and an injected clock
+ * that does not advance hands every step a full budget — a shutdown budget that
+ * a test could switch off. Nothing needs to fake it: the regression that
+ * matters runs a real process.
+ */
+export async function closeWithinBudget(
+  steps: readonly CleanupStep[],
+  budgetMs: number = CLEANUP_BUDGET_MS,
+): Promise<CleanupResult> {
+  const now = (): number => performance.now();
+  const startedAt = now();
+  const unfinished: string[] = [];
+  const failed: CleanupFailure[] = [];
+  const finished = (): StepOutcome => ({ kind: 'finished' });
+  const threw = (cause: unknown): StepOutcome => ({ kind: 'threw', cause });
+  for (const step of steps) {
+    const remaining = budgetMs - (now() - startedAt);
+    if (remaining <= 0) {
+      unfinished.push(step.name);
+      continue;
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const outcome = await Promise.race<StepOutcome>([
+      step.close().then(finished, threw),
+      new Promise<StepOutcome>((resolve) => {
+        timer = setTimeout(() => resolve({ kind: 'expired' }), remaining);
+      }),
+    ]);
+    if (timer !== undefined) clearTimeout(timer);
+    if (outcome.kind === 'expired') unfinished.push(step.name);
+    else if (outcome.kind === 'threw') failed.push({ name: step.name, cause: outcome.cause });
+  }
+  return { unfinished, failed, durationMs: Math.round(now() - startedAt) };
+}
+
+/**
+ * Turn a bounded cleanup into an ending: say what happened, and make sure it
+ * actually ends.
+ *
+ * `process.exitCode` only decides the code the process reports *when it exits*.
+ * A step that ran out of time may still be holding a handle — that is what
+ * running out of time usually means — and a process holding one waits for the
+ * event loop to drain, which is precisely the wait the supervisor answers with
+ * SIGKILL. So an unfinished step is not a note to log on the way out; it is the
+ * reason to leave now.
+ *
+ * `exit` is a parameter so this decision can be exercised without ending the
+ * test runner — but the regression that matters runs a real process
+ * (`scripts/shutdown-budget.fixture.ts`), because "the promise resolved" was
+ * never the property in question.
+ */
+export function concludeShutdown(
+  result: CleanupResult,
+  drainWasClean: boolean,
+  exit: (code: number) => void = (code) => process.exit(code),
+): void {
+  for (const failure of result.failed) {
+    console.error(`Shutdown could not close ${failure.name}:`, failure.cause);
+  }
+  if (result.unfinished.length > 0) {
+    console.error(
+      `Shutdown left ${result.unfinished.join(' and ')} unclosed after ${result.durationMs}ms — the cleanup budget is spent, exiting anyway.`,
+    );
+  }
+  const cleanupCompleted = result.unfinished.length === 0 && result.failed.length === 0;
+  const code = drainWasClean && cleanupCompleted ? 0 : 1;
+  process.exitCode = code;
+  // A cleanup that did not complete does not get to wait. Either a step ran out
+  // of time — so something is still held — or closing it threw, which says the
+  // same thing with less certainty about what. A shutdown that completed exits
+  // on its own, and letting it do so keeps the ordinary path ordinary.
+  // Last on purpose: nothing after this line runs.
+  if (!cleanupCompleted) exit(code);
+}

package/template/packages/backend/src/cli.ts

@@ -1,13 +1,17 @@
 #!/usr/bin/env bun
 
-import { appIdentity } from '@app/config/identity';
+import { appDeclaration } from '@app/config/declaration';
 import { createCli } from 'stitchkit/cli';
 import { createSurface } from './surface';
 
 const { services, socket } = await createSurface();
 
 try {
-  await createCli({ name: appIdentity.slug, version: appIdentity.version, services });
+  await createCli({
+    name: appDeclaration.identity.slug,
+    version: appDeclaration.identity.version,
+    services,
+  });
 } finally {
   await socket.close();
 }

package/template/packages/backend/src/index.ts

@@ -1,5 +1,5 @@
 import { env } from '@app/config';
-import { appIdentity } from '@app/config/identity';
+import { apiRole, appDeclaration } from '@app/config/declaration';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import {
   bindProcessSignals,
@@ -8,6 +8,7 @@ import {
   openApiRoute,
 } from 'stitchkit/server';
 import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools';
+import { closeWithinBudget, concludeShutdown } from './cleanup';
 import { prisma } from './lib/db';
 import { createSurface } from './surface';
 import { onError } from './transport/errors';
@@ -15,12 +16,18 @@ import { onError } from './transport/errors';
 async function main(): Promise<void> {
   const { services, socket } = await createSurface();
   const mcp = createMcpHandler({
-    serverInfo: { name: appIdentity.slug, version: appIdentity.version },
+    serverInfo: {
+      name: appDeclaration.identity.slug,
+      version: appDeclaration.identity.version,
+    },
     auth: () => ({ scope: 'public' }),
     services,
   });
   const openApi = generateOpenApiDocument({
-    info: { title: `${appIdentity.name} API`, version: appIdentity.version },
+    info: {
+      title: `${appDeclaration.identity.name} API`,
+      version: appDeclaration.identity.version,
+    },
     groups: [{ pathPrefix: '/api', services }],
   });
 
@@ -28,7 +35,7 @@ async function main(): Promise<void> {
     groups: [{ pathPrefix: '/api', services }],
     port: env.API_PORT,
     hostname: env.BIND_HOST,
-    cors: { origin: env.CORS_ORIGIN },
+    cors: env.CORS_ORIGIN ? { origin: env.CORS_ORIGIN } : undefined,
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
     socket,
@@ -48,11 +55,29 @@ async function main(): Promise<void> {
   // application's and close after the drain. A second signal forces this same
   // shutdown, a third hands the signal back to its default disposition.
   bindProcessSignals(server, {
-    shutdown: { gracePeriodMs: 30_000 },
+    // The FLOOR comes from the declaration, which is where a supervisor reads
+    // it too — one number, not two that can disagree. It is a property of the
+    // code: whatever supervises this process must allow at least this much
+    // before sending SIGKILL, or the drain never finishes.
+    shutdown: { gracePeriodMs: apiRole.drainFloorMs },
     onComplete: async (result) => {
-      await mcp.close();
-      await prisma.$disconnect();
-      process.exitCode = result.outcome === 'clean' ? 0 : 1;
+      // Bounded on purpose. The supervisor's kill timeout is derived from this
+      // budget, so a close that hangs past it turns an orderly shutdown into a
+      // SIGKILL — the one ending that runs no cleanup at all.
+      const cleanup = await closeWithinBudget([
+        { name: 'MCP', close: () => mcp.close() },
+        { name: 'database', close: () => prisma.$disconnect() },
+      ]);
+      // Say how the drain ended. Without this an operator sees a process that
+      // vanished and an exit code, and cannot tell a clean drain from one the
+      // deadline or a second signal cut short.
+      console.log(
+        `Shutdown ${result.outcome}${result.reason ? ` (${result.reason})` : ''} in ${result.durationMs}ms — ${result.completedRequests} requests completed, ${result.abortedRequests} aborted, ${result.forcedWebSockets} sockets forced`,
+      );
+      // Sets the code, reports any close that threw, and — if a step is still
+      // holding something — ends the process here rather than waiting for a
+      // handle that already missed its deadline. Nothing follows it.
+      concludeShutdown(cleanup, result.outcome === 'clean');
     },
     onError: (phase, error) => {
       console.error(`Shutdown failed during ${phase}`, error);

package/template/packages/backend/src/surface.ts

@@ -3,6 +3,11 @@ import { createSocketIOServer } from 'stitchkit/server';
 import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
-  const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN } });
+  // An EMPTY allow-list is same-origin: no origin is permitted to open a
+  // cross-origin socket, and no browser on this app's own origin needs one.
+  // `CORS_ORIGIN` is set only when the browser genuinely lives elsewhere.
+  // (Once the workspace targets a Stitchkit release where `cors` itself is
+  // optional, this becomes `undefined` and the empty array goes away.)
+  const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN ?? [] } });
   return { socket, services: [createSystemService()] };
 }

package/template/packages/backend/src/transport/errors.ts

@@ -1,7 +1,9 @@
-import type { StitchErrorCode } from 'stitchkit';
 import { createErrorHook } from 'stitchkit/server';
 
-const codeMap: Record<StitchErrorCode, string> = {
+// Deliberately not annotated as an exhaustive `Record<StitchErrorCode, …>`:
+// this template compiles against both its pinned Stitchkit target and HEAD, and
+// the code union differs between them. Unlisted codes travel as themselves.
+const codeMap = {
   BAD_REQUEST: 'bad_request',
   VALIDATION_ERROR: 'validation_error',
   UNAUTHORIZED: 'unauthorized',

package/template/packages/config/package.json

@@ -5,7 +5,10 @@
   "type": "module",
   "exports": {
     ".": "./src/server.ts",
-    "./identity": "./src/identity.ts"
+    "./variables": "./src/variables.ts",
+    "./declaration": "./src/declaration.ts",
+    "./shutdown": "./src/shutdown.ts",
+    "./app-identity": "./src/app-identity.generated.ts"
   },
   "scripts": {
     "check": "bun x tsc --noEmit",
@@ -14,10 +17,11 @@
   "dependencies": {
     "@t3-oss/env-core": "^0.13.11",
     "dotenv": "^17.4.2",
+    "stitchkit": "catalog:",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "typescript": "^7.0.2"
   }
 }

package/template/packages/config/src/app-identity.generated.ts

@@ -0,0 +1,20 @@
+// GENERATED FILE — do not edit.
+//
+// Rendered from `project.json` by `scripts/declaration.ts`.
+//
+// Identity ONLY, inlined rather than imported, because this is the part of the
+// declaration a browser may know. Importing the whole declaration from a client
+// component would put role commands, working directories, build artifact paths,
+// the migration lockfile and every environment variable name into the browser
+// bundle — the same mistake as publishing internal topology from a status
+// endpoint, made from the other side.
+
+export const appIdentity = {
+  "slug": "stitchkit-starter",
+  "name": "Stitchkit Starter",
+  "version": "0.1.0",
+  "description": {
+    "en": "Stitchkit Starter is a production application built with Stitchkit.",
+    "ru": "Stitchkit Starter — production-приложение на Stitchkit."
+  }
+};

package/template/packages/config/src/declaration.ts

@@ -0,0 +1,30 @@
+import { findProjectRole, parseProjectDeclaration } from 'stitchkit/declaration';
+import source from '../../../project.json' with { type: 'json' };
+
+/**
+ * What this repository says about itself — the one machine-readable statement
+ * that is true with no machine in existence.
+ *
+ * Ports, hosts, addresses, machine paths and supervision policy are NOT here by
+ * construction: the schema has nowhere to put them. A deployment supplies those
+ * under the variable names the declaration lists.
+ */
+export const appDeclaration = parseProjectDeclaration(source);
+
+/**
+ * This application's API role.
+ *
+ * Resolved once, here, so the role's own code can read what the declaration
+ * says about it — the drain floor above all — instead of restating it. A
+ * declaration without the role is a broken declaration, and saying so at
+ * startup beats a silent `undefined` deep inside a shutdown path.
+ */
+const API_ROLE_NAME = 'api';
+
+export const apiRole = (() => {
+  const role = findProjectRole(appDeclaration, API_ROLE_NAME);
+  if (!role) {
+    throw new Error(`project.json declares no "${API_ROLE_NAME}" role.`);
+  }
+  return role;
+})();

package/template/packages/config/src/server.ts

@@ -1,27 +1,18 @@
 import path from 'node:path';
 import { createEnv } from '@t3-oss/env-core';
 import { config } from 'dotenv';
-import { z } from 'zod';
-import { featureServerSchema } from './features';
+import { applicationVariables } from './variables';
 
 config({ path: path.resolve(import.meta.dirname, '../../../.env'), quiet: true });
 
+/**
+ * The API role's view of the environment: every declared variable.
+ *
+ * The variables themselves are declared once in `variables.ts` — this module
+ * only says which of them this role validates, and where the file is read from.
+ */
 export const env = createEnv({
-  server: {
-    NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
-    DATABASE_URL: z.url(),
-    // Loopback by default — exposing the app to the network is an explicit
-    // opt-in (`BIND_HOST=0.0.0.0`), never something a forgotten edit causes.
-    BIND_HOST: z.string().min(1).default('127.0.0.1'),
-    API_PORT: z.coerce.number().int().positive(),
-    WEB_PORT: z.coerce.number().int().positive(),
-    NEXT_PUBLIC_API_URL: z.url(),
-    INTERNAL_API_URL: z.url(),
-    NEXT_PUBLIC_WEB_URL: z.url(),
-    LOG_FORMAT: z.enum(['pretty', 'json']).default('pretty'),
-    CORS_ORIGIN: z.url(),
-    ...featureServerSchema,
-  },
+  server: applicationVariables,
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,
 });

package/template/packages/config/src/shutdown.ts

@@ -0,0 +1,20 @@
+/**
+ * The parts of a shutdown that are NOT the drain, as one number each.
+ *
+ * `terminationBudgetMs` adds these to a role's drain floor and refuses a
+ * supervision policy that allows less. That only means something if each part
+ * is really bounded — and cleanup was not: the drain has a deadline, but the
+ * closes that run after it (an MCP session, a database pool) had none, so the
+ * "budget" was an estimate wearing the shape of an upper bound, and a role
+ * could still be killed mid-shutdown by a timeout the generator had approved.
+ *
+ * They live here rather than in the generator because two readers need them and
+ * a number in two places is two numbers: the generator, which tells a
+ * supervisor how long to wait, and the role itself, which must not take longer.
+ */
+
+/** After the drain deadline, how long a forced finish may take. */
+export const FORCE_BUDGET_MS = 5_000;
+
+/** After the server is done, how long the role's own closes may take. */
+export const CLEANUP_BUDGET_MS = 5_000;