Skip to content

Clone any website into a pixel-accurate Next.js app with AI — Playwright-measured extraction (no eyeballing), spec-gated parallel builder agents, and scored pixel-diff QA at phone/tablet/desktop. Works with Claude Code, Cursor, Copilot + 9 more.

19.4 KB
Raw Blame
#!/usr/bin/env node
// Generate the MECHANICAL parts of a component spec straight from extraction
// JSON — frontmatter skeleton, DOM Structure, Computed Styles, Assets, Text
// Content, Responsive Behavior — leaving clearly marked <!-- AGENT: fill -->
// blocks for the judgment sections (interaction_model, States & Behaviors,
// Per-State Content, implementation notes).
//
// Specs used to be hand-transcribed from sections/<name>.json; agents
// mis-transcribe, which is why the skill has the rule "if the spec disagrees
// with the JSON, the JSON wins". This script kills the transcription step: the
// mechanical sections are now generated from the same JSON they used to be
// copied from, and the agent only writes the parts that need judgment.
//
// Usage:
//   node scripts/spec-scaffold.mjs --route / --section hero [--section pricing]
//   node scripts/spec-scaffold.mjs --route / --all          # every section of the route
//     [--host plausible.io]       host dir under research/ (from manifest when omitted)
//     [--research docs/research]  research root (default docs/research)
//     [--out <research>/components]
//
// Reads:  <research>/<host>/sections/<name>.json   (walk — legacy or compact)
//         <research>/<host>/responsive.json, probe-<name>.json, assets.json
//         <research>/<host>/sections/<name>-*.json (state captures -> listed as states)
// Writes: <out>/<route-slug>/<name>.spec.md
//
// The output passes lint-spec.mjs once the agent fills the marked blocks —
// until then interaction_model is invalid on purpose, so an unfilled scaffold
// can never be dispatched to a builder.
import { readFileSync, readdirSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { join, basename } from "node:path";
import { hostOf, slugify, parseArgs, toList } from "./lib.mjs";
import { walkNodes, resolveStyles, nodeLabel } from "./extract/walk-format.mjs";

// A section this small with zero captured states doesn't need the full spec
// ceremony — lint-spec accepts the lighter schema when tier: light is set,
// and cross-checks the walk so the tier can't be claimed to dodge rigor.
const LIGHT_TIER_MAX_NODES = 15;

const args = parseArgs(process.argv.slice(2));
const research = typeof args.research === "string" ? args.research : "docs/research";
const outRoot = typeof args.out === "string" ? args.out : join(research, "components");
const route = typeof args.route === "string" ? args.route : "/";
const routeSlug = route === "/" ? "home" : slugify(route.replace(/^\//, ""));

let host = typeof args.host === "string" ? args.host : null;
let sections = toList(args.section).map(String);

const manifestPath = join(research, "manifest.json");
if (existsSync(manifestPath)) {
  const m = JSON.parse(readFileSync(manifestPath, "utf8"));
  if (!host && m.site) host = hostOf(m.site);
  if (args.all) {
    const p = m.pages.find((p) => p.route === route);
    if (!p) {
      console.error(`Route ${route} not in manifest. Routes: ${m.pages.map((p) => p.route).join(", ")}`);
      process.exit(1);
    }
    sections = p.sections.map((s) => s.name);
  }
}
if (!host) {
  // fall back to the only host dir that has extraction output
  const candidates = existsSync(research)
    ? readdirSync(research).filter((d) => existsSync(join(research, d, "sections")))
    : [];
  if (candidates.length === 1) host = candidates[0];
}
if (!host || !sections.length) {
  console.error("Usage: node scripts/spec-scaffold.mjs --route / --section hero [--section x ...] | --all  [--host h] [--research dir] [--out dir]");
  process.exit(1);
}

const hostDir = join(research, host);
const sectionsDir = join(hostDir, "sections");
const readJson = (p) => (existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null);
const responsive = readJson(join(hostDir, "responsive.json"));
const assetsDoc = readJson(join(hostDir, "assets.json"));

const trunc = (s, n) => (s && s.length > n ? s.slice(0, n - 1) + "…" : s || "");
const AGENT = (hint) => `<!-- AGENT: fill — ${hint} -->`;
// script/style nodes are in the walk (ground truth) but are noise in a spec
const isNoise = (node) => ["script", "style", "noscript", "template"].includes(node.tag);

// ── naming ──────────────────────────────────────────────────────────────────
function componentName(name) {
  if (/^(nav|header)$/.test(name)) return "SiteHeader";
  if (name === "footer") return "SiteFooter";
  const pascal = name.split(/[^a-z0-9]+/i).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
  return pascal.endsWith("Section") ? pascal : pascal + "Section";
}

// ── DOM structure (collapsed wrapper chains, grouped sibling runs) ──────────
const MAX_DOM_LINES = 18;
function domStructure(tree) {
  const lines = [];
  let truncated = false;
  const rec = (node, depth, countPrefix) => {
    if (!node || node.error) return;
    if (lines.length >= MAX_DOM_LINES) {
      truncated = true;
      return;
    }
    let label = nodeLabel(node);
    let cur = node;
    // a chain of lone wrappers is one line: div.container > div.mx-auto > …
    while ((cur.children || []).length === 1 && !cur.text && !cur.img && label.length < 80) {
      cur = cur.children[0];
      label += " > " + nodeLabel(cur);
    }
    const text = cur.text ? ` — "${trunc(cur.text, 48)}"` : "";
    const dims = cur.rect && depth <= 1 ? ` [${cur.rect.w}×${cur.rect.h}]` : "";
    lines.push(`${"  ".repeat(depth)}- ${countPrefix}${label}${dims}${text}`);
    const kids = (cur.children || []).filter((k) => k && !k.error && !k.truncated && !isNoise(k));
    const sig = (k) => `${k.tag}|${k.classes || ""}`;
    let i = 0;
    while (i < kids.length) {
      let j = i + 1;
      while (j < kids.length && sig(kids[j]) === sig(kids[i])) j++;
      rec(kids[i], depth + 1, j - i >= 2 ? `×${j - i} ` : "");
      i = j;
    }
    if (cur.truncatedChildren) lines.push(`${"  ".repeat(depth + 1)}- … +${cur.truncatedChildren} more children (see JSON)`);
  };
  rec(tree, 0, "");
  if (truncated) lines.push(`- … truncated — full tree in the section JSON (ground truth)`);
  return lines;
}

// ── computed styles (selective + deduplicated) ──────────────────────────────
const MAX_STYLE_LINES = 26;
function summarizeStyles(s, hasText) {
  const parts = [];
  if (hasText && s.fontSize) {
    let t = `${s.fontSize}/${s.fontWeight || "400"}/${s.lineHeight || "-"}`;
    if (s.letterSpacing) t += ` ${s.letterSpacing}`;
    if (s.color) t += ` ${s.color}`;
    parts.push(t);
    if (s.textAlign && !["start", "left"].includes(s.textAlign)) parts.push(s.textAlign);
    if (s.textTransform) parts.push(s.textTransform);
  }
  if (s.backgroundColor) parts.push(`bg ${s.backgroundColor}`);
  if (s.backgroundImage) parts.push(`bg-img ${trunc(s.backgroundImage, 42)}`);
  if (s.borderRadius) parts.push(`radius ${s.borderRadius}`);
  const bw = s.borderTopWidth || s.borderBottomWidth || s.borderLeftWidth || s.borderRightWidth;
  if (bw && s.borderStyle && s.borderStyle !== "none") parts.push(`border ${bw} ${s.borderStyle} ${s.borderColor || ""}`.trim());
  if (s.boxShadow) parts.push(`shadow ${trunc(s.boxShadow, 48)}`);
  const pads = [s.paddingTop, s.paddingRight, s.paddingBottom, s.paddingLeft].map((v) => v || "0px");
  if (pads.some((v) => v !== "0px")) parts.push(`pad ${pads.join(" ")}`);
  const margins = [["mt", s.marginTop], ["mr", s.marginRight], ["mb", s.marginBottom], ["ml", s.marginLeft]].filter(([, v]) => v);
  if (margins.length) parts.push(margins.map(([k, v]) => `${k} ${v}`).join(" "));
  if (/flex/.test(s.display || "")) {
    let f = `flex ${s.flexDirection || "row"}`;
    if (s.gap) f += ` gap ${s.gap}`;
    if (s.justifyContent) f += ` justify ${s.justifyContent}`;
    if (s.alignItems) f += ` items ${s.alignItems}`;
    parts.push(f);
  } else if (/grid/.test(s.display || "")) {
    parts.push(`grid cols [${trunc(s.gridTemplateColumns || "", 40)}]${s.gap ? ` gap ${s.gap}` : ""}`);
  }
  if (s.maxWidth) parts.push(`max-w ${s.maxWidth}`);
  if (s.position && s.position !== "static") {
    parts.push(`${s.position}${s.zIndex && s.zIndex !== "auto" ? ` z${s.zIndex}` : ""}${s.top ? ` top ${s.top}` : ""}${s.bottom ? ` bottom ${s.bottom}` : ""}`);
  }
  if (s.opacity && s.opacity !== "1") parts.push(`opacity ${s.opacity}`);
  if (s.transform) parts.push(`transform ${trunc(s.transform, 36)}`);
  return parts.join("; ");
}

function styleLines(doc, tree, maxLines = MAX_STYLE_LINES) {
  const seen = new Map();
  const entries = [];
  for (const { node, ancestors } of walkNodes(tree)) {
    if (node.isSvg || isNoise(node)) continue;
    const styles = resolveStyles(node, ancestors, doc);
    const hasText = !!node.text;
    const visual = !!(styles.backgroundColor || styles.backgroundImage || styles.boxShadow || styles.borderRadius);
    const layout = /(flex|grid)/.test(styles.display || "");
    if (ancestors.length && !hasText && !visual && !layout && !node.img) continue;
    const summary = summarizeStyles(styles, hasText);
    if (!summary) continue;
    const sig = `${node.tag}|${summary}`;
    if (seen.has(sig)) {
      seen.get(sig).count++;
      continue;
    }
    const parent = ancestors[ancestors.length - 1];
    const label = (parent ? nodeLabel(parent) + " > " : "") + nodeLabel(node) + (hasText ? ` ("${trunc(node.text, 22)}")` : "");
    const entry = { label, summary, count: 1, size: node.rect ? ` [${node.rect.w}×${node.rect.h}]` : "" };
    seen.set(sig, entry);
    entries.push(entry);
  }
  const lines = entries.slice(0, maxLines).map(
    (e) => `- **${e.label}**${e.count > 1 ? ` ×${e.count}` : ""}${e.size}: ${e.summary}`
  );
  if (entries.length > maxLines) {
    lines.push(`- … +${entries.length - maxLines} more styled nodes — resolve any node with \`node scripts/resolve-walk.mjs\` (JSON is ground truth)`);
  }
  return lines;
}

// ── text content (verbatim) ─────────────────────────────────────────────────
const MAX_TEXT_LINES = 36;
function textLines(tree) {
  const all = [];
  for (const { node } of walkNodes(tree)) {
    if (node.text && !isNoise(node)) all.push(`- ${node.tag}: "${node.text}"`);
  }
  // collapse exact consecutive repeats
  const lines = [];
  for (let i = 0; i < all.length; i++) {
    let j = i + 1;
    while (j < all.length && all[j] === all[i]) j++;
    lines.push(j - i >= 2 ? `${all[i]} ×${j - i}` : all[i]);
    i = j - 1;
  }
  if (lines.length > MAX_TEXT_LINES) {
    const extra = lines.length - MAX_TEXT_LINES;
    lines.length = MAX_TEXT_LINES;
    lines.push(`- … +${extra} more text nodes — verbatim in the section JSON`);
  }
  return lines.length ? lines : ["None — no text nodes in this section."];
}

// ── assets ──────────────────────────────────────────────────────────────────
function assetInfo(doc, tree) {
  const localFor = (src) => assetsDoc?.downloads?.find((d) => d.remote === src)?.local || null;
  const seen = new Set();
  const lines = [];
  const locals = [];
  let svgCount = 0;
  for (const { node, ancestors } of walkNodes(tree)) {
    if (node.isSvg) svgCount++;
    if (node.img?.src && !seen.has(node.img.src)) {
      seen.add(node.img.src);
      const local = localFor(node.img.src);
      if (local) locals.push(local);
      lines.push(`- img ${basename(new URL(node.img.src, "https://x/").pathname)} (${node.img.w}×${node.img.h})${node.img.alt ? ` alt "${trunc(node.img.alt, 40)}"` : ""} → ${local || "NOT DOWNLOADED — check assets.json"}`);
    }
    const bg = resolveStyles(node, ancestors, doc).backgroundImage;
    const m = bg && bg.match(/url\(["']?([^"')]+)["']?\)/);
    if (m && !m[1].startsWith("data:") && !seen.has(m[1])) {
      seen.add(m[1]);
      const local = localFor(m[1]);
      if (local) locals.push(local);
      lines.push(`- background-image ${basename(m[1])} on ${nodeLabel(node)} → ${local || "NOT DOWNLOADED"}`);
    }
  }
  if (svgCount) lines.push(`- inline SVG ×${svgCount} — use/extend components in src/components/icons.tsx`);
  if (!lines.length) lines.push("None — text and CSS only.");
  const fmAssets = locals.length
    ? locals.slice(0, 4).join(", ") + (locals.length > 4 ? ` +${locals.length - 4} more` : "")
    : svgCount ? "icons only (icons.tsx)" : "none";
  return { lines, fmAssets };
}

// ── state captures (mechanical reference for the agent's judgment block) ────
function stateCaptures(name) {
  const out = [];
  if (!existsSync(sectionsDir)) return out;
  for (const f of readdirSync(sectionsDir)) {
    if (!f.startsWith(name + "-") || !f.endsWith(".json")) continue;
    const doc = readJson(join(sectionsDir, f));
    if (!doc?.trigger) continue;
    const byProp = {};
    for (const d of doc.diff || []) byProp[d.prop] = (byProp[d.prop] || 0) + 1;
    const top = Object.entries(byProp).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([p]) => p);
    out.push({
      suffix: f.slice(name.length + 1, -5),
      file: f,
      trigger: doc.trigger,
      settleMs: doc.settleMs,
      changes: (doc.diff || []).length,
      added: (doc.added || []).length,
      removed: (doc.removed || []).length,
      topProps: top,
    });
  }
  return out;
}

// ── responsive behavior ─────────────────────────────────────────────────────
function responsiveLines(name, selector) {
  const entry = responsive?.sections?.find((s) => s.name === name) || responsive?.sections?.find((s) => s.selector === selector);
  const probe = readJson(join(hostDir, `probe-${slugify(name)}.json`));
  const probeFor = (vp) => {
    const bySel = probe?.results?.[vp];
    if (!bySel) return null;
    return bySel[selector] || Object.values(bySel)[0] || null;
  };
  const lines = [];
  for (const [vp, px] of [["phone", 390], ["ipad", 768], ["pc", 1440]]) {
    const sig = entry?.[vp];
    const pr = probeFor(vp);
    if (!sig && !pr) continue;
    const parts = [];
    if (sig) {
      parts.push(`section ${sig.width}×${sig.height}px`);
      if (sig.paddingX && sig.paddingX !== "0px / 0px") parts.push(`pad-x ${sig.paddingX}`);
      if (sig.headingFontSize) parts.push(`heading ${sig.headingFontSize}`);
      if (sig.fontSize) parts.push(`body ${sig.fontSize}`);
      const cols = sig.innerLayout?.realColumns;
      if (cols) parts.push(`${cols} col${cols > 1 ? "s" : ""} (${sig.innerLayout.itemCount} items, gap ${sig.innerLayout.gap})`);
      if (sig.hiddenChildren) parts.push(`${sig.hiddenChildren} hidden children`);
    }
    if (pr) {
      const p = [];
      if (pr.paddingTop && pr.paddingTop !== "0px") p.push(`pt ${pr.paddingTop}`);
      if (pr.paddingBottom && pr.paddingBottom !== "0px") p.push(`pb ${pr.paddingBottom}`);
      if (pr.marginTop && pr.marginTop !== "0px") p.push(`mt ${pr.marginTop}`);
      if (pr.maxWidth && pr.maxWidth !== "none") p.push(`max-w ${pr.maxWidth}`);
      if (pr.lineHeight) p.push(`lh ${pr.lineHeight}`);
      if (pr.gridTemplateColumns && pr.gridTemplateColumns !== "none") p.push(`grid [${trunc(pr.gridTemplateColumns, 36)}]`);
      if (p.length) parts.push(p.join(", "));
    }
    lines.push(`- ${vp} ${px}: ${parts.join("; ")}`);
  }
  if (!lines.length) {
    return [AGENT(`no responsive.json entry for "${name}" — run probe.mjs --route ${route} and fill measured values for phone/ipad/pc`)];
  }
  for (const c of entry?.summary?.changes || []) lines.push(`- change: ${c}`);
  if (entry?.summary?.ipadBehavior) lines.push(`- ${entry.summary.ipadBehavior}`);
  lines.push(`- exact per-property values: probe-${slugify(name)}.json + responsive.json (ground truth)`);
  return lines;
}

// ── main ────────────────────────────────────────────────────────────────────
let failed = 0;
for (const name of sections) {
  const doc = readJson(join(sectionsDir, `${name}.json`));
  if (!doc) {
    console.error(`✗ ${name}: no ${join(sectionsDir, `${name}.json`)} — extract it first (page.mjs)`);
    failed++;
    continue;
  }
  if (!doc.tree) {
    console.error(`✗ ${name}: ${name}.json is a state capture, not a section walk — scaffold the base section`);
    failed++;
    continue;
  }
  const tree = doc.tree;
  const captures = stateCaptures(name);
  const comp = componentName(name);
  const nodeCount = [...walkNodes(tree)].length;
  const light = nodeCount <= LIGHT_TIER_MAX_NODES && captures.length === 0;
  const { lines: assetLines, fmAssets } = assetInfo(doc, tree);
  const statesFm = ["default", ...captures.map((c) => c.suffix)].join(", ");

  const captureLines = captures.length
    ? captures.map((c) =>
        `- state "${c.suffix}" (${c.file}): trigger \`${c.trigger}\`, settle ${c.settleMs}ms — ${c.changes} props changed` +
        (c.added || c.removed ? `, +${c.added}/-${c.removed} nodes` : "") +
        (c.topProps.length ? ` (top: ${c.topProps.join(", ")})` : "")
      )
    : [`- No state captures on disk. Cross-check css.json interactiveStates — a :hover/:focus rule for this section with no capture means extraction is not done.`];

  // Utility-CSS fast path: when the extraction captured cleaned markup, the
  // class list IS the spec — quote it and keep computed styles down to a few
  // key anchors for verification instead of an exhaustive dump.
  const markupBlock = doc.html
    ? `
## Source Markup
Utility CSS detected — translate this markup first, verify with probe values second.
\`\`\`html
${doc.html}
\`\`\`
`
    : "";
  const stylesBlock = doc.html
    ? styleLines(doc, tree, 8).join("\n") + "\n- Key anchors only — the Source Markup above is the primary spec; resolve any node via resolve-walk.mjs."
    : styleLines(doc, tree).join("\n");

  const md = `---
component: ${comp}
target: src/components/${comp}.tsx
page: ${route}
screenshot: docs/design-references/${host}/${name}-pc.png
interaction_model: ${AGENT("one of: static | click-driven | scroll-driven | hover-driven | time-driven | mixed")}
states: ${statesFm}
assets: ${fmAssets}
responsive: phone, ipad, pc${light ? "\ntier: light" : ""}
---

# ${comp} Specification

## DOM Structure
${domStructure(tree).join("\n")}
${markupBlock}
## Computed Styles
${stylesBlock}

## States & Behaviors
${AGENT("per behavior: Trigger / State A / State B / Transition + implementation approach (CSS transition, IntersectionObserver, …). Mechanical capture data below is reference, not a substitute.")}
${captureLines.join("\n")}

## Per-State Content
${AGENT('full content per state for tabbed/stateful sections; write "N/A — static" if the section has one state')}

## Assets
${assetLines.join("\n")}

## Text Content
${textLines(tree).join("\n")}

## Responsive Behavior
${responsiveLines(name, doc.selector).join("\n")}

## Notes
${AGENT("implementation notes for the builder: component split, data file shape for src/data/, gotchas. Delete this section if nothing to add.")}
`;

  const outDir = join(outRoot, routeSlug);
  mkdirSync(outDir, { recursive: true });
  const outPath = join(outDir, `${name}.spec.md`);
  writeFileSync(outPath, md);
  const bodyLines = md.split("\n").length;
  console.log(`✓ ${outPath} (${bodyLines} lines, ${captures.length} captured state(s)${light ? ", tier: light" : ""}) — fill the <!-- AGENT: fill --> blocks, then lint`);
}
process.exit(failed ? 1 : 0);