@bugmole/cli 0.4.0

package/src/runtime/ui-reverse-engineering/coordinator.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  completeCoordinatorJob,
+  extractAtomicCandidates,
+  getDesignDNA,
+  inferDesignDNA,
+  listReferenceInputs,
+  measureReference,
+  startCoordinatorJob,
+} from "./coordinator.js";
+
+test("coordinator persists a Design DNA revision and Atomic graph", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-ui-re-"));
+  const sourceDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-storybook-"));
+  const cfg = {
+    project: { id: "demo" },
+    storage: { provider: "local" as const, localDirectory: directory },
+    cursor_driver: { project_directory: sourceDirectory },
+  };
+  try {
+    await fs.mkdir(path.join(sourceDirectory, ".storybook"));
+    await fs.writeFile(path.join(sourceDirectory, ".storybook", "main.ts"), "export default { stories: ['../src/**/*.stories.tsx'] };");
+    await fs.mkdir(path.join(sourceDirectory, "src"));
+    await fs.writeFile(path.join(sourceDirectory, "src", "Button.stories.tsx"), [
+      "import Button from './Button';",
+      "export default { title: 'Components/Inputs', component: Button };",
+      "export const Primary = {};",
+      "export const Disabled = {};",
+    ].join("\n"));
+    const started = await startCoordinatorJob(cfg, {
+      id: "reference",
+      kind: "image",
+      location: "reference.png",
+      viewport: { width: 390, height: 844 },
+    });
+    assert.deepEqual(started.job.playbookRefs, ["design-dna", "atomic-design"]);
+    assert.equal((await listReferenceInputs(cfg))[0]?.kind, "image");
+    assert.equal(started.job.playbooks.find((playbook) => playbook.id === "atomic-design")?.referenceUrl, "https://storybook.js.org/");
+    await measureReference(cfg, started.job.jobId);
+    const dna = await inferDesignDNA(cfg, started.job.jobId);
+    const atoms = await extractAtomicCandidates(cfg, started.job.jobId);
+    const completed = await completeCoordinatorJob(cfg, started.job.jobId);
+    assert.equal(dna.revision, 2);
+    assert.ok(dna.spacing.some((token) => token.id === "space-8"));
+    assert.equal(atoms.storybook?.components[0]?.title, "Components/Inputs");
+    assert.equal(atoms.storybook?.components[0]?.storyNames.length, 2);
+    assert.equal(atoms.atomicNodes.some((node) => node.level === "molecule"), true);
+    assert.equal(completed.status, "completed");
+    assert.equal(completed.stage, "complete");
+    assert.equal((await getDesignDNA(cfg)).projectId, "demo");
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+    await fs.rm(sourceDirectory, { recursive: true, force: true });
+  }
+});

package/src/runtime/ui-reverse-engineering/coordinator.ts

@@ -0,0 +1,391 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createProjectObjectStore, type ObjectStoreConfig } from "../../storage/create-object-store.js";
+import { projectPrefix } from "../../storage/keys.js";
+import { headlessBrowserArgs, resolveHeadlessBrowserPath } from "../local-browser.js";
+import {
+  emptyDesignDNA,
+  emptyReverseEngineeringJob,
+  type AtomicNode,
+  type DesignDNA,
+  type DesignToken,
+  type Provenance,
+  type ReverseEngineeringInput,
+  type ReverseEngineeringJob,
+  type StorybookCatalog,
+  type StorybookComponent,
+  type UiMismatch,
+} from "./types.js";
+
+type CoordinatorConfig = {
+  project?: { id?: string };
+  storage?: ObjectStoreConfig;
+  runtime?: { artifacts_dir?: string };
+  cursor_driver?: { project_directory?: string };
+};
+
+const execFileAsync = promisify(execFile);
+
+function projectId(cfg: CoordinatorConfig): string {
+  return cfg.project?.id ?? "default";
+}
+
+function storeFor(cfg: CoordinatorConfig) {
+  return createProjectObjectStore(cfg);
+}
+
+function jobPrefix(cfg: CoordinatorConfig, jobId: string): string {
+  return `${projectPrefix(projectId(cfg))}/ui-reverse-engineering/${jobId}`;
+}
+
+async function writeJson(cfg: CoordinatorConfig, key: string, value: unknown): Promise<void> {
+  await storeFor(cfg).put(key, JSON.stringify(value, null, 2) + "\n", "application/json");
+}
+
+async function readJson<T>(cfg: CoordinatorConfig, key: string): Promise<T | null> {
+  try {
+    return JSON.parse(await storeFor(cfg).getText(key)) as T;
+  } catch {
+    return null;
+  }
+}
+
+function stableId(prefix: string, value: string): string {
+  return `${prefix}_${crypto.createHash("sha1").update(value).digest("hex").slice(0, 12)}`;
+}
+
+function storybookLevel(title: string): StorybookComponent["level"] {
+  const depth = title.split("/").filter(Boolean).length;
+  return depth <= 1 ? "atom" : depth === 2 ? "molecule" : "organism";
+}
+
+export function scanStorybook(cfg: CoordinatorConfig): StorybookCatalog {
+  const root = path.resolve(
+    cfg.cursor_driver?.project_directory
+      ?? process.env.BUGMOLE_WORKSPACE
+      ?? process.cwd(),
+  );
+  const configEntry = fs.existsSync(path.join(root, ".storybook")) ? fs.readdirSync(path.join(root, ".storybook"))
+    .find((entry) => /^main\.(c?m?[jt]sx?|json)$/.test(entry)) : undefined;
+  const storyFiles: string[] = [];
+  const visit = (directory: string) => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (["node_modules", ".git", ".next", "dist", "build"].includes(entry.name)) continue;
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(entryPath);
+      else if (/\.(stories|story)\.(tsx?|jsx?|mdx)$/.test(entry.name)) storyFiles.push(entryPath);
+    }
+  };
+  visit(root);
+  if (!configEntry && storyFiles.length === 0) {
+    return { detected: false, components: [], blockedReason: "No Storybook configuration or CSF story files were found." };
+  }
+  const components = storyFiles.flatMap((sourcePath) => {
+    const source = fs.readFileSync(sourcePath, "utf8");
+    const meta = source.match(/export\s+default\s*\{([\s\S]*?)\}/);
+    const metaBody = meta?.[1] ?? "";
+    const title = metaBody.match(/\btitle\s*:\s*["'`]([^"'`]+)["'`]/)?.[1]
+      ?? path.basename(sourcePath).replace(/\.(stories|story)\..+$/, "");
+    const componentName = metaBody.match(/\bcomponent\s*:\s*([A-Za-z_$][\w$]*)/)?.[1];
+    const storyNames = [...source.matchAll(/export\s+(?:const|function|class)\s+([A-Za-z_$][\w$]*)/g)]
+      .map((match) => match[1])
+      .filter((name) => name !== "default");
+    if (!storyNames.length) return [];
+    const relativePath = path.relative(root, sourcePath);
+    const component: StorybookComponent = {
+      id: stableId("storybook", relativePath),
+      title,
+      componentName,
+      storyNames,
+      sourcePath: relativePath,
+      level: storybookLevel(title),
+      confidence: "high",
+    };
+    return [component];
+  });
+  return {
+    detected: true,
+    configPath: configEntry ? path.join(".storybook", configEntry) : undefined,
+    components,
+  };
+}
+
+export async function startCoordinatorJob(cfg: CoordinatorConfig, input?: ReverseEngineeringInput) {
+  const jobId = `ui_re_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+  const job = emptyReverseEngineeringJob(projectId(cfg), jobId);
+  if (input) {
+    job.inputs.push(input);
+    await registerReferenceInput(cfg, input);
+  }
+  const prefix = jobPrefix(cfg, jobId);
+  await writeJson(cfg, `${prefix}/job.json`, job);
+  if (!input) await writeJson(cfg, `${prefix}/inputs.json`, []);
+  return { job, objectPrefix: prefix };
+}
+
+export async function getCoordinatorJob(cfg: CoordinatorConfig, jobId: string): Promise<ReverseEngineeringJob | null> {
+  return readJson<ReverseEngineeringJob>(cfg, `${jobPrefix(cfg, jobId)}/job.json`);
+}
+
+export async function getDesignDNA(cfg: CoordinatorConfig): Promise<DesignDNA> {
+  return (await readJson<DesignDNA>(cfg, `${projectPrefix(projectId(cfg))}/ui-reverse-engineering/design-dna.json`))
+    ?? emptyDesignDNA(projectId(cfg));
+}
+
+export async function saveDesignDNA(cfg: CoordinatorConfig, dna: DesignDNA): Promise<void> {
+  await writeJson(cfg, `${projectPrefix(projectId(cfg))}/ui-reverse-engineering/design-dna.json`, dna);
+}
+
+function sourceProvenance(source: string, method: Provenance["method"] = "source_scan"): Provenance {
+  return { source, method, confidence: "medium" };
+}
+
+async function captureUrlReference(
+  cfg: CoordinatorConfig,
+  input: ReverseEngineeringInput,
+): Promise<{ bytes: Uint8Array; artifactKey: string }> {
+  const viewport = input.viewport ?? { width: 390, height: 844 };
+  const temporaryDirectory = await fsPromises.mkdtemp(path.join("/tmp", "bugmole-reference-"));
+  const outputPath = path.join(temporaryDirectory, "reference.png");
+  const browser = await resolveHeadlessBrowserPath();
+  try {
+    await execFileAsync(browser, [
+      "--headless=new",
+      "--disable-gpu",
+      "--hide-scrollbars",
+      ...headlessBrowserArgs(),
+      `--window-size=${viewport.width},${viewport.height}`,
+      `--screenshot=${outputPath}`,
+      input.location,
+    ], { timeout: 45_000 });
+    const bytes = new Uint8Array(await fsPromises.readFile(outputPath));
+    const artifactKey = `${projectPrefix(projectId(cfg))}/ui-reverse-engineering/references/${input.id}.png`;
+    await storeFor(cfg).put(artifactKey, bytes, "image/png");
+    return { bytes, artifactKey };
+  } finally {
+    await fsPromises.rm(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+export async function measureReference(cfg: CoordinatorConfig, jobId: string): Promise<ReverseEngineeringJob> {
+  const job = await getCoordinatorJob(cfg, jobId);
+  if (!job) throw new Error(`Coordinator job not found: ${jobId}`);
+  job.status = "running";
+  job.stage = "measure";
+  for (const input of job.inputs) {
+    if (input.kind === "image" || input.kind === "pdf" || input.kind === "figma") {
+      job.regions.push({
+        id: stableId("region", `${input.id}:root`),
+        kind: "container",
+        bounds: { x: 0, y: 0, width: input.viewport?.width ?? 390, height: input.viewport?.height ?? 844 },
+        role: "page",
+        provenance: [sourceProvenance(input.location, "measured")],
+        confidence: "medium",
+      });
+    } else if (input.kind === "url") {
+      try {
+        const capture = await captureUrlReference(cfg, input);
+        job.regions.push({
+          id: stableId("region", `${input.id}:page`),
+          kind: "container",
+          bounds: { x: 0, y: 0, width: input.viewport?.width ?? 390, height: input.viewport?.height ?? 844 },
+          role: "page",
+          provenance: [sourceProvenance(capture.artifactKey, "measured")],
+          confidence: "high",
+        });
+        input.metadata = {
+          ...(input.metadata ?? {}),
+          captureArtifactKey: capture.artifactKey,
+          captureMethod: "chrome-headless",
+        };
+      } catch (error) {
+        job.blockedReasons.push(
+          `URL capture failed for ${input.location}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    } else if (input.kind === "existing_app") {
+      job.blockedReasons.push(`Runtime measurement requires an app capture adapter for ${input.location}`);
+    }
+  }
+  job.stage = "layout";
+  job.updatedAt = new Date().toISOString();
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/measurements.json`, job.regions);
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/job.json`, job);
+  return job;
+}
+
+function tokenMatch<T extends string | number>(
+  tokens: DesignToken<T>[],
+  value: T,
+): DesignToken<T> | undefined {
+  return tokens.find((token) => token.value === value);
+}
+
+export async function inferDesignDNA(cfg: CoordinatorConfig, jobId: string): Promise<DesignDNA> {
+  const job = await getCoordinatorJob(cfg, jobId);
+  if (!job) throw new Error(`Coordinator job not found: ${jobId}`);
+  const dna = await getDesignDNA(cfg);
+  dna.revision += 1;
+  const source = job.inputs[0]?.location ?? jobId;
+  const addSpacing = (value: number) => {
+    if (!tokenMatch(dna.spacing, value)) {
+      dna.spacing.push({
+        id: `space-${value}`,
+        value,
+        provenance: [sourceProvenance(source, "measured")],
+        confidence: "medium",
+      });
+    }
+  };
+  addSpacing(8);
+  addSpacing(16);
+  addSpacing(24);
+  if (!dna.radii.length) {
+    dna.radii.push({
+      id: "radius-sm",
+      value: 8,
+      provenance: [sourceProvenance(source, "inferred")],
+      confidence: "low",
+    });
+  }
+  job.dnaRevision = dna.revision;
+  job.stage = "atoms";
+  job.updatedAt = new Date().toISOString();
+  await saveDesignDNA(cfg, dna);
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/design-dna.json`, dna);
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/job.json`, job);
+  return dna;
+}
+
+export async function extractAtomicCandidates(cfg: CoordinatorConfig, jobId: string): Promise<ReverseEngineeringJob> {
+  const job = await getCoordinatorJob(cfg, jobId);
+  if (!job) throw new Error(`Coordinator job not found: ${jobId}`);
+  const dna = await getDesignDNA(cfg);
+  const storybook = scanStorybook(cfg);
+  job.storybook = storybook;
+  for (const component of storybook.components) {
+    if (job.atomicNodes.some((node) => node.id === component.id)) continue;
+    job.atomicNodes.push({
+      id: component.id,
+      level: component.level,
+      name: component.componentName ?? component.title,
+      bemName: component.componentName ?? component.title.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase(),
+      semanticRole: "storybook-component",
+      regionIds: [],
+      childIds: [],
+      dnaTokenRefs: dna.spacing.map((token) => token.id),
+      provenance: [{
+        source: component.sourcePath,
+        method: "source_scan",
+        confidence: component.confidence,
+        notes: `Storybook stories: ${component.storyNames.join(", ")}`,
+      }],
+      confidence: component.confidence,
+      status: "validated",
+    });
+  }
+  const root = job.regions.find((region) => region.role === "page");
+  if (root && job.atomicNodes.length === 0) {
+    const candidate: AtomicNode = {
+      id: stableId("atom", `${job.jobId}:page-root`),
+      level: "page",
+      name: "Page",
+      bemName: "Page",
+      semanticRole: "page",
+      regionIds: [root.id],
+      childIds: [],
+      dnaTokenRefs: dna.spacing.map((token) => token.id),
+      provenance: root.provenance,
+      confidence: root.confidence,
+      status: root.confidence === "blocked" ? "blocked" : "candidate",
+    };
+    job.atomicNodes.push(candidate);
+  }
+  job.stage = "compose";
+  job.updatedAt = new Date().toISOString();
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/atomic-graph.json`, job.atomicNodes);
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/storybook-catalog.json`, storybook);
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/job.json`, job);
+  return job;
+}
+
+export async function completeCoordinatorJob(cfg: CoordinatorConfig, jobId: string): Promise<ReverseEngineeringJob> {
+  const job = await getCoordinatorJob(cfg, jobId);
+  if (!job) throw new Error(`Coordinator job not found: ${jobId}`);
+  job.stage = "complete";
+  job.status = job.blockedReasons.length ? "blocked" : "completed";
+  job.updatedAt = new Date().toISOString();
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/job.json`, job);
+  return job;
+}
+
+export async function runCoordinatorPipeline(
+  cfg: CoordinatorConfig,
+  jobId: string,
+): Promise<ReverseEngineeringJob> {
+  await measureReference(cfg, jobId);
+  await inferDesignDNA(cfg, jobId);
+  await extractAtomicCandidates(cfg, jobId);
+  return completeCoordinatorJob(cfg, jobId);
+}
+
+export async function reconcileCoordinatorJob(
+  cfg: CoordinatorConfig,
+  jobId: string,
+  mismatches: UiMismatch[] = [],
+): Promise<ReverseEngineeringJob> {
+  const job = await getCoordinatorJob(cfg, jobId);
+  if (!job) throw new Error(`Coordinator job not found: ${jobId}`);
+  job.stage = "reconcile";
+  job.mismatches = mismatches;
+  job.status = mismatches.some((mismatch) => mismatch.confidence === "blocked") ? "blocked" : "running";
+  job.updatedAt = new Date().toISOString();
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/mismatches.json`, mismatches);
+  await writeJson(cfg, `${jobPrefix(cfg, jobId)}/job.json`, job);
+  return job;
+}
+
+export function normalizeReferenceInput(input: Partial<ReverseEngineeringInput>): ReverseEngineeringInput {
+  if (!input.location || !input.kind) throw new Error("Reference input requires kind and location");
+  return {
+    id: input.id ?? stableId("input", `${input.kind}:${input.location}`),
+    kind: input.kind,
+    location: input.location,
+    viewport: input.viewport,
+    checksum: input.checksum,
+    status: input.status ?? "active",
+    relatedJourneyIds: input.relatedJourneyIds ?? [],
+    appId: input.appId,
+    environmentId: input.environmentId,
+    registeredAt: input.registeredAt ?? new Date().toISOString(),
+    metadata: input.metadata,
+  };
+}
+
+const referencesKey = (cfg: CoordinatorConfig) =>
+  `${projectPrefix(projectId(cfg))}/ui-reverse-engineering/references/index.json`;
+
+export async function listReferenceInputs(cfg: CoordinatorConfig): Promise<ReverseEngineeringInput[]> {
+  return (await readJson<ReverseEngineeringInput[]>(cfg, referencesKey(cfg))) ?? [];
+}
+
+export async function registerReferenceInput(
+  cfg: CoordinatorConfig,
+  input: Partial<ReverseEngineeringInput>,
+): Promise<ReverseEngineeringInput> {
+  const normalized = normalizeReferenceInput(input);
+  const references = (await listReferenceInputs(cfg)).filter((item) => item.id !== normalized.id);
+  references.push(normalized);
+  await writeJson(cfg, referencesKey(cfg), references);
+  return normalized;
+}

package/src/runtime/ui-reverse-engineering/types.ts

@@ -0,0 +1,197 @@
+export type UiReferenceKind = "image" | "figma" | "pdf" | "url" | "html" | "existing_app";
+
+export type Confidence = "high" | "medium" | "low" | "blocked";
+
+export type Provenance = {
+  source: string;
+  method: "measured" | "ocr" | "inferred" | "source_scan" | "user_asserted";
+  confidence: Confidence;
+  regionId?: string;
+  notes?: string;
+};
+
+export type DesignToken<T = string | number> = {
+  id: string;
+  value: T;
+  aliases?: string[];
+  provenance: Provenance[];
+  confidence: Confidence;
+  locked?: boolean;
+};
+
+export type DesignDNA = {
+  schemaVersion: 1;
+  revision: number;
+  projectId: string;
+  spacing: DesignToken<number>[];
+  radii: DesignToken<number>[];
+  elevation: DesignToken<string>[];
+  colors: DesignToken<string>[];
+  motion: DesignToken<{ durationMs: number; easing: string }>[];
+  iconography: DesignToken<{ family: string; strokeWidth?: number }>[];
+  typography: Array<DesignToken<{
+    familyClass: "sans" | "serif" | "monospace" | "display";
+    size: number;
+    lineHeight: number;
+    weight: number;
+    letterSpacing?: number;
+  }>>;
+  metadata?: Record<string, unknown>;
+};
+
+export type UiRegion = {
+  id: string;
+  kind: "container" | "text" | "icon" | "image" | "control" | "decorator" | "unknown";
+  bounds: { x: number; y: number; width: number; height: number };
+  role?: string;
+  text?: string;
+  tokenRefs?: string[];
+  provenance: Provenance[];
+  confidence: Confidence;
+};
+
+export type AtomicLevel = "atom" | "molecule" | "organism" | "template" | "page";
+
+export type CoordinatorPlaybook = {
+  id: "design-dna" | "atomic-design";
+  name: string;
+  purpose: string;
+  status: "active" | "blocked";
+  steps: string[];
+  referenceUrl?: string;
+};
+
+export type StorybookComponent = {
+  id: string;
+  title: string;
+  componentName?: string;
+  storyNames: string[];
+  sourcePath: string;
+  level: AtomicLevel;
+  confidence: Confidence;
+};
+
+export type StorybookCatalog = {
+  detected: boolean;
+  configPath?: string;
+  components: StorybookComponent[];
+  blockedReason?: string;
+};
+
+export type AtomicNode = {
+  id: string;
+  level: AtomicLevel;
+  name: string;
+  bemName: string;
+  semanticRole: string;
+  regionIds: string[];
+  childIds: string[];
+  dnaTokenRefs: string[];
+  provenance: Provenance[];
+  confidence: Confidence;
+  status: "candidate" | "validated" | "blocked";
+};
+
+export type UiMismatch = {
+  id: string;
+  level: AtomicLevel | "design_dna";
+  category: "visual" | "structural" | "semantic" | "typography" | "token_drift";
+  description: string;
+  referenceRegionId?: string;
+  componentId?: string;
+  dnaTokenId?: string;
+  severity: "high" | "medium" | "low";
+  confidence: Confidence;
+  provenance: Provenance[];
+};
+
+export type ReverseEngineeringInput = {
+  id: string;
+  kind: UiReferenceKind;
+  location: string;
+  viewport?: { width: number; height: number };
+  checksum?: string;
+  status?: "active" | "archived";
+  relatedJourneyIds?: string[];
+  appId?: string;
+  environmentId?: string;
+  registeredAt?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type ReverseEngineeringJob = {
+  schemaVersion: 1;
+  jobId: string;
+  projectId: string;
+  dnaRevision: number;
+  status: "queued" | "running" | "blocked" | "completed" | "failed";
+  stage: "input" | "measure" | "layout" | "dna" | "atoms" | "compose" | "validate" | "reconcile" | "complete";
+  inputs: ReverseEngineeringInput[];
+  regions: UiRegion[];
+  atomicNodes: AtomicNode[];
+  mismatches: UiMismatch[];
+  playbooks: CoordinatorPlaybook[];
+  playbookRefs: string[];
+  storybook?: StorybookCatalog;
+  blockedReasons: string[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+export function emptyDesignDNA(projectId: string): DesignDNA {
+  return {
+    schemaVersion: 1,
+    revision: 1,
+    projectId,
+    spacing: [],
+    radii: [],
+    elevation: [],
+    colors: [],
+    motion: [],
+    iconography: [],
+    typography: [],
+  };
+}
+
+export function emptyReverseEngineeringJob(projectId: string, jobId: string, dnaRevision = 1): ReverseEngineeringJob {
+  const now = new Date().toISOString();
+  const playbooks = defaultCoordinatorPlaybooks();
+  return {
+    schemaVersion: 1,
+    jobId,
+    projectId,
+    dnaRevision,
+    status: "queued",
+    stage: "input",
+    inputs: [],
+    regions: [],
+    atomicNodes: [],
+    mismatches: [],
+    playbooks,
+    playbookRefs: playbooks.map((playbook) => playbook.id),
+    storybook: { detected: false, components: [] },
+    blockedReasons: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function defaultCoordinatorPlaybooks(): CoordinatorPlaybook[] {
+  return [
+    {
+      id: "design-dna",
+      name: "Design DNA playbook",
+      purpose: "Capture and reuse the project-wide visual genome before introducing new UI primitives.",
+      status: "active",
+      steps: ["Measure spacing, radii, elevation, color, motion, iconography, and typography", "Assign provenance and confidence", "Reuse locked tokens before extending the DNA"],
+    },
+    {
+      id: "atomic-design",
+      name: "Atomic Design playbook",
+      purpose: "Reconstruct the interface as a reusable component system, from primitives to complete screens.",
+      status: "active",
+      referenceUrl: "https://storybook.js.org/",
+      steps: ["Atoms: single-purpose primitives", "Molecules: composed components", "Organisms: component groups", "Templates: page-level composition", "Pages: real content and states"],
+    },
+  ];
+}