create-stitchkit 0.1.1 → 0.3.0

package/template/docs/ADDING_A_FEATURE.md

@@ -0,0 +1,102 @@
+# Adding a vertical feature
+
+This guide uses a small `status` resource to show the canonical path. The blank
+scaffold starts with only its HTTP readiness endpoint and no application or tool
+surface. In `--example repository` mode, keep the repository slice and add the
+same files beside it.
+
+## 1. Define the wire data
+
+Create `packages/shared/src/schemas/status.ts`:
+
+```ts
+import { z } from 'zod'
+
+export const StatusSchema = z.object({ message: z.string().min(1) })
+export const UpdateStatusInputSchema = StatusSchema
+export type Status = z.infer<typeof StatusSchema>
+```
+
+Export it from the shared package. Do not introduce a second handwritten DTO.
+
+## 2. Define the HTTP/tool contract separately
+
+Create `packages/shared/src/contracts/status.ts` and import the named schemas:
+
+```ts
+import { defineContract } from 'stitchkit'
+import { StatusSchema, UpdateStatusInputSchema } from '../schemas/status'
+
+export const statusContract = defineContract(
+  { prefix: 'status', scope: 'public' },
+  {
+    read: { method: 'GET', path: '/', desc: 'Read status', output: StatusSchema },
+    update: {
+      method: 'PUT', path: '/', desc: 'Update status',
+      input: UpdateStatusInputSchema, output: StatusSchema,
+      expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+    },
+  },
+)
+```
+
+The contract owns transport identity. Do not add a raw route or duplicate path.
+
+## 3. Implement and register the service
+
+Create `packages/backend/src/transport/status-service.ts` with `implement()`.
+Keep persistence and business rules in a domain/service module; the contract
+handler calls that module once. Add the returned service to the `services` array
+in `packages/backend/src/surface.ts`. That one registration drives HTTP,
+OpenAPI, MCP, agent tools and CLI discovery.
+
+## 4. Add typed browser access
+
+Export `statusContract` from `packages/shared/src/index.ts`. In
+`packages/frontend/src/lib/api/client.ts`, create `statusApi` with the same
+`createClient(statusContract, http)` pattern used by the application's other
+contracts. Create the query key and react-query-kit query/mutation hooks in
+`packages/frontend/src/lib/api/status.ts`. On mutation success, update or
+invalidate that canonical key.
+
+Render the hook from a feature component. Pages compose features; they do not
+call `fetch`, construct `/api/status` or decode error bodies themselves.
+
+## 5. Add realtime only when another client must observe the change
+
+Declare the event in the shared realtime source and use a named Zod schema for
+its tuple. The server emits after the domain change succeeds; the frontend cache
+bridge reacts by updating or invalidating the status query. Keep handshake auth,
+authorization and room membership in the application. Socket.IO delivery,
+reconnection, retained subscriptions and validation belong to Stitchkit.
+
+The starter advances its single `catalog.stitchkit` target only after the
+required framework release exists. Do not copy a framework adapter into the
+application or maintain a parallel event-map API.
+
+## 6. Prove the surface and behavior
+
+Generic smoke already derives expected HTTP operations and MCP tool names from
+the registered services and compares them with live OpenAPI/MCP discovery. Add
+an explicit probe only for handler behavior:
+
+```ts
+defineSurfaceProbe({
+  name: 'status update lifecycle',
+  input: UpdateStatusInputSchema,
+  fixture: { message: 'Ready' },
+  output: StatusSchema,
+  run: (input) => statusClient.update(input),
+})
+```
+
+Add domain tests beside domain code, contract/schema tests in shared, and UI E2E
+only for user-visible behavior. Finish with the commands in root `AGENTS.md`.
+
+## Ownership boundary
+
+Application-owned: domain policy, persistence, auth decisions, rooms, cache
+semantics and presentation. Framework-owned: contract routing, validation,
+normalized errors, transport lifecycle, tool discovery and Socket.IO wrappers.
+When the framework-owned layer is missing a generic capability, fix Stitchkit
+and upgrade this application's one catalog target after that release exists.

package/template/e2e/starter.spec.ts

@@ -1,23 +1,40 @@
+import { appIdentity } from '@app/config/identity';
+import { systemContract } from '@app/shared';
 import AxeBuilder from '@axe-core/playwright';
 import { expect, test } from '@playwright/test';
+import { createClient, createHttpClient } from 'stitchkit';
+import { loadToolingEnv } from '../scripts/tooling-env';
+
+const toolingEnv = loadToolingEnv();
 
 test('renders the hydrated starter application and catalogue', async ({ page }) => {
   await page.goto('/en');
   await expect(page.getByRole('heading', { level: 1 })).toContainText(
     'Build the product, not the plumbing',
   );
-  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
   await page.getByRole('link', { name: /UI system/ }).click();
   await expect(page).toHaveURL(/\/en\/ui\/components$/);
   await expect(page.getByRole('heading', { level: 1 })).toContainText('UI components');
 });
 
+test('calls the live backend through the typed contract client', async () => {
+  const client = createClient(
+    systemContract,
+    createHttpClient({
+      baseUrl: `${toolingEnv.NEXT_PUBLIC_API_URL}/api`,
+      credentials: 'omit',
+    }),
+  );
+
+  await expect(client.status()).resolves.toEqual({ status: 'ok' });
+});
+
 test('publishes complete page metadata and a reachable Open Graph card', async ({
   page,
   request,
 }) => {
   await page.goto('/en/ui/themes');
-  await expect(page).toHaveTitle('Theme system · Stitchkit Starter');
+  await expect(page).toHaveTitle(`Theme system · ${appIdentity.name}`);
   await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
     'href',
     /\/en\/ui\/themes$/,
@@ -39,23 +56,6 @@ test('publishes complete page metadata and a reachable Open Graph card', async (
   expect(await sitemapResponse.text()).toContain('/ru/ui/themes');
 });
 
-test('spins the refresh icon in place while its action is pending', async ({ page }) => {
-  await page.route('**/api/repository/refresh', async (route) => {
-    await new Promise((resolve) => setTimeout(resolve, 750));
-    await route.continue();
-  });
-  await page.goto('/en');
-
-  const refresh = page.getByRole('button', { name: 'Refresh repository data' });
-  await expect(refresh).toHaveCSS('height', '32px');
-  await expect(refresh).toHaveCSS('width', '32px');
-  await expect(refresh.locator('.tabler-icon-refresh')).toHaveCount(1);
-  await refresh.click();
-  await expect(refresh).toHaveAttribute('aria-busy', 'true');
-  await expect(refresh.locator('svg')).toHaveCount(1);
-  await expect(refresh.locator('.tabler-icon-refresh')).toHaveClass(/animate-spin/);
-});
-
 test('switches catalogue sections and component tabs', async ({ page }) => {
   await page.goto('/en/ui');
   await expect(page).toHaveURL(/\/en\/ui\/components$/);
@@ -176,7 +176,11 @@ test('keeps long localized navigation labels inside the mobile drawer', async ({
   expect(overflow.page).toBeLessThanOrEqual(1);
 });
 
-test('provides a server-first synchronized theme system', async ({ context, page }) => {
+test('provides a server-first synchronized theme system', async ({
+  browserName,
+  context,
+  page,
+}) => {
   const consoleProblems: string[] = [];
   page.on('console', (message) => {
     if (message.type() === 'error' || message.type() === 'warning') {
@@ -210,17 +214,25 @@ test('provides a server-first synchronized theme system', async ({ context, page
   const secondPage = await context.newPage();
   await secondPage.goto('/en/ui/themes');
   await expect(secondPage.locator('html')).toHaveClass(/dark/);
+  await expect(secondPage.getByTestId('theme-state-selected')).not.toContainText('hydrating');
+  await page.emulateMedia({ reducedMotion: 'reduce' });
   await page.getByRole('button', { name: 'Light', exact: true }).click();
+  if (browserName === 'webkit') {
+    // Playwright WebKit shares localStorage but does not dispatch cross-page storage events.
+    await secondPage.reload();
+  }
   await expect(secondPage.locator('html')).toHaveClass(/light/);
 
   await page.getByRole('button', { name: 'System', exact: true }).click();
   await expect(page.getByTestId('theme-state-selected')).toContainText('system');
   const themeCookie = (await context.cookies()).find(
-    (cookie) => cookie.name === 'stitchkit-starter-theme',
+    (cookie) => cookie.name === `${appIdentity.slug}-theme`,
   );
   expect(themeCookie?.value).toBe('system');
   await page.reload();
-  await expect(page.getByTestId('theme-state-server-cookie')).toContainText('system');
+  const serverCookieState = page.getByTestId('theme-state-server-cookie');
+  await expect(serverCookieState).toHaveCount(1);
+  await expect(serverCookieState).toContainText('system');
   expect(
     consoleProblems.filter((message) =>
       /hydration|useServerInsertedHTML|inline script/i.test(message),

package/template/ecosystem.config.cjs

@@ -1,12 +1,13 @@
 const path = require('node:path');
 const { config } = require('dotenv');
+const identity = require('./app.config.json');
 
 config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
 
 module.exports = {
   apps: [
     {
-      name: 'stitchkit-starter-backend',
+      name: `${identity.slug}-backend`,
       cwd: path.join(__dirname, 'packages/backend'),
       script: 'dist/index.js',
       interpreter: 'bun',
@@ -15,7 +16,7 @@ module.exports = {
       env: { NODE_ENV: 'production' },
     },
     {
-      name: 'stitchkit-starter-frontend',
+      name: `${identity.slug}-frontend`,
       cwd: path.join(__dirname, 'packages/frontend'),
       script: 'node_modules/.bin/next',
       args: ['start', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],

package/template/ecosystem.dev.config.cjs

@@ -1,12 +1,15 @@
 const path = require('node:path');
 const { config } = require('dotenv');
+const identity = require('./app.config.json');
 
-config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
+config({ path: path.join(__dirname, '.env'), quiet: true });
+
+const frontendArgs = ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'];
 
 module.exports = {
   apps: [
     {
-      name: 'stitchkit-starter-backend-dev',
+      name: `${identity.slug}-backend-dev`,
       cwd: path.join(__dirname, 'packages/backend'),
       script: 'src/index.ts',
       interpreter: 'bun',
@@ -16,10 +19,10 @@ module.exports = {
       env: { NODE_ENV: 'development' },
     },
     {
-      name: 'stitchkit-starter-frontend-dev',
+      name: `${identity.slug}-frontend-dev`,
       cwd: path.join(__dirname, 'packages/frontend'),
       script: 'node_modules/.bin/next',
-      args: ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],
+      args: frontendArgs,
       interpreter: 'bun',
       autorestart: true,
       kill_timeout: 10000,

package/template/package.json

@@ -7,11 +7,11 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.44.0"
+    "stitchkit": "^0.46.0"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",
-    "check": "bun run db:generate && bun run check:authored && bun run --filter '*' check",
+    "check": "bun run db:generate && bun run check:authored && bun x tsc -p tsconfig.json --noEmit && bun run --filter '*' check",
     "check:authored": "bun scripts/check-authored.ts",
     "test": "bun run --filter '*' test",
     "build": "bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
@@ -26,6 +26,7 @@
     "cli": "bun packages/backend/src/cli.ts",
     "tools": "bun packages/backend/src/tools.ts",
     "runtime:smoke": "bun scripts/runtime-smoke.ts",
+    "surface:snapshot": "bun scripts/surface-snapshot.ts",
     "e2e": "playwright test",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
@@ -36,14 +37,17 @@
     "dotenv": "^17.4.2"
   },
   "devDependencies": {
+    "@app/config": "workspace:*",
     "@app/shared": "workspace:*",
     "@axe-core/playwright": "^4.11.0",
     "@biomejs/biome": "^2.5.7",
     "@modelcontextprotocol/client": "^2.0.0",
     "@playwright/test": "^1.55.0",
     "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0",
     "oxc-parser": "^0.143.0",
     "socket.io-client": "^4.8.3",
+    "stitchkit": "catalog:",
     "typescript": "^7.0.2",
     "zod": "^4.4.3"
   },

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

@@ -1,12 +1,13 @@
 #!/usr/bin/env bun
 
+import { appIdentity } from '@app/config/identity';
 import { createCli } from 'stitchkit/cli';
 import { createSurface } from './surface';
 
 const { services, socket } = await createSurface();
 
 try {
-  await createCli({ name: 'stitchkit-starter', version: '0.1.0', services });
+  await createCli({ name: appIdentity.slug, version: appIdentity.version, services });
 } finally {
   await socket.io.close();
 }

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

@@ -1,4 +1,5 @@
 import { env } from '@app/config';
+import { appIdentity } from '@app/config/identity';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import { createServer, generateOpenApiDocument, openApiRoute } from 'stitchkit/server';
 import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools';
@@ -9,12 +10,12 @@ import { onError } from './transport/errors';
 async function main(): Promise<void> {
   const { services, socket } = await createSurface();
   const mcp = createMcpHandler({
-    serverInfo: { name: 'stitchkit-starter', version: '0.1.0' },
+    serverInfo: { name: appIdentity.slug, version: appIdentity.version },
     auth: () => ({ scope: 'public' }),
     services,
   });
   const openApi = generateOpenApiDocument({
-    info: { title: 'Stitchkit Starter API', version: '0.1.0' },
+    info: { title: `${appIdentity.name} API`, version: appIdentity.version },
     groups: [{ pathPrefix: '/api', services }],
   });
 
@@ -22,7 +23,7 @@ async function main(): Promise<void> {
     groups: [{ pathPrefix: '/api', services }],
     port: env.API_PORT,
     hostname: '0.0.0.0',
-    cors: { origin: '*' },
+    cors: { origin: env.CORS_ORIGIN },
     hooks: { onError },
     logging: { format: env.LOG_FORMAT },
     websocket: socket.websocket,

package/template/packages/backend/src/surface-manifest.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from 'bun:test';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createContractFactory } from 'stitchkit/contract';
+import { generateOpenApiDocument, implement } from 'stitchkit/server';
+import { z } from 'zod';
+import { discoverCliCommands, discoverMcpTools } from '../../../scripts/surface-conformance';
+import {
+  assertManifestMatchesSnapshot,
+  assertSurfaceConformance,
+  buildSurfaceManifest,
+} from './surface-manifest';
+
+const NoteParamsSchema = z.object({ id: z.string() });
+const NoteSchema = z.object({ id: z.string() });
+// Same address and presence flags as NoteSchema — a different TYPE, for the
+// snapshot-digest test. Named here, never inline in a contract (the template's
+// own schema-separate-from-contract policy).
+const RetypedNoteSchema = z.object({ id: z.number() });
+const { defineContract } = createContractFactory<'public'>();
+
+const service = implement(
+  defineContract(
+    { prefix: 'notes', scope: 'public' },
+    {
+      read: {
+        method: 'GET',
+        path: '/:id',
+        desc: 'Read a note',
+        params: NoteParamsSchema,
+        output: NoteSchema,
+        expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+      },
+    },
+  ),
+  { read: ({ params }) => ({ id: params.id }) },
+);
+
+describe('surface conformance', () => {
+  test('derives matching HTTP and MCP discovery identities without calling handlers', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const openApi = generateOpenApiDocument({
+      info: { title: 'Test', version: '1.0.0' },
+      groups: [{ pathPrefix: '/api', services: [service] }],
+    });
+    expect(manifest).toEqual([
+      {
+        service: 'notes',
+        action: 'read',
+        scope: 'public',
+        hasInput: false,
+        hasOutput: true,
+        inputShape: null,
+        outputShape: expect.stringMatching(/^[0-9a-f]{16}$/),
+        http: [{ method: 'GET', path: '/api/notes/{id}' }],
+        tools: { AGENT: 'read_note', CLI: 'read_note', MCP: 'read_note' },
+      },
+    ]);
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: ['read_note'],
+        cliToolNames: ['read_note'],
+      }),
+    ).not.toThrow();
+  });
+
+  test('fails with transport-specific expected and actual diagnostics', () => {
+    const manifest = buildSurfaceManifest([service]);
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi: { paths: {} },
+        mcpToolNames: [],
+        agentToolNames: [],
+        cliToolNames: [],
+      }),
+    ).toThrow('HTTP/OpenAPI surface mismatch');
+    expect(() =>
+      assertSurfaceConformance({
+        manifest: manifest.map((operation) => ({ ...operation, http: [] })),
+        openApi: { paths: {} },
+        mcpToolNames: ['unexpected'],
+        agentToolNames: ['read_note'],
+        cliToolNames: ['read_note'],
+      }),
+    ).toThrow('MCP discovery surface mismatch');
+  });
+
+  test('missing Stitchkit metadata is an ERROR unless the standard-document mode is declared', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const standardDocument = {
+      paths: {
+        '/api/notes/{id}': {
+          get: { responses: { 200: { description: 'Success' } } },
+        },
+      },
+    };
+    const names = {
+      mcpToolNames: ['read_note'],
+      agentToolNames: ['read_note'],
+      cliToolNames: ['read_note'],
+    };
+    // A silent skip was the hole: no x-stitchkit-* keys meant no comparison at
+    // all. The default mode now refuses; opting out is an explicit decision.
+    expect(() =>
+      assertSurfaceConformance({ manifest, openApi: standardDocument, ...names }),
+    ).toThrow(/no x-stitchkit-\* contract metadata/);
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi: standardDocument,
+        ...names,
+        metadata: 'ignore',
+      }),
+    ).not.toThrow();
+  });
+
+  test('a missing AGENT tool and a missing CLI command each fail conformance', () => {
+    const manifest = buildSurfaceManifest([service]);
+    const openApi = generateOpenApiDocument({
+      info: { title: 'Test', version: '1.0.0' },
+      groups: [{ pathPrefix: '/api', services: [service] }],
+    });
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: [],
+        cliToolNames: ['read_note'],
+      }),
+    ).toThrow('AGENT mount surface mismatch');
+    expect(() =>
+      assertSurfaceConformance({
+        manifest,
+        openApi,
+        mcpToolNames: ['read_note'],
+        agentToolNames: ['read_note'],
+        cliToolNames: [],
+      }),
+    ).toThrow('CLI manifest surface mismatch');
+  });
+
+  test('the committed snapshot catches an expose edit that moves BOTH in-process sides together', () => {
+    // The probe that defeated the old check: removing AGENT/CLI from `expose`
+    // changes the manifest AND the in-process tool lists in lockstep. The
+    // snapshot is the anchor that does not move with the source.
+    const snapshot = buildSurfaceManifest([service]);
+    const narrowed = implement(
+      defineContract(
+        { prefix: 'notes', scope: 'public' },
+        {
+          read: {
+            method: 'GET',
+            path: '/:id',
+            desc: 'Read a note',
+            params: NoteParamsSchema,
+            output: NoteSchema,
+            expose: ['HTTP', 'MCP'],
+          },
+        },
+      ),
+      { read: ({ params }) => ({ id: params.id }) },
+    );
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([narrowed]), snapshot),
+    ).toThrow(/diverged from the committed snapshot/);
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([service]), snapshot),
+    ).not.toThrow();
+  });
+
+  test('a schema TYPE change at the same method and path flips the shape digest', () => {
+    const snapshot = buildSurfaceManifest([service]);
+    const retyped = implement(
+      defineContract(
+        { prefix: 'notes', scope: 'public' },
+        {
+          read: {
+            method: 'GET',
+            path: '/:id',
+            desc: 'Read a note',
+            params: NoteParamsSchema,
+            // Same address, same presence flags — different output TYPE.
+            output: RetypedNoteSchema,
+            expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+          },
+        },
+      ),
+      { read: ({ params }) => ({ id: Number(params.id) }) },
+    );
+    expect(() =>
+      assertManifestMatchesSnapshot(buildSurfaceManifest([retyped]), snapshot),
+    ).toThrow(/diverged from the committed snapshot/);
+  });
+
+  test('fails first on duplicate contract identity', () => {
+    expect(() => buildSurfaceManifest([service, service])).toThrow(
+      'Duplicate operation identity notes.read',
+    );
+  });
+
+  test('a broken /mcp endpoint rejects discovery — even when zero tools are expected', async () => {
+    const broken = Bun.serve({
+      port: 0,
+      fetch: () => new Response('not the MCP endpoint', { status: 404 }),
+    });
+    try {
+      await expect(discoverMcpTools(`http://127.0.0.1:${broken.port}`, [])).rejects.toThrow();
+    } finally {
+      broken.stop(true);
+    }
+  });
+
+  test('the CLI surface observed from the SPAWNED process matches the committed snapshot', async () => {
+    // External observation against the external anchor — neither side is the
+    // in-process `services` object, so they cannot move together.
+    const root = join(import.meta.dir, '../../..');
+    const commands = await discoverCliCommands(root);
+    const snapshot = SurfaceSnapshotCliSchema.parse(
+      JSON.parse(
+        await readFile(join(root, 'packages/backend/src/surface.snapshot.json'), 'utf8'),
+      ),
+    );
+    const expected = snapshot
+      .flatMap((operation) => (operation.tools.CLI ? [operation.tools.CLI] : []))
+      .sort();
+    expect([...commands].sort()).toEqual(expected);
+  });
+});
+
+const SurfaceSnapshotCliSchema = z.array(
+  z.object({ tools: z.object({ CLI: z.string().optional() }) }),
+);