create-stitchkit 0.1.0

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

@@ -0,0 +1,28 @@
+import { createContractFactory } from 'stitchkit';
+import { RepositorySnapshotSchema } from '../schemas/repository';
+
+export type AppScope = 'public';
+
+const { defineContract } = createContractFactory<AppScope>();
+
+export const repositoryContract = defineContract(
+  { prefix: 'repository', scope: 'public' },
+  {
+    read: {
+      method: 'GET',
+      path: '/',
+      desc: 'Read the server-cached repository snapshot',
+      output: RepositorySnapshotSchema,
+      expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+      toolName: 'repository_read',
+    },
+    refresh: {
+      method: 'POST',
+      path: '/refresh',
+      desc: 'Refresh the repository snapshot from GitHub',
+      output: RepositorySnapshotSchema,
+      expose: ['HTTP', 'MCP', 'AGENT', 'CLI'],
+      toolName: 'repository_refresh',
+    },
+  },
+);

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

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

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

@@ -0,0 +1,3 @@
+export * from './contracts/repository';
+export * from './events/repository';
+export * from './schemas/repository';

package/template/packages/shared/src/schemas/repository.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'bun:test';
+import { RepositorySnapshotSchema } from './repository';
+
+describe('repository snapshot schema', () => {
+  test('accepts a bounded GitHub snapshot', () => {
+    const result = RepositorySnapshotSchema.safeParse({
+      fullName: 'owner/repository',
+      description: 'A repository',
+      htmlUrl: 'https://github.com/owner/repository',
+      language: 'TypeScript',
+      visibility: 'PUBLIC',
+      stars: 2,
+      forks: 1,
+      openIssues: 0,
+      commitCount: 42,
+      latestCommit: {
+        sha: 'abc123',
+        message: 'Ship the starter',
+        committedAt: '2026-08-08T00:00:00Z',
+      },
+      cache: {
+        state: 'fresh',
+        fetchedAt: '2026-08-08T00:00:00Z',
+        expiresAt: '2026-08-08T00:15:00Z',
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test('rejects repository visibility outside the database enum', () => {
+    const result = RepositorySnapshotSchema.shape.visibility.safeParse('UNLISTED');
+
+    expect(result.success).toBe(false);
+  });
+});

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

@@ -0,0 +1,28 @@
+import { RepositoryVisibility } from '@app/db/enums';
+import { z } from 'zod';
+
+export const RepositorySnapshotSchema = z.object({
+  fullName: z.string().min(1),
+  description: z.string().nullable(),
+  htmlUrl: z.url(),
+  language: z.string().nullable(),
+  visibility: z.enum(RepositoryVisibility),
+  stars: z.number().int().nonnegative(),
+  forks: z.number().int().nonnegative(),
+  openIssues: z.number().int().nonnegative(),
+  commitCount: z.number().int().nonnegative(),
+  latestCommit: z
+    .object({
+      sha: z.string().min(1),
+      message: z.string().min(1),
+      committedAt: z.iso.datetime(),
+    })
+    .nullable(),
+  cache: z.object({
+    state: z.enum(['fresh', 'revalidated', 'stale']),
+    fetchedAt: z.iso.datetime(),
+    expiresAt: z.iso.datetime(),
+  }),
+});
+
+export type RepositorySnapshot = z.infer<typeof RepositorySnapshotSchema>;

package/template/packages/shared/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "lib": ["ESNext", "DOM"], "types": ["bun"] },
+  "include": ["src"]
+}

package/template/playwright.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig, devices } from '@playwright/test';
+import { toolingEnv } from './scripts/tooling-env';
+
+const baseURL = toolingEnv.PLAYWRIGHT_BASE_URL ?? toolingEnv.NEXT_PUBLIC_WEB_URL;
+
+export default defineConfig({
+  testDir: './e2e',
+  retries: 0,
+  use: { baseURL, trace: 'retain-on-failure' },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chromium', use: { ...devices['Pixel 7'] } },
+  ],
+});

package/template/scripts/check-authored.ts

@@ -0,0 +1,81 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { parseSync, Visitor } from 'oxc-parser';
+
+const roots = ['packages', 'scripts'];
+const processEnvMarker = ['process', 'env'].join('.');
+const replacedThemePackage = ['next', 'themes'].join('-');
+const generatedDirectories = new Set(['.git', '.next', 'dist', 'node_modules']);
+const processEnvBoundaries = new Set([
+  'packages/frontend/src/env.ts',
+  'packages/config/src/server.ts',
+  'scripts/tooling-env.ts',
+]);
+
+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`);
+    },
+    TSTypeAssertion(node) {
+      failures.push(`${path}:${node.loc?.start.line ?? 1}: type assertion`);
+    },
+    TSAnyKeyword(node) {
+      failures.push(`${path}:${node.loc?.start.line ?? 1}: explicit any`);
+    },
+  });
+  visitor.visit(result.program);
+  if (source.includes(processEnvMarker) && !processEnvBoundaries.has(path)) {
+    failures.push(`${path}: direct environment access outside a validated env boundary`);
+  }
+  if (source.includes(replacedThemePackage)) {
+    failures.push(`${path}: use @wrksz/themes as the single theme runtime`);
+  }
+  if (path.startsWith('packages/frontend/') || path.startsWith('packages/shared/')) {
+    for (const specifier of source.matchAll(/from\s+['"]([^'"]+)['"]/g)) {
+      const dependency = specifier[1];
+      if (
+        dependency === '@app/db' ||
+        dependency?.startsWith('@prisma/') ||
+        (path.startsWith('packages/shared/') && dependency?.startsWith('node:')) ||
+        (path.startsWith('packages/shared/') && dependency === 'bun')
+      ) {
+        failures.push(
+          `${path}: server-only dependency ${dependency} crossed the browser boundary`,
+        );
+      }
+    }
+  }
+  return failures;
+}
+
+async function visitDirectory(directory: string): Promise<string[]> {
+  const failures: string[] = [];
+  const entries = await readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && generatedDirectories.has(entry.name)) continue;
+    const path = join(directory, entry.name);
+    if (path.includes('/src/generated')) continue;
+    if (entry.isDirectory()) {
+      failures.push(...(await visitDirectory(path)));
+      continue;
+    }
+    if (!['.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 webPackage = await readFile('packages/frontend/package.json', 'utf8');
+if (webPackage.includes(replacedThemePackage)) {
+  failures.push(
+    'packages/frontend/package.json: use @wrksz/themes as the single theme runtime',
+  );
+}
+if (failures.length > 0) {
+  for (const failure of failures) console.error(failure);
+  process.exit(1);
+}

package/template/scripts/dev.ts

@@ -0,0 +1,23 @@
+import { resolve } from 'node:path';
+import { ensureLocalEnvironment } from './local-env';
+
+const root = resolve(import.meta.dir, '..');
+async function run(command: string[]): Promise<void> {
+  const child = Bun.spawn(command, {
+    cwd: root,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const exitCode = await child.exited;
+  if (exitCode !== 0) throw new Error(`${command.join(' ')} failed with exit code ${exitCode}`);
+}
+
+await ensureLocalEnvironment(root);
+
+await run(['bun', 'run', 'db:setup']);
+await run(['pm2', 'startOrReload', 'ecosystem.dev.config.cjs', '--update-env']);
+
+console.log('Stitchkit Starter development processes are running');
+console.log('Web: http://localhost:3210/en');
+console.log('API: http://localhost:3211');

package/template/scripts/local-env.ts

@@ -0,0 +1,12 @@
+import { copyFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export async function ensureLocalEnvironment(root: string): Promise<void> {
+  const destination = resolve(root, '.env');
+  if (await Bun.file(destination).exists()) return;
+  await copyFile(resolve(root, '_env'), destination);
+}
+
+if (import.meta.main) {
+  await ensureLocalEnvironment(resolve(import.meta.dir, '..'));
+}

package/template/scripts/runtime-smoke.ts

@@ -0,0 +1,67 @@
+import { RepositorySnapshotSchema } from '@app/shared';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { io } from 'socket.io-client';
+import { z } from 'zod';
+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}`);
+  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' });
+  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();
+}
+
+console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');

package/template/scripts/tooling-env.ts

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { config as dotenvConfig } from 'dotenv';
+import { z } from 'zod';
+
+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);

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true
+  }
+}