create-stitchkit 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -6,6 +6,38 @@ is declared in the template root catalog.
 
 ## [Unreleased]
 
+## [0.3.2] — 2026-08-17
+
+### Changed
+
+- **The template targets Stitchkit 0.50.0 and binds process signals through the
+  framework.** Generated backends replace the hand-written shutdown coordinator
+  with `bindProcessSignals(server, …)`: MCP and Prisma close in `onComplete`, the
+  exit code is set there, and failures are reported by phase. The manual version
+  the template used to ship reported a failing `mcp.close()` as a failed
+  shutdown, did nothing on a third signal, and collapsed the grace period when a
+  supervisor delivered two signals at once.
+- **The repository example declares its domain error message once.**
+  `GITHUB_UNAVAILABLE` carries its text in the `defineErrors` definition instead
+  of repeating it at the throw site.
+
+## [0.3.1] — 2026-08-15
+
+### Changed
+
+- **The template targets Stitchkit 0.49.2 and owns one managed server lifecycle.**
+  Generated backends pass the full Socket.IO handle to `createServer()`, close
+  through `server.shutdown()`, and use a repeated process signal to force the
+  same shutdown chain instead of creating a competing close path.
+
+### Fixed
+
+- **Repository refresh and realtime verification are deterministic.** A successful
+  refresh updates the initiating browser from its typed mutation result, remote
+  browsers still update through the Socket.IO cache bridge, and the release lane
+  exercises the complete backend path against a local GitHub-compatible upstream
+  instead of depending on public API availability.
+
 ## [0.3.0] — 2026-08-10
 
 ### ⚠️ Breaking changes

package/examples/repository/_env.example.append

@@ -1,4 +1,6 @@
 GITHUB_REPOSITORY=max-listov/stitchkit
 GITHUB_CACHE_TTL_SECONDS=900
+# Optional. Defaults to the public GitHub API and supports GitHub Enterprise.
+# GITHUB_API_URL=https://api.github.com
 # Optional. Authenticated conditional requests have a higher GitHub rate limit.
 # GITHUB_TOKEN=github_pat_...

package/examples/repository/e2e/repository.spec.ts

@@ -1,4 +1,25 @@
-import { expect, test } from '@playwright/test';
+import { expect, type Page, test } from '@playwright/test';
+
+async function gotoWithRealtime(page: Page): Promise<void> {
+  const connected = page
+    .waitForEvent('websocket', {
+      predicate: (socket) => socket.url().includes('/socket.io/'),
+    })
+    .then((socket) =>
+      socket.waitForEvent('framereceived', {
+        predicate: ({ payload }) => typeof payload === 'string' && payload.startsWith('40'),
+      }),
+    );
+  await page.goto('/en');
+  await connected;
+}
+
+async function expectRepositorySummary(page: Page): Promise<void> {
+  const summary = page.getByTestId('repository-summary');
+  await expect(summary).toHaveCount(1);
+  await expect(summary).toBeVisible();
+  await expect(summary.getByText('max-listov/stitchkit', { exact: true })).toBeVisible();
+}
 
 test('prefetched data hydrates without a loading flash or a client refetch', async ({
   page,
@@ -21,22 +42,23 @@ test('prefetched data hydrates without a loading flash or a client refetch', asy
     await route.continue();
   });
   await page.goto('/en');
-  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
+  await expectRepositorySummary(page);
   expect(clientReads).toBe(0);
 });
 
 test('a server realtime event updates the TanStack cache without a client refetch', async ({
+  context,
   page,
 }) => {
-  await page.goto('/en');
+  await gotoWithRealtime(page);
   const summary = page.getByTestId('repository-summary');
   await expect(summary).toBeVisible();
   const before = await summary.getAttribute('data-fetched-at');
   expect(before).not.toBeNull();
 
-  // Sever the refetch path completely: the refresh mutation invalidates the
-  // query, but its refetch is aborted here — so the ONLY way the summary can
-  // carry a new snapshot is the Socket.IO event through the cache bridge.
+  // Sever the observer's HTTP read path completely, then refresh from a second
+  // tab. The observer never invokes the mutation and cannot consume its HTTP
+  // result, so only the Socket.IO event can update its TanStack cache.
   await page.route('**/api/repository', async (route) => {
     if (route.request().method() === 'GET') {
       await route.abort();
@@ -44,7 +66,9 @@ test('a server realtime event updates the TanStack cache without a client refetc
     }
     await route.continue();
   });
-  await page.getByRole('button', { name: 'Refresh repository data' }).click();
+  const trigger = await context.newPage();
+  await trigger.goto('/en');
+  await trigger.getByRole('button', { name: 'Refresh repository data' }).click();
   await expect(summary).not.toHaveAttribute('data-fetched-at', before ?? '', {
     timeout: 10_000,
   });
@@ -56,7 +80,7 @@ test('renders and refreshes the repository example', async ({ page }) => {
     await route.continue();
   });
   await page.goto('/en');
-  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
+  await expectRepositorySummary(page);
 
   const refresh = page.getByRole('button', { name: 'Refresh repository data' });
   await expect(refresh).toHaveCSS('height', '32px');

package/examples/repository/packages/backend/src/domain/errors.ts

@@ -4,6 +4,8 @@ import { z } from 'zod';
 export const { errors: domainErrors, codes: domainErrorCodes } = defineErrors({
   GITHUB_UNAVAILABLE: {
     status: 503,
+    // Declared once here instead of at every throw site.
+    message: 'GitHub repository data is temporarily unavailable',
     details: z.object({ cause: z.string() }),
   },
 });

package/examples/repository/packages/backend/src/domain/repository/github-cache.ts

@@ -155,12 +155,12 @@ export class GitHubRepositoryCache {
 
     try {
       const [repositoryResponse, commitsResponse] = await Promise.all([
-        this.fetcher(new URL(`/repos/${repositoryName}`, 'https://api.github.com'), {
+        this.fetcher(new URL(`/repos/${repositoryName}`, env.GITHUB_API_URL), {
           headers: githubHeaders(),
           signal: AbortSignal.timeout(8_000),
         }),
         this.fetcher(
-          new URL(`/repos/${repositoryName}/commits?per_page=1`, 'https://api.github.com'),
+          new URL(`/repos/${repositoryName}/commits?per_page=1`, env.GITHUB_API_URL),
           { headers: githubHeaders(), signal: AbortSignal.timeout(8_000) },
         ),
       ]);
@@ -197,7 +197,6 @@ export class GitHubRepositoryCache {
     } catch (error) {
       if (previous) return serialize(previous, 'stale');
       throw domainErrors.GITHUB_UNAVAILABLE({
-        message: 'GitHub repository data is temporarily unavailable',
         details: { cause: error instanceof Error ? error.message : 'Unknown upstream error' },
         hint: 'Retry after the upstream service recovers',
       });

package/examples/repository/packages/config/src/features.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 export const featureServerSchema = {
+  GITHUB_API_URL: z.url().default('https://api.github.com'),
   GITHUB_REPOSITORY: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
   GITHUB_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(900),
   GITHUB_TOKEN: z.string().min(1).optional(),

package/examples/repository/packages/frontend/src/components/repository-summary.tsx

@@ -30,8 +30,8 @@ export function RepositorySummary() {
   const queryClient = useQueryClient();
   const repository = useRepository();
   const refresh = useRefreshRepository({
-    onSuccess: async () => {
-      await queryClient.invalidateQueries({ queryKey: useRepository.getKey() });
+    onSuccess: (snapshot) => {
+      queryClient.setQueryData(useRepository.getKey(), snapshot);
     },
   });
 

package/examples/repository/scripts/runtime-smoke.ts

@@ -3,6 +3,7 @@ import { createRealtimeClient, defineRealtimeContract } from 'stitchkit';
 import { z } from 'zod';
 import { defineSurfaceProbe, runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
+import { assertPublicWebSurface } from './web-surface-smoke';
 
 const toolingEnv = loadToolingEnv();
 const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
@@ -166,4 +167,6 @@ await runSurfaceConformance({
   }
 }
 
-console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');
+await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
+
+console.log('Runtime HTTP, OpenAPI, Socket.IO, MCP and public web smoke passed');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",

package/template/bun.lock

@@ -138,7 +138,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.46.0",
+    "stitchkit": "^0.50.0",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.46", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.25", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-LIAO6kAG8fpXQb9L0iwPk1FIbXftvqnyC56v5NEAzeWTeL8fUsy/Hx86VPBTWEDFdwbVprjWifJOAqS6AOj3mA=="],
@@ -1117,7 +1117,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.46.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-vHFaXHp5Ws4sFSRptqPqwpc7CGEEbmHY+duvvGkNGwuyp51aY4De3bXVh1xiZSGiUN5IS0jhj1P59GG3VjP/Ag=="],
+    "stitchkit": ["stitchkit@0.50.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-lMadqgQ9aryAhULyA0biVjx9bn86HOUhcUj809TyHy2MuUZSnL9qI4fiByQbVAqlxW6i1a1RLAeguEJeu6jwWg=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 

package/template/e2e/starter.spec.ts

@@ -29,10 +29,7 @@ test('calls the live backend through the typed contract client', async () => {
   await expect(client.status()).resolves.toEqual({ status: 'ok' });
 });
 
-test('publishes complete page metadata and a reachable Open Graph card', async ({
-  page,
-  request,
-}) => {
+test('publishes complete page metadata', async ({ page }) => {
   await page.goto('/en/ui/themes');
   await expect(page).toHaveTitle(`Theme system · ${appIdentity.name}`);
   await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
@@ -45,15 +42,9 @@ test('publishes complete page metadata and a reachable Open Graph card', async (
   );
 
   const imageUrl = await page.locator('meta[property="og:image"]').getAttribute('content');
-  expect(imageUrl).not.toBeNull();
-  if (!imageUrl) throw new Error('Open Graph image URL is missing');
-  const imageResponse = await request.get(imageUrl);
-  expect(imageResponse.status()).toBe(200);
-  expect(imageResponse.headers()['content-type']).toContain('image/png');
-
-  const sitemapResponse = await request.get('/sitemap.xml');
-  expect(sitemapResponse.status()).toBe(200);
-  expect(await sitemapResponse.text()).toContain('/ru/ui/themes');
+  expect(imageUrl).toBe(
+    new URL('/api/og/en/themes', toolingEnv.NEXT_PUBLIC_WEB_URL).toString(),
+  );
 });
 
 test('switches catalogue sections and component tabs', async ({ page }) => {

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.46.0"
+    "stitchkit": "^0.50.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",

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

@@ -9,5 +9,5 @@ const { services, socket } = await createSurface();
 try {
   await createCli({ name: appIdentity.slug, version: appIdentity.version, services });
 } finally {
-  await socket.io.close();
+  await socket.close();
 }

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

@@ -1,7 +1,12 @@
 import { env } from '@app/config';
 import { appIdentity } from '@app/config/identity';
 import { wrapInRequestContext } from 'stitchkit/observability';
-import { createServer, generateOpenApiDocument, openApiRoute } from 'stitchkit/server';
+import {
+  bindProcessSignals,
+  createServer,
+  generateOpenApiDocument,
+  openApiRoute,
+} from 'stitchkit/server';
 import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools';
 import { prisma } from './lib/db';
 import { createSurface } from './surface';
@@ -26,9 +31,8 @@ async function main(): Promise<void> {
     cors: { origin: env.CORS_ORIGIN },
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
-    websocket: socket.websocket,
+    socket,
     rawRoutes: [
-      socket.route,
       openApiRoute('/openapi.json', openApi),
       createMcpHttpRoute({ path: '/mcp', handler: mcp }),
       {
@@ -40,15 +44,22 @@ async function main(): Promise<void> {
     wrapFetch: (fetch) => wrapInRequestContext(fetch),
   });
 
-  async function shutdown(): Promise<void> {
-    server.stop();
-    await mcp.close();
-    await socket.io.close();
-    await prisma.$disconnect();
-  }
+  // The server owns HTTP and Socket.IO; MCP, Prisma and the exit code are the
+  // 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 },
+    onComplete: async (result) => {
+      await mcp.close();
+      await prisma.$disconnect();
+      process.exitCode = result.outcome === 'clean' ? 0 : 1;
+    },
+    onError: (phase, error) => {
+      console.error(`Shutdown failed during ${phase}`, error);
+      process.exitCode = 1;
+    },
+  });
 
-  process.once('SIGTERM', shutdown);
-  process.once('SIGINT', shutdown);
   console.log(`API listening on http://127.0.0.1:${env.API_PORT}`);
 }
 

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

@@ -20,5 +20,5 @@ try {
     ),
   );
 } finally {
-  await socket.io.close();
+  await socket.close();
 }

package/template/scripts/runtime-smoke.ts

@@ -3,8 +3,10 @@ import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
 import { runSurfaceConformance } from './surface-conformance';
 import { loadToolingEnv } from './tooling-env';
+import { assertPublicWebSurface } from './web-surface-smoke';
 
-const apiOrigin = loadToolingEnv().NEXT_PUBLIC_API_URL;
+const toolingEnv = loadToolingEnv();
+const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
 
 async function json(path: string): Promise<unknown> {
   const response = await fetch(`${apiOrigin}${path}`);
@@ -26,5 +28,6 @@ if (!Object.keys(openApi.paths).includes('/api/system/status')) {
 }
 
 await runSurfaceConformance({ apiOrigin });
+await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
 
-console.log('Runtime HTTP, typed client, OpenAPI and MCP smoke passed');
+console.log('Runtime HTTP, typed client, OpenAPI, MCP and public web smoke passed');

package/template/scripts/surface-conformance.ts

@@ -134,7 +134,7 @@ export async function runSurfaceConformance({
       }
     }
   } finally {
-    await socket.io.close();
+    await socket.close();
   }
 }
 

package/template/scripts/surface-snapshot.ts

@@ -17,5 +17,5 @@ try {
   await writeFile(target, `${JSON.stringify(manifest, null, 2)}\n`);
   console.log(`Wrote ${manifest.length} operation(s) to ${SURFACE_SNAPSHOT_PATH}`);
 } finally {
-  await socket.io.close();
+  await socket.close();
 }

package/template/scripts/web-surface-smoke.ts

@@ -0,0 +1,28 @@
+const OG_IMAGE_PATH = '/api/og/en/themes';
+const SITEMAP_PATH = '/sitemap.xml';
+
+function publicUrl(origin: string, path: string): URL {
+  return new URL(path, new URL(origin).origin);
+}
+
+export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
+  const image = await fetch(publicUrl(webOrigin, OG_IMAGE_PATH));
+  if (image.status !== 200) {
+    throw new Error(`GET ${OG_IMAGE_PATH} returned ${image.status}`);
+  }
+  const imageType = image.headers.get('content-type');
+  if (!imageType?.toLowerCase().startsWith('image/png')) {
+    throw new Error(`GET ${OG_IMAGE_PATH} returned ${imageType ?? 'no content type'}`);
+  }
+  if ((await image.arrayBuffer()).byteLength === 0) {
+    throw new Error(`GET ${OG_IMAGE_PATH} returned an empty image`);
+  }
+
+  const sitemap = await fetch(publicUrl(webOrigin, SITEMAP_PATH));
+  if (sitemap.status !== 200) {
+    throw new Error(`GET ${SITEMAP_PATH} returned ${sitemap.status}`);
+  }
+  if (!(await sitemap.text()).includes('/ru/ui/themes')) {
+    throw new Error(`GET ${SITEMAP_PATH} omitted the localized theme-system URL`);
+  }
+}