feat: Sprint 1 — Playwright e2e + sandbox orchestration (TDD)

- e2e: Playwright chat-flow (sign up -> chat) with api/web webServer harness
- api: sandbox services subset/media-proxy/manifest/gc + DockerClient contract
- api: SandboxManager orchestrator (fake-Docker tested); /health route
- 53 unit tests green; Playwright e2e green

api/__tests__/sandbox/gc.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { decideGc } from '../../src/sandbox/gc.ts';
+
+const opts = { idleMs: 15 * 60 * 1000, hardMs: 24 * 60 * 60 * 1000 };
+const now = 1_000_000;
+
+describe('decideGc', () => {
+  it('pauses a running sandbox after the idle threshold', () => {
+    expect(decideGc({ status: 'running', lastActiveAt: now - opts.idleMs - 1, createdAt: 0 }, now, opts)).toBe('pause');
+  });
+
+  it('keeps an active running sandbox', () => {
+    expect(decideGc({ status: 'running', lastActiveAt: now - 1000, createdAt: 0 }, now, opts)).toBe('keep');
+  });
+
+  it('destroys any sandbox past the hard timeout regardless of activity', () => {
+    expect(decideGc({ status: 'running', lastActiveAt: now - 1000, createdAt: now - opts.hardMs - 1 }, now, opts)).toBe(
+      'destroy',
+    );
+  });
+
+  it('does not re-pause an already paused sandbox', () => {
+    expect(decideGc({ status: 'paused', lastActiveAt: now - opts.idleMs - 1, createdAt: 0 }, now, opts)).toBe('keep');
+  });
+
+  it('keeps a destroyed sandbox', () => {
+    expect(decideGc({ status: 'destroyed', lastActiveAt: 0, createdAt: 0 }, now, opts)).toBe('keep');
+  });
+});

api/__tests__/sandbox/manifest.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { diffManifest } from '../../src/sandbox/manifest.ts';
+
+describe('diffManifest', () => {
+  it('detects added, changed, and removed paths', () => {
+    const before = {
+      '/theme/style.css': 'a1',
+      '/theme/theme.json': 'b2',
+      '/theme/old.css': 'c3',
+    };
+    const after = {
+      '/theme/style.css': 'a1',
+      '/theme/theme.json': 'b2-new',
+      '/theme/new.css': 'd4',
+    };
+
+    expect(diffManifest(before, after)).toEqual({
+      added: ['/theme/new.css'],
+      changed: ['/theme/theme.json'],
+      removed: ['/theme/old.css'],
+    });
+  });
+
+  it('reports empty arrays when nothing changed', () => {
+    const manifest = { '/a.css': 'x' };
+    expect(diffManifest(manifest, { ...manifest })).toEqual({ added: [], changed: [], removed: [] });
+  });
+});

api/__tests__/sandbox/media-proxy.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { mediaProxyTarget, resolveMediaPath, stageReplacement } from '../../src/sandbox/media-proxy.ts';
+
+describe('media proxy', () => {
+  it('proxies an upload to the origin', () => {
+    expect(mediaProxyTarget('https://example.com', '/wp-content/uploads/2024/hero.jpg')).toBe(
+      'https://example.com/wp-content/uploads/2024/hero.jpg',
+    );
+  });
+
+  it('serves a staged replacement locally instead of proxying', () => {
+    const staged = new Set(['/wp-content/uploads/2024/hero.jpg']);
+    expect(resolveMediaPath('https://example.com', '/wp-content/uploads/2024/hero.jpg', staged)).toBe(
+      '/wp-content/uploads/2024/hero.jpg',
+    );
+    expect(resolveMediaPath('https://example.com', '/wp-content/uploads/2024/other.jpg', staged)).toBe(
+      'https://example.com/wp-content/uploads/2024/other.jpg',
+    );
+  });
+
+  it('copies a file only when it is replaced', () => {
+    expect(stageReplacement('https://example.com', '/wp-content/uploads/2024/hero.jpg', 12)).toEqual({
+      copiedPaths: ['/wp-content/uploads/2024/hero.jpg'],
+    });
+  });
+});

api/__tests__/sandbox/subset.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { exportDbSubset } from '../../src/sandbox/subset.ts';
+import type { SiteExport } from '../../src/sandbox/types.ts';
+
+const dump = (): SiteExport => ({
+  origin: 'https://example.com',
+  tables: {
+    wp_posts: [{ ID: 1, post_title: 'Home' }],
+    wp_postmeta: [{ post_id: 1, meta_key: '_edit_lock', meta_value: '1' }],
+    wp_options: [
+      { option_name: 'blogname', option_value: 'Biz' },
+      { option_name: 'woocommerce_stripe_secret_key', option_value: 'sk_live_xxx' },
+      { option_name: 'smtp_pass', option_value: 'secret' },
+    ],
+    wp_terms: [{ term_id: 1, name: 'Menu' }],
+    wp_term_taxonomy: [{ term_taxonomy_id: 1 }],
+    wp_term_relationships: [{ object_id: 1 }],
+    wp_wc_orders: [{ id: 99, total: '40.00' }],
+    wp_comments: [{ comment_ID: 1, comment_content: 'hi' }],
+  },
+  uploads: [],
+});
+
+describe('exportDbSubset', () => {
+  it('keeps posts, postmeta, and options for a content playbook', () => {
+    expect(exportDbSubset(dump(), { playbook: 'content', postIds: [1] }).tables).toEqual(
+      expect.arrayContaining(['wp_posts', 'wp_postmeta', 'wp_options']),
+    );
+  });
+
+  it('drops Woo orders and comments from a content-edit slice', () => {
+    const tables = exportDbSubset(dump(), { playbook: 'content', postIds: [1] }).tables;
+    expect(tables).not.toContain('wp_wc_orders');
+    expect(tables).not.toContain('wp_comments');
+  });
+
+  it('adds taxonomy tables for a design playbook', () => {
+    const tables = exportDbSubset(dump(), { playbook: 'design', postIds: [1] }).tables;
+    expect(tables).toEqual(expect.arrayContaining(['wp_terms', 'wp_term_taxonomy', 'wp_term_relationships']));
+  });
+
+  it('limits a plugin playbook to options only', () => {
+    expect(exportDbSubset(dump(), { playbook: 'plugin', postIds: [1] }).tables).toEqual(['wp_options']);
+  });
+
+  it('redacts option names ending in _key, _secret, or smtp_pass', () => {
+    const options = exportDbSubset(dump(), { playbook: 'content', postIds: [1] }).options;
+    expect(options).toContain('blogname');
+    expect(options.some((name) => /(_key|_secret|smtp_pass)$/.test(name))).toBe(false);
+  });
+});

api/__tests__/services/sandbox-manager.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { SandboxManager } from '../../src/services/sandbox-manager.ts';
+import type { DockerClient } from '../../src/sandbox/docker-client.ts';
+
+class FakeDocker implements DockerClient {
+  created: string[] = [];
+  destroyed: string[] = [];
+
+  async createSandbox(image: string) {
+    this.created.push(image);
+    return { id: 'sb-1', status: 'running' as const };
+  }
+
+  async destroySandbox(id: string) {
+    this.destroyed.push(id);
+  }
+
+  async status(id: string) {
+    return this.destroyed.includes(id) ? undefined : { id, status: 'running' as const };
+  }
+}
+
+describe('SandboxManager', () => {
+  it('spins up a sandbox and returns a preview URL', async () => {
+    const docker = new FakeDocker();
+    const manager = new SandboxManager(docker, { image: 'wursor-base:latest', previewBaseUrl: 'https://preview.wursor.dev' });
+
+    const result = await manager.start();
+    expect(result).toEqual({ sandboxId: 'sb-1', previewUrl: 'https://preview.wursor.dev/sb-1' });
+    expect(docker.created).toEqual(['wursor-base:latest']);
+  });
+
+  it('honors an explicit image override', async () => {
+    const docker = new FakeDocker();
+    const manager = new SandboxManager(docker, { image: 'wursor-base:latest', previewBaseUrl: 'https://preview.wursor.dev' });
+
+    await manager.start('wursor-base:canary');
+    expect(docker.created).toEqual(['wursor-base:canary']);
+  });
+
+  it('destroys a sandbox', async () => {
+    const docker = new FakeDocker();
+    const manager = new SandboxManager(docker, { image: 'wursor-base:latest', previewBaseUrl: 'https://preview.wursor.dev' });
+
+    await manager.destroy('sb-1');
+    expect(docker.destroyed).toEqual(['sb-1']);
+  });
+});

api/src/app.ts

@@ -5,6 +5,7 @@ import { InMemoryUserStore } from './services/user-store.ts';
 export async function buildApp() {
   const app = Fastify();
   const store = new InMemoryUserStore();
+  app.get('/health', async () => ({ ok: true }));
   await authRoutes(app, store);
   return app;
 }

api/src/sandbox/docker-client.ts

@@ -0,0 +1,10 @@
+export type SandboxInfo = {
+  id: string;
+  status: 'running' | 'destroyed';
+};
+
+export interface DockerClient {
+  createSandbox(image: string): Promise<SandboxInfo>;
+  destroySandbox(id: string): Promise<void>;
+  status(id: string): Promise<SandboxInfo | undefined>;
+}

api/src/sandbox/gc.ts

@@ -0,0 +1,27 @@
+export type SandboxStatus = 'running' | 'paused' | 'destroyed';
+
+export type SandboxState = {
+  status: SandboxStatus;
+  lastActiveAt: number;
+  createdAt: number;
+};
+
+export type GcAction = 'keep' | 'pause' | 'destroy';
+
+export type GcOptions = {
+  idleMs: number;
+  hardMs: number;
+};
+
+export function decideGc(state: SandboxState, now: number, opts: GcOptions): GcAction {
+  if (state.status === 'destroyed') {
+    return 'keep';
+  }
+  if (now - state.createdAt >= opts.hardMs) {
+    return 'destroy';
+  }
+  if (state.status === 'running' && now - state.lastActiveAt >= opts.idleMs) {
+    return 'pause';
+  }
+  return 'keep';
+}

api/src/sandbox/manifest.ts

@@ -0,0 +1,14 @@
+export type Manifest = Record<string, string>;
+
+export type ManifestDiff = {
+  added: string[];
+  changed: string[];
+  removed: string[];
+};
+
+export function diffManifest(before: Manifest, after: Manifest): ManifestDiff {
+  const added = Object.keys(after).filter((path) => !(path in before));
+  const removed = Object.keys(before).filter((path) => !(path in after));
+  const changed = Object.keys(after).filter((path) => path in before && before[path] !== after[path]);
+  return { added, changed, removed };
+}

api/src/sandbox/media-proxy.ts

@@ -0,0 +1,11 @@
+export function mediaProxyTarget(origin: string, path: string): string {
+  return `${origin}${path}`;
+}
+
+export function resolveMediaPath(origin: string, path: string, staged: ReadonlySet<string>): string {
+  return staged.has(path) ? path : mediaProxyTarget(origin, path);
+}
+
+export function stageReplacement(_origin: string, path: string, _bytes: number): { copiedPaths: string[] } {
+  return { copiedPaths: [path] };
+}

api/src/sandbox/subset.ts

@@ -0,0 +1,19 @@
+import type { Playbook, SiteExport, SubsetRequest, SubsetResult } from './types.ts';
+
+const PLAYBOOK_TABLES: Record<Playbook, Set<string>> = {
+  content: new Set(['wp_posts', 'wp_postmeta', 'wp_options']),
+  design: new Set(['wp_posts', 'wp_postmeta', 'wp_options', 'wp_terms', 'wp_term_taxonomy', 'wp_term_relationships']),
+  plugin: new Set(['wp_options']),
+};
+
+const secret = /(_key|_secret|smtp_pass)$/;
+
+export function exportDbSubset(dump: SiteExport, request: SubsetRequest): SubsetResult {
+  const wanted = PLAYBOOK_TABLES[request.playbook];
+  const tables = Object.keys(dump.tables).filter((name) => wanted.has(name));
+  const options = (dump.tables.wp_options ?? [])
+    .map((row) => String(row.option_name ?? ''))
+    .filter((name) => name !== '' && !secret.test(name));
+
+  return { tables, options };
+}

api/src/sandbox/types.ts

@@ -0,0 +1,17 @@
+export type Playbook = 'content' | 'design' | 'plugin';
+
+export type SiteExport = {
+  origin: string;
+  tables: Record<string, Array<Record<string, string | number>>>;
+  uploads: { path: string; bytes: number }[];
+};
+
+export type SubsetRequest = {
+  playbook: Playbook;
+  postIds: number[];
+};
+
+export type SubsetResult = {
+  tables: string[];
+  options: string[];
+};

api/src/services/sandbox-manager.ts

@@ -0,0 +1,22 @@
+import type { DockerClient } from '../sandbox/docker-client.ts';
+
+export type SandboxManagerOptions = {
+  image: string;
+  previewBaseUrl: string;
+};
+
+export class SandboxManager {
+  constructor(
+    private readonly docker: DockerClient,
+    private readonly opts: SandboxManagerOptions,
+  ) {}
+
+  async start(image?: string): Promise<{ sandboxId: string; previewUrl: string }> {
+    const info = await this.docker.createSandbox(image ?? this.opts.image);
+    return { sandboxId: info.id, previewUrl: `${this.opts.previewBaseUrl}/${info.id}` };
+  }
+
+  async destroy(id: string): Promise<void> {
+    await this.docker.destroySandbox(id);
+  }
+}