create-stitchkit 0.5.1 → 0.6.1

package/template/packages/frontend/src/features/board/board-live.ts

@@ -0,0 +1,91 @@
+'use client';
+
+import { type Board, BoardSchema, boardContract, liveContract } from '@app/shared';
+import { createClient, createRealtimeClient } from 'stitchkit';
+import { createWatchClient, type WatchStateFrame, watchTransport } from 'stitchkit/live';
+
+/**
+ * One socket and one watch client for the life of the tab.
+ *
+ * Kept in a module local rather than in React state, and that is the whole
+ * point: the server shares one read between everyone asking the same question,
+ * and a client per component would defeat that from the other side. A component
+ * that remounts joins the subscription that exists.
+ */
+let shared: ReturnType<typeof connect> | undefined;
+
+/**
+ * Where the socket dials.
+ *
+ * The page's own origin unless a deployment says otherwise, and "otherwise" is
+ * handed down per request rather than compiled in — a `NEXT_PUBLIC_` value is
+ * substituted at build time, which would freeze one deployment's address into
+ * the artifact. `PUBLIC_REALTIME_ORIGIN` exists because a WebSocket upgrade does
+ * not survive a proxying route handler, so the two roles can share an origin for
+ * HTTP and still need to name the socket's.
+ */
+function connect(realtimeOrigin?: string) {
+  const realtime = createRealtimeClient(liveContract, {
+    url: realtimeOrigin ?? window.location.origin,
+  });
+  realtime.connect();
+  return {
+    realtime,
+    // `watchTransport` is the conversion the framework owns: a bound realtime
+    // client's `on` is generic over its contract, and TypeScript will not relate
+    // that to a transport interface. One call, and no cast in this application.
+    watch: createWatchClient(boardContract, {
+      transport: watchTransport(realtime),
+      // A tab that navigates away and back inside the window paints from memory
+      // and costs no read.
+      holdMs: 30_000,
+    }),
+  };
+}
+
+/** The typed HTTP client, for the one operation that writes. */
+export const boardApi = createClient(boardContract, { baseUrl: '/api' });
+
+export interface BoardWatch {
+  close(): void;
+}
+
+/**
+ * Watch the board.
+ *
+ * `onState` is the honest half and is not optional in practice: `opening` means
+ * subscribed and nothing read yet, which is neither healthy nor broken, and
+ * `unavailable` carries the read's own words rather than a flag. A socket that
+ * drops says so here and resumes on its own when it comes back.
+ */
+export function watchBoard(
+  onValue: (board: Board) => void,
+  onState: (state: WatchStateFrame) => void,
+  realtimeOrigin?: string,
+): BoardWatch {
+  shared ??= connect(realtimeOrigin);
+  const handle = shared.watch.list({});
+  const stop = handle.subscribe({
+    value: (value) => {
+      // Parsed at the boundary rather than asserted. A watched read carries the
+      // operation's output, so a value that fails its own schema means this tab
+      // and the server disagree about the contract — a half-finished deploy, or
+      // a cached bundle from before one. That is worth showing; a cast would
+      // render it as though it were fine and fail somewhere unrelated.
+      const parsed = BoardSchema.safeParse(value);
+      if (!parsed.success) {
+        onState({
+          key: { service: boardContract.meta.prefix, action: 'list', digest: '' },
+          phase: 'unavailable',
+          reason: 'source-error',
+          message:
+            'The board arrived in a shape this page does not know — reload to update it.',
+        });
+        return;
+      }
+      onValue(parsed.data);
+    },
+    state: onState,
+  });
+  return { close: stop };
+}

package/template/packages/frontend/src/features/board/board-panel.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import type { Board } from '@app/shared';
+import { useEffect, useState } from 'react';
+import type { WatchStateFrame } from 'stitchkit/live';
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Input,
+  Spinner,
+} from '@/components/ui';
+import { boardApi, watchBoard } from './board-live';
+
+/**
+ * The board, live.
+ *
+ * The demonstration is the second tab: open one, post from the other, and the
+ * note appears without this component asking for it. Nothing here polls, and
+ * nothing here refetches after a write — the server re-reads once, for everyone
+ * watching, and pushes the answer.
+ */
+export function BoardPanel({ realtimeOrigin }: { realtimeOrigin?: string }) {
+  const [board, setBoard] = useState<Board>();
+  const [state, setState] = useState<WatchStateFrame>();
+  const [draft, setDraft] = useState('');
+  const [posting, setPosting] = useState(false);
+
+  useEffect(() => {
+    const watch = watchBoard(setBoard, setState, realtimeOrigin);
+    return () => watch.close();
+  }, [realtimeOrigin]);
+
+  async function post(event: React.FormEvent) {
+    event.preventDefault();
+    const body = draft.trim();
+    if (!body || posting) return;
+    setPosting(true);
+    try {
+      // The write returns the board too, so this tab does not wait for its own
+      // announcement to come back around. Every other tab learns from the push.
+      setBoard(await boardApi.post({ body }));
+      setDraft('');
+    } finally {
+      setPosting(false);
+    }
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Board</CardTitle>
+      </CardHeader>
+      <CardContent className='space-y-4'>
+        <form className='flex gap-2' onSubmit={post}>
+          <Input
+            aria-label='Note'
+            maxLength={140}
+            onChange={(event) => setDraft(event.target.value)}
+            placeholder='Say something, then open a second tab'
+            value={draft}
+          />
+          <Button disabled={posting || draft.trim().length === 0} type='submit'>
+            Post
+          </Button>
+        </form>
+
+        <BoardStatus board={board} state={state} />
+
+        <ul className='space-y-2'>
+          {board?.notes.map((note) => (
+            <li className='rounded-md border px-3 py-2 text-sm' key={note.id}>
+              {note.body}
+            </li>
+          ))}
+        </ul>
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * Three states, not two.
+ *
+ * `opening` is subscribed and nothing read yet — early, not broken — and showing
+ * it as a failure tells a reader something is wrong when the truth is that it
+ * has not arrived. `unavailable` shows the read's own words, because "something
+ * went wrong" is the message that helps nobody.
+ */
+function BoardStatus({ board, state }: { board?: Board; state?: WatchStateFrame }) {
+  if (state?.phase === 'unavailable') {
+    return (
+      <p className='text-destructive text-sm'>
+        Not live: {state.message ?? state.reason ?? 'the server stopped answering'}
+      </p>
+    );
+  }
+  if (!board) {
+    return (
+      <p className='flex items-center gap-2 text-muted-foreground text-sm'>
+        <Spinner /> Waiting for the first read…
+      </p>
+    );
+  }
+  return (
+    <p className='text-muted-foreground text-sm'>
+      {board.total} {board.total === 1 ? 'note' : 'notes'}, live
+    </p>
+  );
+}

package/template/packages/frontend/src/lib/query-client.test.ts

@@ -19,4 +19,10 @@ describe('query dehydration policy', () => {
     expect(shouldDehydrate(successful)).toBe(true);
     expect(shouldDehydrate(pending)).toBe(true);
   });
+
+  test('retries a query once and never retries a mutation', () => {
+    const defaults = getQueryClient().getDefaultOptions();
+    expect(defaults.queries?.retry).toBe(1);
+    expect(defaults.mutations?.retry).toBe(false);
+  });
 });

package/template/packages/frontend/src/lib/query-client.ts

@@ -1,28 +1,36 @@
-import { defaultShouldDehydrateQuery, isServer, QueryClient } from '@tanstack/react-query';
+import {
+  defaultShouldDehydrateQuery,
+  environmentManager,
+  QueryClient,
+  type QueryClientConfig,
+} from '@tanstack/react-query';
 import { cache } from 'react';
 
-function createQueryClient(): QueryClient {
-  return new QueryClient({
-    defaultOptions: {
-      queries: { staleTime: 30_000, retry: 1 },
-      dehydrate: {
-        // `pending` queries dehydrate too: a server component may kick off a
-        // prefetch without awaiting it, and streaming SSR hands the in-flight
-        // promise to the client, which resumes it instead of refetching. The
-        // default predicate would drop exactly those queries and reintroduce
-        // the client-side loading flash.
-        shouldDehydrateQuery: (query) =>
-          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
-      },
+// The template targets the published catalog release, so it cannot import
+// `createQueryClientFactory` yet; the retry policy below is the part of that
+// factory a released core already lets it state. UPGRADING names the cutover.
+const config = {
+  defaultOptions: {
+    // One retry for queries, none for mutations — a mutation retried on a
+    // timeout may run twice; a query only reads.
+    queries: { staleTime: 30_000, retry: 1 },
+    mutations: { retry: false },
+    dehydrate: {
+      shouldDehydrateQuery: (query) =>
+        defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
     },
-  });
+  },
+} satisfies QueryClientConfig;
+
+function createQueryClient(): QueryClient {
+  return new QueryClient(config);
 }
 
 const getServerQueryClient = cache(createQueryClient);
 let browserQueryClient: QueryClient | undefined;
 
 export function getQueryClient(): QueryClient {
-  if (isServer) return getServerQueryClient();
-  if (!browserQueryClient) browserQueryClient = createQueryClient();
+  if (environmentManager.isServer()) return getServerQueryClient();
+  browserQueryClient ??= createQueryClient();
   return browserQueryClient;
 }

package/template/packages/shared/package.json

@@ -13,10 +13,10 @@
   },
   "dependencies": {
     "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/shared/src/contracts/board.ts

@@ -0,0 +1,54 @@
+import { createContractFactory } from 'stitchkit';
+import { defineEvents } from 'stitchkit/live';
+import { BoardChangedSchema, BoardSchema, PostNoteSchema } from '../schemas/board';
+
+const { defineContract } = createContractFactory<'public'>({
+  toolExposure: 'explicit',
+});
+
+/**
+ * The board: read it, add to it.
+ *
+ * Two operations, and the interesting one is `list` — it is a **watched read**.
+ * Nothing about that shows up here, which is the point: a watched read is an
+ * ordinary `GET` that the server happens to re-run when something it depends on
+ * changes. The contract stays the contract, and one caller can fetch it once
+ * while another watches it.
+ */
+export const boardContract = defineContract(
+  { prefix: 'board', scope: 'public' },
+  {
+    list: {
+      method: 'GET',
+      path: '/',
+      desc: 'Read the board',
+      output: BoardSchema,
+      expose: ['HTTP'],
+    },
+    post: {
+      method: 'POST',
+      path: '/',
+      desc: 'Add a note to the board',
+      input: PostNoteSchema,
+      output: BoardSchema,
+      expose: ['HTTP'],
+    },
+  },
+);
+
+/**
+ * What the server announces, declared beside what it can be asked.
+ *
+ * One topic, one payload schema, and a delivery mode — `emit`, because an
+ * announcement that the board changed is an observation and nothing waits on it.
+ * The wire name is the prefixed one, `board.changed`, and it is the only name
+ * this topic has: the short key below is where the full one is built.
+ *
+ * Declared in `shared` for the same reason the contract is: the server publishes
+ * it and the browser subscribes to it, and a topic described twice is a topic
+ * that will be published in one shape and parsed in another.
+ */
+export const boardEvents = defineEvents(
+  { prefix: 'board' },
+  { changed: { schema: BoardChangedSchema, mode: 'emit' } },
+);

package/template/packages/shared/src/contracts/live.ts

@@ -0,0 +1,20 @@
+import { toRealtimeContract, watchContract } from 'stitchkit/live';
+import { boardEvents } from './board';
+
+/**
+ * Everything this application says over its one socket.
+ *
+ * Its own announcements, projected from the same declaration both ends read,
+ * plus the protocol a watched read travels on. Declared in `shared` because the
+ * server binds it and the browser binds it, and a contract described twice is a
+ * contract that will be published in one shape and parsed in another — which is
+ * the failure `defineContract` exists to make impossible for requests and this
+ * makes impossible for announcements.
+ */
+export const liveContract = {
+  serverToClient: {
+    ...toRealtimeContract(boardEvents).serverToClient,
+    ...watchContract.serverToClient,
+  },
+  clientToServer: watchContract.clientToServer,
+};

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

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

package/template/packages/shared/src/schemas/board.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * One note on the board.
+ *
+ * Small on purpose: the board exists to show a value that several browsers
+ * watch at once, and everything about it that is not that gets in the way.
+ */
+export const NoteSchema = z
+  .object({
+    id: z.uuid(),
+    /** Trimmed and bounded here, so the same limit holds for every transport. */
+    body: z.string().trim().min(1).max(140),
+    postedAt: z.iso.datetime({ offset: true }),
+  })
+  .strict();
+export type Note = z.infer<typeof NoteSchema>;
+
+/** What a reader of the board receives — newest first, and how many there are. */
+export const BoardSchema = z
+  .object({
+    notes: z.array(NoteSchema),
+    total: z.number().int().nonnegative(),
+  })
+  .strict();
+export type Board = z.infer<typeof BoardSchema>;
+
+/** What a writer sends. The server owns `id` and `postedAt`; a client cannot set either. */
+export const PostNoteSchema = z.object({ body: NoteSchema.shape.body }).strict();
+export type PostNote = z.infer<typeof PostNoteSchema>;
+
+/**
+ * The payload of the announcement that the board changed.
+ *
+ * It carries the note's id rather than the note. An announcement says *that*
+ * something changed; the value comes from the read, which is the one place that
+ * decides what a reader is allowed to see. A payload that carried the row would
+ * be a second, unauthorised copy of the answer.
+ */
+export const BoardChangedSchema = z.object({ noteId: NoteSchema.shape.id }).strict();
+export type BoardChanged = z.infer<typeof BoardChangedSchema>;

package/template/project.json

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

package/templates/agent/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": ["**", "!!node_modules", "!!dist", "!!project.json", "!!**/.stitchkit"]
   },

package/templates/agent/package.json

@@ -16,16 +16,16 @@
     "build": "bun build src/index.ts --outdir dist --target bun --packages external"
   },
   "dependencies": {
-    "@openrouter/ai-sdk-provider": "^3.0.0",
-    "ai": "^7.0.87",
+    "@openrouter/ai-sdk-provider": "^3.1.0",
+    "ai": "^7.0.107",
     "stitchkit": "file:../../../core",
     "stitchkit-tui": "file:../../../tui",
-    "zod": "4.5.4"
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "@types/bun": "^1.4.0",
-    "@types/react": "^19.2.14",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
     "typescript": "^7.0.2"
   },
   "engines": {