@design-ai/cli 4.55.0 → 4.57.0

package/cli/lib/site-bundle-handoff.mjs

@@ -0,0 +1,271 @@
+// Target-repo handoff reports for Website Improvement bundles.
+
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  buildSitePrompt,
+  resolveSitePromptTask,
+} from "./site-prompts.mjs";
+import { analyzeSiteWorkspace } from "./site-analysis.mjs";
+import { buildBundleCheckCommand } from "./site-bundle-commands.mjs";
+import { formatBundleRepairGuidanceLines } from "./site-bundle-repair.mjs";
+import { buildSiteBundleCheckReport } from "./site-bundle-check.mjs";
+import {
+  buildBundleHandoffCommandManifest,
+  buildBundleHandoffOperatorRunbook,
+  formatBundleHandoffOperatorRunbookLines,
+} from "./site-bundle-handoff-runbook.mjs";
+import {
+  SITE_TARGET_REPO_EXECUTION_CHECKLIST,
+  buildSiteBundleHandoffBoundaries,
+  emptyBundleTaskCatalog,
+  formatBundleHandoffIssueLines,
+  formatBundleHandoffTaskCatalogLines,
+  summarizeBundleTaskCatalog,
+  summarizeSelectedTask,
+  summarizeSiteBundleHandoffSource,
+} from "./site-bundle-handoff-summary.mjs";
+import { readBundleTextIfPresent } from "./site-bundle-files.mjs";
+import { formatGeneratedContractDriftSummary } from "./site-bundle-contract.mjs";
+
+function loadSiteBundleWorkspace(directory) {
+  const relativePath = "website-workspace.tasks.json";
+  const targetPath = path.join(directory, relativePath);
+  if (!existsSync(targetPath) || !statSync(targetPath).isFile()) {
+    throw new Error(`Cannot select a handoff task because ${relativePath} is missing from the bundle`);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(targetPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot select a handoff task because ${relativePath} is invalid JSON: ${error.message}`);
+  }
+
+  return analyzeSiteWorkspace(raw, { filePath: targetPath }).workspace;
+}
+
+function buildSiteBundleHandoffPrompt(checkReport, bundleTexts) {
+  const bundleDigest = checkReport.summary.checksumBundleDigest || "not recorded";
+  const checksumStatus = `${checkReport.counts.verifiedChecksumFiles}/${checkReport.counts.expectedChecksumFiles} verified`;
+  const handoffBoundaries = buildSiteBundleHandoffBoundaries(checkReport);
+  const taskSelectionLine = bundleTexts.selectedTask
+    ? `${bundleTexts.selectedTask.id} (${bundleTexts.selectedTask.title}; ${bundleTexts.selectedTask.source})`
+    : "bundled codex-implementation.md default";
+  const bundleReadinessLine = checkReport.status === "pass"
+    ? "The bundle passed local bundle-check validation. Proceed in the target website repo after confirming the repo path."
+    : "The bundle did not fully pass local bundle-check validation. Resolve the listed bundle issues before treating this as implementation authority.";
+  return [
+    "# Website improvement target-repo handoff prompt",
+    "",
+    "You are Codex working in the target website repository, not in the design-ai repository.",
+    "Use this verified Website Improvement handoff bundle as read-only planning evidence. Do not modify the design-ai repo while executing this prompt.",
+    "",
+    "## Verified Bundle",
+    `- Bundle directory: ${checkReport.directory}`,
+    `- Source bundle provenance: ${checkReport.status}/${checkReport.valid ? "valid" : "invalid"} from ${checkReport.directory}`,
+    `- Source bundle strict check command: \`${buildBundleCheckCommand(checkReport.directory, { strict: true })}\``,
+    `- Site: ${checkReport.summary.siteName || "unknown"}`,
+    `- Source workspace: ${checkReport.summary.source || "unknown"}`,
+    `- Bundle status: ${checkReport.status}`,
+    `- Workspace status: ${checkReport.workspaceStatus}`,
+    `- MCP status: ${checkReport.mcpStatus}`,
+    `- MCP probe status: ${checkReport.mcpProbeStatus}`,
+    `- MCP probes: ${checkReport.mcpProbeCounts.pass}/${checkReport.mcpProbeCounts.count} passing, ${checkReport.mcpProbeCounts.warn} warning, ${checkReport.mcpProbeCounts.fail} failing`,
+    `- Tasks: ${checkReport.summary.totalTasks}`,
+    `- Primary task selection: ${taskSelectionLine}`,
+    `- Evidence counts: executed work ${checkReport.summary.implementationEvidence.executedWork}, verification ${checkReport.summary.implementationEvidence.verificationResults}, risks ${checkReport.summary.implementationEvidence.remainingRisks}, next actions ${checkReport.summary.implementationEvidence.nextActions}`,
+    `- Generated files: ${checkReport.counts.verifiedGeneratedFiles}/${checkReport.counts.expectedGeneratedFiles} match the current CLI bundle contract`,
+    `- Generated drift files: ${formatGeneratedContractDriftSummary(checkReport.generatedContract)}`,
+    `- SHA-256 bundle digest: ${bundleDigest}`,
+    `- Checksums: ${checksumStatus}`,
+    `- Handoff generation boundary flags: external calls no; target repo mutation no`,
+    `- Handoff boundaries: ${handoffBoundaries.join(", ")}`,
+    "",
+    "## Available Bundle Tasks",
+    `Task catalog source: ${bundleTexts.taskCatalog?.source || "unknown"}`,
+    `Default task: ${bundleTexts.taskCatalog?.defaultTaskId || "none"}`,
+    ...(bundleTexts.defaultTask?.strictHandoffCommand
+      ? [`Default task strict command: \`${bundleTexts.defaultTask.strictHandoffCommand}\``]
+      : []),
+    `Selected task: ${bundleTexts.taskCatalog?.selectedTaskId || "none"}`,
+    ...(bundleTexts.selectedTask?.strictHandoffCommand
+      ? [`Selected task strict command: \`${bundleTexts.selectedTask.strictHandoffCommand}\``]
+      : []),
+    `Effective task: ${bundleTexts.effectiveTask?.id || "none"}`,
+    ...(bundleTexts.effectiveTask?.strictHandoffCommand
+      ? [`Effective task strict command: \`${bundleTexts.effectiveTask.strictHandoffCommand}\``]
+      : []),
+    "To choose a specific task, re-run this handoff with `--task <number-or-id>`.",
+    ...formatBundleHandoffTaskCatalogLines(bundleTexts.taskCatalog),
+    "",
+    "## Operator Runbook",
+    `Runbook stages: ${bundleTexts.operatorRunbook?.stageCount || 0} (${bundleTexts.operatorRunbook?.requiredStageCount || 0} required, ${bundleTexts.operatorRunbook?.optionalStageCount || 0} optional)`,
+    `Next command key: ${bundleTexts.operatorRunbook?.nextCommandKey || "none"}`,
+    ...formatBundleHandoffOperatorRunbookLines(bundleTexts.operatorRunbook),
+    "",
+    "## Bundle Gate",
+    bundleReadinessLine,
+    formatBundleHandoffIssueLines(checkReport.issues),
+    "",
+    "Repair guidance:",
+    ...formatBundleRepairGuidanceLines(checkReport.repairGuidance),
+    "",
+    "## Operating Rules",
+    "1. Confirm the current working directory is the target website repo before editing files.",
+    "2. Inspect the target repo architecture, existing components, design tokens, routing, styling, and test scripts before implementation.",
+    "3. Reuse existing UI/system patterns and keep the change scoped to the selected improvement task.",
+    "4. Do not add production dependencies unless the target repo clearly requires them and the tradeoff is documented.",
+    "5. Preserve WCAG 2.1 AA expectations: visible focus, keyboard reachability, semantic structure, and text contrast.",
+    "6. Verify desktop, tablet, and mobile behavior plus target repo lint/typecheck/build commands when available.",
+    "7. Keep the handoff bundle files read-only; record implementation evidence in the target repo final response or report.",
+    "",
+    "## Target Repo Execution Checklist",
+    ...SITE_TARGET_REPO_EXECUTION_CHECKLIST.map((item) => `- [ ] ${item.label}: ${item.evidence}`),
+    "",
+    "## Primary Codex Implementation Prompt",
+    bundleTexts.codexImplementation || "_codex-implementation.md was not readable from the bundle._",
+    "",
+    "## Additional Bundle Context",
+    "Use these files only as supporting evidence:",
+    "- `website-handoff.md`: audit summary, priority recommendations, and remaining risk context.",
+    "- `mcp-probes.json`: read-only MCP probe evidence for repo, Figma, Browser, and deployment references.",
+    "- `mcp-action-plan.md`: MCP readiness gaps and operator sequence.",
+    "- `website-prompts.md`: alternate Codex/Claude review, QA, deployment, research, and copy prompts.",
+    "- `summary.json`: bundle manifest, source workspace, task count, and checksum digest.",
+    "",
+    "### Handoff Report Snapshot",
+    bundleTexts.websiteHandoff || "_website-handoff.md was not readable from the bundle._",
+    "",
+    "## Required Final Response",
+    "Return a concise implementation report with:",
+    "- Files changed in the target repo",
+    "- The specific website improvement task completed",
+    "- Verification commands and browser/viewport checks performed",
+    "- Remaining risks or follow-up work",
+    `- Bundle digest used for handoff: ${bundleDigest}`,
+  ].join("\n");
+}
+
+export function buildSiteBundleHandoffReport({
+  target,
+  cwd = process.cwd(),
+  taskSelector = "",
+} = {}) {
+  const checkReport = buildSiteBundleCheckReport({ target, cwd });
+  const includedFilePaths = [
+    "summary.json",
+    "mcp-probes.json",
+    "mcp-action-plan.md",
+    "website-handoff.md",
+    "website-prompts.md",
+    "codex-implementation.md",
+  ];
+  let bundleWorkspace = null;
+  let taskCatalogError = "";
+  let selectedTask = null;
+  let codexImplementation = readBundleTextIfPresent(checkReport.directory, "codex-implementation.md");
+  try {
+    bundleWorkspace = loadSiteBundleWorkspace(checkReport.directory);
+  } catch (error) {
+    taskCatalogError = error.message;
+  }
+  if (String(taskSelector || "").trim()) {
+    if (!bundleWorkspace) {
+      throw new Error(taskCatalogError || "Cannot select a handoff task because the bundle workspace is unavailable");
+    }
+    const task = resolveSitePromptTask(bundleWorkspace, taskSelector);
+    selectedTask = summarizeSelectedTask(task, taskSelector, "bundle-workspace", checkReport.directory);
+    codexImplementation = buildSitePrompt(bundleWorkspace, "codex-implementation", { taskSelector });
+  }
+  const taskCatalog = bundleWorkspace
+    ? summarizeBundleTaskCatalog(bundleWorkspace, checkReport.directory, selectedTask)
+    : emptyBundleTaskCatalog(taskCatalogError);
+  const defaultTask = taskCatalog.items[0] || null;
+  const effectiveTask = selectedTask || defaultTask;
+
+  const bundleTexts = {
+    taskCatalog,
+    defaultTask,
+    effectiveTask,
+    selectedTask,
+    codexImplementation,
+    websiteHandoff: readBundleTextIfPresent(checkReport.directory, "website-handoff.md"),
+  };
+  const boundaries = buildSiteBundleHandoffBoundaries(checkReport);
+  const sourceBundle = summarizeSiteBundleHandoffSource(checkReport);
+  const commandManifest = buildBundleHandoffCommandManifest({
+    sourceBundle,
+    taskCatalog,
+    defaultTask,
+    selectedTask,
+    effectiveTask,
+  });
+  const operatorRunbook = buildBundleHandoffOperatorRunbook(commandManifest);
+  const runbookPrompt = buildSiteBundleHandoffPrompt(checkReport, {
+    ...bundleTexts,
+    operatorRunbook,
+  });
+  return {
+    status: checkReport.status,
+    valid: checkReport.valid,
+    directory: checkReport.directory,
+    sourceBundle,
+    commandManifest,
+    operatorRunbook,
+    boundaries,
+    externalCalls: false,
+    targetRepoMutation: false,
+    bundle: {
+      directory: checkReport.directory,
+      siteName: checkReport.summary.siteName || "",
+      source: checkReport.summary.source || "",
+      sourceBundle,
+      workspaceStatus: checkReport.workspaceStatus || "unknown",
+      mcpStatus: checkReport.mcpStatus || "unknown",
+      mcpProbeStatus: checkReport.mcpProbeStatus || "unknown",
+      mcpProbeCounts: { ...checkReport.mcpProbeCounts },
+      totalTasks: checkReport.summary.totalTasks || 0,
+      implementationEvidence: { ...checkReport.summary.implementationEvidence },
+      checksumAlgorithm: checkReport.summary.checksumAlgorithm || "",
+      checksumBundleDigest: checkReport.summary.checksumBundleDigest || "",
+      expectedChecksumFiles: checkReport.counts.expectedChecksumFiles,
+      verifiedChecksumFiles: checkReport.counts.verifiedChecksumFiles,
+      checksumFailures: checkReport.counts.checksumFailures,
+      expectedGeneratedFiles: checkReport.counts.expectedGeneratedFiles,
+      verifiedGeneratedFiles: checkReport.counts.verifiedGeneratedFiles,
+      generatedFailures: checkReport.counts.generatedFailures,
+      generatedDriftFiles: [...checkReport.generatedContract.driftFiles],
+      taskCatalog,
+      defaultTask,
+      effectiveTask,
+      selectedTask,
+      commandManifest,
+      operatorRunbook,
+      boundaries,
+      externalCalls: false,
+      targetRepoMutation: false,
+      repairGuidance: { ...checkReport.repairGuidance },
+      executionChecklist: SITE_TARGET_REPO_EXECUTION_CHECKLIST,
+    },
+    prompt: runbookPrompt,
+    files: checkReport.files.map((file) => ({
+      ...file,
+      included: includedFilePaths.includes(file.path),
+    })),
+    issues: checkReport.issues,
+  };
+}
+
+export function formatSiteBundleHandoffJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+export function formatSiteBundleHandoffHuman(report) {
+  return report.prompt;
+}

package/cli/lib/site-bundle-readme.mjs

@@ -0,0 +1,98 @@
+// README and handoff guidance builders for Website Improvement bundles.
+
+import { markdownTable } from "./site-strings.mjs";
+import { SITE_TARGET_REPO_EXECUTION_CHECKLIST } from "./site-bundle-handoff-summary.mjs";
+
+export function buildSiteBundleHandoffGuidance(bundleStatus) {
+  const strictCommand = "design-ai site <bundle-dir> --bundle-handoff --strict --out target-repo-handoff.md";
+  const draftCommand = "design-ai site <bundle-dir> --bundle-handoff --out target-repo-handoff.md";
+  const verifyCommand = "design-ai site <bundle-dir> --bundle-check --strict --json";
+  const strictReady = bundleStatus === "pass";
+  return {
+    strictReady,
+    readiness: strictReady ? "ready-for-strict-handoff" : "review-warnings-before-strict-handoff",
+    recommendedCommand: strictReady ? strictCommand : draftCommand,
+    strictCommand,
+    draftCommand,
+    verifyCommand,
+    note: strictReady
+      ? "Use the strict handoff command before target-repo implementation."
+      : "Use the draft handoff command only for planning while readiness warnings remain; use the strict handoff command before treating the bundle as implementation authority.",
+    executionChecklist: SITE_TARGET_REPO_EXECUTION_CHECKLIST,
+  };
+}
+
+export function buildSiteBundleReadme(workspace, bundleSummary, mcpReport, mcpProbeReport, filePaths) {
+  const commandTarget = bundleSummary.source === "stdin" ? "<workspace.json>" : bundleSummary.source;
+  const handoff = bundleSummary.handoff;
+  return [
+    `# Website improvement handoff bundle: ${workspace.siteProfile.name}`,
+    "",
+    "> Generated by `design-ai site --bundle` from a Website Improvement Console workspace export.",
+    "",
+    "## Contents",
+    markdownTable(
+      ["File", "Purpose"],
+      filePaths.map((filePath) => {
+        const purpose = {
+          "summary.json": "Machine-readable bundle manifest and readiness summary",
+          "website-workspace.tasks.json": "Workspace JSON with deterministic starter refactor tasks added",
+          "mcp-check.json": "Machine-readable MCP readiness gate output",
+          "mcp-probes.json": "Machine-readable read-only MCP probe readiness output",
+          "mcp-action-plan.md": "Operator-facing MCP readiness action plan",
+          "website-handoff.md": "Markdown handoff report for implementation planning",
+          "website-prompts.md": "Full Codex and Claude prompt bundle",
+          "codex-implementation.md": "Top-priority Codex implementation prompt",
+        }[filePath] || "Bundle artifact";
+        return [filePath, purpose];
+      }),
+    ),
+    "",
+    "## Status",
+    `- Bundle status: ${mcpReport.status}`,
+    `- Workspace status: ${bundleSummary.workspaceStatus}`,
+    `- Source: ${bundleSummary.source}`,
+    `- Site: ${workspace.siteProfile.name}`,
+    `- Live URL: ${workspace.siteProfile.liveUrl || "not provided"}`,
+    `- Repo: ${workspace.siteProfile.repoUrl || workspace.siteProfile.localPath || "not provided"}`,
+    `- Tasks: ${bundleSummary.taskGeneration.totalTasks}`,
+    `- Evidence entries: ${bundleSummary.implementationEvidence.executedWork + bundleSummary.implementationEvidence.verificationResults}`,
+    `- MCP ready: ${mcpReport.counts.ready}/${mcpReport.counts.total}`,
+    `- MCP probes: ${mcpProbeReport.pass}/${mcpProbeReport.count} passing`,
+    "",
+    "## Handoff Readiness",
+    `- Strict-ready: ${handoff.strictReady ? "yes" : "no"}`,
+    `- Readiness: ${handoff.readiness}`,
+    `- Recommended command: \`${handoff.recommendedCommand}\``,
+    `- Strict command: \`${handoff.strictCommand}\``,
+    `- Draft command: \`${handoff.draftCommand}\``,
+    `- Verify command: \`${handoff.verifyCommand}\``,
+    `- Note: ${handoff.note}`,
+    "",
+    "## Target Repo Execution Checklist",
+    ...handoff.executionChecklist.map((item) => `- [ ] ${item.label}: ${item.evidence}`),
+    "",
+    "## Suggested Sequence",
+    "1. Read `summary.json`, `mcp-check.json`, `mcp-probes.json`, and `mcp-action-plan.md` first.",
+    "2. Run `design-ai site <bundle-dir> --bundle-check --strict --json`; if it exits non-zero, review the warnings or failures before implementation.",
+    "3. Run the recommended handoff command above. Use the draft command only for planning while readiness warnings remain.",
+    "4. Use `codex-implementation.md` in the target website repo for the top-priority task when you need the raw task prompt.",
+    "5. Use `website-prompts.md` for deeper Codex/Claude review, visual QA, deployment verification, competitor research, and final handoff.",
+    "6. Record target-repo executed work, verification results, remaining risks, and next actions in `website-handoff.md` after implementation.",
+    "",
+    "## Regenerate",
+    `- \`design-ai site ${commandTarget} --bundle --out website-handoff-bundle --force\``,
+    `- \`design-ai site ${commandTarget} --mcp-check --strict --json\``,
+    `- \`design-ai site website-handoff-bundle --bundle-check --strict --json\``,
+    `- \`design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md\``,
+    "",
+    "## Checksum Verification",
+    "- `summary.json` records SHA-256 checksums for every generated bundle file except `summary.json` itself.",
+    "- `summary.json.checksums.bundleDigest` records a deterministic fingerprint of the checksum manifest for quick bundle identity comparison.",
+    "- `design-ai site <bundle-dir> --bundle-check --strict --json` recomputes those checksums so transferred or manually edited bundles fail before target-repo handoff.",
+    "",
+    "## Boundaries",
+    "- This bundle is deterministic and local.",
+    "- It does not call external MCPs, mutate the target website repo, run Lighthouse/axe, capture screenshots, or write to deployment/CMS/Sentry systems.",
+  ].join("\n");
+}

package/cli/lib/site-bundle-repair-report.mjs

@@ -0,0 +1,143 @@
+// Repair report orchestration for Website Improvement handoff bundles.
+
+import path from "node:path";
+
+import {
+  addIssue,
+  analyzeSiteWorkspace,
+  loadSiteWorkspaceInput,
+  statusFromIssues,
+} from "./site-analysis.mjs";
+import { buildSiteHandoffBundle } from "./site-bundle-build.mjs";
+import { buildSiteBundleCheckReport } from "./site-bundle-check.mjs";
+import {
+  formatBundleRepairGuidanceLines,
+  summarizeBundleRepairCheck,
+} from "./site-bundle-repair.mjs";
+
+function buildSiteBundleRepairReportFromChecks({
+  beforeReport,
+  afterReport = null,
+  written = null,
+  applied = false,
+} = {}) {
+  const issues = [];
+  const repairGuidance = beforeReport.repairGuidance;
+
+  if (!repairGuidance.available) {
+    addIssue(issues, "fail", "bundle-repair-unavailable", repairGuidance.reason);
+  } else if (!applied) {
+    addIssue(issues, "pass", "bundle-repair-preview-ready", "Bundle repair preview is ready; run again with --yes to rewrite the handoff bundle directory");
+  } else if (!afterReport || afterReport.status !== "pass") {
+    addIssue(issues, "fail", "bundle-repair-verify-fail", "Bundle repair applied, but the repaired bundle did not pass bundle-check verification");
+  } else {
+    addIssue(issues, "pass", "bundle-repair-applied", "Bundle repair applied and the regenerated bundle passed local bundle-check verification");
+  }
+
+  const status = statusFromIssues(issues);
+  return {
+    directory: beforeReport.directory,
+    workspaceFile: path.join(beforeReport.directory, "website-workspace.tasks.json"),
+    dryRun: !applied,
+    applied,
+    valid: status !== "fail",
+    status,
+    repairGuidance,
+    before: summarizeBundleRepairCheck(beforeReport),
+    after: afterReport ? summarizeBundleRepairCheck(afterReport) : null,
+    written: written ? {
+      directory: written.directory,
+      files: written.files,
+      count: written.files.length,
+    } : null,
+    issues,
+  };
+}
+
+export function buildSiteBundleRepairPreview({
+  target,
+  cwd = process.cwd(),
+} = {}) {
+  const beforeReport = buildSiteBundleCheckReport({ target, cwd });
+  return buildSiteBundleRepairReportFromChecks({ beforeReport });
+}
+
+export function buildSiteBundleRepairBundle({
+  target,
+  cwd = process.cwd(),
+} = {}) {
+  const beforeReport = buildSiteBundleCheckReport({ target, cwd });
+  const preview = buildSiteBundleRepairReportFromChecks({ beforeReport });
+  if (!preview.repairGuidance.available) {
+    return {
+      preview,
+      beforeReport,
+      bundle: null,
+    };
+  }
+
+  const input = loadSiteWorkspaceInput({
+    target: preview.workspaceFile,
+    cwd,
+  });
+  const analyzed = analyzeSiteWorkspace(input.raw, { filePath: input.filePath });
+  const bundle = buildSiteHandoffBundle(analyzed.workspace, analyzed.summary);
+  return {
+    preview,
+    beforeReport,
+    bundle,
+  };
+}
+
+export function buildSiteBundleRepairAppliedReport({
+  beforeReport,
+  written,
+  cwd = process.cwd(),
+} = {}) {
+  const afterReport = buildSiteBundleCheckReport({
+    target: beforeReport.directory,
+    cwd,
+  });
+  return buildSiteBundleRepairReportFromChecks({
+    beforeReport,
+    afterReport,
+    written,
+    applied: true,
+  });
+}
+
+export function formatSiteBundleRepairJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+export function formatSiteBundleRepairHuman(report) {
+  const afterLines = report.after ? [
+    `After status: ${report.after.status}`,
+    `After generated drift files: ${report.after.generatedDriftFiles.length ? report.after.generatedDriftFiles.join(", ") : "none"}`,
+    `After bundle digest: ${report.after.checksumBundleDigest || "not recorded"}`,
+  ] : [
+    "After status: not applied",
+  ];
+  return [
+    `Website Improvement handoff bundle repair: ${report.directory}`,
+    "",
+    `Status: ${report.status}`,
+    `Dry run: ${report.dryRun ? "yes" : "no"}`,
+    `Applied: ${report.applied ? "yes" : "no"}`,
+    `Workspace: ${report.workspaceFile}`,
+    `Before status: ${report.before.status}`,
+    `Before generated drift files: ${report.before.generatedDriftFiles.length ? report.before.generatedDriftFiles.join(", ") : "none"}`,
+    `Before bundle digest: ${report.before.checksumBundleDigest || "not recorded"}`,
+    ...afterLines,
+    ...(report.written ? [
+      `Written directory: ${report.written.directory}`,
+      `Written files: ${report.written.count}`,
+    ] : []),
+    "",
+    "Repair guidance:",
+    ...formatBundleRepairGuidanceLines(report.repairGuidance),
+    "",
+    "Issues:",
+    ...report.issues.map((issue) => `- [${issue.level}] ${issue.id}: ${issue.message}`),
+  ].join("\n");
+}

package/cli/lib/site-bundle-repair.mjs

@@ -0,0 +1,68 @@
+// Repair guidance helpers for Website Improvement handoff bundles.
+
+import {
+  existsSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+
+import { shellQuote } from "./site-bundle-commands.mjs";
+
+export function buildBundleRepairGuidance(directory, generatedContract) {
+  const workspacePath = path.join(directory, "website-workspace.tasks.json");
+  const reportBaseName = path.basename(directory);
+  const reportDirectory = path.dirname(directory);
+  const previewReportPath = path.join(reportDirectory, `${reportBaseName}-repair-preview.json`);
+  const appliedReportPath = path.join(reportDirectory, `${reportBaseName}-repair-applied.json`);
+  const hasWorkspace = existsSync(workspacePath) && statSync(workspacePath).isFile();
+  const available = Boolean(generatedContract.available && hasWorkspace);
+  return {
+    available,
+    reason: available
+      ? "Regenerate the bundle from its embedded website-workspace.tasks.json when generated contract drift is reported."
+      : "Repair guidance requires a readable website-workspace.tasks.json and generated contract analysis.",
+    command: available ? `design-ai site ${shellQuote(workspacePath)} --bundle --out ${shellQuote(directory)} --force` : "",
+    previewCommand: available ? `design-ai site ${shellQuote(directory)} --bundle-repair --json` : "",
+    applyCommand: available ? `design-ai site ${shellQuote(directory)} --bundle-repair --yes --json` : "",
+    previewReportCommand: available ? `design-ai site ${shellQuote(directory)} --bundle-repair --json --out ${shellQuote(previewReportPath)}` : "",
+    applyReportCommand: available ? `design-ai site ${shellQuote(directory)} --bundle-repair --yes --json --out ${shellQuote(appliedReportPath)}` : "",
+    verifyCommand: available ? `design-ai site ${shellQuote(directory)} --bundle-check --strict --json` : "",
+    mutates: available ? "handoff-bundle-directory-only" : "none",
+    targetRepoMutation: false,
+    externalCalls: false,
+  };
+}
+
+export function formatBundleRepairGuidanceLines(repairGuidance) {
+  if (!repairGuidance.available) {
+    return [
+      `- Available: no`,
+      `- Reason: ${repairGuidance.reason}`,
+    ];
+  }
+  return [
+    "- Available: yes",
+    `- Reason: ${repairGuidance.reason}`,
+    `- Regenerate: ${repairGuidance.command}`,
+    `- Preview repair: ${repairGuidance.previewCommand}`,
+    `- Apply repair: ${repairGuidance.applyCommand}`,
+    `- Preview report: ${repairGuidance.previewReportCommand}`,
+    `- Apply report: ${repairGuidance.applyReportCommand}`,
+    `- Verify: ${repairGuidance.verifyCommand}`,
+    `- Scope: ${repairGuidance.mutates}; target repo mutation ${repairGuidance.targetRepoMutation ? "yes" : "no"}; external calls ${repairGuidance.externalCalls ? "yes" : "no"}`,
+  ];
+}
+
+export function summarizeBundleRepairCheck(report) {
+  return {
+    status: report.status,
+    valid: report.valid,
+    checksumBundleDigest: report.summary.checksumBundleDigest || "",
+    checksumFailures: report.counts.checksumFailures,
+    generatedFailures: report.counts.generatedFailures,
+    verifiedGeneratedFiles: report.counts.verifiedGeneratedFiles,
+    expectedGeneratedFiles: report.counts.expectedGeneratedFiles,
+    generatedDriftFiles: [...report.generatedContract.driftFiles],
+    issueCount: report.issues.length,
+  };
+}