@design-ai/cli 4.55.0 → 4.57.0

package/cli/lib/site-prompts.mjs

@@ -0,0 +1,332 @@
+// Prompt and handoff report builders for Website Improvement workspaces.
+
+import { normalizeImplementationEvidence } from "./site-evidence.mjs";
+import { SITE_PROMPT_TEMPLATE_IDS, SITE_PROMPT_TEMPLATES } from "./site-content.mjs";
+import { AUDIT_CATEGORIES, MCP_ITEMS, PRIORITY_OPTIONS, categoryById } from "./site-options.mjs";
+import { markdownList } from "./site-strings.mjs";
+
+export function profileBlock(workspace) {
+  const profile = workspace.siteProfile;
+  return [
+    "Site profile:",
+    `- Name: ${profile.name}`,
+    `- Live URL: ${profile.liveUrl || "not provided"}`,
+    `- Repo URL: ${profile.repoUrl || "not provided"}`,
+    `- Local path: ${profile.localPath || "not provided"}`,
+    `- Figma URL: ${profile.figmaUrl || "not provided"}`,
+    `- Deploy: ${profile.deployProvider}`,
+    `- Sentry: ${profile.sentryProject || "not provided"}`,
+    `- CMS: ${profile.cms}`,
+    `- Database: ${profile.database}`,
+    `- Viewports: ${profile.viewports.join(", ")}`,
+    "",
+    "Priority pages:",
+    markdownList(profile.pages, "No pages listed"),
+    "",
+    "User flows:",
+    markdownList(profile.userFlows, "No user flows listed"),
+    "",
+    "Brand/design notes:",
+    profile.brandNotes || "No brand notes provided.",
+  ].join("\n");
+}
+
+function auditBlock(workspace) {
+  return AUDIT_CATEGORIES.map((category) => {
+    const row = workspace.auditChecklist[category.id];
+    return [
+      `- ${category.label} [${row.status}]`,
+      `  Notes: ${row.notes || "none"}`,
+      `  Findings: ${row.findings.length ? row.findings.join("; ") : "none"}`,
+    ].join("\n");
+  }).join("\n");
+}
+
+export function mcpBlock(workspace) {
+  return MCP_ITEMS.map(([key, label]) => `- ${label}: ${workspace.mcpReadiness[key]}`).join("\n");
+}
+
+function taskBlock(task) {
+  if (!task) return "No refactor task selected. Use the Refactor Plan section first.";
+  return [
+    "Selected task:",
+    `- Task ID: ${task.id}`,
+    `- Title: ${task.title}`,
+    `- Category: ${categoryById(task.category).label}`,
+    `- Problem: ${task.problem}`,
+    `- Evidence: ${task.evidence || "not provided"}`,
+    `- Impact: ${task.impact}`,
+    `- Effort: ${task.effort}`,
+    `- Priority: ${task.priority}`,
+    `- Pages: ${task.pages.join(", ") || "not specified"}`,
+    `- Recommended MCP: ${task.recommendedMcp.join(", ") || "none"}`,
+    "",
+    "Verification:",
+    markdownList(task.verification, "Run target repo verification"),
+    "",
+    "Risks:",
+    markdownList(task.risks, "No risks listed"),
+  ].join("\n");
+}
+
+function primaryTask(workspace) {
+  return orderedRefactorTasks(workspace)[0] || null;
+}
+
+export function orderedRefactorTasks(workspace) {
+  return workspace.refactorTasks
+    .map((task, index) => ({ task, index }))
+    .sort((a, b) => {
+      const priorityDelta = PRIORITY_OPTIONS.indexOf(a.task.priority) - PRIORITY_OPTIONS.indexOf(b.task.priority);
+      if (priorityDelta !== 0) return priorityDelta;
+      return a.index - b.index;
+    })
+    .map((item) => item.task);
+}
+
+export function resolveSitePromptTask(workspace, selector = "") {
+  const tasks = orderedRefactorTasks(workspace);
+  const trimmed = String(selector || "").trim();
+  if (!trimmed) return primaryTask(workspace);
+
+  const byId = workspace.refactorTasks.find((task) => task.id === trimmed);
+  if (byId) return byId;
+
+  if (/^[1-9]\d*$/.test(trimmed)) {
+    const index = Number.parseInt(trimmed, 10) - 1;
+    if (tasks[index]) return tasks[index];
+  }
+
+  const ids = tasks.map((task, index) => `${index + 1}:${task.id}`).join(", ");
+  throw new Error(`Unknown refactor task: ${trimmed}. Use one of: ${ids || "no tasks available"}`);
+}
+
+export function buildSitePrompt(workspace, templateId, { taskSelector = "" } = {}) {
+  const profile = profileBlock(workspace);
+  const audit = auditBlock(workspace);
+  const mcp = mcpBlock(workspace);
+  const task = taskBlock(resolveSitePromptTask(workspace, taskSelector));
+  const commonRules = [
+    "Rules:",
+    "- Work in the target website repository, not in this design-ai repository.",
+    "- Inspect existing architecture, components, state, styling, and design tokens before editing.",
+    "- Keep changes scoped and avoid new dependencies unless clearly justified.",
+    "- Preserve accessibility: keyboard reachability, visible focus, semantic HTML, screen-reader labels, and WCAG 2.1 AA contrast.",
+    "- Verify desktop, tablet, and mobile layouts.",
+  ].join("\n");
+
+  const map = {
+    "codex-repo-intake": [
+      "# Codex repo intake prompt",
+      profile,
+      "",
+      "Goal: inspect the target website repo and produce a concise implementation plan for website improvement work.",
+      "",
+      commonRules,
+      "",
+      "Read first:",
+      "- package/dependency manifest",
+      "- app/router entrypoints",
+      "- layout and design system primitives",
+      "- styling/token setup",
+      "- test/build scripts",
+      "",
+      "Return: repo structure, routing, reusable components, state/data model, likely touch points, risks, and exact verification commands.",
+    ],
+    "codex-implementation": [
+      "# Codex implementation prompt",
+      profile,
+      "",
+      task,
+      "",
+      commonRules,
+      "",
+      "Implement the smallest safe fix. After editing, run the target repo's most relevant lint/typecheck/build/test command and summarize changed files plus verification.",
+    ],
+    "codex-visual-qa": [
+      "# Codex visual QA prompt",
+      profile,
+      "",
+      "Audit checklist state:",
+      audit,
+      "",
+      `Use Browser/Playwright if available. Verify the priority pages across ${workspace.siteProfile.viewports.join(", ")}. Check layout, typography, CTA hierarchy, forms, focus indicators, console errors, and broken assets.`,
+    ],
+    "codex-deployment": [
+      "# Codex deployment verification prompt",
+      profile,
+      "",
+      "MCP readiness:",
+      mcp,
+      "",
+      "Verify the deployment or preview URL, runtime logs, environment assumptions, SEO metadata, and major user flows. Report pass/fail evidence and remaining launch risks.",
+    ],
+    "claude-design-review": [
+      "# Claude design review prompt",
+      profile,
+      "",
+      "Review the live site or screenshots as a senior product designer. Focus on visual hierarchy, layout rhythm, typography, color, spacing, CTA clarity, responsive behavior, and accessibility concerns. Provide one best path and cite concrete evidence.",
+    ],
+    "claude-competitor": [
+      "# Claude competitor research prompt",
+      profile,
+      "",
+      "Research 3-5 relevant competitors or peer websites. Compare homepage structure, conversion path, proof points, pricing presentation, visual tone, content clarity, and SEO positioning. Return a concise opportunity map, not a generic benchmark.",
+    ],
+    "claude-copy-ux": [
+      "# Claude copy/UX critique prompt",
+      profile,
+      "",
+      "Critique the site's copy, information architecture, trust signals, CTA language, and conversion flow. Rewrite only the highest-impact sections and explain why the edits reduce user uncertainty.",
+    ],
+    "handoff-report": [
+      "# Final handoff report prompt",
+      profile,
+      "",
+      "Refactor plan:",
+      workspace.refactorTasks.map((item) => `- [${item.priority}] ${item.title}: ${item.problem}`).join("\n") || "- No tasks listed",
+      "",
+      "Create a final handoff report with target site info, audit summary, priority recommendations, executed work, verification results, remaining risks, and next actions.",
+    ],
+  };
+
+  return (map[templateId] || map["codex-repo-intake"]).join("\n");
+}
+
+export function buildSitePromptBundle(workspace) {
+  return [
+    `# Website improvement prompt bundle: ${workspace.siteProfile.name}`,
+    "",
+    "> Generated by design-ai site from a Website Improvement Console workspace export.",
+    "",
+    ...SITE_PROMPT_TEMPLATE_IDS.flatMap((templateId) => [
+      `## ${templateId}`,
+      "",
+      buildSitePrompt(workspace, templateId),
+      "",
+    ]),
+  ].join("\n").trimEnd();
+}
+
+export function buildSiteBundleImplementationPrompt(workspace) {
+  const tasks = orderedRefactorTasks(workspace);
+  if (tasks.length > 0) {
+    return buildSitePrompt(workspace, "codex-implementation", { taskSelector: "1" });
+  }
+
+  return [
+    "# Codex implementation prompt",
+    profileBlock(workspace),
+    "",
+    mcpBlock(workspace),
+    "",
+    "Task ID: no-refactor-task-yet",
+    "Goal: inspect the target website repository, confirm the website improvement workspace facts, and produce concrete audit findings before implementation starts.",
+    "",
+    "Rules:",
+    "- Work in the target website repository, not in this design-ai repository.",
+    "- Do not modify production code until you identify specific audit findings and implementation tasks.",
+    "- Inspect existing architecture, components, state, styling, and design tokens before proposing edits.",
+    "- Preserve accessibility: keyboard reachability, visible focus, semantic HTML, screen-reader labels, and WCAG 2.1 AA contrast.",
+    "- Verify desktop, tablet, and mobile layouts before recommending implementation scope.",
+    "",
+    "Next step:",
+    "- Add audit findings to the Website Improvement workspace, then run `design-ai site website-workspace.json --tasks --out website-workspace.tasks.json` and regenerate this implementation prompt with `design-ai site website-workspace.tasks.json --prompt codex-implementation --task 1 --out codex-implementation.md`.",
+  ].join("\n");
+}
+
+export function formatSitePromptTemplatesJson() {
+  return JSON.stringify({
+    count: SITE_PROMPT_TEMPLATES.length,
+    templates: SITE_PROMPT_TEMPLATES,
+  }, null, 2);
+}
+
+export function formatSitePromptTemplatesHuman() {
+  return [
+    "Website Improvement prompt templates",
+    "",
+    ...SITE_PROMPT_TEMPLATES.flatMap((template, index) => [
+      `${index + 1}. ${template.id}`,
+      `   Label: ${template.label}`,
+      `   Agent: ${template.agent}`,
+      `   Output: ${template.output}`,
+      `   Task selectable: ${template.taskSelectable ? "yes" : "no"}`,
+      `   ${template.description}`,
+    ]),
+    "",
+    "Use:",
+    "  design-ai site <workspace.json> --prompt <template-id>",
+    "  design-ai site <workspace.json> --prompt codex-implementation --task <id-or-number>",
+  ].join("\n");
+}
+
+export function buildSiteHandoffReport(workspace) {
+  const profile = workspace.siteProfile;
+  const tasks = workspace.refactorTasks;
+  const evidence = normalizeImplementationEvidence(workspace.implementationEvidence);
+  return [
+    `# Website improvement handoff: ${profile.name}`,
+    "",
+    "> Generated by design-ai site from a Website Improvement Console workspace export.",
+    "",
+    "## Target site",
+    "",
+    `- Live URL: ${profile.liveUrl || "not provided"}`,
+    `- Repo URL: ${profile.repoUrl || "not provided"}`,
+    `- Local path: ${profile.localPath || "not provided"}`,
+    `- Figma URL: ${profile.figmaUrl || "not provided"}`,
+    `- Deploy provider: ${profile.deployProvider}`,
+    `- CMS: ${profile.cms}`,
+    `- Database: ${profile.database}`,
+    `- Viewports: ${profile.viewports.join(", ")}`,
+    "",
+    "## Diagnostic summary",
+    "",
+    auditBlock(workspace),
+    "",
+    "## MCP Readiness",
+    "",
+    mcpBlock(workspace),
+    "",
+    "## Priority improvement plan",
+    "",
+    tasks.length ? tasks.map((task) => [
+      `### [${task.priority.toUpperCase()}] ${task.title}`,
+      "",
+      `- Category: ${categoryById(task.category).label}`,
+      `- Impact: ${task.impact}`,
+      `- Effort: ${task.effort}`,
+      `- Pages: ${task.pages.join(", ") || "not specified"}`,
+      `- MCP: ${task.recommendedMcp.join(", ") || "none"}`,
+      `- Problem: ${task.problem}`,
+      `- Evidence: ${task.evidence || "not provided"}`,
+      "",
+      "Verification:",
+      markdownList(task.verification, "Run target repo verification"),
+      "",
+      "Risks:",
+      markdownList(task.risks, "No risks listed"),
+    ].join("\n")).join("\n\n") : "No refactor tasks generated yet.",
+    "",
+    "## Executed work",
+    "",
+    markdownList(evidence.executedWork, "Not recorded yet. Add implementation notes after running Codex in the target repo."),
+    "",
+    "## Verification results",
+    "",
+    markdownList(evidence.verificationResults, "Not recorded yet. Paste target repo lint/typecheck/build, Browser QA, and deployment checks here."),
+    "",
+    "## Remaining risks",
+    "",
+    markdownList(evidence.remainingRisks, "No remaining risks recorded."),
+    "",
+    "## Next actions",
+    "",
+    markdownList(evidence.nextActions, "No next actions recorded."),
+    "",
+    "## Notes",
+    "",
+    workspace.reportNotes || "No notes recorded.",
+  ].join("\n");
+}

package/cli/lib/site-starter.mjs

@@ -0,0 +1,153 @@
+// Starter artifacts for Website Improvement workspaces.
+
+import {
+  SITE_INTAKE_TEMPLATE_MARKDOWN,
+  SITE_INTAKE_TEMPLATE_MARKDOWN_KO,
+  SITE_INTAKE_TEMPLATE_SECTIONS,
+} from "./site-content.mjs";
+import { DEFAULT_IMPLEMENTATION_RISKS } from "./site-evidence.mjs";
+import { SITE_INTAKE_TEMPLATE_LANGUAGE_OPTIONS } from "./site-options.mjs";
+
+export function buildSiteIntakeTemplateMarkdown({ language = "en" } = {}) {
+  if (!SITE_INTAKE_TEMPLATE_LANGUAGE_OPTIONS.includes(language)) {
+    throw new Error(`language must be one of: ${SITE_INTAKE_TEMPLATE_LANGUAGE_OPTIONS.join(", ")}`);
+  }
+  return language === "ko" ? SITE_INTAKE_TEMPLATE_MARKDOWN_KO : SITE_INTAKE_TEMPLATE_MARKDOWN;
+}
+
+export function formatSiteIntakeTemplateJson({ language = "en" } = {}) {
+  const content = buildSiteIntakeTemplateMarkdown({ language });
+  return JSON.stringify({
+    kind: "website-improvement-intake-template",
+    version: 1,
+    format: "markdown",
+    language,
+    recommendedFileName: language === "ko" ? "company-website-intake.ko.md" : "company-website-intake.md",
+    sections: SITE_INTAKE_TEMPLATE_SECTIONS,
+    privacy: {
+      storesCredentials: false,
+      storesProductionSecrets: false,
+      storesCustomerData: false,
+    },
+    commands: {
+      nextActions: "design-ai site --init --name \"<site name>\" --live-url <live-url> --local-path <absolute-target-repo-path> --next-actions --out website-next-actions.md --force",
+      bundle: "design-ai site --init --name \"<site name>\" --live-url <live-url> --local-path <absolute-target-repo-path> --bundle --out website-handoff-bundle --strict --force",
+      bundleCheck: "design-ai site website-handoff-bundle --bundle-check --strict --json --out website-bundle-check.json --force",
+      bundleHandoff: "design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md --force",
+    },
+    content,
+  }, null, 2);
+}
+
+export function createSampleSiteWorkspace() {
+  return {
+    version: 1,
+    updatedAt: "2026-05-30T00:00:00.000Z",
+    siteProfile: {
+      id: "sample-korean-saas",
+      name: "Korean SaaS marketing site",
+      liveUrl: "https://example.com",
+      repoUrl: "https://github.com/acme/korean-saas-site",
+      localPath: "/Users/you/dev/korean-saas-site",
+      figmaUrl: "https://figma.com/file/example",
+      brandNotes: "Quiet B2B SaaS tone, Pretendard typography, dense but readable Korean product copy, indigo accent only for action and focus.",
+      deployProvider: "vercel",
+      sentryProject: "acme/korean-saas-web",
+      cms: "sanity",
+      database: "none",
+      pages: ["/", "/pricing", "/signup", "/docs"],
+      userFlows: [
+        "Visitor compares pricing and starts signup",
+        "Existing customer finds feature proof before contacting sales",
+      ],
+      viewports: ["desktop", "tablet", "mobile"],
+    },
+    auditChecklist: {
+      "visual-design": {
+        status: "in-progress",
+        notes: "Hero hierarchy and CTA contrast need review before company pilot.",
+        findings: ["Primary CTA competes with secondary link on the homepage"],
+      },
+      "ux-flow": {
+        status: "todo",
+        notes: "Map visitor path from landing page to pricing and signup.",
+        findings: [],
+      },
+      responsive: {
+        status: "todo",
+        notes: "Check 1440, 1024, 390, and 360 width layouts.",
+        findings: [],
+      },
+      accessibility: {
+        status: "todo",
+        notes: "Keyboard and focus audit required for nav, pricing toggle, and forms.",
+        findings: ["Focus state is not yet documented for the mobile menu"],
+      },
+      performance: {
+        status: "todo",
+        notes: "Run Lighthouse after visual pass.",
+        findings: [],
+      },
+      seo: {
+        status: "todo",
+        notes: "Inspect title, description, heading order, canonical, OG.",
+        findings: [],
+      },
+      "technical-quality": {
+        status: "todo",
+        notes: "Confirm component reuse before editing target repo.",
+        findings: [],
+      },
+      "runtime-issues": {
+        status: "todo",
+        notes: "Open console/network once preview deploy is available.",
+        findings: [],
+      },
+      "content-quality": {
+        status: "in-progress",
+        notes: "Copy should lead with proof and reduce generic SaaS phrasing.",
+        findings: ["Pricing page does not explain plan fit in the first viewport"],
+      },
+    },
+    mcpReadiness: {
+      github: "required",
+      figma: "optional",
+      browser: "required",
+      chromeDevtools: "optional",
+      deploy: "required",
+      sentry: "optional",
+      database: "unused",
+      cms: "optional",
+      collaboration: "optional",
+      research: "optional",
+    },
+    refactorTasks: [
+      {
+        id: "task-homepage-cta",
+        title: "Clarify homepage CTA hierarchy",
+        category: "visual-design",
+        problem: "Primary and secondary actions compete in the hero, which weakens the visitor's first decision.",
+        evidence: "Sample finding: Primary CTA competes with secondary link on the homepage.",
+        impact: "high",
+        effort: "medium",
+        priority: "p1",
+        pages: ["/"],
+        recommendedMcp: ["browser", "figma"],
+        codexPrompt: "Inspect the target homepage implementation, preserve existing design system patterns, and revise the hero CTA hierarchy so the primary signup action is visually dominant while the secondary action remains available.",
+        verification: [
+          "Run target repo lint/build",
+          "Verify desktop/tablet/mobile hero layout",
+          "Confirm focus indicators and text contrast",
+        ],
+        risks: ["Could change conversion copy without stakeholder approval"],
+      },
+    ],
+    implementationEvidence: {
+      executedWork: [],
+      verificationResults: [],
+      remainingRisks: [...DEFAULT_IMPLEMENTATION_RISKS],
+      nextActions: [],
+    },
+    reportNotes: "MVP audit is a planning console. Run the generated prompts inside the target website repo before marking implementation complete.",
+  };
+}

package/cli/lib/site-strings.mjs

@@ -0,0 +1,23 @@
+// Shared string helpers for Website Improvement workspace reports.
+
+export function normalizeStringArray(value, fallback = []) {
+  const source = Array.isArray(value) ? value : fallback;
+  return source
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+}
+
+export function markdownTable(headers, rows) {
+  const escapeCell = (value) => String(value || "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+  return [
+    `| ${headers.map(escapeCell).join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`),
+  ].join("\n");
+}
+
+export function markdownList(items, fallback) {
+  const normalized = normalizeStringArray(items);
+  if (normalized.length === 0) return `- ${fallback}`;
+  return normalized.map((item) => `- ${item}`).join("\n");
+}

package/cli/lib/site-tasks.mjs

@@ -0,0 +1,93 @@
+// Website Improvement task generation helpers.
+
+import {
+  AUDIT_CATEGORIES,
+  categoryById,
+} from "./site-options.mjs";
+import { normalizeSiteWorkspace } from "./site-workspace.mjs";
+
+function recommendedMcpForCategory(categoryId) {
+  const map = {
+    "visual-design": ["browser", "figma"],
+    "ux-flow": ["browser", "github"],
+    responsive: ["browser", "chromeDevtools"],
+    accessibility: ["browser", "chromeDevtools"],
+    performance: ["chromeDevtools", "deploy"],
+    seo: ["browser", "deploy"],
+    "technical-quality": ["github"],
+    "runtime-issues": ["browser", "chromeDevtools", "sentry"],
+    "content-quality": ["figma", "research", "cms"],
+  };
+  return map[categoryId] || ["github"];
+}
+
+function buildCodexTaskPrompt(workspace, categoryId, finding) {
+  const profile = workspace.siteProfile;
+  return [
+    "You are working in the target website repo, not in design-ai.",
+    `Site: ${profile.name}`,
+    `Live URL: ${profile.liveUrl}`,
+    `Category: ${categoryById(categoryId).label}`,
+    `Problem: ${finding}`,
+    "",
+    "Inspect the target repo first. Reuse existing architecture, UI components, state patterns, styling conventions, and design tokens. Do not add dependencies unless the existing codebase clearly requires them.",
+    "",
+    "Implement the smallest safe improvement, then verify desktop/tablet/mobile behavior, keyboard focus, screen-reader semantics where relevant, and the target repo's lint/typecheck/build commands.",
+  ].join("\n");
+}
+
+function taskFromCategory(workspace, category, finding) {
+  const priority = category.id === "accessibility" || category.id === "runtime-issues" ? "p0" : "p1";
+  const impact = priority === "p0" ? "high" : "medium";
+  return {
+    id: `task-${category.id}`,
+    title: `Resolve ${category.label} finding`,
+    category: category.id,
+    problem: finding,
+    evidence: "Audit finding captured in the Website Improvement Console.",
+    impact,
+    effort: "medium",
+    priority,
+    pages: workspace.siteProfile.pages.slice(0, 3),
+    recommendedMcp: recommendedMcpForCategory(category.id),
+    codexPrompt: buildCodexTaskPrompt(workspace, category.id, finding),
+    verification: [
+      ...category.defaultVerification,
+      "Run target repo lint/typecheck/build when available",
+    ],
+    risks: [
+      "Target repo architecture may constrain the fix",
+      "Manual stakeholder review may be needed before changing copy or brand language",
+    ],
+  };
+}
+
+export function generateSiteRefactorTasks(workspaceInput) {
+  const workspace = normalizeSiteWorkspace(workspaceInput);
+  const existingIds = new Set(workspace.refactorTasks.map((task) => task.id));
+  const existingCategories = new Set(workspace.refactorTasks.map((task) => task.category));
+  const created = [];
+
+  for (const category of AUDIT_CATEGORIES) {
+    if (existingCategories.has(category.id)) continue;
+    const row = workspace.auditChecklist[category.id];
+    const findings = row.findings;
+    if (findings.length === 0) continue;
+
+    const task = taskFromCategory(workspace, category, findings[0]);
+    if (existingIds.has(task.id)) continue;
+    created.push(task);
+    existingIds.add(task.id);
+    existingCategories.add(category.id);
+  }
+
+  return {
+    workspace: {
+      ...workspace,
+      updatedAt: workspace.updatedAt,
+      refactorTasks: workspace.refactorTasks.concat(created),
+    },
+    created,
+    skippedCount: AUDIT_CATEGORIES.filter((category) => existingCategories.has(category.id)).length - created.length,
+  };
+}

package/cli/lib/site-test-support.mjs

@@ -0,0 +1,68 @@
+// Shared test helpers for the site.* test suite.
+
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  SITE_BUNDLE_CHECKSUM_FILES,
+  analyzeSiteWorkspace,
+  buildSiteBundleHandoffReport,
+  buildSiteHandoffBundle,
+  createSampleSiteWorkspace,
+  formatSiteBundleHandoffHuman,
+  formatSiteBundleHandoffJson,
+} from "./site.mjs";
+
+export function sha256HexForTest(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+
+export function bundleDigestForTest(checksumFiles) {
+  const manifest = SITE_BUNDLE_CHECKSUM_FILES.map((filePath) => `${filePath}\t${checksumFiles[filePath] || ""}`).join("\n");
+  return sha256HexForTest(`${manifest}\n`);
+}
+
+export async function captureConsole(fn) {
+  const stdout = [];
+  const originalLog = console.log;
+  const originalExitCode = process.exitCode;
+  console.log = (...args) => {
+    stdout.push(args.join(" "));
+  };
+  process.exitCode = undefined;
+  try {
+    await fn();
+    return {
+      stdout: stdout.join("\n"),
+      exitCode: process.exitCode,
+    };
+  } finally {
+    console.log = originalLog;
+    process.exitCode = originalExitCode;
+  }
+}
+
+export async function withTempDir(fn) {
+  const dir = mkdtempSync(path.join(tmpdir(), "design-ai-site-"));
+  try {
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export function buildHandoffFixture(dir) {
+  const workspace = createSampleSiteWorkspace();
+  const { summary } = analyzeSiteWorkspace(workspace, { filePath: "stdin" });
+  const bundle = buildSiteHandoffBundle(workspace, summary);
+  for (const file of bundle.files) {
+    writeFileSync(path.join(dir, file.path), file.content, "utf8");
+  }
+  const report = buildSiteBundleHandoffReport({ target: dir });
+  const json = JSON.parse(formatSiteBundleHandoffJson(report));
+  const human = formatSiteBundleHandoffHuman(report);
+  return { workspace, summary, bundle, report, json, human };
+}