@design-ai/cli 4.55.0 → 4.57.0

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

@@ -0,0 +1,157 @@
+import { SITE_BUNDLE_CHECKSUM_FILES } from "./site-content.mjs";
+import { IMPLEMENTATION_EVIDENCE_KEYS } from "./site-evidence.mjs";
+import {
+  addIssue,
+  statusFromIssues,
+} from "./site-analysis.mjs";
+import { buildSiteBundleCheckReport } from "./site-bundle-check.mjs";
+
+export function summarizeBundleForCompare(report) {
+  return {
+    directory: report.directory,
+    status: report.status,
+    valid: report.valid,
+    siteName: report.summary.siteName || "",
+    source: report.summary.source || "",
+    workspaceStatus: report.workspaceStatus || "unknown",
+    mcpStatus: report.mcpStatus || "unknown",
+    mcpProbeStatus: report.mcpProbeStatus || "unknown",
+    mcpProbeCounts: { ...report.mcpProbeCounts },
+    totalTasks: report.summary.totalTasks || 0,
+    implementationEvidence: { ...report.summary.implementationEvidence },
+    checksumAlgorithm: report.summary.checksumAlgorithm || "",
+    checksumBundleDigest: report.summary.checksumBundleDigest || "",
+    checksumFailures: report.counts.checksumFailures,
+    generatedFailures: report.counts.generatedFailures,
+    verifiedGeneratedFiles: report.counts.verifiedGeneratedFiles,
+    generatedDriftFiles: [...report.generatedContract.driftFiles],
+    issueCount: report.issues.length,
+  };
+}
+
+export function buildBundleMetadataChanges(left, right) {
+  const pairs = [
+    ["siteName", "Site name", left.summary.siteName || "", right.summary.siteName || ""],
+    ["source", "Source", left.summary.source || "", right.summary.source || ""],
+    ["workspaceStatus", "Workspace status", left.workspaceStatus || "unknown", right.workspaceStatus || "unknown"],
+    ["mcpStatus", "MCP status", left.mcpStatus || "unknown", right.mcpStatus || "unknown"],
+    ["mcpProbeStatus", "MCP probe status", left.mcpProbeStatus || "unknown", right.mcpProbeStatus || "unknown"],
+    ...["count", "pass", "warn", "fail"].map((key) => [
+      `mcpProbeCounts.${key}`,
+      `MCP probe ${key}`,
+      String(left.summary.mcpProbeCounts[key] || 0),
+      String(right.summary.mcpProbeCounts[key] || 0),
+    ]),
+    ["totalTasks", "Task count", String(left.summary.totalTasks || 0), String(right.summary.totalTasks || 0)],
+    ...IMPLEMENTATION_EVIDENCE_KEYS.map((key) => [
+      `implementationEvidence.${key}`,
+      `Evidence ${key}`,
+      String(left.summary.implementationEvidence[key] || 0),
+      String(right.summary.implementationEvidence[key] || 0),
+    ]),
+  ];
+  return pairs
+    .filter(([, , leftValue, rightValue]) => leftValue !== rightValue)
+    .map(([key, label, leftValue, rightValue]) => ({ key, label, leftValue, rightValue }));
+}
+
+export function buildBundleFileChanges(left, right) {
+  return SITE_BUNDLE_CHECKSUM_FILES
+    .map((filePath) => ({
+      path: filePath,
+      leftChecksum: String(left.summary.checksumFiles[filePath] || ""),
+      rightChecksum: String(right.summary.checksumFiles[filePath] || ""),
+    }))
+    .filter((file) => file.leftChecksum !== file.rightChecksum);
+}
+
+export function buildSiteBundleCompareReport({ target, compareTarget }) {
+  const left = buildSiteBundleCheckReport({ target });
+  const right = buildSiteBundleCheckReport({ target: compareTarget });
+  const issues = [];
+
+  if (left.status === "fail") {
+    addIssue(issues, "fail", "bundle-compare-left-invalid", "Primary bundle must pass bundle-check before comparison can be trusted");
+  } else if (left.status === "warn") {
+    addIssue(issues, "warn", "bundle-compare-left-warn", "Primary bundle has bundle-check warnings; review them before target-repo handoff");
+  }
+  if (right.status === "fail") {
+    addIssue(issues, "fail", "bundle-compare-right-invalid", "Comparison bundle must pass bundle-check before comparison can be trusted");
+  } else if (right.status === "warn") {
+    addIssue(issues, "warn", "bundle-compare-right-warn", "Comparison bundle has bundle-check warnings; review them before target-repo handoff");
+  }
+
+  const leftDigest = left.summary.checksumBundleDigest || "";
+  const rightDigest = right.summary.checksumBundleDigest || "";
+  const digestMatch = Boolean(leftDigest && rightDigest && leftDigest === rightDigest);
+  const changedFiles = buildBundleFileChanges(left, right);
+  const metadataChanges = buildBundleMetadataChanges(left, right);
+  const hasDifferences = !digestMatch || changedFiles.length > 0 || metadataChanges.length > 0;
+  const hasFailures = issues.some((issue) => issue.level === "fail");
+
+  if (issues.length === 0 && !hasDifferences) {
+    addIssue(issues, "pass", "bundle-compare-identical", "Handoff bundles have the same bundle digest and checksum manifest");
+  } else if (!hasFailures && hasDifferences) {
+    addIssue(issues, "warn", "bundle-compare-different", "Handoff bundles differ; review changed files before target-repo handoff");
+  }
+
+  const status = statusFromIssues(issues);
+  return {
+    status,
+    valid: left.valid && right.valid,
+    sameBundle: !hasDifferences,
+    digestMatch,
+    left: summarizeBundleForCompare(left),
+    right: summarizeBundleForCompare(right),
+    counts: {
+      changedFiles: changedFiles.length,
+      metadataChanges: metadataChanges.length,
+      leftIssues: left.issues.length,
+      rightIssues: right.issues.length,
+      issues: issues.length,
+      warnings: issues.filter((issue) => issue.level === "warn").length,
+      failures: issues.filter((issue) => issue.level === "fail").length,
+    },
+    changedFiles,
+    metadataChanges,
+    issues,
+  };
+}
+
+export function formatSiteBundleCompareJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+function formatMcpProbeCounts(counts = {}) {
+  return `${counts.pass || 0}/${counts.count || 0} passing, ${counts.warn || 0} warning, ${counts.fail || 0} failing`;
+}
+
+export function formatSiteBundleCompareHuman(report) {
+  return [
+    `Website Improvement handoff bundle compare: ${report.left.directory} -> ${report.right.directory}`,
+    "",
+    `Status: ${report.status}`,
+    `Same bundle: ${report.sameBundle ? "yes" : "no"}`,
+    `Digest match: ${report.digestMatch ? "yes" : "no"}`,
+    `Left digest: ${report.left.checksumBundleDigest || "not recorded"}`,
+    `Right digest: ${report.right.checksumBundleDigest || "not recorded"}`,
+    `Changed files: ${report.counts.changedFiles}`,
+    `Metadata changes: ${report.counts.metadataChanges}`,
+    `Generated contract: left ${report.left.verifiedGeneratedFiles}/${SITE_BUNDLE_CHECKSUM_FILES.length}, right ${report.right.verifiedGeneratedFiles}/${SITE_BUNDLE_CHECKSUM_FILES.length}`,
+    `Generated drift files: left ${report.left.generatedDriftFiles.length ? report.left.generatedDriftFiles.join(", ") : "none"}, right ${report.right.generatedDriftFiles.length ? report.right.generatedDriftFiles.join(", ") : "none"}`,
+    `MCP probes: left ${formatMcpProbeCounts(report.left.mcpProbeCounts)}, right ${formatMcpProbeCounts(report.right.mcpProbeCounts)}`,
+    "",
+    "Changed files:",
+    ...(report.changedFiles.length
+      ? report.changedFiles.map((file) => `- ${file.path}`)
+      : ["- none"]),
+    "",
+    "Metadata changes:",
+    ...(report.metadataChanges.length
+      ? report.metadataChanges.map((item) => `- ${item.label}: ${item.leftValue || "not recorded"} -> ${item.rightValue || "not recorded"}`)
+      : ["- none"]),
+    "",
+    "Issues:",
+    ...report.issues.map((issue) => `- [${issue.level}] ${issue.id}: ${issue.message}`),
+  ].join("\n");
+}

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

@@ -0,0 +1,79 @@
+// Generated bundle contract helpers for Website Improvement handoff bundles.
+
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+
+import { addIssue } from "./site-analysis.mjs";
+import { buildSiteHandoffBundle } from "./site-bundle-build.mjs";
+import { SITE_BUNDLE_CHECKSUM_FILES } from "./site-content.mjs";
+import {
+  sha256Hex,
+  shortDigest,
+} from "./site-bundle-files.mjs";
+
+export function emptyBundleGeneratedContract(source = "") {
+  return {
+    available: false,
+    source: source || "",
+    expectedFiles: SITE_BUNDLE_CHECKSUM_FILES.length,
+    verifiedFiles: 0,
+    driftFiles: [],
+    files: [],
+  };
+}
+
+export function buildBundleGeneratedContract(directory, workspace, source) {
+  const contractSource = source || "website-workspace.tasks.json";
+  const expectedBundle = buildSiteHandoffBundle(workspace, { filePath: contractSource });
+  const expectedFiles = new Map(expectedBundle.files.map((file) => [file.path, file.content]));
+  const files = SITE_BUNDLE_CHECKSUM_FILES.map((filePath) => {
+    const expectedContent = expectedFiles.get(filePath);
+    const expectedDigest = typeof expectedContent === "string" ? sha256Hex(expectedContent) : "";
+    const targetPath = path.join(directory, filePath);
+    const present = existsSync(targetPath) && statSync(targetPath).isFile();
+    const actualDigest = present ? sha256Hex(readFileSync(targetPath, "utf8")) : "";
+    return {
+      path: filePath,
+      present,
+      matches: Boolean(present && expectedDigest && actualDigest === expectedDigest),
+      expectedDigest,
+      actualDigest,
+    };
+  });
+  return {
+    available: true,
+    source: contractSource,
+    expectedFiles: SITE_BUNDLE_CHECKSUM_FILES.length,
+    verifiedFiles: files.filter((file) => file.matches).length,
+    driftFiles: files.filter((file) => file.present && !file.matches).map((file) => file.path),
+    files,
+  };
+}
+
+export function addBundleGeneratedContractIssues(generatedContract, issues) {
+  if (!generatedContract.available) return;
+  for (const file of generatedContract.files) {
+    if (!file.present || file.matches) continue;
+    addIssue(
+      issues,
+      "fail",
+      `bundle-generated-${file.path}`,
+      `${file.path} does not match the current CLI-generated bundle contract (expected ${shortDigest(file.expectedDigest)}, actual ${shortDigest(file.actualDigest)})`,
+    );
+  }
+}
+
+export function formatGeneratedContractDriftLines(generatedContract) {
+  const driftFiles = generatedContract.files.filter((file) => file.present && !file.matches);
+  if (driftFiles.length === 0) return ["- none"];
+  return driftFiles.map((file) => `- ${file.path}: expected ${shortDigest(file.expectedDigest)}, actual ${shortDigest(file.actualDigest)}`);
+}
+
+export function formatGeneratedContractDriftSummary(generatedContract) {
+  if (!generatedContract.driftFiles.length) return "none";
+  return generatedContract.driftFiles.join(", ");
+}

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

@@ -0,0 +1,87 @@
+// File, digest, and validation helpers for Website Improvement handoff bundles.
+
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { SITE_BUNDLE_CHECKSUM_FILES } from "./site-content.mjs";
+
+function addIssue(issues, level, id, message) {
+  issues.push({ level, id, message });
+}
+
+export function sha256Hex(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+export function shortDigest(digest) {
+  return digest ? String(digest).slice(0, 12) : "missing";
+}
+
+export function buildBundleDigest(checksumFiles) {
+  const manifest = SITE_BUNDLE_CHECKSUM_FILES.map((filePath) => `${filePath}\t${checksumFiles[filePath] || ""}`).join("\n");
+  return sha256Hex(`${manifest}\n`);
+}
+
+export function buildBundleChecksums(files) {
+  const checksumFiles = Object.fromEntries(
+    files
+      .filter((file) => file.path !== "summary.json")
+      .map((file) => [file.path, sha256Hex(file.content)]),
+  );
+  return {
+    algorithm: "sha256",
+    bundleDigest: buildBundleDigest(checksumFiles),
+    files: checksumFiles,
+  };
+}
+
+export function readBundleFile(directory, relativePath, issues) {
+  const target = path.join(directory, relativePath);
+  if (!existsSync(target)) {
+    addIssue(issues, "fail", `bundle-missing-${relativePath}`, `Bundle file is missing: ${relativePath}`);
+    return null;
+  }
+  if (!statSync(target).isFile()) {
+    addIssue(issues, "fail", `bundle-file-${relativePath}`, `Bundle path must be a file: ${relativePath}`);
+    return null;
+  }
+  return readFileSync(target, "utf8");
+}
+
+export function parseBundleJson(directory, relativePath, issues) {
+  const text = readBundleFile(directory, relativePath, issues);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    addIssue(issues, "fail", `bundle-json-${relativePath}`, `Bundle JSON is invalid in ${relativePath}: ${error.message}`);
+    return null;
+  }
+}
+
+export function arraysEqual(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  if (left.length !== right.length) return false;
+  return left.every((item, index) => item === right[index]);
+}
+
+export function addBundleMarkdownIssue(directory, relativePath, fragments, issues) {
+  const text = readBundleFile(directory, relativePath, issues);
+  if (text === null) return;
+  for (const fragment of fragments) {
+    if (!text.includes(fragment)) {
+      addIssue(issues, "fail", `bundle-markdown-${relativePath}`, `${relativePath} is missing required text: ${fragment}`);
+    }
+  }
+}
+
+export function readBundleTextIfPresent(directory, relativePath) {
+  const targetPath = path.join(directory, relativePath);
+  if (!existsSync(targetPath) || !statSync(targetPath).isFile()) return "";
+  return readFileSync(targetPath, "utf8").trim();
+}

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

@@ -0,0 +1,173 @@
+// Expected next-action initial-validation fixtures for bundle-handoff contract tests.
+
+export   const buildExpectedInitialValidationChecklistSummary = (checklist) => {
+    const checkedItems = checklist.filter((item) => item.checkedInitially);
+    const uncheckedItems = checklist.filter((item) => !item.checkedInitially);
+    const blockingItems = checklist.filter((item) => item.completionBlocking);
+    const blockingUncheckedItems = checklist.filter((item) => item.completionBlocking && !item.checkedInitially);
+    const firstUncheckedItem = uncheckedItems[0] || {};
+    const status = blockingUncheckedItems.length > 0 ? "blocked" : "ready";
+    return {
+      status,
+      statusLabel: status === "blocked" ? "Checklist blocked" : "Checklist ready",
+      statusTone: status === "blocked" ? "danger" : "success",
+      iconName: status === "blocked" ? "list-x" : "list-checks",
+      actionLabel: status === "blocked" ? "Complete required evidence" : "Continue",
+      helperText: status === "blocked"
+        ? `${blockingUncheckedItems.length} required checklist item(s) need evidence before completion.`
+        : "No required checklist items are unchecked on first render.",
+      itemCount: checklist.length,
+      checkedCount: checkedItems.length,
+      uncheckedCount: uncheckedItems.length,
+      requiredCount: checklist.filter((item) => item.required).length,
+      optionalCount: checklist.filter((item) => !item.required).length,
+      blockingCount: blockingItems.length,
+      blockingUncheckedCount: blockingUncheckedItems.length,
+      nonBlockingCount: checklist.filter((item) => !item.completionBlocking).length,
+      completionPercent: checklist.length > 0 ? Math.round((checkedItems.length / checklist.length) * 100) : 100,
+      progressLabel: `${checkedItems.length}/${checklist.length} complete`,
+      allCheckedInitially: uncheckedItems.length === 0,
+      hasUncheckedItems: uncheckedItems.length > 0,
+      hasBlockingUncheckedItems: blockingUncheckedItems.length > 0,
+      canCompleteInitially: blockingUncheckedItems.length === 0,
+      firstUncheckedItemKey: firstUncheckedItem.key || "",
+      firstUncheckedItemLabel: firstUncheckedItem.label || "",
+      firstUncheckedItemMessage: firstUncheckedItem.message || "",
+    };
+  };
+
+export function buildExpectedNextInitialValidation(bundle) {
+  const expectedNextInitialValidationStates = [
+    {
+      key: "strictBundleCheckOutput",
+      label: "Strict bundle-check output",
+      rule: "non-empty-text",
+      status: "missing-required",
+      statusLabel: "Missing required",
+      statusTone: "danger",
+      iconName: "alert-circle",
+      actionLabel: "Provide evidence",
+      helperText: "Required before completion",
+      valid: false,
+      blocking: true,
+      severity: "error",
+      required: true,
+      allowsEmpty: false,
+      touched: false,
+      dirty: false,
+      valuePresent: false,
+      valueLength: 0,
+      minLength: 20,
+      valueShape: "long-text",
+      acceptsMultiple: false,
+      emptyValue: "",
+      payloadPath: "sourceBundle.verification.strictBundleCheckOutput",
+      message: "Provide strict bundle-check output before marking this action complete.",
+    },
+    {
+      key: "bundleDigest",
+      label: "Bundle digest",
+      rule: "checksum-or-digest-text",
+      status: "missing-required",
+      statusLabel: "Missing required",
+      statusTone: "danger",
+      iconName: "alert-circle",
+      actionLabel: "Provide evidence",
+      helperText: "Required before completion",
+      valid: false,
+      blocking: true,
+      severity: "error",
+      required: true,
+      allowsEmpty: false,
+      touched: false,
+      dirty: false,
+      valuePresent: false,
+      valueLength: 0,
+      minLength: 8,
+      valueShape: "short-text",
+      acceptsMultiple: false,
+      emptyValue: "",
+      payloadPath: "sourceBundle.verification.bundleDigest",
+      message: "Provide bundle digest before marking this action complete.",
+    },
+  ];
+  const expectedNextInitialValidationDisplayMetadata = [
+    {
+      key: "strictBundleCheckOutput",
+      label: "Strict bundle-check output",
+      status: "missing-required",
+      statusLabel: "Missing required",
+      statusTone: "danger",
+      iconName: "alert-circle",
+      actionLabel: "Provide evidence",
+      helperText: "Required before completion",
+      blocking: true,
+      required: true,
+      message: "Provide strict bundle-check output before marking this action complete.",
+    },
+    {
+      key: "bundleDigest",
+      label: "Bundle digest",
+      status: "missing-required",
+      statusLabel: "Missing required",
+      statusTone: "danger",
+      iconName: "alert-circle",
+      actionLabel: "Provide evidence",
+      helperText: "Required before completion",
+      blocking: true,
+      required: true,
+      message: "Provide bundle digest before marking this action complete.",
+    },
+  ];
+  const expectedNextInitialValidationChecklist = expectedNextInitialValidationStates.map((state) => ({
+    key: state.key,
+    label: state.label,
+    status: state.status,
+    statusLabel: state.statusLabel,
+    statusTone: state.statusTone,
+    iconName: state.iconName,
+    actionLabel: state.actionLabel,
+    helperText: state.helperText,
+    required: state.required,
+    blocking: state.blocking,
+    completionBlocking: state.blocking,
+    checkedInitially: state.valid,
+    disabled: false,
+    message: state.message,
+    payloadPath: state.payloadPath,
+  }));
+  const expectedNextInitialValidationChecklistSummary = buildExpectedInitialValidationChecklistSummary(
+    expectedNextInitialValidationChecklist,
+  );
+  const expectedNextInitialValidationSummary = {
+    status: "blocked",
+    statusLabel: "Blocked by required evidence",
+    statusTone: "danger",
+    iconName: "alert-circle",
+    actionLabel: "Provide required evidence",
+    helperText: "2 required evidence field(s) need input before completion.",
+    fieldCount: 2,
+    requiredCount: 2,
+    optionalCount: 0,
+    validCount: 0,
+    invalidCount: 2,
+    blockingCount: 2,
+    nonBlockingCount: 0,
+    missingRequiredCount: 2,
+    optionalEmptyCount: 0,
+    dangerDisplayCount: 2,
+    infoDisplayCount: 0,
+    allFieldsPristine: true,
+    canCompleteInitially: false,
+    firstBlockingFieldKey: "strictBundleCheckOutput",
+    firstBlockingFieldLabel: "Strict bundle-check output",
+    firstBlockingMessage: "Provide strict bundle-check output before marking this action complete.",
+  };
+  return {
+    expectedNextInitialValidationChecklist,
+    expectedNextInitialValidationChecklistSummary,
+    expectedNextInitialValidationDisplayMetadata,
+    expectedNextInitialValidationStates,
+    expectedNextInitialValidationSummary,
+  };
+}