@elitedcs/ghl-mcp 3.56.0 → 3.58.0

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

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+/**
+ * mirror.mjs — deterministic site mirror. Copies bytes; never regenerates.
+ *
+ * GUARDRAIL: --rights is REQUIRED. Without it the script prints the step-0
+ * question and exits 2. With --rights none it refuses to copy bytes and points
+ * at the style lane (extract-design.mjs), exit 3. The declaration is written
+ * into run-report.json, which every downstream script reads.
+ *
+ * Usage:
+ *   node mirror.mjs --url <url> --out <dir> --rights <own|client-authorized|written-permission|none>
+ *                   [--declared "free-text note"] [--max-mb 25] [--no-external-media]
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  parseArgs, fetchRaw, fetchText, headSize, mapLimit, ensureDir, ext, isAssetUrl,
+  humanBytes, writeJson, nowIso, RIGHTS_CHOICES, RIGHTS_QUESTION, siteDir, reportsDir,
+} from "./lib.mjs";
+
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.url || !args.out) {
+  console.error("usage: mirror.mjs --url <url> --out <dir> --rights <own|client-authorized|written-permission|none>");
+  process.exit(1);
+}
+if (!args.rights || args.rights === true) {
+  console.error(RIGHTS_QUESTION);
+  process.exit(2);
+}
+if (!RIGHTS_CHOICES.includes(args.rights)) {
+  console.error(`Unknown --rights "${args.rights}". One of: ${RIGHTS_CHOICES.join(", ")}`);
+  process.exit(2);
+}
+if (args.rights === "none") {
+  console.error(
+    [
+      "RIGHTS = none — full byte-for-byte cloning is not the right lane here.",
+      "",
+      "Run the style lane instead. It extracts the page's real design system",
+      "(palette, type scale, spacing, section structure) so the rebuild matches",
+      "the original's quality, and you supply fresh copy and licensed media:",
+      "",
+      `  node extract-design.mjs --url "${args.url}" --out <dir>`,
+      "",
+      "No page bytes, images, video, or copy are copied in that lane.",
+    ].join("\n")
+  );
+  process.exit(3);
+}
+
+const SRC = args.url;
+const RUN_DIR = path.resolve(String(args.out));
+// site/ is the deployable folder; reports/ never ships with it.
+const OUT = siteDir(RUN_DIR);
+const REPORTS = reportsDir(RUN_DIR);
+const MAX_BYTES = Math.round(Number(args["max-mb"] || 25) * 1024 * 1024);
+const REHOST_EXTERNAL = args["no-external-media"] !== true;
+
+const srcUrl = new URL(SRC);
+const ORIGIN = srcUrl.origin;
+
+/**
+ * Cross-origin re-hosting covers MEDIA only. Third-party JS/CSS (analytics
+ * beacons, chat widgets, payment SDKs) stays external: re-hosting a loader
+ * breaks it, copies someone else's code, and hides it from the audit — those
+ * URLs must stay visible in the HTML so audit.mjs can flag them as MUST REPOINT.
+ */
+const REHOST_EXT = [
+  ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".ico", ".avif", ".bmp",
+  ".mp4", ".webm", ".mov", ".m4v", ".mp3", ".wav", ".ogg",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot", ".pdf",
+];
+const isRehostable = (u) => REHOST_EXT.includes(ext(u));
+
+fs.mkdirSync(OUT, { recursive: true });
+fs.mkdirSync(REPORTS, { recursive: true });
+
+/** absolute url -> { local, bytes, contentType, source, status } */
+const downloaded = new Map();
+const skipped = [];
+const oversized = [];
+const failed = [];
+const externalRefsLeft = new Set();
+
+function localPathFor(absUrl, kind) {
+  const u = new URL(absUrl);
+  if (u.origin === ORIGIN) {
+    const p = u.pathname.replace(/^\/+/, "");
+    return p || "index-asset";
+  }
+  // External CDN asset — re-host under media/<host-slug>/<path>
+  const hostSlug = u.hostname.replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+  const p = u.pathname.replace(/^\/+/, "") || "asset";
+  return path.posix.join("media", hostSlug, p);
+}
+
+async function download(absUrl, kind) {
+  if (downloaded.has(absUrl)) return downloaded.get(absUrl);
+  const e = ext(absUrl);
+  const head = await headSize(absUrl);
+  if (head.bytes !== null && head.bytes > MAX_BYTES) {
+    oversized.push({ url: absUrl, bytes: head.bytes, contentType: head.contentType });
+    return null;
+  }
+  const res = await fetchRaw(absUrl);
+  if (!res.ok || res.buf.length === 0) {
+    failed.push({ url: absUrl, status: res.status, error: res.error || null });
+    return null;
+  }
+  if (res.buf.length > MAX_BYTES) {
+    oversized.push({ url: absUrl, bytes: res.buf.length, contentType: res.contentType });
+    return null;
+  }
+  // A page-shaped body where an image belongs = the origin soft-404'd.
+  const looksHtml = /^\s*(<!doctype html|<html)/i.test(res.buf.slice(0, 200).toString("utf8"));
+  const wantsHtml = e === "" || e === ".html";
+  if (looksHtml && !wantsHtml) {
+    skipped.push({ url: absUrl, reason: "origin returned HTML where an asset was expected (asset does not exist / belongs to another tenant)" });
+    return null;
+  }
+  const local = localPathFor(absUrl, kind);
+  const dest = path.join(OUT, local);
+  ensureDir(dest);
+  fs.writeFileSync(dest, res.buf);
+  const rec = { local, bytes: res.buf.length, contentType: res.contentType, kind, status: res.status };
+  downloaded.set(absUrl, rec);
+  return rec;
+}
+
+function abs(ref, base) {
+  try {
+    return new URL(ref, base).toString();
+  } catch {
+    return null;
+  }
+}
+
+function skipRef(ref) {
+  return (
+    !ref ||
+    ref.startsWith("data:") ||
+    ref.startsWith("#") ||
+    ref.startsWith("mailto:") ||
+    ref.startsWith("tel:") ||
+    ref.startsWith("javascript:") ||
+    ref.startsWith("blob:")
+  );
+}
+
+/**
+ * URLs buried in JSON-encoded attributes and inline JSON — the miss that leaves
+ * a page-builder hero blank.
+ *
+ * Elementor background slideshows, WP block attributes, __NEXT_DATA__ and
+ * Shopify section JSON all store media as escaped JSON inside the markup:
+ *
+ *   data-settings="{&quot;url&quot;:&quot;https:\/\/host\/img.jpg&quot;}"
+ *
+ * The slashes are backslash-escaped and the quotes are entities, so neither the
+ * src/href scan nor a plain URL regex finds them. They are never downloaded —
+ * and once the domain is rebranded those URLs point at a domain that does not
+ * exist, so the hero renders empty. Live-caught 2026-07-30.
+ *
+ * Returns the raw matched text (escaping intact, so it can be rewritten in
+ * place) alongside the real absolute URL.
+ */
+function escapedJsonRefs(text) {
+  const mediaExt = "png|jpe?g|webp|gif|svg|avif|ico|bmp|mp4|webm|mov|m4v|mp3|wav|ogg|pdf";
+  const out = [];
+  const re = new RegExp(`https?:(?:\\\\?/){2}[^\\s"'<>]+?\\.(?:${mediaExt})`, "gi");
+  for (const m of text.matchAll(re)) {
+    const raw = m[0];
+    if (!raw.includes("\\/")) continue; // plain URLs are already handled elsewhere
+    out.push({ raw, abs: raw.replace(/\\\//g, "/") });
+  }
+  return out;
+}
+
+/** Refs in an HTML document: src, href, poster, srcset, inline url(). */
+function htmlRefs(html) {
+  const refs = new Set();
+  for (const m of html.matchAll(/(?:src|href|poster|data-src|content)=["']([^"']+)["']/gi)) refs.add(m[1]);
+  for (const m of html.matchAll(/srcset=["']([^"']+)["']/gi)) {
+    for (const part of m[1].split(",")) {
+      const u = part.trim().split(/\s+/)[0];
+      if (u) refs.add(u);
+    }
+  }
+  for (const m of html.matchAll(/url\(([^)]+)\)/gi)) refs.add(m[1].trim().replace(/^['"]|['"]$/g, ""));
+  return [...refs];
+}
+
+/** Refs inside a stylesheet. */
+function cssRefs(css) {
+  const refs = new Set();
+  for (const m of css.matchAll(/url\(([^)]+)\)/gi)) refs.add(m[1].trim().replace(/^['"]|['"]$/g, ""));
+  for (const m of css.matchAll(/@import\s+["']([^"']+)["']/gi)) refs.add(m[1]);
+  return [...refs];
+}
+
+/**
+ * Refs inside a JS bundle — the two forms HTML-only scanners miss:
+ *  1. full CDN URLs baked into the bundle
+ *  2. ROOT-RELATIVE paths ("/logo.png") — the one that caused 6 broken images
+ *     in the 2026-07-28 proving run.
+ */
+function jsRefs(js) {
+  const refs = new Set();
+  const mediaExt = "png|jpe?g|webp|gif|svg|avif|ico|bmp|mp4|webm|mov|m4v|mp3|wav|ogg|woff2?|ttf|otf|pdf";
+  for (const m of js.matchAll(new RegExp(`https?://[A-Za-z0-9._~:/?#\\[\\]@!$&'*+,;%=-]+?\\.(?:${mediaExt})`, "gi"))) {
+    refs.add(m[0]);
+  }
+  for (const m of js.matchAll(new RegExp(`["'\`](/[A-Za-z0-9._/-]+?\\.(?:${mediaExt}))["'\`]`, "gi"))) {
+    refs.add(m[1]);
+  }
+  return [...refs];
+}
+
+/** Replace every occurrence of `from` with `to`, literal (no regex surprises). */
+function replaceAllLiteral(text, from, to) {
+  if (!from || from === to) return text;
+  return text.split(from).join(to);
+}
+
+const log = (...m) => console.error(...m);
+
+/** Same-origin PAGE links (not assets, not feeds/admin endpoints). */
+function pageLinks(html, baseUrl) {
+  const out = new Set();
+  for (const m of html.matchAll(/href=["']([^"'#]+)["']/gi)) {
+    const href = m[1].trim();
+    if (/^(mailto:|tel:|javascript:|data:)/i.test(href)) continue;
+    let u;
+    try { u = new URL(href, baseUrl); } catch { continue; }
+    if (u.origin !== ORIGIN) continue;
+    const p = u.pathname;
+    if (/\.(png|jpe?g|webp|gif|svg|ico|avif|css|js|mjs|pdf|zip|xml|json|mp4|webm|mov|mp3|woff2?|ttf|otf)$/i.test(p)) continue;
+    if (/^\/wp-(json|admin|login|content|includes)|\/feed\/?$|\/comments\/feed/i.test(p)) continue;
+    out.add(canonPage(u.origin + p));
+  }
+  return [...out];
+}
+
+/** Canonical page key so "/x" and "/x/" (and the bare origin) are one page. */
+function canonPage(u) {
+  const x = new URL(u);
+  x.hash = ""; x.search = "";
+  const p = x.pathname.replace(/\/+$/, "");
+  return x.origin + (p || "/");
+}
+
+/** "/contact/" -> "contact/index.html"; "/" -> "index.html". */
+function pageSavePath(pageUrl) {
+  const p = new URL(pageUrl).pathname.replace(/^\/+|\/+$/g, "");
+  return p ? path.posix.join(p, "index.html") : "index.html";
+}
+
+const processedCss = new Set();
+const processedJs = new Set();
+
+/** Mirror ONE page: assets, escaped JSON, origin-localisation, write to disk. */
+async function mirrorPage(pageUrl) {
+  const page = await fetchText(pageUrl);
+  if (!page.ok || !page.text) {
+    failed.push({ url: pageUrl, status: page.status, error: "page fetch failed" });
+    return null;
+  }
+  let html = page.text;
+
+  // pass 1 — refs in this page's HTML
+  const pass1 = [];
+  for (const ref of htmlRefs(html)) {
+    if (skipRef(ref)) continue;
+    const a = abs(ref, pageUrl);
+    if (!a) continue;
+    const u = new URL(a);
+    if (!isAssetUrl(a)) {
+      if (u.origin !== ORIGIN) externalRefsLeft.add(a);
+      continue;
+    }
+    if (u.origin !== ORIGIN && (!REHOST_EXTERNAL || !isRehostable(a))) {
+      externalRefsLeft.add(a);
+      continue;
+    }
+    pass1.push({ ref, abs: a });
+  }
+  await mapLimit(pass1, 6, async (r) => download(r.abs, "html"));
+
+  // pass 2 — refs inside newly downloaded CSS
+  for (const [cssAbs, rec] of [...downloaded.entries()].filter(([u]) => ext(u) === ".css")) {
+    if (processedCss.has(cssAbs)) continue;
+    processedCss.add(cssAbs);
+    const file = path.join(OUT, rec.local);
+    let css = fs.readFileSync(file, "utf8");
+    const targets = [];
+    for (const ref of cssRefs(css).filter((r) => !skipRef(r))) {
+      const a = abs(ref, cssAbs);
+      if (!a || !isAssetUrl(a)) continue;
+      const u = new URL(a);
+      if (u.origin !== ORIGIN && (!REHOST_EXTERNAL || !isRehostable(a))) { externalRefsLeft.add(a); continue; }
+      targets.push({ ref, abs: a });
+    }
+    await mapLimit(targets, 6, async (t) => download(t.abs, "css"));
+    for (const t of targets) {
+      const got = downloaded.get(t.abs);
+      if (got) css = replaceAllLiteral(css, t.ref, "/" + got.local);
+    }
+    fs.writeFileSync(file, css);
+  }
+
+  // pass 3 — refs inside newly downloaded JS bundles
+  for (const [jsAbs, rec] of [...downloaded.entries()].filter(([u]) => [".js", ".mjs"].includes(ext(u)))) {
+    if (processedJs.has(jsAbs)) continue;
+    processedJs.add(jsAbs);
+    const file = path.join(OUT, rec.local);
+    let js = fs.readFileSync(file, "utf8");
+    const targets = [];
+    for (const ref of jsRefs(js)) {
+      const a = abs(ref, ORIGIN + "/");
+      if (!a) continue;
+      const u = new URL(a);
+      if (u.origin !== ORIGIN && (!REHOST_EXTERNAL || !isRehostable(a))) { externalRefsLeft.add(a); continue; }
+      targets.push({ ref, abs: a });
+    }
+    await mapLimit(targets, 6, async (t) => download(t.abs, "js"));
+    for (const t of targets) {
+      const got = downloaded.get(t.abs);
+      if (got && t.ref !== "/" + got.local) js = replaceAllLiteral(js, t.ref, "/" + got.local);
+    }
+    fs.writeFileSync(file, js);
+  }
+
+  // pass 4 — URLs hidden in escaped JSON attributes
+  {
+    const unique = new Map();
+    for (const r of escapedJsonRefs(html)) if (!unique.has(r.abs)) unique.set(r.abs, r);
+    const targets = [];
+    for (const [absUrl, r] of unique) {
+      const u = new URL(absUrl);
+      if (u.origin !== ORIGIN && (!REHOST_EXTERNAL || !isRehostable(absUrl))) { externalRefsLeft.add(absUrl); continue; }
+      targets.push(r);
+    }
+    await mapLimit(targets, 6, async (t) => download(t.abs, "json-attr"));
+    for (const t of targets) {
+      const got = downloaded.get(t.abs);
+      if (got) html = replaceAllLiteral(html, t.raw, ("/" + got.local).replace(/\//g, "\\/"));
+    }
+  }
+
+  // localise same-origin ASSET urls (plain + escaped), incl. inline JS config
+  {
+    const ASSET_DIR = /\/(?:wp-content|wp-includes|assets|static|_next|dist|build|media|uploads|files|cdn)\//i;
+    const originForms = [...new Set([ORIGIN, ORIGIN.replace(/^https:/, "http:"), ORIGIN.replace(/^http:/, "https:")])];
+    for (const form of originForms) {
+      for (const needle of [form, form.replace(/\//g, "\\/")]) {
+        let idx = html.indexOf(needle);
+        while (idx !== -1) {
+          const after = html.slice(idx + needle.length, idx + needle.length + 300);
+          const stop = after.search(/["'\s<>)]|\\"/);
+          const tail = (stop === -1 ? after : after.slice(0, stop)).replace(/\\\//g, "/");
+          if (tail && (ASSET_DIR.test(tail) || isAssetUrl(tail))) {
+            html = html.slice(0, idx) + html.slice(idx + needle.length);
+            idx = html.indexOf(needle, idx);
+          } else {
+            idx = html.indexOf(needle, idx + needle.length);
+          }
+        }
+      }
+    }
+  }
+
+  // rewrite this page's own asset refs to local paths
+  for (const { ref, abs: a } of pass1) {
+    const got = downloaded.get(a);
+    if (!got) continue;
+    const localRef = "/" + got.local;
+    if (ref !== localRef) html = replaceAllLiteral(html, ref, localRef);
+  }
+
+  // <a href> to our own pages -> root-relative, so the nav works locally AND
+  // after deploy. canonical/og:url keep their host so the rebrand can set the
+  // client's real domain.
+  const hostPattern = ORIGIN.replace(/^https?:\/\//, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  html = html.replace(new RegExp(`(<a\\b[^>]*?href=["'])https?://(?:www\\.)?${hostPattern}`, "gi"), "$1");
+
+  const savedAs = pageSavePath(pageUrl);
+  const dest = path.join(OUT, savedAs);
+  ensureDir(dest);
+  fs.writeFileSync(dest, html);
+  return { savedAs, links: pageLinks(page.text, pageUrl) };
+}
+
+async function main() {
+  const CRAWL = args.crawl === true || args.pages !== undefined || args.depth !== undefined;
+  const MAX_PAGES = Number(args["max-pages"] || args.pages || 25);
+  const DEPTH = Number(args.depth || 1);
+
+  const queue = [{ url: SRC, depth: 0 }];
+  const seen = new Set([canonPage(SRC)]);
+  const pages = [];
+
+  while (queue.length && pages.length < (CRAWL ? MAX_PAGES : 1)) {
+    const { url, depth } = queue.shift();
+    log(`→ ${url}`);
+    const res = await mirrorPage(url);
+    if (!res) continue;
+    pages.push({ url, savedAs: res.savedAs });
+    if (!CRAWL || depth >= DEPTH) continue;
+    for (const link of res.links) {
+      const key = canonPage(link);
+      if (seen.has(key) || seen.size >= MAX_PAGES * 4) continue;
+      seen.add(key);
+      queue.push({ url: link, depth: depth + 1 });
+    }
+  }
+
+  if (pages.length === 0) {
+    console.error(`FAILED to fetch ${SRC}. Nothing was written — do not reconstruct the page from memory.`);
+    process.exit(4);
+  }
+  // Guarantee a root document even when the entry URL was a sub-page.
+  if (!fs.existsSync(path.join(OUT, "index.html"))) {
+    fs.copyFileSync(path.join(OUT, pages[0].savedAs), path.join(OUT, "index.html"));
+  }
+
+  const byType = {};
+  let totalBytes = 0;
+  for (const rec of downloaded.values()) {
+    const e = ext(rec.local) || "(none)";
+    byType[e] = byType[e] || { count: 0, bytes: 0 };
+    byType[e].count++; byType[e].bytes += rec.bytes; totalBytes += rec.bytes;
+  }
+
+  const report = {
+    tool: "clone-site/mirror.mjs",
+    generatedAt: nowIso(),
+    rights: {
+      declaration: args.rights,
+      note: typeof args.declared === "string" ? args.declared : null,
+      recordedBy: "user declaration at step 0 — this tool does not verify ownership",
+    },
+    source: { url: SRC, origin: ORIGIN },
+    output: { runDir: RUN_DIR, siteDir: OUT, reportsDir: REPORTS, entry: "index.html" },
+    pages,
+    crawl: { enabled: CRAWL, depth: CRAWL ? DEPTH : 0, maxPages: CRAWL ? MAX_PAGES : 1, discovered: seen.size },
+    inventory: { files: downloaded.size + pages.length, totalBytes, totalHuman: humanBytes(totalBytes), byType },
+    oversized,
+    skippedForeignOrMissing: skipped,
+    failed,
+    externalRefsLeft: [...externalRefsLeft].sort(),
+    assets: [...downloaded.entries()].map(([url, rec]) => ({ url, ...rec })),
+  };
+  writeJson(path.join(REPORTS, "run-report.json"), report);
+
+  const lines = [];
+  lines.push("");
+  lines.push(`MIRROR COMPLETE  ${SRC}`);
+  lines.push(`  rights declared : ${args.rights}${args.declared && args.declared !== true ? ` — "${args.declared}"` : ""}`);
+  lines.push(`  pages mirrored  : ${pages.length}${CRAWL ? ` (crawl depth ${DEPTH}, cap ${MAX_PAGES}, ${seen.size} discovered)` : " — single page. Add --crawl to follow the site's own navigation."}`);
+  for (const p of pages.slice(0, 15)) lines.push(`      ${p.savedAs}`);
+  if (pages.length > 15) lines.push(`      …and ${pages.length - 15} more`);
+  lines.push(`  deployable site : ${OUT}`);
+  lines.push(`  reports (never deploy these): ${REPORTS}/`);
+  lines.push(`  files stored    : ${downloaded.size + pages.length}  (${humanBytes(totalBytes)})`);
+  const typeLine = Object.entries(byType).sort((a, b) => b[1].count - a[1].count).map(([e, v]) => `${e} ${v.count}`).join("  ");
+  if (typeLine) lines.push(`  by type         : ${typeLine}`);
+  if (oversized.length) {
+    lines.push(`  OVERSIZED (>${args["max-mb"] || 25}MB, NOT downloaded — route to R2/Stream): ${oversized.length}`);
+    for (const o of oversized.slice(0, 10)) lines.push(`      ${humanBytes(o.bytes)}  ${o.url}`);
+  }
+  if (skipped.length) lines.push(`  EXCLUDED (origin served HTML — missing or another tenant's asset): ${skipped.length}`);
+  if (failed.length) {
+    lines.push(`  FAILED to fetch: ${failed.length}`);
+    for (const f of failed.slice(0, 10)) lines.push(`      [${f.status}] ${f.url}`);
+  }
+  if (externalRefsLeft.size) lines.push(`  third-party refs left as-is (fonts/analytics/SDKs): ${externalRefsLeft.size}`);
+  lines.push("");
+  lines.push(`  run report: ${path.join(REPORTS, "run-report.json")}`);
+  lines.push(`  NEXT: substitute.mjs --dir ${RUN_DIR} (plan) → audit.mjs → render+repair.mjs → deploy site/ → verify.mjs`);
+  lines.push("");
+  console.log(lines.join("\n"));
+}
+
+main().catch((e) => {
+  console.error("mirror failed:", e);
+  process.exit(1);
+});

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * repair.mjs — fetch assets the clone only asks for AT RUNTIME.
+ *
+ * Static scanning cannot see a URL that JavaScript builds on the fly. The
+ * common case is webpack lazy chunks: a page-builder stores a base path plus a
+ * chunk→hash map and concatenates them at runtime, so the filename exists in no
+ * attribute, stylesheet or literal string. Those files are never mirrored, and
+ * after rebranding they resolve against a domain that does not exist.
+ *
+ * Live-caught 2026-07-30: six Elementor handler chunks 503'd on a rebranded
+ * clone. `section-frontend-handlers` is what paints section backgrounds — with
+ * it missing the hero rendered blank and white headline text sat on white, so
+ * the "byte-for-byte" clone looked nothing like the original. Nothing in the
+ * file-level checks could see it; only loading the page could.
+ *
+ * The loop: render the clone → capture failed requests → repair → render again,
+ * until nothing fails.
+ *
+ * Usage:
+ *   node repair.mjs --dir <run-dir> --origin https://original.example --urls failed.txt
+ *   node repair.mjs --dir <run-dir> --origin https://original.example --url "/path/a.js" --url "/path/b.js"
+ *
+ * `failed.txt` is one URL or path per line; the clone's own host is stripped, so
+ * you can paste what the browser reported verbatim.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseArgs, fetchRaw, mapLimit, ensureDir, ext, humanBytes, readJson, writeJson, nowIso, resolveRun } from "./lib.mjs";
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.dir || !args.origin) {
+  console.error("usage: repair.mjs --dir <run-dir> --origin <original-site-url> (--urls failed.txt | --url <path> ...)");
+  process.exit(1);
+}
+const RUN = resolveRun(String(args.dir));
+const SITE = RUN.site;
+const REPORTS = RUN.reports;
+const ORIGIN = String(args.origin).replace(/\/+$/, "");
+
+// Collect the failing references.
+const raw = [];
+if (args.urls && args.urls !== true) {
+  raw.push(...fs.readFileSync(path.resolve(String(args.urls)), "utf8").split(/\r?\n/));
+}
+const single = process.argv.reduce((acc, a, i, arr) => (a === "--url" && arr[i + 1] ? [...acc, arr[i + 1]] : acc), []);
+raw.push(...single);
+
+/** Reduce anything the browser reported to an origin-relative path. */
+function toPath(entry) {
+  let v = String(entry).trim();
+  if (!v || v.startsWith("#")) return null;
+  if (/^chrome-extension:/i.test(v)) return null; // the user's own extensions
+  if (/^https?:\/\//i.test(v)) {
+    try {
+      v = new URL(v).pathname + new URL(v).search;
+    } catch {
+      return null;
+    }
+  }
+  if (!v.startsWith("/")) v = "/" + v;
+  return v;
+}
+
+const paths = [...new Set(raw.map(toPath).filter(Boolean))];
+if (paths.length === 0) {
+  console.error("No usable URLs given. Pass --urls <file> or one or more --url <path>.");
+  process.exit(1);
+}
+
+const results = await mapLimit(paths, 6, async (p) => {
+  const clean = p.split("?")[0];
+  const local = clean.replace(/^\/+/, "");
+  const dest = path.join(SITE, local);
+  if (fs.existsSync(dest)) return { path: p, status: "already present" };
+
+  const res = await fetchRaw(ORIGIN + p);
+  if (!res.ok || res.buf.length === 0) {
+    return { path: p, status: `FAILED (${res.status}${res.error ? " " + res.error : ""})` };
+  }
+  const looksHtml = /^\s*(<!doctype html|<html)/i.test(res.buf.slice(0, 200).toString("utf8"));
+  if (looksHtml && ![".html", ".htm", ""].includes(ext(clean))) {
+    return { path: p, status: "SKIPPED — origin served HTML (the file does not exist there either)" };
+  }
+  ensureDir(dest);
+  fs.writeFileSync(dest, res.buf);
+  return { path: p, status: "repaired", bytes: res.buf.length, local };
+});
+
+const repaired = results.filter((r) => r.status === "repaired");
+const failed = results.filter((r) => String(r.status).startsWith("FAILED"));
+const skipped = results.filter((r) => String(r.status).startsWith("SKIPPED"));
+const present = results.filter((r) => r.status === "already present");
+
+// Record the repair in the run's reports so the audit can mention it.
+const file = path.join(REPORTS, "repair-report.json");
+let prior = [];
+try { prior = readJson(file).runs || []; } catch {}
+writeJson(file, { runs: [...prior, { at: nowIso(), origin: ORIGIN, results }] });
+
+const out = [];
+out.push("");
+out.push(`RUNTIME REPAIR  ${ORIGIN}`);
+out.push(`  requested: ${paths.length}   repaired: ${repaired.length}   already present: ${present.length}   skipped: ${skipped.length}   failed: ${failed.length}`);
+for (const r of repaired) out.push(`      + ${humanBytes(r.bytes)}  ${r.local}`);
+for (const r of skipped) out.push(`      · ${r.path} — ${r.status}`);
+for (const r of failed) out.push(`      ! ${r.path} — ${r.status}`);
+out.push("");
+out.push("  These files are only requested once the page RUNS, so re-render the clone and capture");
+out.push("  failed requests again. Repeat until nothing fails — one repair pass often reveals the next.");
+out.push("");
+console.log(out.join("\n"));