create-stitchkit 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -12,6 +12,62 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.6.1] — 2026-09-20
+
+### Changed
+
+- **The generated frontend carries the canonical React Query runtime shape.**
+  `lib/query-client.ts` owns request-local SSR identity, one browser singleton,
+  pending dehydration, application `staleTime` and the retry policy a released
+  core already lets it state — one retry for queries, none for mutations — with
+  a test that keeps it there. It does not depend on an unreleased Stitchkit
+  export; `UPGRADING.md` records the one-step cutover to
+  `createQueryClientFactory` after the matching core release is available.
+- **The generated workspace now targets Stitchkit `^0.90.5` and current stable
+  dependencies.** Its root and agent lockfiles were regenerated independently while
+  preserving the single `catalog.stitchkit` source and workspace `catalog:` links.
+
+## [0.6.0] — 2026-09-02
+
+The generated project stops being an empty frame with a to-do at the bottom of
+the page. It ships **one vertical feature**, from schema to transport to UI —
+and it was chosen so that every live primitive Stitchkit gained in 0.75–0.76 is
+there because the feature needs it, not to demonstrate anything.
+
+The demonstration is the second browser tab: post from it, and the first one
+updates without asking. Nothing on that page polls, and nothing refetches after
+a write.
+
+### Added
+
+- **A live board.** `board.list` is a watched read and `board.post` writes to it.
+  Together they use, and only where they are needed:
+  - `defineEvents` — one topic, `board.changed`, declared in `shared` because the
+    server announces it and the browser subscribes to it;
+  - `defineKeyspace` / `openKeyspace` over SQLite — notes are authoritative in
+    memory and durable behind it, so a read in a handler needs no `await` and a
+    restart loses nothing;
+  - `createWatchHub` / `createWatchClient` — every browser asking the same
+    question is **one read** on the server, re-run when the topic says the answer
+    may have changed;
+  - `createTrustFence` — installed on **both** lanes when `TRUSTED_HOSTS` is set,
+    because the Socket.IO lane never reaches a lifecycle hook.
+
+  The comments say which of these to reach for and, more usefully, when not to:
+  a keyspace is for a small bounded set the process wants synchronously, and the
+  moment a thing wants queries, relations or unbounded growth it is a database
+  row and Prisma is already there for it.
+
+- **Two environment variables**, both declared in the one place the project
+  declares variables: `BOARD_STORE_PATH` (defaulted, and the directory is created
+  by the application rather than by whoever deploys it) and `TRUSTED_HOSTS`
+  (unset means no fence, which is honest for a laptop and wrong for anything a
+  network can reach — a fence cannot invent the names it should answer to).
+
+### Changed
+
+- The template now targets `stitchkit` `^0.76.1`, up from `^0.71.0`.
+
 ## [0.5.1] — 2026-09-01
 
 Three findings from someone setting up a new application on the starter from

package/UPGRADING.md

@@ -60,6 +60,72 @@ the first scaffolder release with a migration channel of its own.
 
 ---
 
+## Released migration: 0.6.1
+
+### Canonical query client factory
+
+This migration is additive, but it has a dependency order: first upgrade to a
+Stitchkit release that exports `createQueryClientFactory` from
+`stitchkit/react`. Then replace the local QueryClient construction with:
+
+```ts
+import { cache } from 'react';
+import { createQueryClientFactory } from 'stitchkit/react';
+
+export const getQueryClient = createQueryClientFactory({
+  serverCache: cache,
+  queryClient: {
+    defaultOptions: { queries: { staleTime: 30_000 } },
+  },
+});
+```
+
+Keep project-specific mutation toasts or cache configuration in the factory
+options. Do not copy the framework retry predicate back into the application.
+
+## Released migration: 0.6.0
+
+The scaffolder gained a vertical feature. Adopting it in a project you already
+own is optional — nothing breaks if you skip it — but two things are **operator
+steps**, and skipping those with the feature adopted means the API will not
+start.
+
+### 1. The store directory has to be writable
+
+`BOARD_STORE_PATH` defaults to `.data/board.sqlite`, relative to the API role's
+working directory. The application creates the directory itself; what it cannot
+do is make a read-only volume writable.
+
+```bash
+# on the machine, as the user the API runs as
+test -w "$(dirname "${BOARD_STORE_PATH:-.data/board.sqlite}")" || echo "not writable"
+```
+
+If the role runs from a read-only image, point `BOARD_STORE_PATH` at a mounted
+volume instead.
+
+### 2. Decide about the trust fence, on purpose
+
+`TRUSTED_HOSTS` is unset by default, and unset means **no fence**. That is
+correct on a laptop and wrong on anything a network reaches — but a fence cannot
+guess which names your deployment answers to, so it refuses to invent them.
+
+```bash
+# every authority this deployment answers on, comma separated
+TRUSTED_HOSTS=app.internal,app.internal:5181
+```
+
+Set it and the fence is installed on both lanes: HTTP before routing, and the
+realtime handshake, which never reaches a lifecycle hook on either runtime. If
+your browser lives on another origin you already declared it as `CORS_ORIGIN`,
+and the fence reads that one rather than asking you a second time.
+
+### 3. Nothing else
+
+The rest of the feature is code you either copy or do not. The framework range
+moved to `^0.76.1`; if you upgrade the dependency without taking the feature,
+[the framework's own guide](../../docs/guide/upgrading.md) is the one to follow.
+
 ## Released migration: 0.5.0
 
 ### the approval policy names a tool that no longer exists

package/examples/repository/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": "repository",
     "action": "read",

package/examples/repository/packages/backend/src/surface.ts

@@ -1,16 +1,63 @@
 import { env } from '@app/config';
 import { repositoryRealtimeContract } from '@app/shared';
-import { bindRealtimeServer, createSocketIOServer } from 'stitchkit/server';
+import type { TrustFence } from 'stitchkit/server';
+import { bindRealtimeServer, createSocketIOServer, createTrustFence } from 'stitchkit/server';
+import { type BoardRuntime, openBoard } from './lib/board';
+import { bindLive } from './lib/live';
+import { createBoardService } from './transport/board-service';
 import { createRepositoryService } from './transport/repository-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 compares the
+ * authority a request addressed against a list, and it cannot invent the list.
+ * Unset means no fence — honest for a checkout on a laptop, wrong for anything
+ * a network can reach.
+ */
+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();
+
   const socket = await createSocketIOServer({
     cors: { origin: env.CORS_ORIGIN ?? [] },
+    // The socket's own admission point. `/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 }),
   });
+
+  // Two bindings over one socket, deliberately. This example's own contract and
+  // the live one are separate declarations with separate event names, and
+  // merging them into a single registry here would mean editing the merge every
+  // time either side gains a topic.
   const realtime = bindRealtimeServer(repositoryRealtimeContract, socket);
+  const live = bindLive(board, socket);
+
   const repositoryService = createRepositoryService((snapshot) =>
     realtime.emit('repository:refreshed', snapshot),
   );
-  return { socket, services: [createSystemService(), repositoryService] };
+
+  return {
+    socket,
+    fence,
+    board,
+    hub: live.hub,
+    services: [createSystemService(), createBoardService(board), repositoryService],
+  };
 }

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

@@ -4,6 +4,7 @@ import { BrandMark } from '@/components/brand-mark';
 import { RepositorySummary } from '@/components/repository-summary';
 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';
@@ -15,6 +16,7 @@ interface StarterPageProps {
   applicationDescription: string;
   heroTitle: string;
   catalogueLabel: string;
+  realtimeOrigin?: string;
   locale: AppLocale;
 }
 
@@ -62,6 +64,7 @@ export async function StarterPage({
   applicationDescription,
   heroTitle,
   catalogueLabel,
+  realtimeOrigin,
   locale,
 }: StarterPageProps) {
   const homeSeo = getSeoPage('home', locale);
@@ -140,6 +143,10 @@ export async function StarterPage({
               </div>
             </div>
 
+            <div className='mt-6 w-full max-w-xl'>
+              <BoardPanel realtimeOrigin={realtimeOrigin} />
+            </div>
+
             <div className='mt-5 w-full'>
               <RepositorySummary />
             </div>

package/examples/repository/packages/shared/src/index.ts

@@ -1,5 +1,8 @@
+export * from './contracts/board';
+export * from './contracts/live';
 export * from './contracts/repository';
 export * from './contracts/system';
 export * from './realtime/repository';
+export * from './schemas/board';
 export * from './schemas/repository';
 export * from './schemas/system';

package/examples/repository/project.json

@@ -105,6 +105,11 @@
         "shape": "string",
         "required": false
       },
+      {
+        "name": "BOARD_STORE_PATH",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "CORS_ORIGIN",
         "shape": "url",
@@ -179,6 +184,11 @@
         "shape": "url",
         "required": false
       },
+      {
+        "name": "TRUSTED_HOSTS",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "WEB_PORT",
         "shape": "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",
@@ -73,17 +73,17 @@
     "prepublishOnly": "bun run check && bun run test && bun run build"
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@opentui/core": "^0.5.9",
-    "@opentui/react": "^0.5.9",
-    "@openrouter/ai-sdk-provider": "^3.0.0",
-    "@types/bun": "^1.4.0",
-    "@types/react": "^19.2.18",
-    "ai": "^7.0.84",
-    "react": "^19.2.8",
-    "stitchkit": "0.71.0",
+    "@opentui/core": "^0.5.11",
+    "@opentui/react": "^0.5.11",
+    "@openrouter/ai-sdk-provider": "^3.1.0",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
+    "ai": "^7.0.107",
+    "react": "^19.3.0",
+    "stitchkit": "0.90.5",
     "typescript": "^7.0.2"
   },
   "engines": {

package/template/biome.json

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