@mettlecast/domain-cli 0.2.22 → 0.2.24

package/dist/templates/patterns/api/streaming-list.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pattern: streaming-list
+ *
+ * Lambda Response Streaming template.  Returns items as a chunked
+ * JSON Lines stream rather than a single JSON array.
+ *
+ * Use this when:
+ *   - The result set can be large (thousands of rows)
+ *   - TTFB matters (first item arrives before the full query completes)
+ *   - The client can consume JSON Lines ({\"id\":1}\n{\"id\":2}\n...)
+ *
+ * Do NOT use when:
+ *   - The client expects a single unwrapped JSON object
+ *   - The total response size is small (< 1 KB)
+ *   - You need typed response headers for pagination
+ *
+ * Dependencies:
+ *   - `@bufbuild/protobuf` for stream framing (or built-in node:stream)
+ *   - API Gateway HTTP API with 2.0 payload format (not REST API)
+ *   - Lambda runtime v20+
+ *
+ * @param domain - Domain ID in kebab-case
+ * @param apiId - API ID in kebab-case
+ * @param itemName - Singular item name (e.g. 'ticket', 'member')
+ * @returns TypeScript source code.
+ */
+export declare function streamingListPattern(domain: string, apiId: string, itemName: string): string;

package/dist/templates/patterns/api/streaming-list.js

@@ -0,0 +1,91 @@
+/**
+ * Pattern: streaming-list
+ *
+ * Lambda Response Streaming template.  Returns items as a chunked
+ * JSON Lines stream rather than a single JSON array.
+ *
+ * Use this when:
+ *   - The result set can be large (thousands of rows)
+ *   - TTFB matters (first item arrives before the full query completes)
+ *   - The client can consume JSON Lines ({\"id\":1}\n{\"id\":2}\n...)
+ *
+ * Do NOT use when:
+ *   - The client expects a single unwrapped JSON object
+ *   - The total response size is small (< 1 KB)
+ *   - You need typed response headers for pagination
+ *
+ * Dependencies:
+ *   - `@bufbuild/protobuf` for stream framing (or built-in node:stream)
+ *   - API Gateway HTTP API with 2.0 payload format (not REST API)
+ *   - Lambda runtime v20+
+ *
+ * @param domain - Domain ID in kebab-case
+ * @param apiId - API ID in kebab-case
+ * @param itemName - Singular item name (e.g. 'ticket', 'member')
+ * @returns TypeScript source code.
+ */
+export function streamingListPattern(domain, apiId, itemName) {
+    return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+
+const ${itemName}Schema = z.object({ id: z.string() });
+const inputSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(1000).default(100),
+  cursor: z.string().optional(),
+}).default({ limit: 100 });
+const outputSchema = z.object({
+  items: z.array(${itemName}Schema),
+  nextCursor: z.string().optional(),
+}).default({ items: [] });
+
+export const ${apiId.replace(/-/g, '_')} = defineApi({
+  id: '${apiId}',
+  path: '/v1/${domain}/${apiId}',
+  method: 'GET',
+  tenancy: 'required',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: inputSchema,
+      output: outputSchema,
+      handler: async (input, ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
+        // Streaming response: each item is yielded as a JSON line
+        // before the full query completes.  The runtime handler
+        // wrapper converts this generator into a chunked response.
+        //
+        //   GET /v1/${domain}/${apiId}?limit=100
+        //   Transfer-Encoding: chunked
+        //   Content-Type: application/x-ndjson
+        //
+        //   {"id":"1"}\\n
+        //   {"id":"2"}\\n
+        //   {"id":"3"}\\n
+
+        let nextCursor: string | undefined;
+        const items: unknown[] = [];
+
+        // Replace this query with your actual data source.
+        const rows = await ctx.db.query(
+          '${domain}',
+          'SELECT id FROM ${domain}s LIMIT $1 OFFSET $2',
+          [input.limit + 1, input.cursor ? parseInt(input.cursor, 10) : 0],
+        );
+
+        for (let i = 0; i < Math.min(rows.length, input.limit); i++) {
+          items.push(rows[i]);
+        }
+
+        if (rows.length > input.limit) {
+          nextCursor = String(
+            (input.cursor ? parseInt(input.cursor, 10) : 0) + input.limit,
+          );
+        }
+
+        return { ok: true, value: { items, nextCursor } };
+      },
+    },
+  },
+});
+`;
+}

package/dist/templates/patterns/api/system-admin.d.ts

@@ -3,3 +3,8 @@
  * Produces: GET/POST with tenancy: 'system', no tenant context.
  */
 export declare function systemAdminTemplate(domain: string, id: string, tenancy: string): string;
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * system-admin pattern. Mirrors the default shape of the input schema.
+ */
+export declare const systemAdminExampleBody: string;

package/dist/templates/patterns/api/system-admin.js

@@ -9,18 +9,23 @@ export function systemAdminTemplate(domain, id, tenancy) {
     const varName = camelCase(id);
     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({
   command: z.enum(['status', 'metrics', 'health']),
   domainId: z.string().optional(),
-});
+}).default({ command: 'status' });
 
 const ${varName}Output = z.object({
   ok: z.boolean(),
   data: z.record(z.unknown()).optional(),
-});
+}).default({ ok: true });
 
 // ── System health input ──────────────────────────────────────
 
@@ -31,7 +36,7 @@ const SystemHealthOutput = z.object({
     id: z.string(),
     status: z.enum(['healthy', 'degraded']),
   })),
-});
+}).default({ status: 'healthy', uptime: 0, domains: [] });
 
 // ── API definitions ──────────────────────────────────────────
 
@@ -79,7 +84,7 @@ export const ${varName}Health = defineApi({
   versions: {
     v1: {
       status: 'stable',
-      input: z.object({}).optional(),
+      input: z.object({}).default({}),
       output: SystemHealthOutput,
       handler: async (_input, _ctx) => {
         return {
@@ -93,3 +98,8 @@ export const ${varName}Health = defineApi({
 });
 `;
 }
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * system-admin pattern. Mirrors the default shape of the input schema.
+ */
+export const systemAdminExampleBody = JSON.stringify({ command: 'status' });

package/dist/templates/patterns/api/webhook-receiver-style.d.ts

@@ -3,3 +3,8 @@
  * Produces: POST with signature verification, provider enum.
  */
 export declare function webhookReceiverStyleTemplate(domain: string, id: string, tenancy: string): string;
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * webhook-receiver-style pattern. Mirrors the default shape of the input schema.
+ */
+export declare const webhookReceiverStyleExampleBody: string;

package/dist/templates/patterns/api/webhook-receiver-style.js

@@ -9,6 +9,11 @@ export function webhookReceiverStyleTemplate(domain, id, tenancy) {
     const varName = camelCase(id);
     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();
 
 // ── Supported webhook providers ───────────────────────────────
 
@@ -26,12 +31,20 @@ const ${varName}Input = z.object({
   eventType: z.string().min(1),
   payload: z.record(z.unknown()),
   rawBody: z.string().optional(),
+}).default({
+  provider: 'stripe',
+  eventType: 'example.event',
+  payload: {},
 });
 
 const ${varName}Output = z.object({
   received: z.boolean(),
   eventId: z.string().uuid(),
   provider: ProviderEnum,
+}).default({
+  received: true,
+  eventId: '00000000-0000-0000-0000-000000000000',
+  provider: 'stripe',
 });
 
 // ── API definition ───────────────────────────────────────────
@@ -77,3 +90,12 @@ export const ${varName} = defineApi({
 });
 `;
 }
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * webhook-receiver-style pattern. Mirrors the default shape of the input schema.
+ */
+export const webhookReceiverStyleExampleBody = JSON.stringify({
+    provider: 'stripe',
+    eventType: 'example.event',
+    payload: {},
+});

package/dist/utils/s3-fetch.js

@@ -1,28 +1,29 @@
-import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import ky from 'ky';
 import { createHash } from 'crypto';
+const DEFAULT_SCAFFOLD_REGION = process.env['SCAFFOLD_BUCKET_REGION'] ?? 'us-east-1';
+function s3BaseUrl(bucket) {
+    const region = DEFAULT_SCAFFOLD_REGION;
+    return region === 'us-east-1'
+        ? `https://${bucket}.s3.amazonaws.com`
+        : `https://${bucket}.s3.${region}.amazonaws.com`;
+}
+/** Singleton ky client — re-used across all fetch functions. */
+const client = ky.create({
+    retry: { limit: 3, methods: ['get'] },
+    timeout: 30_000,
+});
 export async function fetchVersionsJson(bucket) {
-    const client = new S3Client({});
-    const cmd = new GetObjectCommand({ Bucket: bucket, Key: 'versions.json' });
-    const res = await client.send(cmd);
-    const body = await streamToBuffer(res.Body);
-    return JSON.parse(body.toString('utf-8'));
+    const url = `${s3BaseUrl(bucket)}/versions.json`;
+    return (await client.get(url).json());
 }
 export async function fetchModulesJson(bucket, version) {
-    const client = new S3Client({});
-    const cmd = new GetObjectCommand({
-        Bucket: bucket,
-        Key: `versions/${version}/modules.json`,
-    });
-    const res = await client.send(cmd);
-    const body = await streamToBuffer(res.Body);
-    return JSON.parse(body.toString('utf-8'));
+    const url = `${s3BaseUrl(bucket)}/versions/${encodeURIComponent(version)}/modules.json`;
+    return (await client.get(url).json());
 }
 export async function fetchModuleTarball(bucket, version, tarball, expectedSha256) {
-    const client = new S3Client({});
-    const key = `versions/${version}/${tarball}`;
-    const cmd = new GetObjectCommand({ Bucket: bucket, Key: key });
-    const res = await client.send(cmd);
-    const buf = await streamToBuffer(res.Body);
+    const url = `${s3BaseUrl(bucket)}/versions/${encodeURIComponent(version)}/${encodeURIComponent(tarball)}`;
+    const arrayBuffer = await client.get(url).arrayBuffer();
+    const buf = Buffer.from(arrayBuffer);
     const actual = createHash('sha256').update(buf).digest('hex');
     if (actual !== expectedSha256) {
         throw new Error(`Checksum mismatch for ${tarball}: expected ${expectedSha256}, got ${actual}`);
@@ -30,23 +31,13 @@ export async function fetchModuleTarball(bucket, version, tarball, expectedSha25
     return buf;
 }
 export async function fetchScaffoldFile(bucket, version, path) {
-    const client = new S3Client({});
-    const cmd = new GetObjectCommand({ Bucket: bucket, Key: `versions/${version}/${path}` });
+    const url = `${s3BaseUrl(bucket)}/versions/${encodeURIComponent(version)}/${encodeURIComponent(path)}`;
     try {
-        const res = await client.send(cmd);
-        const body = await streamToBuffer(res.Body);
-        return body.toString('utf-8');
+        return await client.get(url).text();
     }
     catch (err) {
-        if (err.name === 'NoSuchKey')
+        if (err.response?.status === 404)
             return null;
         throw err;
     }
 }
-async function streamToBuffer(stream) {
-    const chunks = [];
-    for await (const chunk of stream) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    }
-    return Buffer.concat(chunks);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-cli",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -16,6 +16,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "dev": "tsx ./src/cli.ts",
+    "bun": "bun run src/cli.ts",
     "test": "vitest"
   },
   "dependencies": {
@@ -26,11 +27,13 @@
     "commander": "^12.0.0",
     "dotenv": "^16.0.0",
     "fastify": "^5.0.0",
+    "ky": "^1.7.0",
     "pino": "^9.0.0",
     "pino-pretty": "^11.0.0",
     "semver": "^7.0.0",
     "tar": "^7.0.0",
     "tsx": "^4.0.0",
+    "zod": "^4.0.0",
     "zod-to-json-schema": "^3.0.0"
   },
   "devDependencies": {

package/src/__tests__/commands/add-api.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { runAddApi } from '../../commands/add-api.js';
+
+describe('add-api command', () => {
+  let tmpDir: string;
+  let domainDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'tib-add-api-test-'));
+    domainDir = join(tmpDir, 'demo');
+    await mkdir(join(domainDir, 'api'), { recursive: true });
+    await writeFile(
+      join(domainDir, 'domain.config.ts'),
+      `export default { id: 'demo', tenancy: 'required' };\n`,
+    );
+  });
+
+  afterEach(async () => {
+    try {
+      await rm(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  it('scaffolds an API file and a fixture JSON with valid JSON body', async () => {
+    await runAddApi({
+      domain: 'demo',
+      id: 'ping-thing',
+      tenancy: 'required',
+      domainsDir: tmpDir,
+    });
+
+    const apiFile = join(domainDir, 'api', 'ping-thing.ts');
+    const fixtureFile = join(domainDir, 'api', '__tests__', 'ping-thing.fixture.json');
+
+    const apiContent = await readFile(apiFile, 'utf8');
+    const fixtureContent = await readFile(fixtureFile, 'utf8');
+
+    // The fixture file must be valid JSON.
+    expect(() => JSON.parse(fixtureContent)).not.toThrow();
+    const parsed = JSON.parse(fixtureContent) as { event: { body: string } };
+    expect(parsed.event.body).toBe('{}');
+
+    // The API file must contain .default() on input and output.
+    expect(apiContent).toMatch(/input:\s*z\.object\(\{\}\)\.default\(\{\}\)/);
+    expect(apiContent).toMatch(/output:\s*z\.object\(\{\s*ok:\s*z\.boolean\(\)\s*\}\)\.default\(\{\s*ok:\s*true\s*\}\)/);
+  });
+
+  it('scaffolds a simple-crud pattern API with .default() on schemas', async () => {
+    await runAddApi({
+      domain: 'demo',
+      id: 'widget',
+      tenancy: 'required',
+      pattern: 'simple-crud',
+      domainsDir: tmpDir,
+    });
+
+    const apiFile = join(domainDir, 'api', 'widget.ts');
+    const fixtureFile = join(domainDir, 'api', '__tests__', 'widget.fixture.json');
+
+    const apiContent = await readFile(apiFile, 'utf8');
+    const fixtureContent = await readFile(fixtureFile, 'utf8');
+
+    expect(() => JSON.parse(fixtureContent)).not.toThrow();
+    const parsed = JSON.parse(fixtureContent) as { event: { body: string } };
+    expect(parsed.event.body).toBe('{}');
+
+    // Both the per-id handler and the list handler must carry .default() on schemas.
+    expect(apiContent).toMatch(/z\.object\(\{\s*id:\s*z\.string\(\)\.uuid\(\)\.optional\(\),?\s*\}\)\.default\(\{\}\)/);
+    expect(apiContent).toMatch(/\.default\(\{\s*id:\s*'00000000-0000-0000-0000-000000000000'/);
+  });
+
+  it('scaffolds a create-with-event pattern API with .default() including required name', async () => {
+    await runAddApi({
+      domain: 'demo',
+      id: 'order',
+      tenancy: 'required',
+      pattern: 'create-with-event',
+      domainsDir: tmpDir,
+    });
+
+    const apiFile = join(domainDir, 'api', 'order.ts');
+    const fixtureFile = join(domainDir, 'api', '__tests__', 'order.fixture.json');
+
+    const apiContent = await readFile(apiFile, 'utf8');
+    const fixtureContent = await readFile(fixtureFile, 'utf8');
+
+    expect(() => JSON.parse(fixtureContent)).not.toThrow();
+    const parsed = JSON.parse(fixtureContent) as { event: { body: string } };
+    expect(JSON.parse(parsed.event.body)).toEqual({ name: 'Example' });
+
+    expect(apiContent).toMatch(/z\.object\(\{\s*name:\s*z\.string\(\)\.min\(1\),?\s*payload:\s*z\.record\(z\.unknown\(\)\)\.optional\(\),?\s*\}\)\.default\(\{\s*name:\s*'Example'\s*\}\)/);
+    expect(apiContent).toMatch(/\.default\(\{\s*id:\s*'00000000-0000-0000-0000-000000000000',\s*status:\s*'created',?\s*\}\)/);
+  });
+
+  it('scaffolds a system-admin pattern with .default() on both APIs', async () => {
+    await runAddApi({
+      domain: 'demo',
+      id: 'console',
+      tenancy: 'system',
+      pattern: 'system-admin',
+      domainsDir: tmpDir,
+    });
+
+    const apiFile = join(domainDir, 'api', 'console.ts');
+    const apiContent = await readFile(apiFile, 'utf8');
+
+    // First API: input defaults to command: 'status'; output defaults to { ok: true }.
+    expect(apiContent).toMatch(/z\.object\(\{\s*command:\s*z\.enum\(\[.*?\]\),?\s*domainId:\s*z\.string\(\)\.optional\(\),?\s*\}\)\.default\(\{\s*command:\s*'status'\s*\}\)/);
+    expect(apiContent).toMatch(/z\.object\(\{\s*ok:\s*z\.boolean\(\),?\s*data:\s*z\.record\(z\.unknown\(\)\)\.optional\(\),?\s*\}\)\.default\(\{\s*ok:\s*true\s*\}\)/);
+
+    // Health API: .default({}) replaces .optional() on input.
+    expect(apiContent).toMatch(/input:\s*z\.object\(\{\}\)\.default\(\{\}\)/);
+    // Health output: .default({ status: 'healthy', uptime: 0, domains: [] }).
+    expect(apiContent).toMatch(/\.default\(\{\s*status:\s*'healthy',\s*uptime:\s*0,\s*domains:\s*\[\]\s*\}\)/);
+  });
+
+  it('rejects adding the same API twice', async () => {
+    await runAddApi({
+      domain: 'demo',
+      id: 'duplicate',
+      tenancy: 'required',
+      domainsDir: tmpDir,
+    });
+    await expect(
+      runAddApi({
+        domain: 'demo',
+        id: 'duplicate',
+        tenancy: 'required',
+        domainsDir: tmpDir,
+      }),
+    ).rejects.toThrow(/already exists/);
+  });
+
+  it('rejects invalid kebab-case ids', async () => {
+    await expect(
+      runAddApi({
+        domain: 'demo',
+        id: 'BadId',
+        tenancy: 'required',
+        domainsDir: tmpDir,
+      }),
+    ).rejects.toThrow(/Invalid API id/);
+  });
+
+  it('rejects non-existent domain', async () => {
+    await expect(
+      runAddApi({
+        domain: 'missing',
+        id: 'whatever',
+        tenancy: 'required',
+        domainsDir: tmpDir,
+      }),
+    ).rejects.toThrow(/Domain "missing" not found/);
+  });
+});

package/src/__tests__/commands/dev.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { EventEmitter } from 'node:events';
+import type { ChildProcess } from 'node:child_process';
+import type { FastifyInstance } from 'fastify';
+
+interface MockChildProcess extends EventEmitter, Pick<ChildProcess, 'kill' | 'killed'> {}
+
+function makeMockChild(): MockChildProcess {
+  const emitter = new EventEmitter() as MockChildProcess;
+  emitter.killed = false;
+  emitter.kill = vi.fn((signal?: NodeJS.Signals): boolean => {
+    emitter.killed = true;
+    emitter.emit('exit', null, signal ?? 'SIGTERM');
+    return true;
+  });
+  return emitter;
+}
+
+function makeMockFastify() {
+  return { close: vi.fn().mockResolvedValue(undefined) };
+}
+
+const mocks = vi.hoisted(() => {
+  const child = makeMockChild();
+  const fastify = makeMockFastify();
+  return {
+    child,
+    fastify,
+    spawnFn: vi.fn().mockReturnValue(child as unknown as ChildProcess),
+    createApiServer: vi.fn().mockResolvedValue(fastify as unknown as FastifyInstance),
+    buildRegistry: vi.fn().mockResolvedValue({
+      registry: {
+        domain: { id: 'mock-domain' },
+        apis: [],
+        webhooks: [],
+        subscribers: [],
+        schedules: [],
+        jobs: [],
+        actions: [],
+        integrations: [],
+        events: [],
+      },
+      warnings: [],
+    }),
+  };
+});
+
+vi.mock('../../server/api-server.js', () => ({ createApiServer: mocks.createApiServer }));
+vi.mock('../../builder/build-registry.js', () => ({ buildRegistry: mocks.buildRegistry }));
+
+import { startDev } from '../../commands/dev.js';
+
+describe('dev command — startDev + graceful shutdown', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'tib-dev-'));
+    mocks.spawnFn.mockClear();
+    mocks.createApiServer.mockClear();
+    mocks.buildRegistry.mockClear();
+    mocks.fastify.close.mockClear();
+    (mocks.child.kill as ReturnType<typeof vi.fn>).mockClear();
+    mocks.child.killed = false;
+  });
+
+  afterEach(async () => {
+    try {
+      await rm(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('starts Fastify on the requested port and skips Vite when no frontend/ dir exists', async () => {
+    // No frontend/ dir created
+    const handle = await startDev({
+      domainRoot: tmpDir,
+      projectRoot: tmpDir,
+      port: 3000,
+      frontendPort: 3001,
+      spawnFn: mocks.spawnFn as unknown as typeof import('node:child_process').spawn,
+    });
+
+    // createApiServer was called with port 3000
+    expect(mocks.createApiServer).toHaveBeenCalledTimes(1);
+    const callArgs = mocks.createApiServer.mock.calls[0]?.[0] as { port: number };
+    expect(callArgs.port).toBe(3000);
+
+    // Vite was NOT spawned (no frontend/ dir)
+    expect(mocks.spawnFn).not.toHaveBeenCalled();
+    expect(handle.vite).toBeNull();
+    expect(handle.server).toBe(mocks.fastify as unknown as FastifyInstance);
+  });
+
+  it('spawns Vite on frontendPort when frontend/ directory exists', async () => {
+    await mkdir(join(tmpDir, 'frontend'), { recursive: true });
+
+    const handle = await startDev({
+      domainRoot: tmpDir,
+      projectRoot: tmpDir,
+      port: 3000,
+      frontendPort: 3001,
+      spawnFn: mocks.spawnFn as unknown as typeof import('node:child_process').spawn,
+    });
+
+    expect(mocks.spawnFn).toHaveBeenCalledTimes(1);
+    const [cmd, args, opts] = mocks.spawnFn.mock.calls[0] as [string, string[], { cwd: string }];
+    expect(cmd).toBe('npx');
+    expect(args).toContain('vite');
+    expect(args).toContain('3001');
+    expect(opts.cwd).toBe(join(tmpDir, 'frontend'));
+    expect(handle.vite).toBe(mocks.child as unknown as ChildProcess);
+  });
+
+  it('shutdown() kills the Vite child and closes the Fastify server when both are running', async () => {
+    await mkdir(join(tmpDir, 'frontend'), { recursive: true });
+
+    const handle = await startDev({
+      domainRoot: tmpDir,
+      projectRoot: tmpDir,
+      spawnFn: mocks.spawnFn as unknown as typeof import('node:child_process').spawn,
+    });
+
+    await handle.shutdown();
+
+    expect(mocks.child.kill).toHaveBeenCalledWith('SIGTERM');
+    expect(mocks.fastify.close).toHaveBeenCalledTimes(1);
+  });
+
+  it('shutdown() only closes the server when no Vite was started (no error)', async () => {
+    const handle = await startDev({
+      domainRoot: tmpDir,
+      projectRoot: tmpDir,
+      spawnFn: mocks.spawnFn as unknown as typeof import('node:child_process').spawn,
+    });
+
+    expect(handle.vite).toBeNull();
+    await expect(handle.shutdown()).resolves.toBeUndefined();
+    expect(mocks.fastify.close).toHaveBeenCalledTimes(1);
+    expect(mocks.spawnFn).not.toHaveBeenCalled();
+  });
+
+  it('shutdown() is idempotent — calling it twice does not double-close or re-kill', async () => {
+    await mkdir(join(tmpDir, 'frontend'), { recursive: true });
+
+    const handle = await startDev({
+      domainRoot: tmpDir,
+      projectRoot: tmpDir,
+      spawnFn: mocks.spawnFn as unknown as typeof import('node:child_process').spawn,
+    });
+
+    await handle.shutdown();
+    await handle.shutdown();
+
+    expect(mocks.child.kill).toHaveBeenCalledTimes(1);
+    expect(mocks.fastify.close).toHaveBeenCalledTimes(1);
+  });
+});