create-stitchkit 0.1.0 → 0.2.0

package/template/packages/frontend/src/app/[locale]/page.tsx

@@ -1,10 +1,7 @@
-import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
+import { appIdentity } from '@app/config/identity';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
 import { LocaleSchema } from '@/i18n/locales';
-import { createServerRepositoryApi } from '@/lib/api/client';
-import { useRepository } from '@/lib/api/queries';
-import { getQueryClient } from '@/lib/query-client';
 import { createPageMetadata } from '@/lib/seo/metadata';
 import { StarterPage } from './starter-page';
 
@@ -22,23 +19,15 @@ export async function generateMetadata({
 export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
   const { locale } = await params;
   const appLocale = LocaleSchema.parse(locale);
-  const queryClient = getQueryClient();
-  const api = createServerRepositoryApi();
   const t = await getTranslations('App');
-  await queryClient.prefetchQuery({
-    queryKey: useRepository.getKey(),
-    queryFn: () => api.read(),
-  });
 
   return (
-    <HydrationBoundary state={dehydrate(queryClient)}>
-      <StarterPage
-        applicationName={t('title')}
-        applicationDescription={t('description')}
-        heroTitle={t('heroTitle')}
-        catalogueLabel={t('ui')}
-        locale={appLocale}
-      />
-    </HydrationBoundary>
+    <StarterPage
+      applicationName={appIdentity.name}
+      applicationDescription={appIdentity.description[appLocale]}
+      heroTitle={t('heroTitle')}
+      catalogueLabel={t('ui')}
+      locale={appLocale}
+    />
   );
 }

package/template/packages/frontend/src/app/[locale]/starter-page.tsx

@@ -1,7 +1,6 @@
 import { IconArrowUpRight } from '@tabler/icons-react';
 import Image from 'next/image';
 import { BrandMark } from '@/components/brand-mark';
-import { RepositorySummary } from '@/components/repository-summary';
 import { LanguageSwitcher, ThemeToggle } from '@/components/system-controls';
 import { buttonVariants } from '@/components/ui';
 import type { AppLocale } from '@/i18n/locales';
@@ -140,9 +139,9 @@ export function StarterPage({
               </div>
             </div>
 
-            <div className='mt-5 w-full'>
-              <RepositorySummary />
-            </div>
+            <p className='mt-5 text-sm text-muted-foreground'>
+              Add your first vertical feature from schema to transport and UI.
+            </p>
           </section>
         </div>
       </div>

package/template/packages/frontend/src/app/[locale]/ui/_catalogue/landing-showcase.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { appIdentity } from '@app/config/identity';
 import { IconArrowRight, IconBraces, IconDatabase, IconWorld } from '@tabler/icons-react';
 import type { ReactNode } from 'react';
 import { BrandMark } from '@/components/brand-mark';
@@ -36,7 +37,7 @@ export function LandingHeader({ actions }: { actions?: ReactNode }) {
     <header className='flex items-center justify-between border-b border-border py-4'>
       <div className='flex items-center gap-2 font-medium'>
         <BrandMark priority />
-        Stitchkit Starter
+        {appIdentity.name}
       </div>
       <div className='flex items-center gap-2'>{actions}</div>
     </header>
@@ -152,7 +153,7 @@ export function PricingSection() {
 export function LandingFooter() {
   return (
     <footer className='flex flex-col gap-3 border-t border-border py-8 text-sm text-muted-foreground sm:flex-row sm:items-center sm:justify-between'>
-      <span>Stitchkit Starter · Built with Stitchkit</span>
+      <span>{appIdentity.name} · Built with Stitchkit</span>
       <span>Contracts · UI · Realtime · Tools</span>
     </footer>
   );

package/template/packages/frontend/src/lib/seo/pages.ts

@@ -1,7 +1,8 @@
+import { appIdentity } from '@app/config/identity';
 import { z } from 'zod';
 import type { AppLocale } from '@/i18n/locales';
 
-export const SITE_NAME = 'Stitchkit Starter';
+export const SITE_NAME = appIdentity.name;
 export const StoryIdSchema = z.enum(['components', 'themes', 'blocks']);
 export type StoryId = z.infer<typeof StoryIdSchema>;
 
@@ -42,14 +43,12 @@ const seoPages: Record<SeoPageId, SeoPageDefinition> = {
     copy: {
       en: {
         title: 'UI components',
-        description:
-          'Explore accessible actions, forms, feedback, overlays, data displays and motion components included in the Stitchkit starter.',
+        description: `Explore accessible actions, forms, feedback, overlays, data displays and motion components included in ${SITE_NAME}.`,
         eyebrow: 'UI system',
       },
       ru: {
         title: 'UI-компоненты',
-        description:
-          'Изучите доступные действия, формы, обратную связь, оверлеи, представление данных и анимации в Stitchkit Starter.',
+        description: `Изучите доступные действия, формы, обратную связь, оверлеи, представление данных и анимации в ${SITE_NAME}.`,
         eyebrow: 'UI-система',
       },
     },

package/template/packages/frontend/src/providers/index.tsx

@@ -4,14 +4,11 @@ import { TooltipProvider } from '@radix-ui/react-tooltip';
 import type { ReactNode } from 'react';
 import { Toaster } from '@/components/ui/toaster';
 import { ReactQueryProvider } from './react-query';
-import { RealtimeProvider } from './realtime';
 
 export function Providers({ children }: { children: ReactNode }) {
   return (
     <ReactQueryProvider>
-      <RealtimeProvider>
-        <TooltipProvider delayDuration={250}>{children}</TooltipProvider>
-      </RealtimeProvider>
+      <TooltipProvider delayDuration={250}>{children}</TooltipProvider>
       <Toaster />
     </ReactQueryProvider>
   );

package/template/packages/frontend/src/theme/config.ts

@@ -1,9 +1,10 @@
+import { appIdentity } from '@app/config/identity';
 import type { ThemeProviderProps } from '@wrksz/themes/next';
 
 export type AppTheme = 'light' | 'dark';
 
 export const appThemes: readonly [AppTheme, AppTheme] = ['light', 'dark'];
-export const themeStorageKey = 'stitchkit-starter-theme';
+export const themeStorageKey = `${appIdentity.slug}-theme`;
 
 export const themeProviderConfig = {
   themes: appThemes,

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

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

package/template/scripts/dev-lan.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test';
+import { developmentEnvironment } from './dev';
+import { privateLanAddresses, selectLanAddress } from './dev-lan';
+
+describe('LAN HTTPS address selection', () => {
+  test('normal development clears every LAN-only process variable', () => {
+    expect(developmentEnvironment()).toMatchObject({
+      DEV_HTTPS_CA: '',
+      DEV_HTTPS_CERT: '',
+      DEV_HTTPS_KEY: '',
+      NODE_EXTRA_CA_CERTS: '',
+    });
+    expect(developmentEnvironment({ DEV_HTTPS_CERT: '/cert.pem' }).DEV_HTTPS_CERT).toBe(
+      '/cert.pem',
+    );
+  });
+
+  test('keeps private IPv4 interfaces and ignores public/internal addresses', () => {
+    expect(
+      privateLanAddresses({
+        eth0: [
+          {
+            address: '192.168.1.20',
+            netmask: '',
+            family: 'IPv4',
+            mac: '',
+            internal: false,
+            cidr: null,
+          },
+          {
+            address: '8.8.8.8',
+            netmask: '',
+            family: 'IPv4',
+            mac: '',
+            internal: false,
+            cidr: null,
+          },
+        ],
+        lo: [
+          {
+            address: '127.0.0.1',
+            netmask: '',
+            family: 'IPv4',
+            mac: '',
+            internal: true,
+            cidr: null,
+          },
+        ],
+      }),
+    ).toEqual(['192.168.1.20']);
+  });
+
+  test('auto-selects one address and fails on ambiguity', () => {
+    expect(selectLanAddress(['10.0.0.4'])).toBe('10.0.0.4');
+    expect(() => selectLanAddress(['10.0.0.4', '192.168.1.20'])).toThrow('ambiguous');
+    expect(() => selectLanAddress(['10.0.0.4'], '10.0.0.5')).toThrow('unavailable');
+  });
+});

package/template/scripts/dev-lan.ts

@@ -0,0 +1,176 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir, networkInterfaces } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { appIdentity } from '../packages/config/src/identity';
+import { childEnvironment, env } from '../packages/config/src/server';
+import { runDevelopment } from './dev';
+
+export function privateLanAddresses(
+  interfaces: ReturnType<typeof networkInterfaces>,
+): string[] {
+  const addresses = new Set<string>();
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries ?? []) {
+      if (entry.family !== 'IPv4' || entry.internal) continue;
+      const [first, second] = entry.address.split('.').map(Number);
+      if (
+        first === 10 ||
+        (first === 172 && second !== undefined && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168)
+      ) {
+        addresses.add(entry.address);
+      }
+    }
+  }
+  return [...addresses].sort();
+}
+
+export function selectLanAddress(addresses: readonly string[], requested?: string): string {
+  if (requested) {
+    if (!addresses.includes(requested)) {
+      throw new Error(
+        `Requested LAN address ${requested} is unavailable. Detected: ${addresses.join(', ') || '(none)'}`,
+      );
+    }
+    return requested;
+  }
+  if (addresses.length !== 1) {
+    throw new Error(
+      `LAN address is ${addresses.length === 0 ? 'unavailable' : 'ambiguous'}. Use --host <address>. Detected: ${addresses.join(', ') || '(none)'}`,
+    );
+  }
+  return addresses[0];
+}
+
+async function run(command: string[], environment?: Record<string, string>): Promise<string> {
+  const child = Bun.spawn(command, {
+    env: environment ? childEnvironment(environment) : undefined,
+    stdout: 'pipe',
+    stderr: 'inherit',
+  });
+  const output = await new Response(child.stdout).text();
+  const exitCode = await child.exited;
+  if (exitCode !== 0) throw new Error(`${command.join(' ')} failed with exit code ${exitCode}`);
+  return output.trim();
+}
+
+function requestedHost(args: readonly string[]): string | undefined {
+  const index = args.indexOf('--host');
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value) throw new Error('--host requires an IPv4 address');
+  return value;
+}
+
+async function ensureCertificates(host: string) {
+  if (!Bun.which('mkcert')) {
+    throw new Error(
+      'dev:lan requires mkcert. Install it with `brew install mkcert` (macOS/Linuxbrew) or the official prebuilt binary, then rerun.',
+    );
+  }
+  const caRoot = await run(['mkcert', '-CAROOT']);
+  const ca = join(caRoot, 'rootCA.pem');
+  if (!(await Bun.file(ca).exists())) await run(['mkcert', '-install']);
+
+  const directory = join(homedir(), '.local', 'share', appIdentity.slug, 'lan-https');
+  const cert = join(directory, 'leaf.pem');
+  const key = join(directory, 'leaf-key.pem');
+  const marker = join(directory, 'host');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const previous = await readFile(marker, 'utf8').catch(() => '');
+  if (
+    previous.trim() !== host ||
+    !(await Bun.file(cert).exists()) ||
+    !(await Bun.file(key).exists())
+  ) {
+    await run([
+      'mkcert',
+      '-cert-file',
+      cert,
+      '-key-file',
+      key,
+      host,
+      'localhost',
+      '127.0.0.1',
+      '::1',
+    ]);
+    await writeFile(marker, `${host}\n`, { mode: 0o600 });
+  }
+  return { ca, cert, key };
+}
+
+async function isPortOccupied(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (occupied: boolean, socket?: { end(): void }) => {
+      if (settled) return;
+      settled = true;
+      resolve(occupied);
+      socket?.end();
+    };
+    void Bun.connect({
+      hostname: '127.0.0.1',
+      port,
+      socket: {
+        open: (socket) => finish(true, socket),
+        data: () => undefined,
+        close: () => finish(false),
+        error: () => finish(false),
+      },
+    }).catch(() => finish(false));
+  });
+}
+
+async function assertDevelopmentPortsAvailable(): Promise<void> {
+  const processList = await run(['pm2', 'jlist']);
+  const onlineNames = new Set(
+    z
+      .array(
+        z.object({
+          name: z.string(),
+          pm2_env: z.object({ status: z.string() }),
+        }),
+      )
+      .parse(JSON.parse(processList))
+      .filter((process) => process.pm2_env.status === 'online')
+      .map((process) => process.name),
+  );
+  const expected = new Map([
+    [env.WEB_PORT, `${appIdentity.slug}-frontend-dev`],
+    [env.API_PORT, `${appIdentity.slug}-backend-dev`],
+  ]);
+  for (const [port, owner] of expected) {
+    if ((await isPortOccupied(port)) && !onlineNames.has(owner)) {
+      throw new Error(`Port ${port} is occupied by a process outside ${owner}`);
+    }
+  }
+}
+
+if (import.meta.main) {
+  if (env.NODE_ENV !== 'development') {
+    throw new Error('dev:lan is development-only');
+  }
+  const host = selectLanAddress(
+    privateLanAddresses(networkInterfaces()),
+    requestedHost(Bun.argv),
+  );
+  await assertDevelopmentPortsAvailable();
+  const certificates = await ensureCertificates(host);
+  const apiOrigin = `https://${host}:${env.API_PORT}`;
+  const webOrigin = `https://${host}:${env.WEB_PORT}`;
+  await runDevelopment({
+    CORS_ORIGIN: webOrigin,
+    DEV_HTTPS_CA: certificates.ca,
+    DEV_HTTPS_CERT: certificates.cert,
+    DEV_HTTPS_KEY: certificates.key,
+    INTERNAL_API_URL: apiOrigin,
+    NEXT_PUBLIC_API_URL: apiOrigin,
+    NEXT_PUBLIC_WEB_URL: webOrigin,
+    NODE_EXTRA_CA_CERTS: certificates.ca,
+  });
+  console.log(`${appIdentity.name} trusted LAN development is running`);
+  console.log(`Web: ${webOrigin}/en`);
+  console.log(`API: ${apiOrigin}`);
+  console.log(`Device CA setup: ${apiOrigin}/__dev/lan`);
+}

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,67 +1,23 @@
-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 { 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' });
-  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())),
+});