@elitedcs/ghl-mcp 3.55.0 → 3.57.0

package/skills/clone-site/scripts/extract-design.mjs

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * extract-design.mjs — the STYLE LANE (rights = none, or "I just want the look").
+ *
+ * Pulls the page's real design system — palette, type scale, spacing rhythm,
+ * radii, shadows, breakpoints, section skeleton — so a rebuild starts from the
+ * actual design instead of a from-memory redraw (the failure that produced a
+ * result "not even close" to the original).
+ *
+ * It deliberately copies NO page bytes, NO images, NO video and NO copy. Section
+ * structure is recorded as shape only (role, heading word count, CTA count,
+ * media count) — never verbatim text.
+ *
+ * Usage:
+ *   node extract-design.mjs --url <url> --out <dir>
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseArgs, fetchText, mapLimit, ext, writeJson, nowIso } from "./lib.mjs";
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.url || !args.out) {
+  console.error("usage: extract-design.mjs --url <url> --out <dir>");
+  process.exit(1);
+}
+const SRC = String(args.url);
+const OUT = path.resolve(String(args.out));
+fs.mkdirSync(OUT, { recursive: true });
+
+const rank = (arr) => {
+  const m = new Map();
+  for (const v of arr) m.set(v, (m.get(v) || 0) + 1);
+  return [...m.entries()].sort((a, b) => b[1] - a[1]).map(([value, count]) => ({ value, count }));
+};
+
+function normalizeColor(c) {
+  const s = c.trim().toLowerCase();
+  if (/^#[0-9a-f]{3}$/.test(s)) return "#" + s.slice(1).split("").map((ch) => ch + ch).join("");
+  return s;
+}
+
+async function main() {
+  const page = await fetchText(SRC);
+  if (!page.ok || !page.text) {
+    console.error(`FAILED to fetch ${SRC} (status ${page.status}).`);
+    process.exit(4);
+  }
+  const html = page.text;
+  const origin = new URL(SRC).origin;
+
+  // ---- gather stylesheets (linked + inline) --------------------------------
+  const cssUrls = [];
+  for (const m of html.matchAll(/<link[^>]+rel=["']stylesheet["'][^>]*>/gi)) {
+    const href = (m[0].match(/href=["']([^"']+)["']/i) || [])[1];
+    if (href) {
+      try { cssUrls.push(new URL(href, SRC).toString()); } catch {}
+    }
+  }
+  const fetched = await mapLimit(cssUrls, 6, async (u) => ({ u, r: await fetchText(u) }));
+
+  /**
+   * Framework CSS drowns out the brand. On a WordPress/Elementor page the
+   * plugin stylesheets repeat neutral greys hundreds of times while the actual
+   * brand colours sit in the theme or per-page CSS and appear two or three
+   * times. Ranking by raw frequency therefore returns the FRAMEWORK's palette,
+   * which is how a "design-matched" rebuild ends up looking nothing like the
+   * original. Live-caught 2026-07-30. Split the sources and rank them apart.
+   */
+  const isVendor = (u) =>
+    /\/(?:plugins|node_modules|vendor|libs?)\//i.test(u) ||
+    /(?:bootstrap|swiper|normalize|reset|frontend(?:\.min)?\.css|widget-[\w-]*\.min|apple-webkit|e-animation|animations?\.min|font-?awesome|slick|owl\.carousel)/i.test(u);
+
+  let css = "";        // everything, for structural/type extraction
+  let brandCss = "";   // the site's own CSS — where the brand actually lives
+  for (const { u, r } of fetched) {
+    if (!r.ok) continue;
+    css += "\n" + r.text;
+    if (!isVendor(u)) brandCss += "\n" + r.text;
+  }
+  for (const m of html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+    css += "\n" + m[1];
+    brandCss += "\n" + m[1]; // inline <style> is authored for THIS page
+  }
+  // Inline style="" attributes are deliberate per-element design choices.
+  let inlineCss = "";
+  for (const m of html.matchAll(/style=["']([^"']+)["']/gi)) inlineCss += ";" + m[1];
+  brandCss += "\n" + inlineCss;
+
+  // Vite/Next builds sometimes inline tokens in the JS bundle.
+  const jsUrls = [];
+  for (const m of html.matchAll(/<script[^>]+src=["']([^"']+)["']/gi)) {
+    try {
+      const u = new URL(m[1], SRC).toString();
+      if (new URL(u).origin === origin && [".js", ".mjs"].includes(ext(u))) jsUrls.push(u);
+    } catch {}
+  }
+  const jsBodies = await mapLimit(jsUrls.slice(0, 6), 4, async (u) => (await fetchText(u)).text || "");
+  const jsText = jsBodies.join("\n");
+
+  const all = css + "\n" + jsText;
+
+  // ---- tokens ---------------------------------------------------------------
+  const cssVars = {};
+  const USELESS_VAR = /^(?:initial|inherit|unset|auto|none|normal|block|flex|0|0px|0%)$/i;
+  for (const m of brandCss.matchAll(/(--[A-Za-z0-9_-]+)\s*:\s*([^;{}]+)[;}]/g)) {
+    const k = m[1], v = m[2].trim();
+    if (USELESS_VAR.test(v)) continue; // framework placeholders, not design tokens
+    if (!cssVars[k]) cssVars[k] = v;
+  }
+
+  const colorsIn = (src) => {
+    const hex = [...src.matchAll(/#[0-9a-fA-F]{3,8}\b/g)].map((m) => normalizeColor(m[0]))
+      .filter((c) => c.length === 7 || c.length === 9);
+    const rgb = [...src.matchAll(/rgba?\(\s*\d{1,3}\s*[, ]\s*\d{1,3}\s*[, ]\s*\d{1,3}[^)]*\)/g)].map((m) => m[0].replace(/\s+/g, " "));
+    const hsl = [...src.matchAll(/hsla?\([^)]+\)/g)].map((m) => m[0].replace(/\s+/g, " "));
+    return [...hex, ...rgb, ...hsl];
+  };
+  const NEUTRAL = /^#(?:0{6}|f{6}|(?:([0-9a-f])\1){3})$/i; // pure black/white/grey ramps
+  const brandRanked = rank(colorsIn(brandCss));
+  const colors = brandRanked.slice(0, 24);
+  const frameworkColors = rank(colorsIn(all)).slice(0, 12);
+
+  /**
+   * Frequency alone is a poor brand signal: a page-builder's per-page CSS may
+   * name the brand colour ONCE while the theme repeats greys. So attribute each
+   * accent to the file it came from and weight page-specific CSS highest — then
+   * show the source, rather than pretending a rank order is authoritative.
+   */
+  const sourceWeight = (u) =>
+    /uploads\/[^?]*css\/post-\d+|\/post-\d+\.css|custom|brand|theme/i.test(u) ? 3 : 1;
+  const accentBySource = [];
+  const sources = [
+    ...fetched.filter(({ u, r }) => r.ok && !isVendor(u)).map(({ u, r }) => ({ label: u.split("/").pop().split("?")[0], text: r.text, weight: sourceWeight(u) })),
+    { label: "inline style attributes", text: inlineCss, weight: 3 },
+  ];
+  for (const src of sources) {
+    const accents = rank(colorsIn(src.text).filter((c) => c.startsWith("#") && !NEUTRAL.test(c)));
+    for (const a of accents.slice(0, 6)) accentBySource.push({ value: a.value, count: a.count, source: src.label, weight: src.weight });
+  }
+  const accentScore = new Map();
+  for (const a of accentBySource) {
+    const cur = accentScore.get(a.value) || { value: a.value, score: 0, sources: [] };
+    cur.score += a.count * a.weight;
+    if (!cur.sources.includes(a.source)) cur.sources.push(a.source);
+    accentScore.set(a.value, cur);
+  }
+  const brandAccents = [...accentScore.values()].sort((x, y) => y.score - x.score).slice(0, 10);
+
+  /**
+   * Best signal of all when it exists: the site's DECLARED colour tokens.
+   * Elementor (`--e-global-color-*`), WordPress theme.json
+   * (`--wp--preset--color--*`) and hand-authored `--brand-*` variables name the
+   * palette outright, so no frequency guessing is needed.
+   */
+  const COLOR_VALUE = /^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\()/;
+  const declaredPalette = Object.entries(cssVars)
+    .filter(([k, v]) => COLOR_VALUE.test(v.trim()) &&
+      /(?:global-color|preset--color|brand|palette|--color-|primary|secondary|accent)/i.test(k))
+    .map(([name, value]) => ({ name, value: value.trim() }));
+
+  /**
+   * Page-builders express type as CSS variables (`var(--e-global-typography-x-font-size)`).
+   * Reporting those verbatim is useless for a rebuild, so resolve them against
+   * the variables we collected and drop anything still unresolved.
+   */
+  const resolveVar = (v) => {
+    let out = String(v);
+    for (let i = 0; i < 4 && out.includes("var("); i++) {
+      out = out.replace(/var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,([^)]*))?\)/g, (m, name, fallback) =>
+        cssVars[name] !== undefined ? cssVars[name] : (fallback !== undefined ? fallback.trim() : m)
+      );
+    }
+    return out.trim();
+  };
+  const resolved = (list) =>
+    rank(list.map(resolveVar).filter((v) => v && !v.includes("var(") && !/^(?:inherit|initial|unset)$/i.test(v)));
+
+  const families = resolved(
+    [...css.matchAll(/font-family\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim().replace(/["']/g, ""))
+  ).slice(0, 8);
+  const faceFamilies = rank(
+    [...css.matchAll(/@font-face\s*{[^}]*font-family\s*:\s*["']?([^;"'}]+)["']?/gi)].map((m) => m[1].trim())
+  ).map((f) => f.value);
+  const googleFonts = [...html.matchAll(/https:\/\/fonts\.googleapis\.com\/css2?\?[^"']+/g)].map((m) => m[0]);
+
+  const fontSizes = resolved([...css.matchAll(/font-size\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 16);
+  const weights = resolved([...css.matchAll(/font-weight\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 8);
+  const lineHeights = resolved([...css.matchAll(/line-height\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 8);
+  const spacing = resolved(
+    [...css.matchAll(/(?:padding|margin|gap)(?:-(?:top|right|bottom|left|block|inline))?\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())
+  ).filter((v) => !/^0(?:px)?(?:\s+0(?:px)?)*$/.test(v.value)).slice(0, 20);
+  const radii = rank([...css.matchAll(/border-radius\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 10);
+  const shadows = rank([...css.matchAll(/box-shadow\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 10);
+  const breakpoints = rank([...css.matchAll(/@media[^{]*?\(([^)]*(?:min|max)-width[^)]*)\)/gi)].map((m) => m[1].trim())).slice(0, 10);
+  const containers = rank([...css.matchAll(/max-width\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 10);
+  const gridCols = rank([...css.matchAll(/grid-template-columns\s*:\s*([^;{}]+)/gi)].map((m) => m[1].trim())).slice(0, 10);
+  const usesTailwind = /tailwind|\bbg-\w+-\d{2,3}\b|\btext-\w+-\d{2,3}\b/.test(all);
+
+  // ---- section skeleton (shape only, never verbatim copy) -------------------
+  const body = html
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<!--[\s\S]*?-->/g, "");
+  const strip = (s) => s.replace(/<[^>]+>/g, " ").replace(/&[a-z]+;/gi, " ").replace(/\s+/g, " ").trim();
+  const words = (s) => (strip(s) ? strip(s).split(/\s+/).length : 0);
+
+  const landmarks = [...body.matchAll(/<(section|header|footer|nav|main|article)\b([^>]*)>/gi)];
+  const sections = [];
+  for (let i = 0; i < landmarks.length; i++) {
+    const start = landmarks[i].index;
+    const end = i + 1 < landmarks.length ? landmarks[i + 1].index : body.length;
+    const chunk = body.slice(start, end);
+    const attrs = landmarks[i][2] || "";
+    const cls = ((attrs.match(/class=["']([^"']*)["']/i) || [])[1] || "").toLowerCase();
+    const id = ((attrs.match(/id=["']([^"']*)["']/i) || [])[1] || "").toLowerCase();
+    const hay = `${landmarks[i][1]} ${cls} ${id} ${chunk.slice(0, 4000).toLowerCase()}`;
+    const role =
+      /hero|banner|jumbotron/.test(`${cls} ${id}`) ? "hero" :
+      /testimonial|review|rating|what .* say/.test(hay) ? "testimonials" :
+      /pricing|package|plan|tier|\$\d/.test(hay) ? "pricing" :
+      /faq|frequently asked|accordion/.test(hay) ? "faq" :
+      /footer/.test(landmarks[i][1] + cls + id) ? "footer" :
+      /nav|menu/.test(landmarks[i][1] + cls + id) ? "nav" :
+      /form|book|schedule|apply|contact/.test(hay) ? "capture/CTA" :
+      /benefit|feature|why|how it works|step/.test(hay) ? "benefits/features" :
+      i === 0 ? "hero" : "content";
+    const headings = [...chunk.matchAll(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi)].map((m) => ({
+      level: Number(m[1]),
+      words: words(m[2]),
+    }));
+    sections.push({
+      order: sections.length + 1,
+      tag: landmarks[i][1].toLowerCase(),
+      role,
+      headings,
+      paragraphs: (chunk.match(/<p\b/gi) || []).length,
+      listItems: (chunk.match(/<li\b/gi) || []).length,
+      images: (chunk.match(/<img\b/gi) || []).length,
+      videos: (chunk.match(/<video\b|<iframe[^>]+(youtube|vimeo|wistia)/gi) || []).length,
+      buttons: (chunk.match(/<button\b|class=["'][^"']*\bbtn\b|class=["'][^"']*button/gi) || []).length,
+      forms: (chunk.match(/<form\b/gi) || []).length,
+      approxWords: words(chunk),
+    });
+  }
+  // Page-builders nest landmark elements; the empty wrappers are noise.
+  const meaningful = sections.filter((x) => x.approxWords > 0 || x.images > 0 || x.videos > 0 || x.buttons > 0 || x.forms > 0);
+  const emptyWrappers = sections.length - meaningful.length;
+  sections.length = 0;
+  meaningful.forEach((x, i) => { x.order = i + 1; sections.push(x); });
+  const spaShell = sections.length <= 1 && words(body) < 120;
+
+  const tokens = {
+    tool: "clone-site/extract-design.mjs",
+    lane: "style — design system only; no bytes, images, video or copy were copied",
+    generatedAt: nowIso(),
+    source: SRC,
+    declaredPalette,
+    palette: colors,
+    brandAccents,
+    frameworkPalette: frameworkColors,
+    cssVariables: cssVars,
+    typography: { families, fontFaceFamilies: faceFamilies, googleFontsLinks: googleFonts, sizes: fontSizes, weights, lineHeights },
+    spacingScale: spacing,
+    radii,
+    shadows,
+    breakpoints,
+    containers,
+    gridColumns: gridCols,
+    utilityFramework: usesTailwind ? "tailwind-like utility classes detected" : null,
+    structure: { spaShell, sections, emptyWrappersDropped: emptyWrappers },
+  };
+  writeJson(path.join(OUT, "design-tokens.json"), tokens);
+
+  // ---- human-readable brief -------------------------------------------------
+  const md = [];
+  md.push("# Design system extracted (style lane)");
+  md.push("");
+  md.push(`Source: ${SRC}`);
+  md.push(`Generated: ${nowIso()}`);
+  md.push("");
+  md.push("**No page bytes, images, video or copy were copied.** This is the design system only: rebuild on it with original copy and licensed or original media.");
+  md.push("");
+  md.push("## Palette");
+  md.push("");
+  if (declaredPalette.length) {
+    md.push("**Declared colour tokens** — the site names its own palette. Use these; everything below is inference by comparison:");
+    md.push("");
+    for (const d of declaredPalette) md.push(`- \`${d.name}: ${d.value}\``);
+    md.push("");
+  }
+  if (brandAccents.length) {
+    md.push("**Brand colours** — non-neutral values from the site's OWN stylesheets and inline styles. These are the ones to reuse:");
+    md.push("");
+    for (const c of brandAccents) md.push(`- \`${c.value}\` — from ${c.sources.join(", ")}`);
+    md.push("");
+  }
+  md.push("Full palette from the site's own CSS (includes neutrals):");
+  md.push("");
+  for (const c of colors.slice(0, 14)) md.push(`- \`${c.value}\` ×${c.count}`);
+  md.push("");
+  md.push("_Framework/plugin CSS was ranked separately and excluded above — on a page built with a page-builder it repeats neutral greys far more often than the brand's own colours, so ranking everything together returns the framework's palette instead of the brand's._");
+  md.push("");
+  if (Object.keys(cssVars).length) {
+    md.push("## CSS custom properties (the author's own token names)");
+    md.push("");
+    for (const [k, v] of Object.entries(cssVars).slice(0, 40)) md.push(`- \`${k}: ${v}\``);
+    md.push("");
+  }
+  md.push("## Typography");
+  md.push("");
+  for (const f of families) md.push(`- family: \`${f.value}\` ×${f.count}`);
+  if (googleFonts.length) for (const g of googleFonts) md.push(`- Google Fonts: ${g}`);
+  md.push("");
+  md.push(`- size scale: ${fontSizes.map((s) => s.value).join(", ") || "(none found)"}`);
+  md.push(`- weights: ${weights.map((s) => s.value).join(", ") || "(none found)"}`);
+  md.push(`- line-heights: ${lineHeights.map((s) => s.value).join(", ") || "(none found)"}`);
+  md.push("");
+  md.push("## Rhythm and shape");
+  md.push("");
+  md.push(`- spacing values: ${spacing.slice(0, 12).map((s) => s.value).join(", ") || "(none)"}`);
+  md.push(`- radii: ${radii.map((s) => s.value).join(", ") || "(none)"}`);
+  md.push(`- shadows: ${shadows.slice(0, 4).map((s) => s.value).join(" | ") || "(none)"}`);
+  md.push(`- containers (max-width): ${containers.map((s) => s.value).join(", ") || "(none)"}`);
+  md.push(`- breakpoints: ${breakpoints.map((s) => s.value).join(", ") || "(none)"}`);
+  md.push(`- grid columns: ${gridCols.slice(0, 5).map((s) => s.value).join(" | ") || "(none)"}`);
+  if (usesTailwind) md.push("- utility framework: Tailwind-like classes detected — match the scale, not the class names");
+  md.push("");
+  md.push("## Page skeleton (shape only)");
+  md.push("");
+  if (spaShell) {
+    md.push("⚠ The HTML is a client-rendered shell — the section structure is not in the source.");
+    md.push("Open the page in a browser and record the section order visually before rebuilding.");
+  } else {
+    if (emptyWrappers) md.push(`_${emptyWrappers} empty layout wrappers dropped (page-builder nesting)._`);
+    md.push("");
+    md.push("| # | role | headings (level×words) | ¶ | list | img | video | btn | form | ~words |");
+    md.push("|---|---|---|---|---|---|---|---|---|---|");
+    for (const s of sections) {
+      const h = s.headings.map((x) => `h${x.level}×${x.words}w`).join(" ") || "—";
+      md.push(`| ${s.order} | ${s.role} | ${h} | ${s.paragraphs} | ${s.listItems} | ${s.images} | ${s.videos} | ${s.buttons} | ${s.forms} | ${s.approxWords} |`);
+    }
+  }
+  md.push("");
+  md.push("Heading **word counts** are given instead of the words themselves on purpose: match the rhythm and the information hierarchy, write your own lines.");
+  md.push("");
+  md.push("## Rebuild rules");
+  md.push("");
+  md.push("1. Use the palette, type scale, spacing and radii above verbatim — that is what makes it look as good as the original.");
+  md.push("2. Write every headline, paragraph and CTA fresh for the new business.");
+  md.push("3. Source media the client owns or licenses. Never hot-link the original site's images.");
+  md.push("4. Match the section ORDER and density, not the sentences.");
+  md.push("5. Run the pre-launch audit on the finished page too — a fresh build can still inherit a claim you typed from memory.");
+  md.push("");
+  fs.writeFileSync(path.join(OUT, "DESIGN-SYSTEM.md"), md.join("\n"));
+
+  const out = [];
+  out.push("");
+  out.push(`STYLE LANE — design system extracted from ${SRC}`);
+  out.push(`  palette: ${colors.length} colors    fonts: ${families.length}    sections: ${sections.length}${spaShell ? " (SPA shell — read structure in a browser)" : ""}`);
+  out.push(`  ${path.join(OUT, "DESIGN-SYSTEM.md")}`);
+  out.push(`  ${path.join(OUT, "design-tokens.json")}`);
+  out.push("");
+  out.push("  No bytes, images, video or copy were copied. Rebuild with original copy and licensed media.");
+  out.push("");
+  console.log(out.join("\n"));
+}
+
+main().catch((e) => {
+  console.error("extract-design failed:", e);
+  process.exit(1);
+});

package/skills/clone-site/scripts/lib.mjs

@@ -0,0 +1,262 @@
+/**
+ * Shared helpers for the clone-site scripts.
+ * Dependency-free: Node 20+ global fetch only. These scripts are installed to
+ * ~/.claude/skills/clone-site/scripts/ where no node_modules is available.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const ASSET_EXT = [
+  ".css", ".js", ".mjs",
+  ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".ico", ".avif", ".bmp",
+  ".mp4", ".webm", ".mov", ".m4v", ".ogg", ".mp3", ".wav",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".pdf", ".json",
+];
+
+const CONTENT_TYPE_FAMILY = {
+  ".css": "text/css",
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".png": "image/",
+  ".jpg": "image/",
+  ".jpeg": "image/",
+  ".webp": "image/",
+  ".gif": "image/",
+  ".svg": "image/",
+  ".ico": "image/",
+  ".avif": "image/",
+  ".bmp": "image/",
+  ".mp4": "video/",
+  ".webm": "video/",
+  ".mov": "video/",
+  ".m4v": "video/",
+  ".mp3": "audio/",
+  ".wav": "audio/",
+  ".ogg": "audio/",
+  ".woff": "font",
+  ".woff2": "font",
+  ".ttf": "font",
+  ".otf": "font",
+  ".eot": "font",
+  ".pdf": "application/pdf",
+  ".json": "json",
+};
+
+if (typeof fetch !== "function") {
+  console.error("clone-site needs Node 18 or newer (global fetch). Run `node --version` and upgrade.");
+  process.exit(1);
+}
+
+export const UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+export function ext(urlOrPath) {
+  const clean = String(urlOrPath).split("?")[0].split("#")[0];
+  const dot = clean.lastIndexOf(".");
+  const slash = clean.lastIndexOf("/");
+  if (dot === -1 || dot < slash) return "";
+  return clean.slice(dot).toLowerCase();
+}
+
+export function isAssetUrl(u) {
+  return ASSET_EXT.includes(ext(u));
+}
+
+/**
+ * Does the served content-type match what the extension promises?
+ * This is the soft-404 catcher: static hosts return 200 + HTML for a missing
+ * asset, so a status code proves nothing.
+ */
+export function contentTypeMatches(extension, contentType) {
+  const want = CONTENT_TYPE_FAMILY[extension];
+  if (!want) return true; // unknown extension — no opinion
+  const got = String(contentType || "").toLowerCase();
+  if (!got) return false;
+  if (want === "javascript") return got.includes("javascript") || got.includes("ecmascript");
+  if (want === "font") return got.includes("font") || got.includes("octet-stream");
+  if (want === "json") return got.includes("json");
+  return got.includes(want);
+}
+
+export async function fetchText(url, timeoutMs = 30000) {
+  const res = await fetchRaw(url, timeoutMs);
+  if (!res.ok) return { ok: false, status: res.status, text: "", contentType: res.contentType };
+  return { ok: true, status: res.status, text: res.buf.toString("utf8"), contentType: res.contentType };
+}
+
+export async function fetchRaw(url, timeoutMs = 60000) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      redirect: "follow",
+      signal: ctrl.signal,
+      headers: { "user-agent": UA, accept: "*/*" },
+    });
+    const buf = Buffer.from(await res.arrayBuffer());
+    return {
+      ok: res.ok,
+      status: res.status,
+      buf,
+      contentType: res.headers.get("content-type") || "",
+      finalUrl: res.url || url,
+    };
+  } catch (e) {
+    return { ok: false, status: 0, buf: Buffer.alloc(0), contentType: "", error: String(e && e.message ? e.message : e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function headSize(url, timeoutMs = 20000) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "HEAD",
+      redirect: "follow",
+      signal: ctrl.signal,
+      headers: { "user-agent": UA },
+    });
+    const len = res.headers.get("content-length");
+    return { ok: res.ok, status: res.status, bytes: len ? Number(len) : null, contentType: res.headers.get("content-type") || "" };
+  } catch {
+    return { ok: false, status: 0, bytes: null, contentType: "" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Run tasks with a small concurrency cap; order of results matches input. */
+export async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    for (;;) {
+      const i = next++;
+      if (i >= items.length) return;
+      out[i] = await fn(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+export function ensureDir(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+export function walk(root) {
+  const out = [];
+  const rec = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) rec(full);
+      else if (e.isFile()) out.push(full);
+    }
+  };
+  rec(root);
+  return out.sort();
+}
+
+export const TEXT_EXT = [".html", ".htm", ".css", ".js", ".mjs", ".json", ".txt", ".svg", ".xml", ".webmanifest"];
+
+export function isTextFile(file) {
+  return TEXT_EXT.includes(ext(file));
+}
+
+export function humanBytes(n) {
+  if (n === null || n === undefined) return "?";
+  const units = ["B", "KB", "MB", "GB"];
+  let v = Number(n);
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(v >= 10 || i === 0 ? 0 : 1)}${units[i]}`;
+}
+
+/** Minimal flag parser: --key value, --flag (boolean). */
+export function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const nextArg = argv[i + 1];
+    if (nextArg === undefined || nextArg.startsWith("--")) args[key] = true;
+    else {
+      args[key] = nextArg;
+      i++;
+    }
+  }
+  return args;
+}
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function writeJson(file, data) {
+  ensureDir(file);
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+/** Timestamp with no dependency on the caller's locale. */
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Run-directory layout. Reports NEVER live inside the deployable folder — a
+ * REVIEW-REQUIRED.md published on the live site would hand the world a list of
+ * the original owner's liabilities plus the user's rights declaration.
+ *
+ *   <run-dir>/site/      ← deploy THIS
+ *   <run-dir>/reports/   ← run-report.json, substitution-report.json, REVIEW-REQUIRED.md
+ */
+export function siteDir(runDir) {
+  return path.join(runDir, "site");
+}
+export function reportsDir(runDir) {
+  return path.join(runDir, "reports");
+}
+/** Accept either a run dir (has site/) or, for older runs, a bare site dir. */
+export function resolveRun(dir) {
+  const abs = path.resolve(dir);
+  if (fs.existsSync(path.join(abs, "site"))) return { runDir: abs, site: siteDir(abs), reports: reportsDir(abs) };
+  return { runDir: abs, site: abs, reports: abs, legacy: true };
+}
+
+export const RIGHTS_CHOICES = ["own", "client-authorized", "written-permission", "none"];
+
+export const RIGHTS_LABEL = {
+  own: "I own this site",
+  "client-authorized": "My client owns it and authorized the migration",
+  "written-permission": "I have written permission from the owner",
+  none: "None of these",
+};
+
+export const RIGHTS_QUESTION = `
+STEP 0 — rights declaration (required before any bytes are copied)
+
+  Who owns this page, or what permission do you have to copy it?
+
+    own                  ${RIGHTS_LABEL.own}
+    client-authorized    ${RIGHTS_LABEL["client-authorized"]}
+    written-permission   ${RIGHTS_LABEL["written-permission"]}
+    none                 ${RIGHTS_LABEL.none}
+
+  Pass it as --rights <value>. Your answer is recorded in the run report.
+  "none" is not a dead end — it routes to the style lane (extract-design.mjs),
+  which rebuilds on the real design system with your own copy and media.
+`.trim();