create-stitchkit 0.1.1 → 0.2.0

package/template/scripts/dev.ts

@@ -1,10 +1,13 @@
 import { resolve } from 'node:path';
+import { appIdentity } from '../packages/config/src/identity';
+import { childEnvironment, env } from '../packages/config/src/server';
 import { ensureLocalEnvironment } from './local-env';
 
 const root = resolve(import.meta.dir, '..');
-async function run(command: string[]): Promise<void> {
+async function run(command: string[], environment?: Record<string, string>): Promise<void> {
   const child = Bun.spawn(command, {
     cwd: root,
+    env: environment ? childEnvironment(environment) : undefined,
     stdin: 'inherit',
     stdout: 'inherit',
     stderr: 'inherit',
@@ -13,11 +16,38 @@ async function run(command: string[]): Promise<void> {
   if (exitCode !== 0) throw new Error(`${command.join(' ')} failed with exit code ${exitCode}`);
 }
 
-await ensureLocalEnvironment(root);
+export async function runDevelopment(environment?: Record<string, string>): Promise<void> {
+  await ensureLocalEnvironment(root);
+  const environmentForRun = developmentEnvironment(environment);
+  await run(['bun', 'run', 'db:setup'], environmentForRun);
+  await run(
+    ['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env'],
+    environmentForRun,
+  );
+}
+
+export function developmentEnvironment(
+  overrides: Record<string, string> = {},
+): Record<string, string> {
+  return {
+    API_PORT: String(env.API_PORT),
+    WEB_PORT: String(env.WEB_PORT),
+    CORS_ORIGIN: env.CORS_ORIGIN,
+    NEXT_PUBLIC_API_URL: env.NEXT_PUBLIC_API_URL,
+    NEXT_PUBLIC_WEB_URL: env.NEXT_PUBLIC_WEB_URL,
+    INTERNAL_API_URL: env.INTERNAL_API_URL,
+    DEV_HTTPS_CERT: '',
+    DEV_HTTPS_KEY: '',
+    DEV_HTTPS_CA: '',
+    NODE_EXTRA_CA_CERTS: '',
+    ...overrides,
+  };
+}
 
-await run(['bun', 'run', 'db:setup']);
-await run(['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env']);
+if (import.meta.main) {
+  await runDevelopment();
 
-console.log('Stitchkit Starter development processes are running');
-console.log('Web: http://localhost:3210/en');
-console.log('API: http://localhost:3211');
+  console.log(`${appIdentity.name} development processes are running`);
+  console.log('Web: http://localhost:3210/en');
+  console.log('API: http://localhost:3211');
+}

package/template/scripts/runtime-smoke.ts

@@ -1,69 +1,23 @@
-import { RepositorySnapshotSchema } from '@app/shared';
-import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import { io } from 'socket.io-client';
 import { z } from 'zod';
+import { runSurfaceConformance } from './surface-conformance';
 import { toolingEnv } from './tooling-env';
 
 const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
 
-async function json(path: string, init?: RequestInit): Promise<unknown> {
-  const response = await fetch(`${apiOrigin}${path}`, init);
-  if (!response.ok)
-    throw new Error(`${init?.method ?? 'GET'} ${path} returned ${response.status}`);
+async function json(path: string): Promise<unknown> {
+  const response = await fetch(`${apiOrigin}${path}`);
+  if (!response.ok) throw new Error(`GET ${path} returned ${response.status}`);
   return response.json();
 }
 
-const socket = io(apiOrigin, { transports: ['websocket'] });
-const refreshedEvent = new Promise<string>((resolve, reject) => {
-  const timeout = setTimeout(
-    () => reject(new Error('Socket.IO repository refresh event timed out')),
-    5_000,
-  );
-  socket.once('repository:refreshed', (snapshot) => {
-    clearTimeout(timeout);
-    resolve(snapshot.fullName);
-  });
-});
-
-try {
-  z.object({ status: z.literal('ok') }).parse(await json('/health'));
-  const corsResponse = await fetch(`${apiOrigin}/api/repository/`, {
-    headers: { Origin: 'http://localhost:58302' },
-  });
-  if (corsResponse.headers.get('access-control-allow-origin') !== '*') {
-    throw new Error('Public API does not allow a forwarded browser origin');
-  }
-  const openApi = z
-    .object({ paths: z.record(z.string(), z.unknown()) })
-    .parse(await json('/openapi.json'));
-  if (!Object.keys(openApi.paths).some((path) => path.startsWith('/api/repository'))) {
-    throw new Error('OpenAPI repository path is missing');
-  }
-
-  const refreshed = RepositorySnapshotSchema.parse(
-    await json('/api/repository/refresh', { method: 'POST' }),
-  );
-  if ((await refreshedEvent) !== refreshed.fullName) {
-    throw new Error('Socket.IO repository identity differs');
-  }
-  const cached = RepositorySnapshotSchema.parse(await json('/api/repository/'));
-  if (cached.fullName !== refreshed.fullName) throw new Error('Repository cache read differs');
-
-  const client = new Client(
-    { name: 'starter-lane', version: '1.0.0' },
-    { versionNegotiation: { mode: { pin: '2026-07-28' } } },
-  );
-  const transport = new StreamableHTTPClientTransport(new URL(`${apiOrigin}/mcp`));
-  await client.connect(transport);
-  const tools = await client.listTools();
-  if (!tools.tools.some((tool) => tool.name === 'repository_read')) {
-    throw new Error('MCP repository tool is absent');
-  }
-  const result = await client.callTool({ name: 'repository_read', arguments: {} });
-  if (result.isError) throw new Error('MCP repository read failed');
-  await client.close();
-} finally {
-  socket.close();
+z.object({ status: z.literal('ok') }).parse(await json('/health'));
+const openApi = z
+  .object({ paths: z.record(z.string(), z.unknown()) })
+  .parse(await json('/openapi.json'));
+if (Object.keys(openApi.paths).some((path) => path.startsWith('/api/'))) {
+  throw new Error('Blank starter unexpectedly publishes application contracts');
 }
 
-console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');
+await runSurfaceConformance({ apiOrigin });
+
+console.log('Blank runtime HTTP, OpenAPI and MCP smoke passed');

package/template/scripts/surface-conformance.ts

@@ -0,0 +1,105 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { z } from 'zod';
+import { createSurface } from '../packages/backend/src/surface';
+import {
+  assertSurfaceConformance,
+  buildSurfaceManifest,
+  type SurfaceManifestOperation,
+} from '../packages/backend/src/surface-manifest';
+
+export interface SurfaceProbe {
+  name: string;
+  run: () => Promise<void>;
+}
+
+export function defineSurfaceProbe<TInput, TOutput>({
+  name,
+  input,
+  fixture,
+  output,
+  run,
+}: {
+  name: string;
+  input: z.ZodType<TInput>;
+  fixture: unknown;
+  output?: z.ZodType<TOutput>;
+  run: (input: TInput) => Promise<TOutput>;
+}): SurfaceProbe {
+  return {
+    name,
+    run: async () => {
+      const result = await run(input.parse(fixture));
+      output?.parse(result);
+    },
+  };
+}
+
+interface SurfaceConformanceOptions {
+  apiOrigin: string;
+  probes?: readonly SurfaceProbe[];
+}
+
+async function readJson(url: string): Promise<unknown> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`GET ${url} returned ${response.status}`);
+  return response.json();
+}
+
+async function discoverMcpTools(
+  apiOrigin: string,
+  manifest: readonly SurfaceManifestOperation[],
+): Promise<string[]> {
+  const expectedCount = manifest.filter((operation) => operation.tools.MCP).length;
+  const client = new Client(
+    { name: 'surface-conformance', version: '1.0.0' },
+    { versionNegotiation: { mode: { pin: '2026-07-28' } } },
+  );
+  const transport = new StreamableHTTPClientTransport(new URL(`${apiOrigin}/mcp`));
+  try {
+    await client.connect(transport);
+    try {
+      return (await client.listTools()).tools.map((tool) => tool.name);
+    } catch (error) {
+      if (
+        expectedCount === 0 &&
+        error instanceof Error &&
+        error.message.includes('not supported by the negotiated protocol version')
+      ) {
+        return [];
+      }
+      throw error;
+    }
+  } finally {
+    await client.close();
+  }
+}
+
+export async function runSurfaceConformance({
+  apiOrigin,
+  probes = [],
+}: SurfaceConformanceOptions): Promise<void> {
+  const { services, socket } = await createSurface();
+  try {
+    const manifest = buildSurfaceManifest(services);
+    const openApi = await readJson(`${apiOrigin}/openapi.json`);
+    const mcpToolNames = await discoverMcpTools(apiOrigin, manifest);
+    assertSurfaceConformance({
+      manifest,
+      openApi: OpenApiSnapshotSchema.parse(openApi),
+      mcpToolNames,
+    });
+    for (const probe of probes) {
+      try {
+        await probe.run();
+      } catch (cause) {
+        throw new Error(`Surface probe "${probe.name}" failed`, { cause });
+      }
+    }
+  } finally {
+    await socket.io.close();
+  }
+}
+
+const OpenApiSnapshotSchema = z.object({
+  paths: z.record(z.string(), z.record(z.string(), z.unknown())),
+});