create-stitchkit 0.1.1 → 0.3.0

package/template/playwright.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig, devices } from '@playwright/test';
-import { toolingEnv } from './scripts/tooling-env';
+import { loadToolingEnv } from './scripts/tooling-env';
 
+const toolingEnv = loadToolingEnv();
 const baseURL = toolingEnv.PLAYWRIGHT_BASE_URL ?? toolingEnv.NEXT_PUBLIC_WEB_URL;
 
 export default defineConfig({

package/template/scripts/check-authored.ts

@@ -2,7 +2,8 @@ import { readdir, readFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 import { parseSync, Visitor } from 'oxc-parser';
 
-const roots = ['packages', 'scripts'];
+const roots = ['packages', 'scripts', 'e2e'];
+const rootFiles = ['playwright.config.ts', 'ecosystem.config.cjs', 'ecosystem.dev.config.cjs'];
 const processEnvMarker = ['process', 'env'].join('.');
 const replacedThemePackage = ['next', 'themes'].join('-');
 const generatedDirectories = new Set(['.git', '.next', 'dist', 'node_modules']);
@@ -10,20 +11,26 @@ const processEnvBoundaries = new Set([
   'packages/frontend/src/env.ts',
   'packages/config/src/server.ts',
   'scripts/tooling-env.ts',
+  'ecosystem.config.cjs',
+  'ecosystem.dev.config.cjs',
 ]);
 
+function lineAt(source: string, offset: number): number {
+  return source.slice(0, offset).split('\n').length;
+}
+
 function inspect(path: string, source: string): string[] {
   const result = parseSync(path, source);
   const failures = result.errors.map((error) => `${path}: parse error: ${error.message}`);
   const visitor = new Visitor({
     TSAsExpression(node) {
-      failures.push(`${path}:${node.loc?.start.line ?? 1}: type assertion`);
+      failures.push(`${path}:${lineAt(source, node.start)}: type assertion`);
     },
     TSTypeAssertion(node) {
-      failures.push(`${path}:${node.loc?.start.line ?? 1}: type assertion`);
+      failures.push(`${path}:${lineAt(source, node.start)}: type assertion`);
     },
     TSAnyKeyword(node) {
-      failures.push(`${path}:${node.loc?.start.line ?? 1}: explicit any`);
+      failures.push(`${path}:${lineAt(source, node.start)}: explicit any`);
     },
   });
   visitor.visit(result.program);
@@ -62,13 +69,20 @@ async function visitDirectory(directory: string): Promise<string[]> {
       failures.push(...(await visitDirectory(path)));
       continue;
     }
-    if (!['.ts', '.tsx'].includes(extname(path))) continue;
+    if (!['.cjs', '.ts', '.tsx'].includes(extname(path))) continue;
     failures.push(...inspect(path, await readFile(path, 'utf8')));
   }
   return failures;
 }
 
-const failures = (await Promise.all(roots.map(visitDirectory))).flat();
+const failures = [
+  ...(await Promise.all(roots.map(visitDirectory))).flat(),
+  ...(
+    await Promise.all(
+      rootFiles.map(async (path) => inspect(path, await readFile(path, 'utf8'))),
+    )
+  ).flat(),
+];
 const webPackage = await readFile('packages/frontend/package.json', 'utf8');
 if (webPackage.includes(replacedThemePackage)) {
   failures.push(

package/template/scripts/dev.ts

@@ -1,10 +1,13 @@
 import { resolve } from 'node:path';
+import { appIdentity } from '../packages/config/src/identity';
 import { ensureLocalEnvironment } from './local-env';
+import { inheritToolingEnvironment } from './tooling-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 ? inheritToolingEnvironment(environment) : undefined,
     stdin: 'inherit',
     stdout: 'inherit',
     stderr: 'inherit',
@@ -13,11 +16,47 @@ 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> {
+  ensureLocalEnvironment(root);
+  assertToolAvailable('pm2', 'Install PM2 with `bun add --global pm2`, then rerun.');
+  await run(['pm2', 'ping']);
+  const environmentForRun = await developmentEnvironment(environment);
+  if (environmentForRun.DATABASE_URL?.includes('USER:PASSWORD')) {
+    throw new Error(
+      'DATABASE_URL still contains the starter placeholder. Create a PostgreSQL database, update DATABASE_URL in .env, then rerun `bun run dev`.',
+    );
+  }
+  await run(['bun', 'run', 'db:setup'], environmentForRun);
+  await run(
+    ['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env'],
+    environmentForRun,
+  );
+}
+
+function assertToolAvailable(command: string, instruction: string): void {
+  if (!Bun.which(command)) throw new Error(`${command} is required. ${instruction}`);
+}
 
-await run(['bun', 'run', 'db:setup']);
-await run(['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env']);
+export async function developmentEnvironment(
+  overrides: Record<string, string> = {},
+): Promise<Record<string, string>> {
+  const { env } = await import('../packages/config/src/server');
+  return {
+    DATABASE_URL: env.DATABASE_URL,
+    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,
+    ...overrides,
+  };
+}
+
+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/local-env.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appIdentity } from '../packages/config/src/identity';
+import { ensureLocalEnvironment } from './local-env';
+
+describe('ensureLocalEnvironment', () => {
+  test('renders the application identity into a fresh .env and never touches an existing one', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'sk-env-'));
+    try {
+      await writeFile(
+        join(root, '.env.example'),
+        'DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter\n',
+      );
+      ensureLocalEnvironment(root);
+      const created = await readFile(join(root, '.env'), 'utf8');
+      // In the neutral dev workspace the slug IS the neutral identity, so the
+      // substitution is proven end-to-end by the starter lane on a renamed
+      // scaffold; here we prove the file is created from the example with the
+      // identity-derived database name in place.
+      const databaseName = appIdentity.slug.replaceAll('-', '_');
+      expect(created).toContain(`5432/${databaseName}`);
+
+      // Idempotency — a developer's local credentials survive every dev run.
+      await writeFile(join(root, '.env'), 'DATABASE_URL=postgresql://real-creds@db/mine\n');
+      ensureLocalEnvironment(root);
+      expect(await readFile(join(root, '.env'), 'utf8')).toContain('real-creds');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/template/scripts/local-env.ts

@@ -1,12 +1,23 @@
-import { copyFile } from 'node:fs/promises';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { appIdentity } from '../packages/config/src/identity';
 
-export async function ensureLocalEnvironment(root: string): Promise<void> {
+/**
+ * Create `.env` from `.env.example` on first run, rendering the application
+ * identity into the database name. `.env.example` is the ONLY environment
+ * source the repository ships — the scaffolder never writes `.env`, so a
+ * rename in `app.config.json` changes the database of the next created
+ * environment too. Synchronous on purpose: `playwright.config.ts` and other
+ * synchronous entry points must be able to self-heal before validating.
+ */
+export function ensureLocalEnvironment(root: string): void {
   const destination = resolve(root, '.env');
-  if (await Bun.file(destination).exists()) return;
-  await copyFile(resolve(root, '_env'), destination);
+  if (existsSync(destination)) return;
+  const example = readFileSync(resolve(root, '.env.example'), 'utf8');
+  const databaseName = appIdentity.slug.replaceAll('-', '_');
+  writeFileSync(destination, example.replaceAll('stitchkit_starter', databaseName));
 }
 
 if (import.meta.main) {
-  await ensureLocalEnvironment(resolve(import.meta.dir, '..'));
+  ensureLocalEnvironment(resolve(import.meta.dir, '..'));
 }

package/template/scripts/runtime-smoke.ts

@@ -1,69 +1,30 @@
-import { RepositorySnapshotSchema } from '@app/shared';
-import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import { io } from 'socket.io-client';
+import { systemContract } from '@app/shared';
+import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
-import { toolingEnv } from './tooling-env';
+import { runSurfaceConformance } from './surface-conformance';
+import { loadToolingEnv } from './tooling-env';
 
-const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
+const apiOrigin = loadToolingEnv().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 system = createClient(
+  systemContract,
+  createHttpClient({ baseUrl: `${apiOrigin}/api`, credentials: 'omit' }),
+);
+z.object({ status: z.literal('ok') }).parse(await system.status());
+const openApi = z
+  .object({ paths: z.record(z.string(), z.unknown()) })
+  .parse(await json('/openapi.json'));
+if (!Object.keys(openApi.paths).includes('/api/system/status')) {
+  throw new Error('System status contract is missing from OpenAPI');
 }
 
-console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');
+await runSurfaceConformance({ apiOrigin });
+
+console.log('Runtime HTTP, typed client, OpenAPI and MCP smoke passed');

package/template/scripts/surface-conformance.ts

@@ -0,0 +1,166 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { mountAgent } from 'stitchkit/tools';
+import { z } from 'zod';
+import { createSurface } from '../packages/backend/src/surface';
+import {
+  assertManifestMatchesSnapshot,
+  assertSurfaceConformance,
+  buildSurfaceManifest,
+  type SurfaceManifestOperation,
+} from '../packages/backend/src/surface-manifest';
+
+export const SURFACE_SNAPSHOT_PATH = 'packages/backend/src/surface.snapshot.json';
+
+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();
+}
+
+/**
+ * Observe the CLI surface EXTERNALLY — spawn the real CLI process and parse
+ * its command table, instead of re-deriving the list from the same in-process
+ * `services` the manifest was built from (which could only ever agree).
+ */
+export async function discoverCliCommands(root = process.cwd()): Promise<string[]> {
+  const child = Bun.spawn({
+    cmd: ['bun', 'packages/backend/src/cli.ts', '--help'],
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [output, errors, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(`CLI --help exited with ${exitCode}: ${errors || output}`);
+  }
+  const lines = output.split('\n');
+  const start = lines.findIndex((line) => line.trim() === 'Commands:');
+  if (start === -1) throw new Error('CLI --help output carries no "Commands:" section');
+  const commands: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (!line.startsWith('  ')) break;
+    const name = line.trim().split(/\s+/)[0];
+    if (name) commands.push(name);
+  }
+  return commands;
+}
+
+export async function discoverMcpTools(
+  apiOrigin: string,
+  _manifest: readonly SurfaceManifestOperation[],
+): Promise<string[]> {
+  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);
+    return (await client.listTools()).tools.map((tool) => tool.name);
+  } finally {
+    await client.close();
+  }
+}
+
+export async function runSurfaceConformance({
+  apiOrigin,
+  probes = [],
+}: SurfaceConformanceOptions): Promise<void> {
+  const { services, socket } = await createSurface();
+  try {
+    const manifest = buildSurfaceManifest(services);
+    // The committed snapshot is the anchor no source edit can move along with
+    // itself: removing a transport from `expose` changes the live manifest but
+    // not the snapshot, so the lane fails until the snapshot is deliberately
+    // regenerated and reviewed.
+    const snapshot = SurfaceSnapshotSchema.parse(
+      JSON.parse(await readFile(join(process.cwd(), SURFACE_SNAPSHOT_PATH), 'utf8')),
+    );
+    assertManifestMatchesSnapshot(manifest, snapshot);
+    const openApi = await readJson(`${apiOrigin}/openapi.json`);
+    const mcpToolNames = await discoverMcpTools(apiOrigin, manifest);
+    assertSurfaceConformance({
+      manifest,
+      openApi: OpenApiSnapshotSchema.parse(openApi),
+      mcpToolNames,
+      // AGENT has no external process to observe — it is anchored by the
+      // snapshot above; CLI is observed by spawning the real CLI.
+      agentToolNames: Object.keys(mountAgent(services)),
+      cliToolNames: await discoverCliCommands(),
+    });
+    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())),
+});
+
+const SurfaceSnapshotSchema: z.ZodType<SurfaceManifestOperation[]> = z.array(
+  z.object({
+    service: z.string(),
+    action: z.string(),
+    scope: z.string(),
+    hasInput: z.boolean(),
+    hasOutput: z.boolean(),
+    inputShape: z.string().nullable(),
+    outputShape: z.string().nullable(),
+    http: z.array(
+      z.object({
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']),
+        path: z.string(),
+      }),
+    ),
+    tools: z.object({
+      MCP: z.string().optional(),
+      AGENT: z.string().optional(),
+      CLI: z.string().optional(),
+    }),
+  }),
+);

package/template/scripts/surface-snapshot.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+/**
+ * Regenerate the committed surface snapshot — the anchor `surface-conformance`
+ * compares the live contract surface against. Run it deliberately after an
+ * intended surface change and review the diff like any other contract change.
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createSurface } from '../packages/backend/src/surface';
+import { buildSurfaceManifest } from '../packages/backend/src/surface-manifest';
+import { SURFACE_SNAPSHOT_PATH } from './surface-conformance';
+
+const { services, socket } = await createSurface();
+try {
+  const manifest = buildSurfaceManifest(services);
+  const target = join(process.cwd(), SURFACE_SNAPSHOT_PATH);
+  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();
+}

package/template/scripts/tooling-env.ts

@@ -2,14 +2,27 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { config as dotenvConfig } from 'dotenv';
 import { z } from 'zod';
+import { ensureLocalEnvironment } from './local-env';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
-dotenvConfig({ path: path.resolve(scriptDirectory, '..', '.env'), quiet: true });
-
 const ToolingEnvSchema = z.object({
   NEXT_PUBLIC_API_URL: z.url(),
   NEXT_PUBLIC_WEB_URL: z.url(),
   PLAYWRIGHT_BASE_URL: z.url().optional(),
 });
 
-export const toolingEnv = ToolingEnvSchema.parse(process.env);
+export function loadToolingEnv(root = path.resolve(scriptDirectory, '..')) {
+  // Self-heal FIRST — a fresh clone has no `.env`, and validation must not
+  // fire before the environment can be created (the second-developer path:
+  // `runtime:smoke` and `e2e` both start here).
+  ensureLocalEnvironment(root);
+  dotenvConfig({ path: path.resolve(root, '.env'), quiet: true });
+  return ToolingEnvSchema.parse(process.env);
+}
+
+/** Process inheritance is isolated to this tooling environment boundary. */
+export function inheritToolingEnvironment(
+  overrides: Record<string, string>,
+): Record<string, string | undefined> {
+  return { ...process.env, ...overrides };
+}

package/template/tsconfig.json

@@ -5,9 +5,11 @@
     "moduleResolution": "bundler",
     "strict": true,
     "skipLibCheck": true,
+    "types": ["bun", "node"],
     "allowImportingTsExtensions": true,
     "noEmit": true,
     "resolveJsonModule": true,
     "verbatimModuleSyntax": true
-  }
+  },
+  "include": ["scripts/**/*.ts", "e2e/**/*.ts", "playwright.config.ts"]
 }

package/template/_env

@@ -1,11 +0,0 @@
-NODE_ENV=development
-DATABASE_URL=postgresql://USER:PASSWORD@127.0.0.1:5432/stitchkit_starter
-API_PORT=3211
-WEB_PORT=3210
-NEXT_PUBLIC_API_URL=http://127.0.0.1:3211
-INTERNAL_API_URL=http://127.0.0.1:3211
-NEXT_PUBLIC_WEB_URL=http://127.0.0.1:3210
-LOG_FORMAT=pretty
-GITHUB_REPOSITORY=max-listov/stitchkit
-GITHUB_CACHE_TTL_SECONDS=900
-# GITHUB_TOKEN=github_pat_...

package/template/packages/shared/src/events/repository.ts

@@ -1,9 +0,0 @@
-import type { RepositorySnapshot } from '../schemas/repository';
-
-export interface ServerToClientEvents {
-  'repository:refreshed': (snapshot: RepositorySnapshot) => void;
-}
-
-export interface ClientToServerEvents {
-  'repository:watch': () => void;
-}