create-stitchkit 0.1.1 → 0.3.0

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

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import type { HttpMethod } from 'stitchkit/contract';
+import type { OpenApiDocument, ServiceDef } from 'stitchkit/server';
+import { listToolNames } from 'stitchkit/tools';
+import { z } from 'zod';
+
+export interface SurfaceManifestOperation {
+  service: string;
+  action: string;
+  scope: string;
+  hasInput: boolean;
+  hasOutput: boolean;
+  /** Digest of the input JSON Schema — a TYPE change flips it, not just presence. */
+  inputShape: string | null;
+  /** Digest of the output JSON Schema. */
+  outputShape: string | null;
+  http: Array<{ method: HttpMethod; path: string }>;
+  tools: Partial<Record<'MCP' | 'AGENT' | 'CLI', string>>;
+}
+
+function schemaShape(schema: z.ZodType | undefined, io: 'input' | 'output'): string | null {
+  if (!schema) return null;
+  const document = z.toJSONSchema(schema, { io, unrepresentable: 'any' });
+  return createHash('sha256').update(JSON.stringify(document)).digest('hex').slice(0, 16);
+}
+
+function joinPath(...parts: Array<string | undefined>): string {
+  const joined = parts
+    .filter((part): part is string => Boolean(part))
+    .map((part) => part.replace(/^\/+|\/+$/g, ''))
+    .filter(Boolean)
+    .join('/');
+  return `/${joined}`;
+}
+
+function operationKey(service: string, action: string): string {
+  return `${service}\u0000${action}`;
+}
+
+function sorted(values: Iterable<string>): string[] {
+  return [...values].sort((left, right) => left.localeCompare(right));
+}
+
+function assertSameSet(
+  label: string,
+  expectedValues: Iterable<string>,
+  actualValues: Iterable<string>,
+) {
+  const expected = sorted(expectedValues);
+  const actual = sorted(actualValues);
+  if (
+    expected.length === actual.length &&
+    expected.every((value, index) => value === actual[index])
+  ) {
+    return;
+  }
+  throw new Error(
+    `${label} surface mismatch\nexpected: ${expected.join(', ') || '(empty)'}\nactual: ${actual.join(', ') || '(empty)'}`,
+  );
+}
+
+export function buildSurfaceManifest(
+  services: readonly ServiceDef[],
+  pathPrefix = '/api',
+): SurfaceManifestOperation[] {
+  const operations = new Map<string, SurfaceManifestOperation>();
+  for (const service of services) {
+    for (const method of Object.values(service.methods)) {
+      const key = operationKey(service.name, method.key);
+      if (operations.has(key)) {
+        throw new Error(`Duplicate operation identity ${service.name}.${method.key}`);
+      }
+      operations.set(key, {
+        service: service.name,
+        action: method.key,
+        scope: method.scope ?? service.scope,
+        hasInput: Boolean(method.inputSchema),
+        hasOutput: Boolean(method.outputSchema),
+        inputShape: schemaShape(method.inputSchema, 'input'),
+        outputShape: schemaShape(method.outputSchema, 'output'),
+        http:
+          !method.expose || method.expose.includes('HTTP')
+            ? [
+                {
+                  method: method.method,
+                  path: joinPath(pathPrefix, service.prefix, method.path).replace(
+                    /:([^/]+)/g,
+                    '{$1}',
+                  ),
+                },
+              ]
+            : [],
+        tools: {},
+      });
+    }
+  }
+  for (const tool of listToolNames({ services })) {
+    const operation = operations.get(operationKey(tool.service, tool.method));
+    if (!operation) {
+      throw new Error(`Tool ${tool.name} has no contract identity`);
+    }
+    for (const transport of tool.transports) {
+      if (transport !== 'HTTP') operation.tools[transport] = tool.name;
+    }
+  }
+  return [...operations.values()].sort(
+    (left, right) =>
+      left.service.localeCompare(right.service) || left.action.localeCompare(right.action),
+  );
+}
+
+/**
+ * Compare the LIVE manifest against the committed snapshot — the external
+ * anchor that a source-level change (an `expose` edit, a schema type change, a
+ * scope change) cannot move along with itself. Regenerate deliberately with
+ * `bun run surface:snapshot` and review the diff.
+ */
+export function assertManifestMatchesSnapshot(
+  manifest: readonly SurfaceManifestOperation[],
+  snapshot: readonly SurfaceManifestOperation[],
+): void {
+  const actual = JSON.stringify(manifest, null, 2);
+  const expected = JSON.stringify(snapshot, null, 2);
+  if (actual !== expected) {
+    throw new Error(
+      `Declared surface diverged from the committed snapshot — if the change is intended, regenerate it with "bun run surface:snapshot" and review the diff.\nsnapshot: ${expected}\nactual: ${actual}`,
+    );
+  }
+}
+
+export function assertSurfaceConformance({
+  manifest,
+  openApi,
+  mcpToolNames,
+  agentToolNames,
+  cliToolNames,
+  metadata = 'require',
+}: {
+  manifest: readonly SurfaceManifestOperation[];
+  openApi: Pick<OpenApiDocument, 'paths'>;
+  mcpToolNames: readonly string[];
+  agentToolNames: readonly string[];
+  cliToolNames: readonly string[];
+  /**
+   * `'require'` (default) — the OpenAPI document must carry `x-stitchkit-*`
+   * metadata and it is compared; `'ignore'` — an explicitly declared mode for
+   * standard documents. A silent skip is not an option.
+   */
+  metadata?: 'require' | 'ignore';
+}): void {
+  const openApiOperations = Object.entries(openApi.paths).flatMap(([path, item]) =>
+    Object.entries(item)
+      .filter(([method]) => ['get', 'post', 'put', 'patch', 'delete', 'head'].includes(method))
+      .map(([method, operation]) => ({ method: method.toUpperCase(), path, operation })),
+  );
+  assertSameSet(
+    'HTTP/OpenAPI',
+    manifest.flatMap((operation) =>
+      operation.http.map((entry) => `${entry.method}:${entry.path}`),
+    ),
+    openApiOperations.map(({ method, path }) => `${method}:${path}`),
+  );
+  const carriesContractMetadata = openApiOperations.some(({ operation }) =>
+    OpenApiOperationMetadataPresenceSchema.parse(operation),
+  );
+  if (metadata === 'require' && openApiOperations.length > 0 && !carriesContractMetadata) {
+    throw new Error(
+      'OpenAPI document carries no x-stitchkit-* contract metadata — pass metadata: "ignore" only for a deliberately standard document',
+    );
+  }
+  if (metadata === 'require' && carriesContractMetadata) {
+    assertSameSet(
+      'HTTP/OpenAPI contract metadata',
+      manifest.flatMap((operation) =>
+        operation.http.map(
+          (entry) =>
+            `${entry.method}:${entry.path}:${operation.scope}:${operation.hasInput}:${operation.hasOutput}`,
+        ),
+      ),
+      openApiOperations.map(({ method, path, operation }) => {
+        const metadata = OpenApiOperationMetadataSchema.parse(operation);
+        return `${method}:${path}:${metadata['x-stitchkit-scope']}:${metadata['x-stitchkit-has-input']}:${metadata['x-stitchkit-has-output']}`;
+      }),
+    );
+  }
+  assertSameSet(
+    'MCP discovery',
+    manifest.flatMap((operation) => (operation.tools.MCP ? [operation.tools.MCP] : [])),
+    mcpToolNames,
+  );
+  assertSameSet(
+    'AGENT mount',
+    manifest.flatMap((operation) => (operation.tools.AGENT ? [operation.tools.AGENT] : [])),
+    agentToolNames,
+  );
+  assertSameSet(
+    'CLI manifest',
+    manifest.flatMap((operation) => (operation.tools.CLI ? [operation.tools.CLI] : [])),
+    cliToolNames,
+  );
+}
+
+const OpenApiOperationMetadataSchema = z.object({
+  'x-stitchkit-scope': z.string(),
+  'x-stitchkit-has-input': z.boolean(),
+  'x-stitchkit-has-output': z.boolean(),
+});
+
+const OpenApiOperationMetadataPresenceSchema = z
+  .object({
+    'x-stitchkit-scope': z.unknown().optional(),
+    'x-stitchkit-has-input': z.unknown().optional(),
+    'x-stitchkit-has-output': z.unknown().optional(),
+  })
+  .transform(
+    (metadata) =>
+      metadata['x-stitchkit-scope'] !== undefined ||
+      metadata['x-stitchkit-has-input'] !== undefined ||
+      metadata['x-stitchkit-has-output'] !== undefined,
+  );

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

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/package.json

@@ -4,7 +4,8 @@
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/server.ts"
+    ".": "./src/server.ts",
+    "./identity": "./src/identity.ts"
   },
   "scripts": {
     "check": "bun x tsc --noEmit",

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

@@ -0,0 +1 @@
+export const featureServerSchema = {};

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

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import source from '../../../app.config.json' with { type: 'json' };
+
+export const ApplicationIdentitySchema = z.object({
+  slug: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  name: z.string().trim().min(1).max(80),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  description: z.object({
+    en: z.string().trim().min(1),
+    ru: z.string().trim().min(1),
+  }),
+});
+
+export const appIdentity = ApplicationIdentitySchema.parse(source);

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

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { createEnv } from '@t3-oss/env-core';
 import { config } from 'dotenv';
 import { z } from 'zod';
+import { featureServerSchema } from './features';
 
 config({ path: path.resolve(import.meta.dirname, '../../../.env'), quiet: true });
 
@@ -15,10 +16,16 @@ export const env = createEnv({
     INTERNAL_API_URL: z.url(),
     NEXT_PUBLIC_WEB_URL: z.url(),
     LOG_FORMAT: z.enum(['pretty', 'json']).default('pretty'),
-    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(),
+    CORS_ORIGIN: z.url(),
+    ...featureServerSchema,
   },
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,
 });
+
+/** Preserve the host process environment while applying explicit child-process overrides. */
+export function childEnvironment(
+  overrides: Record<string, string>,
+): Record<string, string | undefined> {
+  return { ...process.env, ...overrides };
+}

package/template/packages/db/schema.prisma

@@ -6,26 +6,3 @@ generator client {
 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/template/packages/frontend/messages/en.json

@@ -1,6 +1,5 @@
 {
   "App": {
-    "title": "Stitchkit Starter",
     "description": "A compact production base with one typed contract across HTTP, MCP, agents and the browser — ready for your product, not a demo domain.",
     "heroTitle": "Build the product, not the plumbing.",
     "ui": "UI system"

package/template/packages/frontend/messages/ru.json

@@ -1,6 +1,5 @@
 {
   "App": {
-    "title": "Stitchkit Starter",
     "description": "Компактная production-база с единым типизированным контрактом для HTTP, MCP, агентов и браузера — готовая к вашему продукту, а не к демо-домену.",
     "heroTitle": "Стройте продукт, а не инфраструктурную рутину.",
     "ui": "UI-система"

package/template/packages/frontend/package.json

@@ -11,7 +11,7 @@
     "test": "bun test --pass-with-no-tests"
   },
   "dependencies": {
-    "@app/db": "workspace:*",
+    "@app/config": "workspace:*",
     "@app/shared": "workspace:*",
     "@radix-ui/react-alert-dialog": "^1.1.23",
     "@radix-ui/react-avatar": "^1.2.6",

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/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/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/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,3 +1,2 @@
-export * from './contracts/repository';
-export * from './events/repository';
-export * from './schemas/repository';
+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>;