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.
JavaScript aiai-agentsclaudeclaude-codecursornextjspixel-perfectplaywrightscreenshot-to-codetailwindcssweb-cloningwebsite-cloner
#!/usr/bin/env node
// Spec linter — the mechanical gate before any builder agent is dispatched.
// A spec that fails here means extraction is incomplete. No builder until it passes.
//
// Usage: node scripts/lint-spec.mjs <spec.md> [more.spec.md ...]
// node scripts/lint-spec.mjs docs/research/components (lints every *.spec.md inside)
// Exit 1 if any spec fails.
//
// Tiers: a spec may declare `tier: light` in its frontmatter (spec-scaffold
// sets it mechanically). The full template is overkill for a static CTA — both
// agents in the head-to-head benchmark said so — so a section whose walk shows
// ≤ LIGHT_TIER_MAX_NODES (15) nodes AND has zero captured states may ship the
// lighter schema: same headings, but States & Behaviors / Per-State Content
// may be a single "N/A — static" line and the minimum-length warning is
// waived. 15 nodes ≈ heading + paragraph + a couple of CTAs — anything with a
// grid, tabs, or captured states is past it. The linter cross-checks the walk
// JSON when it can find it, so the tier can't be claimed to dodge rigor.
import { readFileSync, statSync, readdirSync, existsSync } from "node:fs";
import { join, basename, dirname, relative, isAbsolute } from "node:path";
import { selfReport, findPage, findSection, advanceStage } from "./manifest-lib.mjs";
import { walkNodes } from "./extract/walk-format.mjs";
const LIGHT_TIER_MAX_NODES = 15;
// Ground-truth check for `tier: light`: locate the section's walk JSON under
// any research host dir and verify the claim. Returns null when unverifiable.
function lightTierViolation(name) {
const root = "docs/research";
if (!existsSync(root)) return null;
for (const host of readdirSync(root)) {
const walkPath = join(root, host, "sections", `${name}.json`);
if (!existsSync(walkPath)) continue;
try {
const doc = JSON.parse(readFileSync(walkPath, "utf8"));
if (doc.tree) {
const n = [...walkNodes(doc.tree)].length;
if (n > LIGHT_TIER_MAX_NODES) return `walk has ${n} nodes (max ${LIGHT_TIER_MAX_NODES} for light tier)`;
}
for (const f of readdirSync(join(root, host, "sections"))) {
if (f.startsWith(`${name}-`) && f.endsWith(".json")) {
const cap = JSON.parse(readFileSync(join(root, host, "sections", f), "utf8"));
if (cap.trigger) return `captured state exists (${f}) — light tier is for stateless sections`;
}
}
return null;
} catch {
return null;
}
}
return null;
}
const REQUIRED_FRONTMATTER = ["component", "target", "page", "screenshot", "interaction_model", "states", "assets", "responsive"];
const INTERACTION_MODELS = ["static", "click-driven", "scroll-driven", "hover-driven", "time-driven", "mixed"];
const REQUIRED_HEADINGS = [
"## DOM Structure",
"## Computed Styles",
"## States & Behaviors",
"## Text Content",
"## Responsive Behavior",
];
const MAX_BODY_LINES = 150; // complexity budget — bigger spec = split the section
const MIN_BODY_LINES = 25; // thinner than this = extraction was lazy
const inputs = process.argv.slice(2);
if (!inputs.length) {
console.error("Usage: node scripts/lint-spec.mjs <spec.md|dir> ...");
process.exit(1);
}
// Expand directories to *.spec.md files
const files = inputs.flatMap((p) => {
if (statSync(p).isDirectory()) {
const found = [];
const walk = (dir) => {
for (const e of readdirSync(dir, { withFileTypes: true })) {
const full = join(dir, e.name);
if (e.isDirectory()) walk(full);
else if (e.name.endsWith(".spec.md")) found.push(full);
}
};
walk(p);
return found;
}
return [p];
});
if (!files.length) {
console.error("No .spec.md files found.");
process.exit(1);
}
let failed = 0;
for (const file of files) {
const raw = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
const errors = [];
const warnings = [];
// --- frontmatter ---
const fm = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
if (!fm) {
errors.push("Missing YAML frontmatter (--- ... ---) at top of file");
} else {
const meta = {};
for (const line of fm[1].split("\n")) {
const m = line.match(/^([a-zA-Z_]+):\s*(.*)$/);
if (m) meta[m[1]] = m[2].replace(/^["']|["']$/g, "").trim();
}
for (const key of REQUIRED_FRONTMATTER) {
if (!meta[key]) errors.push(`Frontmatter missing or empty: "${key}"`);
}
const light = meta.tier === "light";
if (meta.tier && !light) {
errors.push(`tier must be "light" or omitted (got "${meta.tier}")`);
}
if (light) {
const violation = lightTierViolation(basename(file).replace(/\.spec\.md$/, ""));
if (violation) errors.push(`tier: light rejected — ${violation}. Use the full schema.`);
}
if (meta.interaction_model && !INTERACTION_MODELS.includes(meta.interaction_model)) {
errors.push(`interaction_model must be one of: ${INTERACTION_MODELS.join(", ")} (got "${meta.interaction_model}")`);
}
if (meta.target && !meta.target.startsWith("src/")) {
errors.push(`target should be a path under src/ (got "${meta.target}")`);
}
if (meta.screenshot && !existsSync(meta.screenshot)) {
errors.push(`screenshot file does not exist: ${meta.screenshot}`);
}
if (meta.responsive) {
for (const vp of ["phone", "ipad", "pc"]) {
if (!meta.responsive.includes(vp)) errors.push(`responsive must cover all three viewports — missing "${vp}"`);
}
}
// --- body ---
const body = fm[2];
for (const h of REQUIRED_HEADINGS) {
if (!body.includes(h)) errors.push(`Missing required heading: "${h}"`);
else {
// heading exists but is its section empty?
const idx = body.indexOf(h);
const next = body.indexOf("\n## ", idx + h.length);
const content = body.slice(idx + h.length, next === -1 ? undefined : next).trim();
if (content.length < 10) errors.push(`Section "${h}" is empty — fill it or write "N/A" with a reason`);
}
}
// Fenced code blocks (the generated Source Markup on utility-CSS sites) are
// machine-quoted, not hand-written — they don't count against the
// complexity budget, which exists to bound what a BUILDER has to reason
// through, and markup is what the builder translates, not extra reasoning.
let inFence = false;
let bodyLines = 0;
for (const line of body.split("\n")) {
if (/^```/.test(line.trim())) {
inFence = !inFence;
continue;
}
if (!inFence) bodyLines++;
}
if (bodyLines > MAX_BODY_LINES) {
errors.push(`Spec body is ${bodyLines} lines outside code fences (max ${MAX_BODY_LINES}). Complexity budget exceeded — SPLIT this section into smaller components.`);
}
if (bodyLines < MIN_BODY_LINES && !light) {
warnings.push(`Spec body is only ${bodyLines} lines — is extraction really complete?`);
}
if (!/getComputedStyle|px|rem|rgb|oklch/.test(body)) {
errors.push("No concrete CSS values found in body — computed styles must be extracted, not described");
}
// The Responsive section must carry MEASURED NUMBERS for all three viewports,
// not prose. Real-site testing showed that specs saying "iPad: same layout"
// make builders guess intermediate values, and every guess costs QA points on
// sites whose spacing scales with root font-size.
const rIdx = body.indexOf("## Responsive Behavior");
if (rIdx !== -1) {
const rEnd = body.indexOf("\n## ", rIdx + 1);
const rBody = body.slice(rIdx, rEnd === -1 ? undefined : rEnd);
const perViewport = { phone: /phone|390/i, ipad: /ipad|tablet|768/i, pc: /pc|desktop|1440/i };
for (const [vp, re] of Object.entries(perViewport)) {
const line = rBody.split("\n").find((l) => re.test(l));
if (!line) {
errors.push(`Responsive Behavior has no line for "${vp}" — all three viewports must be documented`);
continue;
}
// Strip the viewport width itself, then demand at least two real measurements
const measurements = line.replace(/\b(390|768|1440)\b/g, "").match(/\d+(\.\d+)?\s*(px|rem|%|col)/gi) || [];
if (measurements.length < 2) {
errors.push(
`Responsive Behavior "${vp}" needs at least 2 measured values with units (e.g. "h2 28px, padding 48px, 2 cols") — got ${measurements.length}. Copy real numbers from responsive.json instead of describing the layout.`
);
}
if (/\b(same|unchanged|identical|as above|no change)\b/i.test(line) && measurements.length < 3) {
errors.push(
`Responsive Behavior "${vp}" says "same/unchanged" — spell out the actual values. Sites that scale with root font-size change every number between breakpoints even when the layout looks identical.`
);
}
}
}
}
if (errors.length) {
failed++;
console.log(`✗ ${file}`);
errors.forEach((e) => console.log(` ERROR: ${e}`));
} else {
console.log(`✓ ${file}`);
markSpecd(file);
}
warnings.forEach((w) => console.log(` warn: ${w}`));
}
// A passing lint IS the "specd" stage transition — report it to the manifest
// instead of relying on a separate agent command. Spec paths follow
// components/<route-slug>/<name>.spec.md; when the slug doesn't invert to a
// route cleanly (nested routes), fall back to the unique section name.
function markSpecd(file) {
const name = basename(file).replace(/\.spec\.md$/, "");
const slug = basename(dirname(file));
const specPath = isAbsolute(file) ? relative(process.cwd(), file) : file;
const reported = selfReport((m) => {
let page = findPage(m, slug === "home" ? "/" : `/${slug}`);
let sec = findSection(page, name);
if (!sec) {
const hits = m.pages.flatMap((p) => p.sections.filter((s) => s.name === name).map((s) => [p, s]));
if (hits.length === 1) [page, sec] = hits[0];
}
if (!sec) return false;
const advanced = advanceStage(sec, "specd");
const pathChanged = sec.spec !== specPath;
sec.spec = specPath;
return advanced || pathChanged;
});
if (reported) console.log(` manifest: ${name} → specd`);
}
console.log(`\n${files.length - failed}/${files.length} specs pass`);
process.exit(failed ? 1 : 0);