@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless-replatform/scripts/lib/layout-blueprint/geometry.mjs

@@ -0,0 +1,43 @@
+export function round(value, precision = 3) {
+  const factor = 10 ** precision;
+  return Math.round(Number(value || 0) * factor) / factor;
+}
+
+export function normalizedRect(rect, frame) {
+  if (!rect || !frame) return null;
+  return {
+    x: round((Number(rect.left ?? rect.x) - Number(frame.left ?? frame.x ?? 0)) / Math.max(Number(frame.width), 1)),
+    y: round((Number(rect.top ?? rect.y) - Number(frame.top ?? frame.y ?? 0)) / Math.max(Number(frame.height), 1)),
+    width: round(Number(rect.width) / Math.max(Number(frame.width), 1)),
+    height: round(Number(rect.height) / Math.max(Number(frame.height), 1)),
+  };
+}
+
+export function placementFor(rect) {
+  if (!rect) return "center";
+  const centerX = Number(rect.x) + (Number(rect.width) / 2);
+  const centerY = Number(rect.y) + (Number(rect.height) / 2);
+  const horizontal = centerX < 0.38 ? "left" : centerX > 0.62 ? "right" : "center";
+  const vertical = centerY < 0.38 ? "top" : centerY > 0.62 ? "bottom" : "center";
+  return vertical === "center" && horizontal === "center" ? "center" : `${vertical}-${horizontal}`;
+}
+
+export function overlapRatio(first, second) {
+  if (!first || !second) return 0;
+  const left = Math.max(first.x, second.x);
+  const top = Math.max(first.y, second.y);
+  const right = Math.min(first.x + first.width, second.x + second.width);
+  const bottom = Math.min(first.y + first.height, second.y + second.height);
+  if (right <= left || bottom <= top) return 0;
+  const intersection = (right - left) * (bottom - top);
+  return round(intersection / Math.max(Math.min(first.width * first.height, second.width * second.height), 0.0001));
+}
+
+export function horizontalRelation(first, second) {
+  if (!first || !second) return "unknown";
+  const gap = 0.025;
+  if (first.x + first.width + gap <= second.x) return "before";
+  if (second.x + second.width + gap <= first.x) return "after";
+  return "overlap";
+}
+

package/skills/wix-headless-replatform/scripts/lib/layout-blueprint/vocabulary.mjs

@@ -0,0 +1,18 @@
+export const LAYOUT_VOCABULARY_VERSION = 2;
+
+export const VOCABULARY = Object.freeze({
+  composition: ["layered-overlay", "split", "stack", "grid", "rail", "scroll-narrative", "freeform"],
+  canvasWidth: ["full-bleed", "bounded"],
+  canvasHeight: ["viewport", "content", "fixed-ratio", "scroll-driven"],
+  backgroundKind: ["none", "color", "gradient", "image", "video", "composite"],
+  container: ["full", "bounded"],
+  regionRole: ["heading", "body-copy", "media", "action", "tabs", "tab", "navigation", "content"],
+  placement: [
+    "top-left", "top-center", "top-right",
+    "center-left", "center", "center-right",
+    "bottom-left", "bottom-center", "bottom-right",
+  ],
+  layerRole: ["base", "media", "scrim", "decoration", "content"],
+  mediaFit: ["cover", "contain", "fill", "natural"],
+  textWrapPolicy: ["single-line", "wrapped", "clipped-or-overflowing"],
+});

package/skills/wix-headless-replatform/scripts/lib/ui-normalization.css

@@ -0,0 +1,64 @@
+/* @generated-source wix-headless-replatform */
+/* Identity-neutral layout and motion primitives. Source tokens always win. */
+
+[data-rp-layout="horizontal-card-rail"] [data-rp-track],
+[data-rp-layout="card-grid"] {
+  align-items: stretch;
+}
+
+[data-rp-equal-height="true"] [data-rp-item] {
+  height: var(--rp-item-block-size);
+  min-height: var(--rp-item-block-size);
+  max-height: var(--rp-item-block-size);
+}
+
+[data-rp-item] [data-rp-media] {
+  min-width: 0;
+  overflow: hidden;
+}
+
+[data-rp-item] [data-rp-media] > :is(img, video, iframe) {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+[data-rp-item] [data-rp-body] {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+}
+
+[data-rp-item] [data-rp-action] {
+  margin-block-start: auto;
+}
+
+[data-rp-motion="micro"] {
+  transition-duration: var(--rp-micro-duration, 180ms);
+  transition-timing-function: var(--rp-motion-easing, cubic-bezier(0.2, 0, 0, 1));
+}
+
+[data-rp-motion="state"] {
+  transition-duration: var(--rp-state-duration, 360ms);
+  transition-timing-function: var(--rp-motion-easing, cubic-bezier(0.2, 0, 0, 1));
+}
+
+[data-rp-layout] :focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 3px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-rp-motion],
+  [data-rp-layout] *,
+  [data-rp-layout] *::before,
+  [data-rp-layout] *::after {
+    scroll-behavior: auto !important;
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}

package/skills/wix-headless-replatform/scripts/optimize-svg.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { parseArgs } from "./lib/common.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const file = args._[0] || args.file;
+  if (!file) throw new Error("Usage: optimize-svg.mjs <file.svg>");
+  const optimized = await optimizeSvg(await readFile(file, "utf8"));
+  if (args.stdout) process.stdout.write(optimized);
+  else await writeFile(args.out || file, optimized, "utf8");
+}
+
+export async function optimizeSvg(svg) {
+  try {
+    const { optimize } = await import("svgo");
+    return optimize(svg, { multipass: true }).data;
+  } catch {
+    return svg
+      .replace(/<!--[\s\S]*?-->/g, "")
+      .replace(/>\s+</g, "><")
+      .trim();
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/skills/wix-headless-replatform/scripts/post-build-gap.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readdir, readFile, rm } from "node:fs/promises";
+import {
+  docsDir,
+  ensureDir,
+  isAssetLikeUrl,
+  normalizeUrl,
+  parseArgs,
+  readJson,
+  resolveOutputDir,
+  slugForUrl,
+  writeJson,
+  writeText,
+} from "./lib/common.mjs";
+import { ensureBrowserExtractionReady } from "./lib/browser-tooling.mjs";
+import { extractPage } from "./extract-page.mjs";
+import { extractAssets } from "./extract-assets.mjs";
+import { extractInteractions } from "./extract-interactions.mjs";
+import { extractSeoForUrl } from "./extract-seo.mjs";
+import { extractDesignSystem } from "./extract-design-system.mjs";
+import { generateSceneContract } from "./generate-scene-contract.mjs";
+import { generateControlStateContract } from "./generate-control-state-contract.mjs";
+import { generateVisualAssets } from "./generate-visual-assets.mjs";
+import { generateLayoutBlueprint } from "./generate-layout-blueprint.mjs";
+import { generateUiNormalization } from "./generate-ui-normalization.mjs";
+import { analyzeGapEvidence, renderGapAnalysisMarkdown, renderGapFixPlan } from "./lib/gap-analysis.mjs";
+
+export const MAX_GAP_CYCLES = 5;
+
+async function main() {
+  const args = parseArgs();
+  const sourceUrl = normalizeUrl(args._[0] || args.url).toString();
+  const resultUrlValue = args["result-url"] || args["clone-url"];
+  if (!resultUrlValue) throw new Error("Missing --result-url for the running clone, for example http://localhost:4321/");
+  const paths = String(args.paths || "").split(",").map((value) => value.trim()).filter(Boolean);
+  const outputDir = resolveOutputDir(sourceUrl, args.out);
+  const report = await runPostBuildGap({
+    sourceUrl,
+    resultUrl: normalizeUrl(resultUrlValue).toString(),
+    outputDir,
+    screenshots: args.screenshots !== "false",
+    designExtractor: args["design-extractor"],
+    paths,
+  });
+  if (args.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else console.log(`[gap-analysis] iteration ${String(report.iteration).padStart(3, "0")}: score ${report.summary.score}/100, ${report.summary.blockingCount} blocking gap(s), visual review ${report.visualReview.status}`);
+}
+
+export async function runPostBuildGap({ sourceUrl, resultUrl, outputDir, screenshots = true, designExtractor, browserTooling, paths = [] } = {}) {
+  if (!sourceUrl || !resultUrl || !outputDir) throw new Error("sourceUrl, resultUrl, and outputDir are required");
+  const canonicalDocs = docsDir(outputDir);
+  const frozenSource = await loadFrozenSourceEvidence(canonicalDocs);
+  const canonicalSourceMap = sanitizeSourceMap(frozenSource.evidence.sourceMap);
+  const sourceMap = structuredClone(canonicalSourceMap);
+  const selectedPaths = [...new Set(paths.map((value) => new URL(value, sourceUrl).pathname.replace(/\/$/, "") || "/"))];
+  if (selectedPaths.length) {
+    sourceMap.pages = (sourceMap.pages || []).filter((page) => selectedPaths.includes(new URL(page.url).pathname.replace(/\/$/, "") || "/"));
+    if (!sourceMap.pages.length) throw new Error(`No source-map pages matched --paths ${selectedPaths.join(", ")}`);
+  }
+  const gapRoot = path.join(canonicalDocs, "gap-analysis");
+  const previousReport = await readPreviousReport(gapRoot);
+  const iteration = await nextIteration(gapRoot);
+  const iterationDir = path.join(gapRoot, "iterations", String(iteration).padStart(3, "0"));
+  const resultOutputDir = path.join(iterationDir, "result-extraction");
+  const sourceEvidence = frozenSource.evidence;
+  sourceEvidence.sourceMap = sourceMap;
+  const sourceEvidenceReference = {
+    root: frozenSource.extractionDir,
+    fingerprint: frozenSource.manifest.manifestHash,
+    mode: "frozen-manifest-reference",
+  };
+  await ensureDir(iterationDir);
+  await writeJson(path.join(iterationDir, "iteration-manifest.json"), {
+    iteration,
+    sourceUrl,
+    resultUrl,
+    paths: selectedPaths,
+    sourceEvidence: sourceEvidenceReference,
+    status: "extracting",
+    startedAt: new Date().toISOString(),
+  });
+
+  const tooling = browserTooling || await ensureBrowserExtractionReady({ startDir: process.cwd() });
+  const resultEvidence = await extractResultEvidence({
+    sourceMap,
+    sourceUrl,
+    resultUrl,
+    resultOutputDir,
+    screenshots,
+    designExtractor: designExtractor || sourceMap.designExtraction?.selectedExtractor || "auto",
+    browserTooling: tooling,
+  });
+  await attachScreenshotMetadata(sourceEvidence);
+  await attachScreenshotMetadata(resultEvidence);
+  const report = analyzeGapEvidence({ source: sourceEvidence, result: resultEvidence, iteration });
+  report.sourceEvidence = sourceEvidenceReference;
+  report.visualProgress = buildVisualProgressRequirement({ previousReport, report });
+  report.paths = {
+    iterationDir,
+    sourceEvidence: canonicalDocs,
+    resultExtraction: docsDir(resultOutputDir),
+    reportJson: path.join(iterationDir, "gap-analysis.json"),
+    reportMarkdown: path.join(iterationDir, "gap-analysis.md"),
+    fixPlan: path.join(iterationDir, "gap-fix-plan.md"),
+    visualProgress: path.join(iterationDir, "visual-progress.json"),
+  };
+  if (report.visualProgress.required) await writeJson(report.paths.visualProgress, visualProgressTemplate({ report, previousReport }));
+  await writeJson(report.paths.reportJson, report);
+  await writeText(report.paths.reportMarkdown, renderGapAnalysisMarkdown(report));
+  await writeText(report.paths.fixPlan, renderGapFixPlan(report));
+  await writeJson(path.join(gapRoot, "latest.json"), report);
+  await writeText(path.join(gapRoot, "latest.md"), renderGapAnalysisMarkdown(report));
+  await writeJson(path.join(iterationDir, "iteration-manifest.json"), {
+    iteration,
+    sourceUrl,
+    resultUrl,
+    status: "comparison-complete-visual-review-pending",
+    startedAt: report.generatedAt,
+    completedAt: new Date().toISOString(),
+    score: report.summary.score,
+    blockingCount: report.summary.blockingCount,
+    sourceEvidence: sourceEvidenceReference,
+    visualProgress: report.visualProgress,
+  });
+  return report;
+}
+
+async function extractResultEvidence({ sourceMap, sourceUrl, resultUrl, resultOutputDir, screenshots, designExtractor, browserTooling }) {
+  await rm(resultOutputDir, { recursive: true, force: true });
+  const resultDocs = docsDir(resultOutputDir);
+  const pagesDir = path.join(resultDocs, "pages");
+  const screenshotsDir = path.join(resultDocs, "screenshots");
+  await ensureDir(pagesDir);
+  const pages = [];
+  for (const [index, sourcePage] of (sourceMap.pages || []).entries()) {
+    const comparisonPath = pagePath(sourcePage.url, sourceUrl, index);
+    const targetUrl = resultPageUrl(resultUrl, comparisonPath);
+    console.log(`[gap-analysis] extracting result page ${targetUrl}`);
+    const page = await extractPage(targetUrl, {
+      outputDir: resultOutputDir,
+      screenshots,
+      browserTooling,
+      screenshotDir: screenshotsDir,
+      screenshotPrefix: "result",
+    });
+    page.comparisonPath = comparisonPath;
+    page.sourceComparisonUrl = sourcePage.url;
+    pages.push(page);
+    await writeJson(path.join(pagesDir, `${String(index + 1).padStart(3, "0")}-${slugForUrl(targetUrl)}.json`), page);
+  }
+
+  const [seo, assets] = await Promise.all([
+    extractSeoForUrl(resultUrl),
+    extractAssets(resultUrl, { outputDir: resultOutputDir, download: false }),
+  ]);
+  await writeJson(path.join(resultDocs, "seo.json"), seo);
+  await writeJson(path.join(resultDocs, "assets.json"), assets);
+  await writeJson(path.join(resultDocs, "fonts.json"), assets.fonts);
+
+  const interactionMap = await extractInteractions(resultUrl, { outputDir: resultOutputDir, pages, browserTooling });
+  const enrichedPages = interactionMap.pages?.length ? interactionMap.pages : pages;
+  for (const page of enrichedPages) page.comparisonPath ||= pagePath(page.sourceComparisonUrl || page.url, sourceUrl);
+  await writeJson(path.join(resultDocs, "interaction-map.json"), interactionMap);
+  const resultMap = {
+    sourceUrl: resultUrl,
+    comparisonSourceUrl: sourceUrl,
+    normalizedAt: new Date().toISOString(),
+    scope: sourceMap.scope,
+    pages: enrichedPages,
+    assets: assets.assets,
+    fonts: { families: assets.fonts?.families || [], faceCount: assets.fonts?.faces?.length || 0 },
+    interactions: interactionMap.summary || {},
+    seo,
+    tokens: {},
+    extractionRole: "post-build-result",
+  };
+  await writeJson(path.join(resultDocs, "source-map.json"), resultMap);
+
+  console.log("[gap-analysis] extracting result design system and derived contracts");
+  const designSystem = await extractDesignSystem({ sourceUrl: resultUrl, outputDir: resultOutputDir, extractor: designExtractor, browserTooling });
+  resultMap.tokens = designSystem.tokens;
+  resultMap.designExtraction = {
+    selectedExtractor: designSystem.selectedExtractor,
+    actualExtractor: designSystem.actualExtractor || designSystem.extractor,
+    fallbackReason: designSystem.fallbackReason,
+  };
+  await writeJson(path.join(resultDocs, "tokens.json"), designSystem.tokens);
+  await writeJson(path.join(resultDocs, "source-map.json"), resultMap);
+  const sceneContract = await generateSceneContract({ outputDir: resultOutputDir, pages: enrichedPages, interactionMap });
+  await generateControlStateContract({ outputDir: resultOutputDir, interactionMap });
+  await generateVisualAssets({ outputDir: resultOutputDir, pages: enrichedPages, assets });
+  const layoutBlueprint = await generateLayoutBlueprint({ outputDir: resultOutputDir, pages: enrichedPages, interactionMap, sceneContract });
+  await generateUiNormalization({ outputDir: resultOutputDir, pages: enrichedPages, interactionMap, sceneContract, layoutBlueprint });
+  return loadEvidence(resultDocs);
+}
+
+async function readPreviousReport(gapRoot) {
+  try { return await readJson(path.join(gapRoot, "latest.json")); } catch { return null; }
+}
+
+function buildVisualProgressRequirement({ previousReport, report }) {
+  const previousBlocking = (previousReport?.findings || []).filter((finding) => ["critical", "high"].includes(finding.severity) && finding.status !== "resolved" && finding.status !== "accepted");
+  return {
+    required: previousBlocking.length > 0,
+    status: previousBlocking.length ? "pending" : "not-applicable",
+    previousIteration: previousBlocking.length ? previousReport.iteration : null,
+    previousReportPath: previousBlocking.length ? previousReport.paths?.reportJson || null : null,
+    previousBlockingFindingIds: previousBlocking.map((finding) => finding.id),
+    instructions: "For every prior blocking finding, record a named target section and exact source, before-result, and after-result screenshots. A claimed resolution requires verdict improved.",
+  };
+}
+
+function visualProgressTemplate({ report, previousReport }) {
+  const prior = report.visualProgress.previousBlockingFindingIds;
+  const pairs = new Map((report.screenshotPairs || []).map((pair) => [pair.id, pair]));
+  const priorPairs = new Map((previousReport?.screenshotPairs || []).map((pair) => [pair.id, pair]));
+  return {
+    entries: prior.map((findingId) => ({
+      priorFindingId: findingId,
+      target: "Name the affected section or interaction state.",
+      pairId: "Choose the matching screenshot pair ID.",
+      sourceScreenshotPath: "Copy the source path for that pair.",
+      beforeResultScreenshotPath: "Copy the result path from the prior iteration for that pair.",
+      afterResultScreenshotPath: "Copy the result path from this iteration for that pair.",
+      beforeObservation: "Describe the visible pre-fix mismatch.",
+      afterObservation: "Describe what is visibly closer, unchanged, or worse.",
+      verdict: "improved",
+      evidence: "State the visible relationship being judged; do not cite only a score or code change.",
+    })),
+    _templateNote: `Use the source and before/after paths from the matching pair. Current pair IDs: ${[...pairs.keys()].join(", ") || "none"}. Prior pair IDs: ${[...priorPairs.keys()].join(", ") || "available in the prior report"}.`,
+  };
+}
+
+function sanitizeSourceMap(sourceMap) {
+  const sanitized = structuredClone(sourceMap || {});
+  const pages = Array.isArray(sanitized.pages) ? sanitized.pages : [];
+  sanitized.pages = pages.filter((page) => page?.url && !isAssetLikeUrl(page.url));
+  return sanitized;
+}
+
+async function loadEvidence(dir) {
+  const read = async (name, fallback) => {
+    try { return await readJson(path.join(dir, name)); } catch { return fallback; }
+  };
+  return {
+    root: dir,
+    sourceMap: await read("source-map.json", { pages: [] }),
+    assets: await read("assets.json", { assets: [] }),
+    seo: await read("seo.json", {}),
+    interactionMap: await read("interaction-map.json", { interactions: [] }),
+    sceneContract: await read("scene-contract.json", { scenes: [] }),
+    controlStateContract: await read("control-state-contract.json", { controls: [] }),
+    visualAssets: await read("visual-assets.json", { logos: [], icons: [] }),
+    layoutBlueprint: await read("layout-blueprint.json", { pages: [] }),
+    uiNormalization: await read("ui-normalization.json", { sections: [] }),
+    tokens: await read("tokens.json", {}),
+  };
+}
+
+async function loadFrozenSourceEvidence(canonicalDocs) {
+  const latest = await readJson(path.join(canonicalDocs, "extraction", "latest.json"));
+  const extractionDir = path.join(canonicalDocs, "extraction", latest.captureId);
+  const manifest = await readJson(path.join(extractionDir, "extraction-manifest.json"));
+  if (manifest.manifestHash !== latest.manifestHash) throw new Error("Frozen source manifest does not match extraction/latest.json");
+  const observations = path.join(extractionDir, "observations");
+  const page = await readJson(path.join(observations, "page.json"));
+  page.screenshots = Object.fromEntries(Object.entries(page.screenshots || {}).map(([viewport, filePath]) => [
+    viewport,
+    path.isAbsolute(filePath) ? filePath : path.join(observations, filePath),
+  ]));
+  const read = async (name, fallback) => {
+    try { return await readJson(path.join(observations, name)); } catch { return fallback; }
+  };
+  const seo = await read("seo.json", {});
+  const tokens = await read("tokens.json", {});
+  return {
+    extractionDir,
+    manifest,
+    evidence: {
+      root: extractionDir,
+      sourceMap: {
+        sourceUrl: page.url,
+        scope: "home",
+        pages: [page],
+        seo,
+        tokens,
+        designExtraction: tokens.extraction || {},
+      },
+      assets: await read("assets.json", { assets: [] }),
+      seo,
+      interactionMap: await read("interaction-map.json", { interactions: [] }),
+      sceneContract: await read("scene-contract.json", { scenes: [] }),
+      controlStateContract: await read("control-state-contract.json", { controls: [] }),
+      visualAssets: await read("visual-assets.json", { logos: [], icons: [] }),
+      layoutBlueprint: await read("layout-blueprint.json", { pages: [] }),
+      uiNormalization: await read("ui-normalization.json", { sections: [] }),
+      tokens,
+    },
+  };
+}
+
+async function attachScreenshotMetadata(evidence) {
+  for (const page of evidence.sourceMap.pages || []) {
+    page.screenshotMetadata = {};
+    for (const [viewport, filePath] of Object.entries(page.screenshots || {})) {
+      const metadata = await pngMetadata(filePath);
+      if (metadata) page.screenshotMetadata[viewport] = metadata;
+    }
+  }
+}
+
+async function pngMetadata(filePath) {
+  try {
+    const buffer = await readFile(filePath);
+    if (buffer.length < 24 || buffer.toString("hex", 0, 8) !== "89504e470d0a1a0a") return null;
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20), bytes: buffer.length };
+  } catch {
+    return null;
+  }
+}
+
+async function nextIteration(gapRoot) {
+  try {
+    const names = await readdir(path.join(gapRoot, "iterations"));
+    const numbers = names.map((name) => Number(name)).filter(Number.isInteger);
+    const next = Math.max(0, ...numbers) + 1;
+    if (next > MAX_GAP_CYCLES) throw new Error(`Maximum of ${MAX_GAP_CYCLES} visual gap cycles reached; finalize the reviewed final iteration as done_with_gaps when blockers remain.`);
+    return next;
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    return 1;
+  }
+}
+
+function pagePath(pageUrl, sourceUrl, fallbackIndex = 0) {
+  try {
+    const page = new URL(pageUrl, sourceUrl);
+    return page.pathname || "/";
+  } catch {
+    return fallbackIndex ? `/page-${fallbackIndex + 1}` : "/";
+  }
+}
+
+function resultPageUrl(resultUrl, pathname) {
+  const target = new URL(resultUrl);
+  target.pathname = pathname || "/";
+  target.search = "";
+  target.hash = "";
+  return target.toString();
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/skills/wix-headless-replatform/scripts/provision-repeater-cms.mjs

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "./lib/common.mjs";
+
+const API = "https://www.wixapis.com";
+async function main() {
+  const args = parseArgs(); if (!args.out) throw new Error("--out is required");
+  const plan = JSON.parse(await readFile(path.join(args.out, "docs", "site-clone", "repeater-cms.json"), "utf8"));
+  if (!args.execute) return console.log(JSON.stringify({ dryRun: true, collections: plan.collections.map((c) => ({ id: c.id, rows: c.items.length })) }, null, 2));
+  const token = process.env.WIX_AUTH_TOKEN; const siteId = process.env.WIX_SITE_ID;
+  if (!token || !siteId) throw new Error("--execute requires WIX_AUTH_TOKEN and WIX_SITE_ID");
+  for (const collection of plan.collections) {
+    const definition = { id: collection.id, displayName: collection.displayName, fields: fields(), permissions: permissions() };
+    const created = await send("/wix-data/v2/collections", { collection: definition }, token, siteId, [409]);
+    const existing = created?.collection || (await send(`/wix-data/v2/collections/${collection.id}`, undefined, token, siteId, [], "GET"))?.collection;
+    const collectionId = existing?.id || existing?._id || collection.id;
+    if (existing) await send("/wix-data/v2/collections", { collection: { ...existing, permissions: permissions() } }, token, siteId, [], "PUT");
+    await send("/wix-data/v1/permissions", { dataCollectionId: collectionId, dataPermissions: { id: collectionId, itemRead: "ANYONE", itemInsert: "PRIVILEGED", itemUpdate: "PRIVILEGED", itemRemove: "PRIVILEGED" } }, token, siteId);
+    for (const data of collection.items) await send("/wix-data/v2/items", { dataCollectionId: collectionId, dataItem: { id: data.sourceKey, data: { ...data, _id: data.sourceKey } } }, token, siteId, [409]);
+  }
+}
+function fields() { return [["sourceKey","TEXT"],["label","TEXT"],["body","TEXT"],["imagesJson","TEXT"],["linksJson","TEXT"],["sortOrder","NUMBER"],["initialExpanded","BOOLEAN"],["itemStructure","TEXT"]].map(([key,type]) => ({ key, displayName: key, type })); }
+function permissions() { return { read: "ANYONE", insert: "ADMIN", update: "ADMIN", remove: "ADMIN" }; }
+async function send(endpoint, body, token, siteId, allowed = [], method = "POST") { const value = String(token).trim(); const authorization = /^Bearer\s/i.test(value) || /^IST\./.test(value) ? value : `Bearer ${value}`; const res = await fetch(`${API}${endpoint}`, { method, headers: { Authorization: authorization, "wix-site-id": siteId, "Content-Type": "application/json" }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }); if (!res.ok && !allowed.includes(res.status)) throw new Error(`${endpoint}: ${res.status} ${await res.text()}`); return res.ok ? res.json() : null; }
+main().catch((error) => { console.error(error.stack || error.message); process.exit(1); });

package/skills/wix-headless-replatform/scripts/record-gap-decision.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, parseArgs, readJson, writeJson } from "./lib/common.mjs";
+import { finalizeExtractionReport } from "./finalize-extraction-report.mjs";
+
+export const GAP_DECISIONS = new Set(["accept-as-is", "retry-or-fix", "provide-material", "replace", "omit", "leave-unresolved"]);
+
+export async function recordGapDecision({ outputDir, gapId, decision, note = "", materialRefs = [] }) {
+  if (!gapId) throw new Error("gapId is required");
+  if (!GAP_DECISIONS.has(decision)) throw new Error(`Unsupported gap decision: ${decision}`);
+  const docs = docsDir(outputDir);
+  const latest = await readJson(path.join(docs, "extraction", "latest.json"));
+  const gaps = await readJson(path.join(docs, "extraction", latest.captureId, "extraction-gaps.json"));
+  if (!(gaps.gaps || []).some((gap) => gap.id === gapId)) throw new Error(`Unknown extraction gap: ${gapId}`);
+  const decisionPath = path.join(docs, "gap-decisions.json");
+  let artifact;
+  try { artifact = await readJson(decisionPath); } catch { artifact = { schemaVersion: "0083.1", manifestHash: latest.manifestHash, decisions: [] }; }
+  if (artifact.manifestHash !== latest.manifestHash) throw new Error("Gap decisions belong to a stale frozen manifest; review the current final report first");
+  const record = { gapId, decision, note, materialRefs };
+  artifact.decisions = [...artifact.decisions.filter((item) => item.gapId !== gapId), record].sort((a, b) => a.gapId.localeCompare(b.gapId));
+  await writeJson(decisionPath, artifact);
+  const report = await finalizeExtractionReport({ outputDir });
+  return { decisionPath, record, finalStatus: report.status };
+}
+
+async function main() {
+  const args = parseArgs();
+  if (!args.out || !args.gap || !args.decision) throw new Error("--out, --gap, and --decision are required");
+  const materialRefs = String(args.material || "").split(",").map((item) => item.trim()).filter(Boolean);
+  console.log(JSON.stringify(await recordGapDecision({
+    outputDir: path.resolve(String(args.out)),
+    gapId: String(args.gap),
+    decision: String(args.decision),
+    note: String(args.note || ""),
+    materialRefs,
+  }), null, 2));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main().catch((error) => { console.error(error.stack || error.message); process.exit(1); });