create-stitchkit 0.4.0 → 0.4.1

package/template/package.json

@@ -14,7 +14,7 @@
     "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 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",
+    "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,6 +28,7 @@
     "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",
@@ -40,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/index.ts

@@ -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';
@@ -60,15 +61,23 @@ async function main(): Promise<void> {
     // before sending SIGKILL, or the drain never finishes.
     shutdown: { gracePeriodMs: apiRole.drainFloorMs },
     onComplete: async (result) => {
-      await mcp.close();
-      await prisma.$disconnect();
+      // 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`,
       );
-      process.exitCode = result.outcome === 'clean' ? 0 : 1;
+      // 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/config/package.json

@@ -7,6 +7,7 @@
     ".": "./src/server.ts",
     "./variables": "./src/variables.ts",
     "./declaration": "./src/declaration.ts",
+    "./shutdown": "./src/shutdown.ts",
     "./app-identity": "./src/app-identity.generated.ts"
   },
   "scripts": {
@@ -16,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/declaration.ts

@@ -1,5 +1,5 @@
+import { findProjectRole, parseProjectDeclaration } from 'stitchkit/declaration';
 import source from '../../../project.json' with { type: 'json' };
-import { findProjectRole, parseProjectDeclaration } from './project-declaration.generated';
 
 /**
  * What this repository says about itself — the one machine-readable statement

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;

package/template/packages/db/package.json

@@ -19,10 +19,10 @@
     "@app/config": "workspace:*",
     "@prisma/adapter-pg": "^7.9.1",
     "@prisma/client": "^7.9.1",
-    "pg": "^8.22.0"
+    "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@types/pg": "^8.21.0",
+    "@types/pg": "^8.23.1",
     "prisma": "^7.9.1",
     "typescript": "^7.0.2"
   }

package/template/packages/frontend/package.json

@@ -26,23 +26,23 @@
     "@radix-ui/react-tooltip": "^1.2.16",
     "@t3-oss/env-nextjs": "^0.13.11",
     "@tabler/icons-react": "^3.46.0",
-    "@tanstack/react-query": "^5.101.4",
-    "@tanstack/react-table": "^9.1.0",
-    "@wrksz/themes": "^1.1.0",
+    "@tanstack/react-query": "^5.102.3",
+    "@tanstack/react-table": "^9.1.2",
+    "@wrksz/themes": "^1.2.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.4.0",
     "dotenv": "^17.4.2",
-    "framer-motion": "^13.0.0",
-    "next": "^16.3.0",
-    "next-intl": "^4.13.5",
+    "framer-motion": "^13.1.1",
+    "next": "^16.3.2",
+    "next-intl": "^4.13.7",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-query-kit": "^3.3.4",
     "recharts": "^3.10.1",
-    "shiki": "^4.4.2",
+    "shiki": "^4.4.3",
     "socket.io-client": "^4.8.3",
-    "sonner": "^2.0.7",
+    "sonner": "^2.0.8",
     "stitchkit": "catalog:",
     "tailwind-merge": "^3.6.0",
     "vaul": "^1.1.2",
@@ -50,10 +50,10 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.3",
-    "@types/bun": "^1.3.14",
-    "@types/node": "^26.2.0",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26.3.0",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
+    "@types/react-dom": "^19.2.5",
     "babel-plugin-react-compiler": "^1.0.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",

package/template/packages/frontend/src/components/ui/toaster.tsx

@@ -38,7 +38,10 @@ export const toast = {
 };
 
 export function Toaster() {
-  const theme = useThemeValue<'light' | 'dark' | 'system'>({
+  // No explicit type argument: since @wrksz/themes 1.2 the parameter describes
+  // the MAP, not the value, and it infers `const` — so naming the value union
+  // here made the result every member of `string` instead of narrowing it.
+  const theme = useThemeValue({
     light: 'light',
     dark: 'dark',
     default: 'system',

package/template/packages/frontend/src/lib/seo/pages.ts

@@ -1,8 +1,8 @@
-import { appDeclaration } from '@app/config/declaration';
+import { appIdentity } from '@app/config/app-identity';
 import { z } from 'zod';
 import type { AppLocale } from '@/i18n/locales';
 
-export const SITE_NAME = appDeclaration.identity.name;
+export const SITE_NAME = appIdentity.name;
 export const StoryIdSchema = z.enum(['components', 'themes', 'blocks']);
 export type StoryId = z.infer<typeof StoryIdSchema>;
 

package/template/packages/shared/package.json

@@ -16,7 +16,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "typescript": "^7.0.2"
   }
 }

package/template/scripts/acceptance-database.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test';
+import { resolveAcceptanceDatabase } from './acceptance-database';
+
+const deployment = 'postgresql://app:secret@127.0.0.1:5432/starter';
+
+describe('the acceptance gate writes only to a database of its own', () => {
+  test('a distinct database is accepted', () => {
+    expect(
+      resolveAcceptanceDatabase({
+        DATABASE_URL: deployment,
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app:secret@127.0.0.1:5432/starter_acceptance',
+      }),
+    ).toBe('postgresql://app:secret@127.0.0.1:5432/starter_acceptance');
+  });
+
+  test('an unset variable is refused with the line to paste', () => {
+    // The gate used to inherit DATABASE_URL. Defaulting to it is exactly the
+    // behaviour this replaces, so absence has to be a refusal, not a fallback.
+    expect(() => resolveAcceptanceDatabase({ DATABASE_URL: deployment })).toThrow(
+      /ACCEPTANCE_DATABASE_URL=postgresql:\/\/app:secret@127\.0\.0\.1:5432\/starter_acceptance/,
+    );
+  });
+
+  test('the same database written differently is still the same database', () => {
+    // Credentials and the scheme do not make it another database; host, port
+    // and name do. A check on the raw string would pass this and then migrate
+    // the deployment.
+    expect(() =>
+      resolveAcceptanceDatabase({
+        DATABASE_URL: deployment,
+        ACCEPTANCE_DATABASE_URL: 'postgres://someone:else@127.0.0.1/starter',
+      }),
+    ).toThrow(/which is the one DATABASE_URL names/);
+  });
+
+  test('a default port on one side and 5432 on the other is one database', () => {
+    expect(() =>
+      resolveAcceptanceDatabase({
+        DATABASE_URL: 'postgresql://app@db.internal/starter',
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app@db.internal:5432/starter',
+      }),
+    ).toThrow(/which is the one DATABASE_URL names/);
+  });
+
+  test('the same name on another hostname is refused, because a hostname proves nothing', () => {
+    // `localhost` and `127.0.0.1` are one server; so are two DNS names for the
+    // same PostgreSQL. A guard that compared `host:port/name` called these two
+    // different databases and let the gate migrate the deployment's own.
+    expect(() =>
+      resolveAcceptanceDatabase({
+        DATABASE_URL: 'postgresql://app@localhost:5432/starter',
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app@127.0.0.1:5432/starter',
+      }),
+    ).toThrow(/A different host is not proof of a different server/);
+  });
+
+  test('a different name on the same host is fine — the name is what decides', () => {
+    // The control. Without it the rule "refuse everything" would pass the case
+    // above, and no acceptance database would ever be accepted.
+    expect(
+      resolveAcceptanceDatabase({
+        DATABASE_URL: 'postgresql://app@localhost:5432/starter',
+        ACCEPTANCE_DATABASE_URL: 'postgresql://app@localhost:5432/starter_acceptance',
+      }),
+    ).toContain('starter_acceptance');
+  });
+
+  test('a value that is not a URL is named, not silently used', () => {
+    expect(() =>
+      resolveAcceptanceDatabase({ ACCEPTANCE_DATABASE_URL: 'starter_acceptance' }),
+    ).toThrow(/ACCEPTANCE_DATABASE_URL is not a valid URL/);
+  });
+});

package/template/scripts/acceptance-database.ts

@@ -0,0 +1,92 @@
+/**
+ * The database the local acceptance gate is allowed to write to.
+ *
+ * `acceptance:local` creates and destroys its own deployment — its own PM2 home,
+ * its own ephemeral ports, its own host allowlist. The database was the one
+ * thing it still borrowed: it inherited `DATABASE_URL`, and the runtime gates
+ * WRITE. The repository example's smoke posts `/api/repository/refresh` twice,
+ * which upserts. So a gate a developer is told to run before handing work off
+ * wrote rows into whatever `.env` happened to name — including a production
+ * database, if that is what the machine was pointed at.
+ *
+ * Fail-closed on purpose. An acceptance database that is merely *probably*
+ * separate is the same defect one edit later, so an unset variable and one that
+ * names the deployment's own database are both refused before a role starts,
+ * and the refusal carries the line to paste.
+ */
+
+/**
+ * The database NAME, which is all a refusal may rely on.
+ *
+ * Comparing `host:port/name` catches the ordinary mistake and misses the ones
+ * that matter: `localhost` and `127.0.0.1` are one server, and so are two DNS
+ * names pointing at the same PostgreSQL. A guard that reads those as different
+ * databases lets this gate migrate and write into the deployment's own.
+ *
+ * A hostname is not proof of a different server, so it does not take part in
+ * the decision. The cost is a false refusal when two genuinely separate servers
+ * host a database of the same name — answered by renaming the throwaway one,
+ * which the message asks for. That is the trade a fail-closed gate is supposed
+ * to make.
+ */
+function databaseName(url: URL): string {
+  return decodeURIComponent(url.pathname.replace(/^\//, '').replace(/\/+$/, ''));
+}
+
+function parse(name: string, value: string): URL {
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`${name} is not a valid URL.`);
+  }
+}
+
+/** `…/app` → `…/app_acceptance`, so the refusal can name a line worth pasting. */
+function suggestionFrom(deploymentUrl: string | undefined): string {
+  if (!deploymentUrl) return 'postgresql://USER:PASSWORD@127.0.0.1:5432/acceptance';
+  try {
+    const url = new URL(deploymentUrl);
+    url.pathname = `${url.pathname.replace(/\/$/, '')}_acceptance`;
+    return url.toString();
+  } catch {
+    return 'postgresql://USER:PASSWORD@127.0.0.1:5432/acceptance';
+  }
+}
+
+/**
+ * The acceptance database URL, or a refusal explaining exactly what to add.
+ *
+ * Takes the environment rather than reading it, so the rule that keeps a gate
+ * off the deployment's database is testable without one.
+ */
+export function resolveAcceptanceDatabase(
+  environment: Record<string, string | undefined>,
+): string {
+  const acceptance = environment.ACCEPTANCE_DATABASE_URL?.trim();
+  const deployment = environment.DATABASE_URL?.trim();
+
+  if (!acceptance) {
+    throw new Error(
+      'ACCEPTANCE_DATABASE_URL is not set, and `bun run acceptance:local` will not write to the ' +
+        'database this deployment uses. Add a line naming a throwaway database to `.env`:\n' +
+        `  ACCEPTANCE_DATABASE_URL=${suggestionFrom(deployment)}`,
+    );
+  }
+
+  const acceptanceUrl = parse('ACCEPTANCE_DATABASE_URL', acceptance);
+  if (deployment) {
+    const deploymentUrl = parse('DATABASE_URL', deployment);
+    if (databaseName(acceptanceUrl) === databaseName(deploymentUrl)) {
+      throw new Error(
+        `ACCEPTANCE_DATABASE_URL uses the database name "${databaseName(acceptanceUrl)}", which is ` +
+          'the one DATABASE_URL names. A different host 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 — and this gate applies migrations and writes rows. Give it a name of ' +
+          'its own:\n' +
+          `  ACCEPTANCE_DATABASE_URL=${suggestionFrom(deployment)}`,
+      );
+    }
+  }
+
+  return acceptanceUrl.toString();
+}