create-stitchkit 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ is declared in the template root catalog.
 
 ## [Unreleased]
 
+## [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/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) },
         ),
       ]);

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.1",
   "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.49.2",
   },
   "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.49.2", "", { "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-QP0I//fs/khC+bTqYungjpZskAseQAB/Lm8UOx3mZDx+rmYtdsBhlAn0I0hBYE/du9jag5rE032s9HrZgT2VXg=="],
 
     "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.49.2"
   },
   "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

@@ -26,9 +26,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 +39,33 @@ 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();
+  const shutdownController = new AbortController();
+  let shutdownPromise: Promise<void> | undefined;
+
+  function shutdown(): Promise<void> {
+    if (shutdownPromise) {
+      shutdownController.abort();
+      return shutdownPromise;
+    }
+
+    shutdownPromise = (async () => {
+      await server.shutdown({
+        gracePeriodMs: 30_000,
+        signal: shutdownController.signal,
+      });
+      await mcp.close();
+      await prisma.$disconnect();
+    })();
+    return shutdownPromise;
   }
 
-  process.once('SIGTERM', shutdown);
-  process.once('SIGINT', shutdown);
+  const onSignal = () =>
+    void shutdown().catch((error: unknown) => {
+      console.error('Shutdown failed', error);
+    });
+
+  process.on('SIGTERM', onSignal);
+  process.on('SIGINT', onSignal);
   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`);
+  }
+}