create-stitchkit 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ is declared in the template root catalog.
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-08-10
+
+### ⚠️ Breaking changes
+
+- **The default scaffold is now domain-free.** The repository example is explicit
+  so a new product does not need to dismantle demo code.
+  `bun create stitchkit my-app` now creates the blank base; use
+  `bun create stitchkit my-app --example repository` for the previous runnable example.
+
+### Added
+
+- **One generated application identity.** A validated `app.config.json` now drives
+  package, PM2, MCP, OpenAPI, CLI, SEO and theme identity from one edit point.
+- **Contract-derived surface conformance.** Generated runtime smoke compares the
+  registered HTTP and tool manifest with live OpenAPI and MCP discovery, while
+  explicit typed probes remain application-owned.
+- **Optional trusted LAN HTTPS.** `bun run dev:lan` uses mkcert, exact-origin CORS
+  and a development-only onboarding route for secure-context testing on physical
+  devices without changing ordinary development or production behavior.
+- **Agent-first extension guide.** Generated applications include an application-
+  scoped `AGENTS.md` and a complete schema-to-runtime feature workflow in
+  `docs/ADDING_A_FEATURE.md`.
+
 ## [0.1.1] — 2026-08-10
 
 ### Changed

package/README.md

@@ -14,11 +14,18 @@ API, Prisma/PostgreSQL, typed shared contracts, Socket.IO, MCP, CLI tools and a
 complete production UI system.
 
 It uses one conventional `packages/*` namespace: `backend`, `frontend`,
-`config`, `db` and `shared`. The copied application keeps the neutral
-`stitchkit-starter` identity until its owner explicitly renames it.
+`config`, `db` and `shared`. The destination name becomes the generated slug;
+`--display-name` sets the human title. Both are recorded once in
+`app.config.json` and drive package, process, transport, UI and SEO identity.
 
-Its runnable example is the Stitchkit Starter: one configurable GitHub repository
-is persisted through a server-side PostgreSQL cache, including a Prisma-backed
+The default scaffold is domain-free. To add the runnable repository example:
+
+```bash
+bun create stitchkit my-app --example repository
+```
+
+The optional example uses one configurable GitHub repository persisted through a
+server-side PostgreSQL cache, including a Prisma-backed
 visibility enum that flows through the shared schema and typed client. `/en/ui`
 presents every reusable primitive and composition. Every public page ships with
 localized metadata, canonical and language alternatives, sitemap coverage and a

package/dist/cli.js

@@ -2,17 +2,19 @@
 // @bun
 
 // src/cli.ts
-import { basename as basename2, resolve as resolve2 } from "path";
+import { basename as basename3, resolve as resolve2 } from "path";
 var {spawn } = globalThis.Bun;
 
 // src/options.ts
 var HELP = `Create a production-shaped Stitchkit application.
 
 Usage:
-  bun create stitchkit <directory> [--no-install]
+  bun create stitchkit <directory> [--display-name "Product Name"] [--example repository] [--no-install]
 
 Options:
   --no-install  Generate files without installing dependencies
+  --example     Add an isolated runnable example (supported: repository)
+  --display-name  Set the initial public application name
   --help        Show this help
 `;
 function helpText() {
@@ -21,11 +23,26 @@ function helpText() {
 function parseOptions(args) {
   if (args.includes("--help") || args.includes("-h"))
     return "help";
-  const unknown = args.filter((arg) => arg.startsWith("-") && arg !== "--no-install");
+  const unknown = args.filter((arg) => arg.startsWith("-") && arg !== "--no-install" && arg !== "--example" && arg !== "--display-name");
   if (unknown.length > 0) {
     throw new Error(`Unknown option: ${unknown[0]}`);
   }
-  const positionals = args.filter((arg) => !arg.startsWith("-"));
+  const exampleFlagIndex = args.indexOf("--example");
+  const example = exampleFlagIndex === -1 ? undefined : args[exampleFlagIndex + 1];
+  if (exampleFlagIndex !== -1 && example === undefined) {
+    throw new Error("--example requires a value");
+  }
+  if (example !== undefined && example !== "repository") {
+    throw new Error(`Unknown example: ${example}`);
+  }
+  const displayNameFlagIndex = args.indexOf("--display-name");
+  const displayName = displayNameFlagIndex === -1 ? undefined : args[displayNameFlagIndex + 1];
+  if (displayNameFlagIndex !== -1 && displayName === undefined) {
+    throw new Error("--display-name requires a value");
+  }
+  const consumedExampleIndex = exampleFlagIndex === -1 ? -1 : exampleFlagIndex + 1;
+  const consumedDisplayNameIndex = displayNameFlagIndex === -1 ? -1 : displayNameFlagIndex + 1;
+  const positionals = args.filter((arg, index) => !arg.startsWith("-") && index !== consumedExampleIndex && index !== consumedDisplayNameIndex);
   if (positionals.length !== 1) {
     throw new Error("Exactly one destination directory is required");
   }
@@ -34,14 +51,48 @@ function parseOptions(args) {
     throw new Error("Destination directory is required");
   return {
     destination,
-    install: !args.includes("--no-install")
+    install: !args.includes("--no-install"),
+    ...example && { example },
+    ...displayName && { displayName }
   };
 }
 
 // src/scaffold.ts
 import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
 import { homedir } from "os";
-import { basename, dirname, join, parse, relative, resolve, sep } from "path";
+import { basename as basename2, dirname, join, parse, relative, resolve, sep } from "path";
+
+// src/identity.ts
+import { basename } from "path";
+import { z } from "zod";
+var ApplicationSlugSchema = z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, numbers and single hyphens (for example: talk-control)");
+var ApplicationIdentitySchema = z.object({
+  slug: ApplicationSlugSchema,
+  name: z.string().trim().min(1).max(80),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, "Use a semantic version such as 0.1.0"),
+  description: z.object({
+    en: z.string().trim().min(1),
+    ru: z.string().trim().min(1)
+  })
+});
+function displayNameFromSlug(slug) {
+  return slug.split("-").map((part) => `${part[0]?.toUpperCase()}${part.slice(1)}`).join(" ");
+}
+function createApplicationIdentity(destination, displayName) {
+  const slug = ApplicationSlugSchema.parse(basename(destination));
+  const name = displayName?.trim() || displayNameFromSlug(slug);
+  return ApplicationIdentitySchema.parse({
+    slug,
+    name,
+    version: "0.1.0",
+    description: {
+      en: `${name} is a production application built with Stitchkit.`,
+      ru: `${name} \u2014 production-\u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \u043D\u0430 Stitchkit.`
+    }
+  });
+}
+
+// src/scaffold.ts
 var TEXT_EXTENSIONS = new Set([
   ".cjs",
   ".css",
@@ -62,7 +113,9 @@ var TEXT_EXTENSIONS = new Set([
 ]);
 var TEMPLATE_RENAMES = new Map([
   ["_env", ".env"],
+  ["_env.append", ".env"],
   ["_env.example", ".env.example"],
+  ["_env.example.append", ".env.example"],
   ["_gitignore", ".gitignore"]
 ]);
 var IGNORED_DIRECTORIES = new Set([
@@ -82,7 +135,7 @@ function isTemplateSourcePathIncluded(sourcePath) {
     return false;
   if (normalized === "packages/db/src/generated" || normalized.startsWith("packages/db/src/generated/"))
     return false;
-  const name = basename(normalized);
+  const name = basename2(normalized);
   return name !== ".env" && name !== "next-env.d.ts" && !name.endsWith(".log") && !name.endsWith(".tsbuildinfo");
 }
 function shouldIncludeTemplatePath(templateDirectory, sourcePath) {
@@ -142,7 +195,8 @@ async function collectMaterialisedFiles(templateDirectory, directory, files) {
     files.push({
       sourcePath: portablePath(sourceRelativePath),
       outputPath: portablePath(outputRelativePath),
-      content
+      content,
+      append: entry.name.endsWith(".append")
     });
   }
 }
@@ -155,15 +209,43 @@ async function writeMaterialisedFiles(destination, files) {
   for (const file of files) {
     const targetPath = join(destination, file.outputPath);
     await mkdir(dirname(targetPath), { recursive: true });
-    await writeFile(targetPath, file.content);
+    if (file.append) {
+      if (typeof file.content !== "string") {
+        throw new Error(`Append template entries must contain text: ${file.sourcePath}`);
+      }
+      const existing = await readFile(targetPath, "utf8");
+      await writeFile(targetPath, `${existing.trimEnd()}
+${file.content.trimStart()}`);
+    } else {
+      await writeFile(targetPath, file.content);
+    }
   }
 }
-async function scaffoldProject(templateDirectory, destination) {
+async function scaffoldProject(templateDirectory, destination, options = {}) {
   const resolvedDestination = resolve(destination);
+  const identity = createApplicationIdentity(resolvedDestination, options.displayName);
   const destinationExisted = await assertDestinationAvailable(resolvedDestination);
   await mkdir(resolvedDestination, { recursive: true });
   try {
     await writeMaterialisedFiles(resolvedDestination, await materialiseTemplateFiles(templateDirectory));
+    if (options.overlayDirectory) {
+      await writeMaterialisedFiles(resolvedDestination, await materialiseTemplateFiles(options.overlayDirectory));
+    }
+    await writeFile(join(resolvedDestination, "app.config.json"), `${JSON.stringify(identity, undefined, 2)}
+`);
+    const manifestPath = join(resolvedDestination, "package.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    manifest.name = identity.slug;
+    await writeFile(manifestPath, `${JSON.stringify(manifest, undefined, 2)}
+`);
+    const lockPath = join(resolvedDestination, "bun.lock");
+    const lock = await readFile(lockPath, "utf8");
+    await writeFile(lockPath, lock.replace(/"name"\s*:\s*"stitchkit-starter"/, `"name": "${identity.slug}"`));
+    for (const environmentPath of [".env", ".env.example"]) {
+      const fullPath = join(resolvedDestination, environmentPath);
+      const environment = await readFile(fullPath, "utf8");
+      await writeFile(fullPath, environment.replaceAll("stitchkit_starter", identity.slug.replaceAll("-", "_")));
+    }
   } catch (error) {
     if (!destinationExisted) {
       await rm(resolvedDestination, { recursive: true, force: true });
@@ -185,7 +267,11 @@ async function run(args) {
     }
     const destination = resolve2(options.destination);
     const templateDirectory = resolve2(import.meta.dir, "../template");
-    await scaffoldProject(templateDirectory, destination);
+    const overlayDirectory = options.example ? resolve2(import.meta.dir, `../examples/${options.example}`) : undefined;
+    await scaffoldProject(templateDirectory, destination, {
+      ...overlayDirectory && { overlayDirectory },
+      ...options.displayName && { displayName: options.displayName }
+    });
     if (options.install) {
       const install = spawn(["bun", "install"], {
         cwd: destination,
@@ -197,8 +283,9 @@ async function run(args) {
       if (exitCode !== 0)
         throw new Error(`bun install failed with exit code ${exitCode}`);
     }
+    const mode = options.example ? ` with the ${options.example} example` : "";
     process.stdout.write(`
-Created Stitchkit Starter in ${basename2(destination)}
+Created ${options.displayName ?? basename3(destination)}${mode}
 
 `);
     process.stdout.write(`  cd ${options.destination}

package/examples/repository/_env.append

@@ -0,0 +1,3 @@
+GITHUB_REPOSITORY=max-listov/stitchkit
+GITHUB_CACHE_TTL_SECONDS=900
+# GITHUB_TOKEN=github_pat_...

package/examples/repository/_env.example.append

@@ -0,0 +1,4 @@
+GITHUB_REPOSITORY=max-listov/stitchkit
+GITHUB_CACHE_TTL_SECONDS=900
+# Optional. Authenticated conditional requests have a higher GitHub rate limit.
+# GITHUB_TOKEN=github_pat_...

package/examples/repository/e2e/repository.spec.ts

@@ -0,0 +1,19 @@
+import { expect, test } from '@playwright/test';
+
+test('renders and refreshes the repository example', async ({ page }) => {
+  await page.route('**/api/repository/refresh', async (route) => {
+    await new Promise((resolve) => setTimeout(resolve, 750));
+    await route.continue();
+  });
+  await page.goto('/en');
+  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
+
+  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/);
+});

package/{template → examples/repository}/packages/backend/src/domain/repository/github-cache.ts

@@ -1,4 +1,5 @@
 import { env } from '@app/config';
+import { appIdentity } from '@app/config/identity';
 import { RepositoryVisibility } from '@app/db';
 import type { RepositorySnapshot } from '@app/shared';
 import { z } from 'zod';
@@ -80,7 +81,7 @@ const snapshotStore: RepositorySnapshotStore = {
 function githubHeaders(): Headers {
   const headers = new Headers({
     Accept: 'application/vnd.github+json',
-    'User-Agent': 'stitchkit-starter',
+    'User-Agent': appIdentity.slug,
     'X-GitHub-Api-Version': '2026-03-10',
   });
   if (env.GITHUB_TOKEN) headers.set('Authorization', `Bearer ${env.GITHUB_TOKEN}`);

package/examples/repository/packages/backend/src/surface.ts

@@ -0,0 +1,14 @@
+import { env } from '@app/config';
+import type { ClientToServerEvents, ServerToClientEvents } from '@app/shared';
+import { createSocketIOServer } from 'stitchkit/server';
+import { createRepositoryService } from './transport/repository-service';
+
+export async function createSurface() {
+  const socket = await createSocketIOServer<ServerToClientEvents, ClientToServerEvents>({
+    cors: { origin: env.CORS_ORIGIN },
+  });
+  const repositoryService = createRepositoryService((snapshot) =>
+    socket.io.emit('repository:refreshed', snapshot),
+  );
+  return { socket, services: [repositoryService] };
+}

package/examples/repository/packages/config/src/features.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+
+export const featureServerSchema = {
+  GITHUB_REPOSITORY: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
+  GITHUB_CACHE_TTL_SECONDS: z.coerce.number().int().positive().default(900),
+  GITHUB_TOKEN: z.string().min(1).optional(),
+};

package/examples/repository/packages/db/schema.prisma

@@ -0,0 +1,31 @@
+generator client {
+  provider = "prisma-client"
+  output   = "./src/generated"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+enum RepositoryVisibility {
+  PUBLIC
+  PRIVATE
+  INTERNAL
+}
+
+model RepositorySnapshot {
+  fullName            String   @id
+  description         String?
+  htmlUrl             String
+  language            String?
+  visibility          RepositoryVisibility @default(PUBLIC)
+  stars               Int
+  forks               Int
+  openIssues          Int
+  commitCount         Int
+  latestCommitSha     String?
+  latestCommitMessage String?
+  latestCommittedAt   DateTime?
+  fetchedAt           DateTime
+  expiresAt           DateTime
+}

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

@@ -0,0 +1,45 @@
+import { appIdentity } from '@app/config/identity';
+import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
+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';
+
+export const dynamic = 'force-dynamic';
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ locale: string }>;
+}): Promise<Metadata> {
+  const { locale } = await params;
+  return createPageMetadata('home', LocaleSchema.parse(locale));
+}
+
+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={appIdentity.name}
+        applicationDescription={appIdentity.description[appLocale]}
+        heroTitle={t('heroTitle')}
+        catalogueLabel={t('ui')}
+        locale={appLocale}
+      />
+    </HydrationBoundary>
+  );
+}

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

@@ -0,0 +1,151 @@
+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';
+import { Link } from '@/i18n/navigation';
+import { absoluteSiteUrl } from '@/lib/seo/metadata';
+import { getSeoPage, SITE_NAME } from '@/lib/seo/pages';
+import { cn } from '@/lib/utils/cn';
+
+interface StarterPageProps {
+  applicationName: string;
+  applicationDescription: string;
+  heroTitle: string;
+  catalogueLabel: string;
+  locale: AppLocale;
+}
+
+const architecture = [
+  {
+    name: 'Frontend',
+    detail: 'Web',
+    technologies: [
+      { name: 'Next.js', icon: '/icons/next.svg' },
+      { name: 'React', icon: '/icons/react.svg' },
+      { name: 'Tailwind CSS', icon: '/icons/tailwind.svg' },
+      { name: 'React Query', icon: '/icons/react-query.svg' },
+    ],
+  },
+  {
+    name: 'Backend',
+    detail: 'API',
+    technologies: [
+      { name: 'Stitchkit', icon: '/mascot-stitch.png' },
+      { name: 'Bun', icon: '/icons/bun.svg' },
+      { name: 'Zod', icon: '/icons/zod.svg' },
+    ],
+  },
+  {
+    name: 'Data',
+    detail: 'Storage',
+    technologies: [
+      { name: 'PostgreSQL', icon: '/icons/postgresql.svg' },
+      { name: 'Prisma', icon: '/icons/prisma.svg', invertInDark: true },
+    ],
+  },
+  {
+    name: 'Tooling',
+    detail: 'Quality',
+    technologies: [
+      { name: 'TypeScript', icon: '/icons/typescript.svg' },
+      { name: 'TSConfig', icon: '/icons/tsconfig.svg' },
+      { name: 'Biome', icon: '/icons/biome.svg' },
+    ],
+  },
+];
+
+export function StarterPage({
+  applicationName,
+  applicationDescription,
+  heroTitle,
+  catalogueLabel,
+  locale,
+}: StarterPageProps) {
+  const homeSeo = getSeoPage('home', locale);
+  const structuredData = {
+    '@context': 'https://schema.org',
+    '@type': 'SoftwareApplication',
+    name: SITE_NAME,
+    applicationCategory: 'DeveloperApplication',
+    operatingSystem: 'Web',
+    url: absoluteSiteUrl(`/${locale}`),
+    description: homeSeo.description,
+  };
+
+  return (
+    <main className='h-svh overflow-y-auto bg-background lg:overflow-hidden'>
+      <script type='application/ld+json'>{JSON.stringify(structuredData)}</script>
+      <div className='mx-auto flex min-h-full w-full max-w-7xl flex-col px-5 lg:h-full lg:px-8'>
+        <header className='flex h-16 shrink-0 items-center justify-between'>
+          <div className='flex min-w-0 items-center gap-2 font-medium'>
+            <BrandMark priority />
+            <span className='truncate'>{applicationName}</span>
+          </div>
+          <div className='flex items-center gap-2'>
+            <LanguageSwitcher />
+            <ThemeToggle />
+            <Link
+              aria-label={catalogueLabel}
+              className={cn(buttonVariants({ variant: 'outline', size: 'sm' }))}
+              href='/ui'
+            >
+              <span className='hidden sm:inline'>{catalogueLabel}</span>
+              <IconArrowUpRight />
+            </Link>
+          </div>
+        </header>
+
+        <div className='flex flex-1 flex-col items-center justify-center py-8 text-center lg:min-h-0 lg:py-5'>
+          <section className='flex w-full min-w-0 flex-col items-center'>
+            <h1 className='max-w-4xl font-display text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl lg:leading-[0.96]'>
+              {heroTitle}
+            </h1>
+            <p className='mt-5 max-w-3xl text-base leading-7 text-muted-foreground lg:text-lg'>
+              {applicationDescription}
+            </p>
+
+            <div className='mt-8 w-full max-w-4xl'>
+              <div className='grid grid-cols-2 overflow-hidden rounded-xl border border-border bg-card text-left sm:grid-cols-4'>
+                {architecture.map((item) => (
+                  <div
+                    className='min-w-0 border-border px-3 py-3 odd:border-r first:border-b second:border-b sm:border-r sm:border-b-0 sm:last:border-r-0 sm:px-4'
+                    key={item.name}
+                  >
+                    <div className='flex min-w-0 items-baseline gap-2'>
+                      <p className='truncate text-sm font-medium'>{item.name}</p>
+                      <p className='text-xs text-muted-foreground'>{item.detail}</p>
+                    </div>
+                    <div className='mt-2 flex min-h-6 items-center gap-2'>
+                      {item.technologies.map((technology) => (
+                        <Image
+                          alt={technology.name}
+                          className={
+                            technology.invertInDark
+                              ? 'technology-icon-invert-dark size-5 shrink-0 object-contain'
+                              : 'size-5 shrink-0 object-contain'
+                          }
+                          height={20}
+                          key={technology.icon}
+                          src={technology.icon}
+                          title={technology.name}
+                          width={20}
+                        />
+                      ))}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+
+            <div className='mt-5 w-full'>
+              <RepositorySummary />
+            </div>
+          </section>
+        </div>
+      </div>
+    </main>
+  );
+}

package/examples/repository/packages/frontend/src/providers/index.tsx

@@ -0,0 +1,18 @@
+'use client';
+
+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>
+      <Toaster />
+    </ReactQueryProvider>
+  );
+}

package/examples/repository/packages/shared/src/index.ts

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

package/examples/repository/scripts/runtime-smoke.ts

@@ -0,0 +1,91 @@
+import { RepositorySnapshotSchema } from '@app/shared';
+import { io } from 'socket.io-client';
+import { z } from 'zod';
+import { defineSurfaceProbe, 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}`);
+  return response.json();
+}
+
+z.object({ status: z.literal('ok') }).parse(await json('/health'));
+
+await runSurfaceConformance({
+  apiOrigin,
+  probes: [
+    defineSurfaceProbe({
+      name: 'repository refresh lifecycle',
+      input: z.object({ path: z.literal('/api/repository/refresh') }),
+      fixture: { path: '/api/repository/refresh' },
+      output: RepositorySnapshotSchema,
+      run: async ({ path }) => {
+        const socket = io(apiOrigin, { transports: ['websocket'] });
+        try {
+          await new Promise<void>((resolve, reject) => {
+            const timeout = setTimeout(
+              () => reject(new Error('Socket.IO connection timed out')),
+              5_000,
+            );
+            const onConnect = () => {
+              clearTimeout(timeout);
+              socket.off('connect_error', onConnectError);
+              resolve();
+            };
+            const onConnectError = (error: Error) => {
+              clearTimeout(timeout);
+              socket.off('connect', onConnect);
+              reject(error);
+            };
+            socket.once('connect', onConnect);
+            socket.once('connect_error', onConnectError);
+          });
+          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);
+            });
+          });
+          const refreshed = RepositorySnapshotSchema.parse(
+            await json(path, { 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');
+          }
+          return refreshed;
+        } finally {
+          socket.close();
+        }
+      },
+    }),
+  ],
+});
+
+{
+  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');
+  }
+}
+
+console.log('Runtime HTTP, OpenAPI, Socket.IO and MCP smoke passed');