@mettlecast/domain-cli 0.2.22 → 0.2.23

package/src/commands/generate-sdk.ts

@@ -0,0 +1,125 @@
+/**
+ * generate-sdk — read a domain's OpenAPI 3.1 spec and produce a typed
+ * TypeScript client that returns `Result<T, AppError>` from every API
+ * call. Uses the domain-runtime's Result types for compile-time safe
+ * error handling.
+ *
+ * Usage: npx mc-domain-module generate-sdk <domain>
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { cliLogger } from '../utils/logger.js';
+
+export interface GenerateSdkOptions {
+  domain: string;
+  projectRoot?: string;
+  /** Path to the OpenAPI spec. Defaults to domains/<domain>/api/openapi.generated.json */
+  input?: string;
+  /** Output directory. Defaults to frontend/src/sdk/generated/<domain>/ */
+  output?: string;
+}
+
+interface OpenApiSpec {
+  paths?: Record<string, Record<string, { operationId?: string; description?: string }>>;
+}
+
+export async function runGenerateSdk(options: GenerateSdkOptions): Promise<string> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const domain = options.domain;
+  const inputPath = options.input ?? join(projectRoot, 'domains', domain, 'api', 'openapi.generated.json');
+  const outputDir = options.output ?? join(projectRoot, 'frontend', 'src', 'sdk', 'generated', domain);
+
+  const specJson = await readFile(inputPath, 'utf8');
+  const spec = JSON.parse(specJson) as OpenApiSpec;
+
+  const functions: string[] = [];
+  let functionCount = 0;
+
+  if (spec.paths) {
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      for (const [method, op] of Object.entries(methods)) {
+        const operationId = op?.operationId ?? `${method}_${path.replace(/[^a-zA-Z0-9]/g, '_')}`;
+        const fnName = camelCase(operationId.replace(/\./g, '_'));
+        functions.push(generateApiFunction(fnName, path, method, operationId));
+        functionCount++;
+      }
+    }
+  }
+
+  const output = generateSdkFile(domain, functions);
+
+  await mkdir(outputDir, { recursive: true });
+  const indexFile = join(outputDir, 'index.ts');
+  await writeFile(indexFile, output, 'utf8');
+
+  // Write a .genhash file so the doctor check can verify freshness
+  const registryPath = join(projectRoot, '.mc', `${domain}-registry.json`);
+  const registryJson = await readFile(registryPath, 'utf8');
+  const hash = createHash('sha256').update(registryJson).digest('hex');
+  const genhashFile = join(outputDir, '.genhash');
+  await writeFile(genhashFile, `${domain} ${hash}`, 'utf8');
+
+  cliLogger.info({ outputDir, functionCount }, 'generate-sdk: client written');
+  return outputDir;
+}
+
+/**
+ * Generate a single API function body.
+ */
+function generateApiFunction(name: string, path: string, method: string, _operationId: string): string {
+  const payloadParam = method === 'get' ? '' : ', body: unknown';
+
+  return `
+/**
+ * ${_operationId}
+ * @returns Result containing the typed response or an AppError.
+ */
+export async function ${name}(
+  ${method === 'get' ? '' : 'body: unknown'}
+): Promise<Result<unknown, AppError>> {
+  const res = await fetch('${path}', {
+    method: '${method.toUpperCase()}',
+    headers: { 'Content-Type': 'application/json' },
+    ${method !== 'get' ? 'body: JSON.stringify(body),' : ''}
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ kind: 'internal', traceId: '', message: res.statusText }));
+    return err as unknown as Result<never, AppError>;
+  }
+  const value = await res.json();
+  return ok(value as unknown);
+}`;
+}
+
+/**
+ * Generate the full SDK file.
+ */
+function generateSdkFile(domain: string, functions: string[]): string {
+  return `// Generated from domains/${domain}/api/openapi.generated.json — do not edit
+// Re-run npx mc-domain-module generate-sdk ${domain} after schema changes.
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok } from '@mettlecast/domain-runtime';
+
+${functions.join('\n')}
+`;
+}
+
+/**
+ * Convert kebab-case or dot-separated to camelCase.
+ */
+function camelCase(s: string): string {
+  return s
+    .replace(/[-._]([a-z])/g, (_, c) => c.toUpperCase())
+    .replace(/^./, (c) => c.toLowerCase());
+}
+
+/**
+ * CLI entry point.
+ */
+export async function runGenerateSdkCli(domain: string, opts: { projectRoot?: string; input?: string; output?: string } = {}): Promise<void> {
+  const outputDir = await runGenerateSdk({ domain, ...opts });
+  // eslint-disable-next-line no-console
+  console.log(`SDK client written to: ${outputDir}`);
+}

package/src/commands/init.ts

@@ -0,0 +1,78 @@
+/**
+ * init — bootstrap a freshly scaffolded project so it is ready for
+ * local development and CI.  Runs npm install, builds the CLI, and
+ * runs a baseline doctor check.
+ *
+ * Usage: npx mc-domain-module init
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+import { runDoctor } from './doctor.js';
+
+export interface InitOptions {
+  projectRoot?: string;
+  /** Skip npm install if node_modules already exists. Default: true */
+  skipInstallIfExists?: boolean;
+}
+
+export async function runInit(options: InitOptions = {}): Promise<void> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const skipInstall = options.skipInstallIfExists !== false;
+
+  // ── 1. npm install ──────────────────────────────────────────────────
+  const nodeModulesDir = join(projectRoot, 'node_modules');
+  if (skipInstall && existsSync(nodeModulesDir)) {
+    cliLogger.info('node_modules exists — skipping npm install');
+  } else {
+    cliLogger.info('Running npm install...');
+    execSync('npm install --legacy-peer-deps', {
+      cwd: projectRoot,
+      stdio: 'inherit',
+    });
+  }
+
+  // ── 2. Build the CLI ────────────────────────────────────────────────
+  const cliDir = join(projectRoot, 'packages', 'domain-cli');
+  if (existsSync(cliDir)) {
+    cliLogger.info('Installing domain-cli dependencies...');
+    execSync('npm install --legacy-peer-deps', {
+      cwd: cliDir,
+      stdio: 'inherit',
+    });
+    cliLogger.info('Building domain-cli...');
+    execSync('npm run build', {
+      cwd: cliDir,
+      stdio: 'inherit',
+    });
+  }
+
+  // ── 3. Baseline doctor ──────────────────────────────────────────────
+  cliLogger.info('Running doctor (baseline)...');
+  const report = await runDoctor({ projectRoot, strict: true });
+  const passes = report.checks.filter(c => c.status === 'PASS').length;
+  const fails = report.checks.filter(c => c.status === 'FAIL').length;
+  const warns = report.checks.filter(c => c.status === 'WARN').length;
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `\nDoctor baseline: ${passes} PASS, ${fails} FAIL, ${warns} WARN`,
+  );
+
+  if (report.exitCode !== 0) {
+    // eslint-disable-next-line no-console
+    console.log(
+      '\nDoctor found issues — this is expected on a fresh scaffold.\n' +
+        'Run `npx mc-domain-module doctor` for details.\n',
+    );
+  } else {
+    // eslint-disable-next-line no-console
+    console.log('\nProject is ready!');
+  }
+}
+
+export async function runInitCli(opts: InitOptions = {}): Promise<void> {
+  await runInit(opts);
+}

package/src/commands/reseed-page.ts

@@ -3,6 +3,7 @@ import { join, resolve, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { createGunzip } from 'node:zlib';
 import { Readable } from 'node:stream';
+import ky from 'ky';
 import { cliLogger } from '../utils/logger.js';
 import {
   fetchVersionsJson,
@@ -125,21 +126,19 @@ async function createGitHubPR(
   labels?: string[]
 ): Promise<{ url: string; number: number }> {
   const url = `https://api.github.com/repos/${owner}/${repo}/pulls`;
-  const res = await fetch(url, {
-    method: 'POST',
+  const res = await ky.post(url, {
     headers: {
       Authorization: `Bearer ${token}`,
       Accept: 'application/vnd.github+json',
-      'Content-Type': 'application/json',
       'X-GitHub-Api-Version': '2022-11-28',
     },
-    body: JSON.stringify({
+    json: {
       title,
       body,
       head: branch,
       base: 'develop',
-      labels,
-    }),
+      ...(labels && labels.length > 0 && { labels }),
+    },
   });
 
   if (!res.ok) {

package/src/commands/upgrade.ts

@@ -3,6 +3,7 @@ import { Readable } from 'node:stream';
 import { mkdir, writeFile, unlink } from 'node:fs/promises';
 import { join, resolve, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
+import ky from 'ky';
 import { cliLogger } from '../utils/logger.js';
 import {
   fetchVersionsJson,
@@ -180,21 +181,19 @@ async function createGitHubPR(
   labels?: string[]
 ): Promise<{ url: string; number: number }> {
   const url = `https://api.github.com/repos/${owner}/${repo}/pulls`;
-  const res = await fetch(url, {
-    method: 'POST',
+  const res = await ky.post(url, {
     headers: {
       Authorization: `Bearer ${token}`,
       Accept: 'application/vnd.github+json',
-      'Content-Type': 'application/json',
       'X-GitHub-Api-Version': '2022-11-28',
     },
-    body: JSON.stringify({
+    json: {
       title,
       body,
       head: branch,
       base: 'develop',
       ...(labels && labels.length > 0 && { labels }),
-    }),
+    },
   });
 
   if (!res.ok) {
@@ -344,6 +343,8 @@ function buildFrontendComponentsPrBody(
 
 export interface UpgradeOptions {
   dryRun: boolean;
+  /** Read-only variant: compute diffs, print a CI-parseable summary, exit 0 (no drift) or 1 (drift detected). Never writes files. */
+  check: boolean;
   projectDir: string;
   githubToken?: string;
   frontendComponents?: boolean;
@@ -355,7 +356,8 @@ export async function runUpgrade(
 ): Promise<void> {
   const projectDir = resolve(opts.projectDir ?? process.cwd());
 
-  console.log(`\nTIB Upgrade${opts.dryRun ? ' (dry run)' : ''}\n`);
+  const actionLabel = opts.check ? 'check' : opts.dryRun ? 'dry run' : 'upgrade';
+  console.log(`\nTIB Upgrade (${actionLabel})\n`);
   console.log(`Project: ${projectDir}\n`);
 
   // 1. Read manifest + scaffold-config
@@ -568,6 +570,24 @@ export async function runUpgrade(
     }
   }
 
+  if (opts.check) {
+    // Read-only CI gate — report drift and exit.
+    const totalChanged = added.length + updated.length + deleted.length;
+    if (totalChanged === 0 && conflicts.length === 0) {
+      console.log('\n✓ No drift — project is up to date with scaffold.\n');
+      process.exitCode = 0;
+    } else {
+      console.log(`\n✗ Drift detected: ${totalChanged} file(s) changed, ${conflicts.length} conflict(s).`);
+      if (added.length > 0) console.log(`  Added   : ${added.map((r) => r.path).join(', ')}`);
+      if (updated.length > 0) console.log(`  Updated : ${updated.map((r) => r.path).join(', ')}`);
+      if (deleted.length > 0) console.log(`  Deleted : ${deleted.map((r) => r.path).join(', ')}`);
+      if (conflicts.length > 0) console.log(`  Conflicts: ${conflicts.map((r) => r.path).join(', ')}`);
+      console.log('\nRun `npx mc-domain-module upgrade` to apply changes.\n');
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (opts.dryRun) {
     console.log('\nDry run complete — no files were written.\n');
     return;

package/src/commands/why.ts

@@ -0,0 +1,171 @@
+/**
+ * Command to explain the project's current scaffold state and any available upgrades.
+ * Reads .mc/manifest.json for the current scaffold version + enabled module list,
+ * fetches the latest version from S3, and prints a diff to stdout.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fetchVersionsJson } from '../utils/s3-fetch.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the why command.
+ */
+export interface WhyOptions {
+  /** Project root directory. Defaults to process.cwd(). */
+  projectRoot?: string;
+  /** Override S3 bucket used to fetch versions.json. Defaults to the public TIB bucket. */
+  scaffoldBucket?: string;
+  /** Output raw JSON instead of a human-readable report. */
+  json?: boolean;
+}
+
+/**
+ * Report describing the project's current scaffold state and any pending upgrade.
+ */
+export interface WhyReport {
+  /** Scaffold version recorded in .mc/manifest.json (or "unknown" if no manifest). */
+  currentVersion: string;
+  /** Module IDs currently enabled in the project. */
+  enabledModules: string[];
+  /** Latest version published to the scaffold S3 bucket. */
+  latestVersion: string;
+  /** True when the current pinned version is older than the latest. */
+  upgradeAvailable: boolean;
+  /** Number of releases between current and latest (-1 if versions cannot be compared). */
+  versionsBehind: number;
+  /** All known scaffold versions (most recent first). */
+  allVersions: string[];
+}
+
+const DEFAULT_BUCKET = 'mc-scaffold';
+const MANIFEST_PATH_SEGMENTS = ['.mc', 'manifest.json'] as const;
+
+/**
+ * Read the project's current scaffold state from .mc/manifest.json.
+ * Returns sensible defaults when the manifest is missing or unreadable.
+ */
+async function readManifestState(projectRoot: string): Promise<{
+  scaffoldVersion: string;
+  enabledModules: string[];
+}> {
+  const manifestPath = join(projectRoot, ...MANIFEST_PATH_SEGMENTS);
+  try {
+    const content = await readFile(manifestPath, 'utf-8');
+    const parsed = JSON.parse(content) as {
+      scaffoldVersion?: unknown;
+      enabledModules?: unknown;
+    };
+    const scaffoldVersion =
+      typeof parsed.scaffoldVersion === 'string' ? parsed.scaffoldVersion : 'unknown';
+    const enabledModules = Array.isArray(parsed.enabledModules)
+      ? parsed.enabledModules.filter((m): m is string => typeof m === 'string')
+      : [];
+    return { scaffoldVersion, enabledModules };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { scaffoldVersion: 'unknown', enabledModules: [] };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Compute the number of releases between two version strings, using the order
+ * returned by versions.json (most recent first). Returns -1 when either version
+ * is not present in the list.
+ */
+function computeVersionsBehind(current: string, latest: string, all: string[]): number {
+  if (current === 'unknown') return -1;
+  const latestIdx = all.indexOf(latest);
+  const currentIdx = all.indexOf(current);
+  if (latestIdx === -1 || currentIdx === -1) return -1;
+  return Math.max(0, currentIdx - latestIdx);
+}
+
+/**
+ * Execute the why command: gather local + remote scaffold state, return a report.
+ * @param options - WhyOptions with optional projectRoot and scaffoldBucket.
+ * @returns A WhyReport describing current vs. latest state.
+ */
+export async function runWhy(options: WhyOptions = {}): Promise<WhyReport> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const bucket = options.scaffoldBucket ?? DEFAULT_BUCKET;
+
+  const { scaffoldVersion, enabledModules } = await readManifestState(projectRoot);
+  cliLogger.debug({ scaffoldVersion, enabledModules }, 'why: read local manifest');
+
+  const versionsJson = await fetchVersionsJson(bucket);
+  const latestVersion = versionsJson.latest;
+  const allVersions = versionsJson.versions;
+  const upgradeAvailable = latestVersion !== scaffoldVersion;
+  const versionsBehind = computeVersionsBehind(scaffoldVersion, latestVersion, allVersions);
+
+  return {
+    currentVersion: scaffoldVersion,
+    enabledModules,
+    latestVersion,
+    upgradeAvailable,
+    versionsBehind,
+    allVersions,
+  };
+}
+
+/**
+ * Format a WhyReport as a multi-line human-readable string.
+ */
+export function formatWhyReport(report: WhyReport): string {
+  const lines: string[] = [];
+  lines.push('=== Scaffold State ===');
+  lines.push(`Current version : ${report.currentVersion}`);
+  lines.push(`Latest version  : ${report.latestVersion}`);
+  if (report.upgradeAvailable) {
+    if (report.versionsBehind > 0) {
+      lines.push(`Upgrade available: yes (${report.versionsBehind} release(s) behind)`);
+    } else {
+      lines.push('Upgrade available: yes');
+    }
+  } else {
+    lines.push('Upgrade available: no — you are on the latest version');
+  }
+
+  lines.push('');
+  lines.push(`Enabled modules  : ${report.enabledModules.length === 0 ? '(none)' : ''}`);
+  for (const m of report.enabledModules) {
+    lines.push(`  - ${m}`);
+  }
+
+  lines.push('');
+  lines.push('Pending upgrade diff:');
+  if (!report.upgradeAvailable) {
+    lines.push('  (none)');
+  } else {
+    const idx = report.allVersions.indexOf(report.currentVersion);
+    if (idx <= 0) {
+      lines.push(`  (full jump: ${report.currentVersion} → ${report.latestVersion})`);
+    } else {
+      const newer = report.allVersions.slice(0, idx);
+      for (const v of newer) {
+        lines.push(`  ${v}  (newer than ${report.currentVersion})`);
+      }
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * CLI entry point: print a human-readable (or JSON) report and return the report.
+ */
+export async function runWhyCli(options: WhyOptions = {}): Promise<WhyReport> {
+  const report = await runWhy(options);
+  if (options.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    // eslint-disable-next-line no-console
+    process.stdout.write(formatWhyReport(report));
+  }
+  return report;
+}

package/src/templates/api-skeleton.ts

@@ -20,8 +20,24 @@ function camelCase(s: string): string {
  */
 export function apiSkeletonTemplate(domainId: string, apiId: string, tenancy: string): string {
   const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+  const outputType = `${camelCase(domainId)}${camelCase(apiId)}Output`;
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+// Initialise OpenTelemetry tracing for the process.  Idempotent —
+// safe to call at module scope.  Sets up OTLP export (when
+// OTEL_EXPORTER_OTLP_ENDPOINT is set) or console-export for
+// local dev.  Auto-instruments outbound HTTP calls via ky.
+initOtel();
+
+// Shared HTTP client with retry on 503/429.  Replace this with
+// your own client if you need custom headers or auth.
+const http = createKyClient();
+
+const outputSchema = z.object({ ok: z.boolean() }).default({ ok: true });
 
 export const ${camelCase(apiId)} = defineApi({
   id: '${apiId}',
@@ -31,10 +47,12 @@ export const ${camelCase(apiId)} = defineApi({
   versions: {
     v1: {
       status: 'stable',
-      input: z.object({}).optional(),
-      output: z.object({ ok: z.boolean() }),
-      handler: async (_input, _ctx) => {
-        return { ok: true };
+      input: z.object({}).default({}),
+      output: outputSchema,
+      handler: async (_input, _ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
+        // Replace this with your handler logic.
+        // Return ok(value) on success, err({ ... }) on failure.
+        return ok({ ok: true });
       },
     },
   },
@@ -48,11 +66,19 @@ export const ${camelCase(apiId)} = defineApi({
 
 /**
  * Generates a fixture JSON skeleton for API testing.
+ * The fixture embeds the input schema's default shape as the example payload
+ * in the event body so that the test driver can deserialize it directly.
  * @param domainId - Domain ID in kebab-case.
  * @param apiId - API ID in kebab-case.
+ * @param exampleBody - JSON-stringified example payload matching the input
+ *   schema's default shape. Defaults to '{}'.
  * @returns JSON string with mock event and context for testing.
  */
-export function apiFixtureSkeleton(domainId: string, apiId: string): string {
+export function apiFixtureSkeleton(
+  domainId: string,
+  apiId: string,
+  exampleBody: string = '{}',
+): string {
   return JSON.stringify({
     description: `Fixture for ${domainId}.${apiId}`,
     event: {
@@ -71,7 +97,7 @@ export function apiFixtureSkeleton(domainId: string, apiId: string): string {
       },
       pathParameters: {},
       headers: { 'content-type': 'application/json', 'accept-version': '1' },
-      body: null,
+      body: exampleBody,
     },
   }, null, 2) + '\n';
 }

package/src/templates/patterns/api/create-with-event.ts

@@ -13,17 +13,25 @@ export function createWithEventTemplate(domain: string, id: string, tenancy: str
 
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 // ── Zod schemas ──────────────────────────────────────────────
 
 const ${varName}Input = z.object({
   name: z.string().min(1),
   payload: z.record(z.unknown()).optional(),
-});
+}).default({ name: 'Example' });
 
 const ${varName}Output = z.object({
   id: z.string().uuid(),
   status: z.enum(['created', 'pending']),
+}).default({
+  id: '00000000-0000-0000-0000-000000000000',
+  status: 'created',
 });
 
 // ── API definition ───────────────────────────────────────────
@@ -66,3 +74,9 @@ export const ${varName} = defineApi({
 });
 `;
 }
+
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * create-with-event pattern. Mirrors the default shape of the input schema.
+ */
+export const createWithEventExampleBody = JSON.stringify({ name: 'Example' });

package/src/templates/patterns/api/idempotent-mutation.ts

@@ -13,18 +13,30 @@ export function idempotentMutationTemplate(domain: string, id: string, tenancy:
 
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 // ── Zod schemas ──────────────────────────────────────────────
 
 const ${varName}Input = z.object({
   id: z.string().uuid(),
   payload: z.record(z.unknown()),
+}).default({
+  id: '00000000-0000-0000-0000-000000000000',
+  payload: {},
 });
 
 const ${varName}Output = z.object({
   id: z.string().uuid(),
   status: z.enum(['applied', 'already-processed']),
   idempotencyKey: z.string(),
+}).default({
+  id: '00000000-0000-0000-0000-000000000000',
+  status: 'applied',
+  idempotencyKey: '00000000-0000-0000-0000-000000000000',
 });
 
 // ── API definition ───────────────────────────────────────────
@@ -77,3 +89,12 @@ export const ${varName} = defineApi({
 });
 `;
 }
+
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * idempotent-mutation pattern. Mirrors the default shape of the input schema.
+ */
+export const idempotentMutationExampleBody = JSON.stringify({
+  id: '00000000-0000-0000-0000-000000000000',
+  payload: {},
+});

package/src/templates/patterns/api/paginated-list.ts

@@ -13,6 +13,11 @@ export function paginatedListTemplate(domain: string, id: string, tenancy: strin
 
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 // ── Pagination contract ──────────────────────────────────────
 
@@ -25,13 +30,13 @@ const PageInput = z.object({
     .max(100)
     .default(20),
   filter: z.string().optional(),
-});
+}).default({});
 
 const PageOutput = z.object({
   items: z.array(z.object({ id: z.string().uuid() })),
   nextCursor: z.string().optional(),
   total: z.number().int().optional(),
-});
+}).default({ items: [], nextCursor: undefined, total: undefined });
 
 // ── API definition ───────────────────────────────────────────
 
@@ -64,3 +69,9 @@ export const ${varName} = defineApi({
 });
 `;
 }
+
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * paginated-list pattern. Mirrors the default shape of the input schema.
+ */
+export const paginatedListExampleBody = '{}';