create-stitchkit 0.5.1 → 0.6.1

package/template/e2e/starter.spec.ts

@@ -26,7 +26,13 @@ test('calls the live backend through the typed contract client', async () => {
     }),
   );
 
-  await expect(client.status()).resolves.toEqual({ status: 'ok' });
+  // The release gate runs several isolated starters in parallel. A process can
+  // pass readiness and still briefly lose the first new connection while the
+  // host is saturated; retry the real typed call, while a dead backend still
+  // fails within the bounded acceptance window.
+  await expect(async () => {
+    await expect(client.status()).resolves.toEqual({ status: 'ok' });
+  }).toPass({ timeout: 5_000 });
 });
 
 test('publishes complete page metadata', async ({ page }) => {

package/template/package.json

@@ -7,7 +7,13 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.71.0"
+    "stitchkit": "^0.90.5"
+  },
+  "overrides": {
+    "@playwright/test": "1.63.0",
+    "playwright": "1.63.0",
+    "playwright-core": "1.63.0",
+    "zod": "4.6.5"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
@@ -37,22 +43,22 @@
     "gen:declaration": "bun scripts/declaration.ts"
   },
   "dependencies": {
-    "dotenv": "^17.4.2"
+    "dotenv": "^18.0.1"
   },
   "devDependencies": {
     "@app/config": "workspace:*",
     "@app/shared": "workspace:*",
     "@axe-core/playwright": "^4.13.0",
-    "@biomejs/biome": "^2.5.11",
+    "@biomejs/biome": "^2.5.14",
     "@modelcontextprotocol/client": "^2.0.0",
-    "@playwright/test": "^1.62.1",
-    "@types/bun": "^1.4.0",
-    "@types/node": "^26.4.0",
-    "oxc-parser": "^0.147.0",
+    "@playwright/test": "^1.63.0",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.2",
+    "oxc-parser": "^0.150.0",
     "socket.io-client": "^4.8.3",
     "stitchkit": "catalog:",
     "typescript": "^7.0.2",
-    "zod": "^4.5.4"
+    "zod": "^4.6.5"
   },
   "engines": {
     "bun": ">=1.2.0",

package/template/packages/backend/package.json

@@ -17,15 +17,15 @@
     "@app/db": "workspace:*",
     "@app/shared": "workspace:*",
     "@modelcontextprotocol/server": "^2.0.0",
-    "@prisma/adapter-pg": "^7.9.1",
-    "@socket.io/bun-engine": "^0.1.1",
-    "ai": "^7.0.78",
+    "@prisma/adapter-pg": "^7.10.0",
+    "@socket.io/bun-engine": "^0.1.2",
+    "ai": "^7.0.107",
     "socket.io": "^4.8.3",
     "stitchkit": "catalog:",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "typescript": "^7.0.2"
   }
 }

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

@@ -3,6 +3,7 @@ import { apiRole, appDeclaration } from '@app/config/declaration';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import {
   bindProcessSignals,
+  composeLifecycleHooks,
   createServer,
   generateOpenApiDocument,
   openApiRoute,
@@ -14,7 +15,7 @@ import { createSurface } from './surface';
 import { onError } from './transport/errors';
 
 async function main(): Promise<void> {
-  const { services, socket } = await createSurface();
+  const { services, socket, fence, board, hub } = await createSurface();
   const mcp = createMcpHandler({
     serverInfo: {
       name: appDeclaration.identity.slug,
@@ -36,7 +37,10 @@ async function main(): Promise<void> {
     port: env.API_PORT,
     hostname: env.BIND_HOST,
     cors: env.CORS_ORIGIN ? { origin: env.CORS_ORIGIN } : undefined,
-    hooks: { onError },
+    // The fence FIRST: hook composition stops at the first hook that answers,
+    // so a fence behind anything that can respond is a fence that sometimes
+    // does not run.
+    hooks: fence ? composeLifecycleHooks(fence.hooks, { onError }) : { onError },
     logging: { format: env.LOG_FORMAT },
     socket,
     rawRoutes: [
@@ -66,6 +70,10 @@ async function main(): Promise<void> {
       // SIGKILL — the one ending that runs no cleanup at all.
       const cleanup = await closeWithinBudget([
         { name: 'MCP', close: () => mcp.close() },
+        // Stops re-reading for browsers that are already gone, then lets the
+        // board finish the writes it accepted and say how many it could not.
+        { name: 'watch hub', close: async () => hub.close() },
+        { name: 'board', close: () => board.close() },
         { name: 'database', close: () => prisma.$disconnect() },
       ]);
       // Say how the drain ended. Without this an operator sees a process that

package/template/packages/backend/src/lib/board.ts

@@ -0,0 +1,99 @@
+import { Database } from 'bun:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { env } from '@app/config';
+import { type Board, boardEvents, type Note, NoteSchema, type PostNote } from '@app/shared';
+import {
+  defineKeyspace,
+  type OpenedKeyspace,
+  openKeyspace,
+  sqliteKeyspaceBackend,
+} from 'stitchkit/application';
+import type { EventPayloads } from 'stitchkit/live';
+import { createEventBus, type EventBus } from 'stitchkit/server';
+
+/**
+ * The board's notes: authoritative in memory, durable behind it.
+ *
+ * A keyspace and not a Prisma model, deliberately, and the boundary is worth
+ * knowing rather than guessing. A keyspace is for a **small, bounded set the
+ * whole process wants synchronously** — read it in a handler without awaiting,
+ * write it and know the write survived. The moment a thing wants queries,
+ * relations, pagination or unbounded growth, it is a database row and this is
+ * the wrong home for it.
+ */
+const notes = defineKeyspace('notes', {
+  schema: NoteSchema,
+  key: (note: Note) => note.id,
+});
+
+/** The board, and the lifecycle its owner drives. */
+export interface BoardRuntime {
+  /** Every announcement this role makes. Subscribed by the watch hub. */
+  readonly events: EventBus<EventPayloads<typeof boardEvents>>;
+  /** Synchronous, from memory. This is what makes a watched read cheap. */
+  read(): Board;
+  post(input: PostNote): Promise<Board>;
+  close(): Promise<void>;
+}
+
+const MOST_RECENT = 50;
+
+export async function openBoard(): Promise<BoardRuntime> {
+  // Closed by the declaration: an undeclared topic is refused rather than
+  // delivered to nobody, and a topic can only be announced by the verb its
+  // declaration chose.
+  const events = createEventBus<EventPayloads<typeof boardEvents>>({
+    topics: boardEvents.topics,
+    onListenerError: (error, event) => {
+      console.error(`Listener for ${event} failed`, error);
+    },
+  });
+
+  // The directory too, not only the file. A starter that requires an operator to
+  // create a folder before it will boot is a starter that fails on the first run
+  // with an error about SQLite rather than about what is missing.
+  mkdirSync(dirname(env.BOARD_STORE_PATH), { recursive: true });
+  const database = new Database(env.BOARD_STORE_PATH, { create: true });
+
+  // Opened directly rather than declared to a kernel, because this role owns
+  // its own lifecycle: it binds its signals and closes what it holds in the
+  // order `cleanup.ts` lists. An application built on `createApplication` would
+  // declare `keyspaceResource(notes, …)` instead and let the graph order it.
+  const opened: OpenedKeyspace<Note> = await openKeyspace(notes, {
+    backend: sqliteKeyspaceBackend(notes, { database }),
+    // After durability and after memory — never before either. A subscriber
+    // woken by this reads immediately, and an announcement that arrived first
+    // would be a wake-up to the previous value.
+    onChanged: (change) => events.emit('board.changed', { noteId: change.key }),
+  });
+
+  function read(): Board {
+    const all = [...opened.keyspace.list()].sort((left, right) =>
+      right.postedAt.localeCompare(left.postedAt),
+    );
+    return { notes: all.slice(0, MOST_RECENT), total: all.length };
+  }
+
+  return {
+    events,
+    read,
+    async post(input) {
+      await opened.keyspace.put({
+        id: crypto.randomUUID(),
+        body: input.body,
+        postedAt: new Date().toISOString(),
+      });
+      // The write resolved, so it is durable and in memory; this read cannot
+      // miss it. The watchers hear about it through the announcement above.
+      return read();
+    },
+    async close() {
+      opened.stopAdmission();
+      await opened.drain();
+      await opened.close();
+      database.close();
+      events.clear();
+    },
+  };
+}

package/template/packages/backend/src/lib/live.ts

@@ -0,0 +1,73 @@
+import { boardContract, liveContract } from '@app/shared';
+import { createWatchHub, type WatchHub } from 'stitchkit/application';
+import { bindRealtimeServer, type RealtimeServerHandle } from 'stitchkit/server';
+import type { BoardRuntime } from './board';
+
+/** What makes the board’s answer stale — the one topic, named once. */
+const INVALIDATED_BY = 'board.changed';
+
+/** A read the browser is allowed to watch. */
+const WATCHABLE = new Set([`${boardContract.meta.prefix}/list`]);
+
+export interface LiveHandle {
+  readonly hub: WatchHub;
+}
+
+export function bindLive(board: BoardRuntime, handle: RealtimeServerHandle): LiveHandle {
+  const realtime = bindRealtimeServer(liveContract, handle, {
+    onRejected: (rejected) => {
+      // A frame that failed its schema is reported where it was refused. Silence
+      // here is how two versions of an application go on talking past each other.
+      console.warn(`Realtime frame refused: ${rejected.event} (${rejected.reason})`);
+    },
+  });
+
+  const hub = createWatchHub({
+    // The hub does not dispatch; it asks the application. One reader for the
+    // watched answer and the plain `GET` alike, so the two cannot disagree.
+    read: async (operation) => {
+      if (operation.action !== 'list') {
+        throw new Error(`${operation.service}.${operation.action} is not readable here`);
+      }
+      return board.read();
+    },
+    watchable: (operation) => WATCHABLE.has(`${operation.service}/${operation.action}`),
+    // The board's list takes no arguments, so its topic is the whole board.
+    // When a read *does* depend on an argument — one conversation of many — the
+    // topic is narrowed with it (`board.changed:${args.id}`), or one change wakes
+    // every watcher of the operation and pays for a read per watcher.
+    invalidatedBy: () => [INVALIDATED_BY],
+    subscribe: (topic, listener) => {
+      // The hub hands back the topics `invalidatedBy` returned, so this is a
+      // narrowing rather than a check — and it refuses rather than quietly
+      // returning a no-op, because an invalidation that silently never fires
+      // is a board that stops updating with nothing to show for it.
+      if (topic !== INVALIDATED_BY) {
+        throw new Error(`The board declares no invalidation topic named ${topic}`);
+      }
+      return board.events.on(topic, listener);
+    },
+    // A browser may watch a handful of questions, not an unbounded number: the
+    // limit is what turns a bug in a page into a refusal instead of a leak.
+    maxWatchesPerSubscriber: 8,
+    // A page that navigates away and back inside the window finds the answer
+    // warm and costs no read.
+    holdMs: 30_000,
+  });
+
+  realtime.onConnection(({ raw, events }) => {
+    const watcher = hub.attach({
+      value: (frame) => events.emit('stitchkit.watch.value', frame),
+      state: (frame) => events.emit('stitchkit.watch.state', frame),
+    });
+    events.on('stitchkit.watch.open', (payload, acknowledge) => {
+      acknowledge(watcher.open(payload.key, payload.args));
+    });
+    events.on('stitchkit.watch.close', (payload) => watcher.close(payload.key));
+    // Every key this connection held is released here. Without it the hub goes
+    // on re-reading for a browser that closed its tab.
+    raw.on('disconnect', () => watcher.detach());
+  });
+
+  return { hub };
+}

package/template/packages/backend/src/surface.snapshot.json

@@ -1,4 +1,36 @@
 [
+  {
+    "service": "board",
+    "action": "list",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
+  {
+    "service": "board",
+    "action": "post",
+    "scope": "public",
+    "hasInput": true,
+    "hasOutput": true,
+    "inputShape": "b1d8eb61c62cafed",
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "POST",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
   {
     "service": "system",
     "action": "status",

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

@@ -1,13 +1,63 @@
 import { env } from '@app/config';
-import { createSocketIOServer } from 'stitchkit/server';
+import { createSocketIOServer, createTrustFence, type TrustFence } from 'stitchkit/server';
+import { type BoardRuntime, openBoard } from './lib/board';
+import { bindLive } from './lib/live';
+import { createBoardService } from './transport/board-service';
 import { createSystemService } from './transport/system-service';
 
+/**
+ * The fence this deployment answers behind, or nothing.
+ *
+ * `trustedHosts` has no default and cannot have one: a fence can compare the
+ * authority a request addressed against a list, and it cannot invent the list.
+ * Unset means no fence, which is honest for a checkout on a laptop and wrong for
+ * anything a network can reach.
+ *
+ * The browser origin is the one already declared for CORS. They answer different
+ * questions — CORS says what a page may *read*, the fence says which authority
+ * this server agreed to *answer on* — but a deployment that names a cross-origin
+ * browser has named it once, and asking twice is asking for two answers that
+ * disagree.
+ */
+function createFence(): TrustFence | undefined {
+  if (!env.TRUSTED_HOSTS) return undefined;
+  const browserOrigin = env.CORS_ORIGIN ? [new URL(env.CORS_ORIGIN).host] : [];
+  return createTrustFence({
+    trustedHosts: env.TRUSTED_HOSTS.split(',').map((entry) => entry.trim()),
+    ...(browserOrigin.length > 0 && { trustedOrigins: browserOrigin }),
+    onRefused: (refusal) => {
+      console.warn(
+        `Refused a ${refusal.lane} request: ${refusal.reason} (host ${refusal.host ?? 'absent'})`,
+      );
+    },
+  });
+}
+
 export async function createSurface() {
+  const board: BoardRuntime = await openBoard();
+  const fence = createFence();
+
   // 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()] };
+  const socket = await createSocketIOServer({
+    cors: { origin: env.CORS_ORIGIN ?? [] },
+    // The socket's own admission point, and the reason the fence has two halves:
+    // `/socket.io/*` never reaches a lifecycle hook on either runtime, so a
+    // fence installed only in `hooks` would leave open the lane this app pushes
+    // its live data over.
+    ...(fence && { allowRequest: fence.allowRequest }),
+  });
+
+  const live = bindLive(board, socket);
+
+  return {
+    socket,
+    fence,
+    board,
+    hub: live.hub,
+    services: [createSystemService(), createBoardService(board)],
+  };
 }

package/template/packages/backend/src/transport/board-service.ts

@@ -0,0 +1,18 @@
+import { type Board, boardContract } from '@app/shared';
+import { implement } from 'stitchkit/server';
+import type { BoardRuntime } from '../lib/board';
+
+/**
+ * The board's two operations.
+ *
+ * Nothing here knows it is watched. `list` is an ordinary handler that reads
+ * memory and returns; the watch hub calls this same implementation when a topic
+ * says the answer may have changed, so a watching browser and a plain `GET` can
+ * never disagree — there is one reader, not two.
+ */
+export function createBoardService(board: BoardRuntime) {
+  return implement(boardContract, {
+    list: (): Board => board.read(),
+    post: ({ input }) => board.post(input),
+  });
+}

package/template/packages/config/package.json

@@ -16,12 +16,12 @@
   },
   "dependencies": {
     "@t3-oss/env-core": "^0.13.11",
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.1",
     "stitchkit": "catalog:",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "typescript": "^7.0.2"
   }
 }

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

@@ -73,6 +73,22 @@ const baseVariables = {
    * requiring an origin there would be requiring knowledge of the place.
    */
   CORS_ORIGIN: z.url().optional(),
+  /**
+   * Where the board keeps its notes. A file, so they survive a restart — which
+   * is the only thing that makes the board worth watching rather than a toy.
+   */
+  BOARD_STORE_PATH: z.string().min(1).default('.data/board.sqlite'),
+  /**
+   * The authorities this API answers on, comma-separated — `host` or
+   * `host:port`.
+   *
+   * Set it and the trust fence is installed on BOTH lanes: HTTP before routing,
+   * and the realtime handshake, which never reaches a lifecycle hook on either
+   * runtime. Unset and there is no fence, which is honest for a local checkout
+   * and wrong for anything reachable from a network — a fence cannot invent the
+   * list of names it should answer to.
+   */
+  TRUSTED_HOSTS: z.string().min(1).optional(),
 };
 
 /**

package/template/packages/db/package.json

@@ -17,13 +17,13 @@
   },
   "dependencies": {
     "@app/config": "workspace:*",
-    "@prisma/adapter-pg": "^7.9.1",
-    "@prisma/client": "^7.9.1",
+    "@prisma/adapter-pg": "^7.10.0",
+    "@prisma/client": "^7.10.0",
     "pg": "^8.23.0"
   },
   "devDependencies": {
     "@types/pg": "^8.23.1",
-    "prisma": "^7.9.1",
+    "prisma": "^7.10.0",
     "typescript": "^7.0.2"
   }
 }

package/template/packages/frontend/package.json

@@ -25,35 +25,35 @@
     "@radix-ui/react-tabs": "^1.1.21",
     "@radix-ui/react-tooltip": "^1.2.16",
     "@t3-oss/env-nextjs": "^0.13.11",
-    "@tabler/icons-react": "^3.46.0",
-    "@tanstack/react-query": "^5.102.3",
-    "@tanstack/react-table": "^9.1.2",
+    "@tabler/icons-react": "^3.47.0",
+    "@tanstack/react-query": "^5.103.1",
+    "@tanstack/react-table": "^9.2.4",
     "@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.1.1",
-    "next": "^16.3.2",
-    "next-intl": "^4.13.7",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "dotenv": "^18.0.1",
+    "framer-motion": "^13.4.0",
+    "next": "^16.3.5",
+    "next-intl": "^4.14.5",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "react-query-kit": "^3.3.4",
     "recharts": "^3.10.1",
     "shiki": "^4.4.3",
     "socket.io-client": "^4.8.3",
     "sonner": "^2.0.8",
     "stitchkit": "catalog:",
-    "tailwind-merge": "^3.6.0",
+    "tailwind-merge": "^3.7.0",
     "vaul": "^1.1.2",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.3",
-    "@types/bun": "^1.4.0",
-    "@types/node": "^26.3.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "babel-plugin-react-compiler": "^1.0.0",
     "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",

package/template/packages/frontend/src/app/[locale]/page.tsx

@@ -1,6 +1,7 @@
 import { appIdentity } from '@app/config/app-identity';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
+import { env } from '@/env';
 import { LocaleSchema } from '@/i18n/locales';
 import { createPageMetadata } from '@/lib/seo/metadata';
 import { StarterPage } from './starter-page';
@@ -28,6 +29,7 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
       heroTitle={t('heroTitle')}
       catalogueLabel={t('ui')}
       locale={appLocale}
+      realtimeOrigin={env.PUBLIC_REALTIME_ORIGIN}
     />
   );
 }

package/template/packages/frontend/src/app/[locale]/starter-page.tsx

@@ -3,6 +3,7 @@ import Image from 'next/image';
 import { BrandMark } from '@/components/brand-mark';
 import { LanguageSwitcher, ThemeToggle } from '@/components/system-controls';
 import { buttonVariants } from '@/components/ui';
+import { BoardPanel } from '@/features/board/board-panel';
 import type { AppLocale } from '@/i18n/locales';
 import { Link } from '@/i18n/navigation';
 import { absoluteSiteUrl } from '@/lib/seo/metadata';
@@ -14,6 +15,7 @@ interface StarterPageProps {
   applicationDescription: string;
   heroTitle: string;
   catalogueLabel: string;
+  realtimeOrigin?: string;
   locale: AppLocale;
 }
 
@@ -61,6 +63,7 @@ export async function StarterPage({
   applicationDescription,
   heroTitle,
   catalogueLabel,
+  realtimeOrigin,
   locale,
 }: StarterPageProps) {
   const homeSeo = getSeoPage('home', locale);
@@ -139,8 +142,13 @@ export async function StarterPage({
               </div>
             </div>
 
+            <div className='mt-6 w-full max-w-xl'>
+              <BoardPanel realtimeOrigin={realtimeOrigin} />
+            </div>
+
             <p className='mt-5 text-sm text-muted-foreground'>
-              Add your first vertical feature from schema to transport and UI.
+              One vertical feature, from schema to transport to UI. Open a second tab and post
+              from it — nothing on this page polls.
             </p>
           </section>
         </div>