create-stitchkit 0.2.0 → 0.3.1

package/template/packages/backend/src/surface.snapshot.json

@@ -0,0 +1,18 @@
+[
+  {
+    "service": "system",
+    "action": "status",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "58b078ade3ee6167",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/system/status"
+      }
+    ],
+    "tools": {}
+  }
+]

package/template/packages/backend/src/surface.ts

@@ -1,7 +1,8 @@
 import { env } from '@app/config';
 import { createSocketIOServer } from 'stitchkit/server';
+import { createSystemService } from './transport/system-service';
 
 export async function createSurface() {
   const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN } });
-  return { socket, services: [] };
+  return { socket, services: [createSystemService()] };
 }

package/template/packages/backend/src/tools.ts

@@ -5,11 +5,14 @@ const { services, socket } = await createSurface();
 
 try {
   const surface = { services };
+  const toolNames = listToolNames(surface)
+    .filter((tool) => tool.transports.some((transport) => transport !== 'HTTP'))
+    .map((tool) => tool.name);
   console.log(
     JSON.stringify(
       {
         manifest: buildToolManifest({ services, transport: 'AGENT' }),
-        names: listToolNames(surface),
+        names: toolNames,
         transports: summarizeTransports(surface),
       },
       null,
@@ -17,5 +20,5 @@ try {
     ),
   );
 } finally {
-  await socket.io.close();
+  await socket.close();
 }

package/template/packages/backend/src/transport/errors.ts

@@ -11,6 +11,7 @@ const codeMap: Record<StitchErrorCode, string> = {
   CONFLICT: 'conflict',
   RATE_LIMITED: 'rate_limited',
   INTERNAL_SERVER_ERROR: 'internal_error',
+  REALTIME_CONTRACT_VIOLATION: 'internal_error',
 };
 
 export const onError = createErrorHook({

package/template/packages/backend/src/transport/system-service.ts

@@ -0,0 +1,8 @@
+import { type SystemStatus, systemContract } from '@app/shared';
+import { implement } from 'stitchkit/server';
+
+export function createSystemService() {
+  return implement(systemContract, {
+    status: (): SystemStatus => ({ status: 'ok' }),
+  });
+}

package/template/packages/config/src/server.ts

@@ -16,10 +16,7 @@ export const env = createEnv({
     INTERNAL_API_URL: z.url(),
     NEXT_PUBLIC_WEB_URL: z.url(),
     LOG_FORMAT: z.enum(['pretty', 'json']).default('pretty'),
-    CORS_ORIGIN: z.string().min(1).default('*'),
-    DEV_HTTPS_CERT: z.string().min(1).optional(),
-    DEV_HTTPS_KEY: z.string().min(1).optional(),
-    DEV_HTTPS_CA: z.string().min(1).optional(),
+    CORS_ORIGIN: z.url(),
     ...featureServerSchema,
   },
   runtimeEnv: process.env,

package/template/packages/frontend/package.json

@@ -12,7 +12,6 @@
   },
   "dependencies": {
     "@app/config": "workspace:*",
-    "@app/db": "workspace:*",
     "@app/shared": "workspace:*",
     "@radix-ui/react-alert-dialog": "^1.1.23",
     "@radix-ui/react-avatar": "^1.2.6",

package/template/packages/frontend/src/lib/query-client.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'bun:test';
+import { getQueryClient } from './query-client';
+
+describe('query dehydration policy', () => {
+  test('includes successful prefetched data and pending streamed queries', () => {
+    const queryClient = getQueryClient();
+    queryClient.setQueryData(['prefetched-project'], { id: 'project-1' });
+    void queryClient.prefetchQuery({
+      queryKey: ['pending-project'],
+      queryFn: () => new Promise(() => undefined),
+    });
+
+    const shouldDehydrate = queryClient.getDefaultOptions().dehydrate?.shouldDehydrateQuery;
+    if (!shouldDehydrate) throw new Error('dehydration policy is required');
+    const successful = queryClient.getQueryCache().find({ queryKey: ['prefetched-project'] });
+    const pending = queryClient.getQueryCache().find({ queryKey: ['pending-project'] });
+    if (!successful || !pending) throw new Error('test queries were not created');
+
+    expect(shouldDehydrate(successful)).toBe(true);
+    expect(shouldDehydrate(pending)).toBe(true);
+  });
+});

package/template/packages/frontend/src/lib/query-client.ts

@@ -1,11 +1,19 @@
-import { isServer, QueryClient } from '@tanstack/react-query';
+import { defaultShouldDehydrateQuery, isServer, QueryClient } from '@tanstack/react-query';
 import { cache } from 'react';
 
 function createQueryClient(): QueryClient {
   return new QueryClient({
     defaultOptions: {
       queries: { staleTime: 30_000, retry: 1 },
-      dehydrate: { shouldDehydrateQuery: (query) => query.state.status === 'pending' },
+      dehydrate: {
+        // `pending` queries dehydrate too: a server component may kick off a
+        // prefetch without awaiting it, and streaming SSR hands the in-flight
+        // promise to the client, which resumes it instead of refetching. The
+        // default predicate would drop exactly those queries and reintroduce
+        // the client-side loading flash.
+        shouldDehydrateQuery: (query) =>
+          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
+      },
     },
   });
 }

package/template/packages/frontend/tsconfig.json

@@ -8,6 +8,12 @@
     "plugins": [{ "name": "next" }],
     "paths": { "@/*": ["./src/*"] }
   },
-  "include": ["next-env.d.ts", "src/**/*.ts", "src/**/*.tsx", ".next/types/**/*.ts"],
+  "include": [
+    "next-env.d.ts",
+    "next.config.ts",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
   "exclude": ["node_modules"]
 }

package/template/packages/shared/package.json

@@ -12,7 +12,6 @@
     "test": "bun test --pass-with-no-tests"
   },
   "dependencies": {
-    "@app/db": "workspace:*",
     "stitchkit": "catalog:",
     "zod": "^4.4.3"
   },

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

@@ -0,0 +1,19 @@
+import { createContractFactory } from 'stitchkit';
+import { SystemStatusSchema } from '../schemas/system';
+
+const { defineContract } = createContractFactory<'public'>({
+  toolExposure: 'explicit',
+});
+
+export const systemContract = defineContract(
+  { prefix: 'system', scope: 'public' },
+  {
+    status: {
+      method: 'GET',
+      path: '/status',
+      desc: 'Read application readiness',
+      output: SystemStatusSchema,
+      expose: ['HTTP'],
+    },
+  },
+);

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

@@ -1 +1,2 @@
-export {};
+export * from './contracts/system';
+export * from './schemas/system';

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

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+
+export const SystemStatusSchema = z.object({ status: z.literal('ok') });
+export type SystemStatus = z.infer<typeof SystemStatusSchema>;

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,13 +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';
+import { inheritToolingEnvironment } from './tooling-env';
 
 const root = resolve(import.meta.dir, '..');
 async function run(command: string[], environment?: Record<string, string>): Promise<void> {
   const child = Bun.spawn(command, {
     cwd: root,
-    env: environment ? childEnvironment(environment) : undefined,
+    env: environment ? inheritToolingEnvironment(environment) : undefined,
     stdin: 'inherit',
     stdout: 'inherit',
     stderr: 'inherit',
@@ -17,8 +17,15 @@ async function run(command: string[], environment?: Record<string, string>): Pro
 }
 
 export async function runDevelopment(environment?: Record<string, string>): Promise<void> {
-  await ensureLocalEnvironment(root);
-  const environmentForRun = developmentEnvironment(environment);
+  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'],
@@ -26,20 +33,22 @@ export async function runDevelopment(environment?: Record<string, string>): Prom
   );
 }
 
-export function developmentEnvironment(
+function assertToolAvailable(command: string, instruction: string): void {
+  if (!Bun.which(command)) throw new Error(`${command} is required. ${instruction}`);
+}
+
+export async function developmentEnvironment(
   overrides: Record<string, string> = {},
-): 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,
-    DEV_HTTPS_CERT: '',
-    DEV_HTTPS_KEY: '',
-    DEV_HTTPS_CA: '',
-    NODE_EXTRA_CA_CERTS: '',
     ...overrides,
   };
 }

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,7 +1,11 @@
+import { systemContract } from '@app/shared';
+import { createClient, createHttpClient } from 'stitchkit';
 import { z } from 'zod';
 import { runSurfaceConformance } from './surface-conformance';
-import { toolingEnv } from './tooling-env';
+import { loadToolingEnv } from './tooling-env';
+import { assertPublicWebSurface } from './web-surface-smoke';
 
+const toolingEnv = loadToolingEnv();
 const apiOrigin = toolingEnv.NEXT_PUBLIC_API_URL;
 
 async function json(path: string): Promise<unknown> {
@@ -11,13 +15,19 @@ async function json(path: string): Promise<unknown> {
 }
 
 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).some((path) => path.startsWith('/api/'))) {
-  throw new Error('Blank starter unexpectedly publishes application contracts');
+if (!Object.keys(openApi.paths).includes('/api/system/status')) {
+  throw new Error('System status contract is missing from OpenAPI');
 }
 
 await runSurfaceConformance({ apiOrigin });
+await assertPublicWebSurface(toolingEnv.NEXT_PUBLIC_WEB_URL);
 
-console.log('Blank runtime HTTP, OpenAPI and MCP smoke passed');
+console.log('Runtime HTTP, typed client, OpenAPI, MCP and public web smoke passed');

package/template/scripts/surface-conformance.ts

@@ -1,12 +1,18 @@
+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>;
@@ -45,11 +51,42 @@ async function readJson(url: string): Promise<unknown> {
   return response.json();
 }
 
-async function discoverMcpTools(
+/**
+ * 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[],
+  _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' } } },
@@ -57,18 +94,7 @@ async function discoverMcpTools(
   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;
-    }
+    return (await client.listTools()).tools.map((tool) => tool.name);
   } finally {
     await client.close();
   }
@@ -81,12 +107,24 @@ export async function runSurfaceConformance({
   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 {
@@ -96,10 +134,33 @@ export async function runSurfaceConformance({
       }
     }
   } finally {
-    await socket.io.close();
+    await socket.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.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/scripts/web-surface-smoke.ts

@@ -0,0 +1,28 @@
+const OG_IMAGE_PATH = '/api/og/en/themes';
+const SITEMAP_PATH = '/sitemap.xml';
+
+function publicUrl(origin: string, path: string): URL {
+  return new URL(path, new URL(origin).origin);
+}
+
+export async function assertPublicWebSurface(webOrigin: string): Promise<void> {
+  const image = await fetch(publicUrl(webOrigin, OG_IMAGE_PATH));
+  if (image.status !== 200) {
+    throw new Error(`GET ${OG_IMAGE_PATH} returned ${image.status}`);
+  }
+  const imageType = image.headers.get('content-type');
+  if (!imageType?.toLowerCase().startsWith('image/png')) {
+    throw new Error(`GET ${OG_IMAGE_PATH} returned ${imageType ?? 'no content type'}`);
+  }
+  if ((await image.arrayBuffer()).byteLength === 0) {
+    throw new Error(`GET ${OG_IMAGE_PATH} returned an empty image`);
+  }
+
+  const sitemap = await fetch(publicUrl(webOrigin, SITEMAP_PATH));
+  if (sitemap.status !== 200) {
+    throw new Error(`GET ${SITEMAP_PATH} returned ${sitemap.status}`);
+  }
+  if (!(await sitemap.text()).includes('/ru/ui/themes')) {
+    throw new Error(`GET ${SITEMAP_PATH} omitted the localized theme-system URL`);
+  }
+}