@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-headless-replatform/scripts/extract-seo.mjs

@@ -1,25 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { docsDir, fetchText, normalizeUrl, parseArgs, resolveOutputDir, writeJson } from "./lib/common.mjs";
-import { extractSeo } from "./lib/html-extract.mjs";
-
-async function main() {
-  const args = parseArgs();
-  const url = normalizeUrl(args._[0] || args.url).toString();
-  const outputDir = resolveOutputDir(url, args.out);
-  const seo = await extractSeoForUrl(url);
-  await writeJson(path.join(docsDir(outputDir), "seo.json"), seo);
-  if (args.json) process.stdout.write(`${JSON.stringify(seo, null, 2)}\n`);
-}
-
-export async function extractSeoForUrl(url) {
-  const html = await fetchText(url);
-  return extractSeo(html, url);
-}
-
-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/extract-tokens.mjs

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { docsDir, normalizeUrl, parseArgs, readJson, resolveOutputDir, writeJson } from "./lib/common.mjs";
-
-async function main() {
-  const args = parseArgs();
-  const url = normalizeUrl(args._[0] || args.url).toString();
-  const outputDir = resolveOutputDir(url, args.out);
-  const tokens = await extractTokens({ outputDir });
-  await writeJson(path.join(docsDir(outputDir), "tokens.json"), tokens);
-  if (args.json) process.stdout.write(`${JSON.stringify(tokens, null, 2)}\n`);
-}
-
-export async function extractTokens({ outputDir }) {
-  const sourceMapPath = path.join(docsDir(outputDir), "source-map.json");
-  let sourceMap = { pages: [] };
-  try {
-    sourceMap = await readJson(sourceMapPath);
-  } catch {
-    // Allow standalone use before source-map exists.
-  }
-  const colors = new Set();
-  const fonts = new Set();
-  const radii = new Set();
-  const shadows = new Set();
-  const fontSizes = new Set();
-
-  for (const page of sourceMap.pages || []) {
-    for (const color of page.tokens?.colors || []) colors.add(color);
-    for (const font of page.tokens?.fontFamilies || []) fonts.add(font);
-    for (const radius of page.tokens?.radii || []) radii.add(radius);
-    for (const shadow of page.tokens?.shadows || []) shadows.add(shadow);
-    for (const item of page.tokens?.computed || []) {
-      if (item.color && item.color !== "rgba(0, 0, 0, 0)") colors.add(item.color);
-      if (item.backgroundColor && item.backgroundColor !== "rgba(0, 0, 0, 0)") colors.add(item.backgroundColor);
-      if (item.fontFamily) fonts.add(item.fontFamily);
-      if (item.fontSize) fontSizes.add(item.fontSize);
-      if (item.borderRadius && item.borderRadius !== "0px") radii.add(item.borderRadius);
-      if (item.boxShadow && item.boxShadow !== "none") shadows.add(item.boxShadow);
-    }
-  }
-
-  return {
-    colors: Array.from(colors).slice(0, 32),
-    fontFamilies: Array.from(fonts).slice(0, 16),
-    fontSizes: Array.from(fontSizes).slice(0, 16),
-    radii: Array.from(radii).slice(0, 16),
-    shadows: Array.from(shadows).slice(0, 16),
-    recommendedTailwindTokens: {
-      colors: "Map primary, secondary, background, foreground, muted, accent, border from extracted colors.",
-      fonts: "Map sans/display/body from extracted font families and local downloaded fonts.",
-      spacing: "Infer from section rhythm; start with Tailwind defaults and add container widths.",
-    },
-    generatedAt: new Date().toISOString(),
-  };
-}
-
-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/finalize-extraction-report.mjs

@@ -1,126 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { docsDir, parseArgs, readJson, writeJson, writeText } from "./lib/common.mjs";
-import { EXTRACTION_SCHEMA_VERSION, assertValidArtifact } from "./lib/extraction-contract.mjs";
-
-export async function finalizeExtractionReport({ outputDir }) {
-  const docs = docsDir(outputDir);
-  const latest = await readJson(path.join(docs, "extraction", "latest.json"));
-  const extractionDir = path.join(docs, "extraction", latest.captureId);
-  const manifest = await readJson(path.join(extractionDir, "extraction-manifest.json"));
-  const gapArtifact = await readJson(path.join(extractionDir, "extraction-gaps.json"));
-  const decisionArtifact = await optionalJson(path.join(docs, "gap-decisions.json"), { manifestHash: latest.manifestHash, decisions: [] });
-  if (decisionArtifact.manifestHash !== latest.manifestHash) throw new Error("Gap decisions refer to a stale frozen manifest");
-  const decisions = new Map((decisionArtifact.decisions || []).map((decision) => [decision.gapId, decision]));
-  const ledger = await optionalJson(path.join(docs, "build", "section-implementation.json"), { units: [] });
-  const qa = await optionalJson(path.join(docs, "qa", "visual-qa.json"), null);
-  const gapReview = await optionalJson(path.join(docs, "gap-analysis", "latest.json"), null);
-  const gaps = (gapArtifact.gaps || []).filter((gap) => gap.status !== "resolved").map((gap) => {
-    const implementation = ledger.units?.find((unit) => unit.id === gap.ownerUnitId);
-    return {
-      id: gap.id,
-      unitId: gap.ownerUnitId,
-      scope: gap.scope,
-      status: gap.status,
-      reason: gap.reason,
-      missingFields: gap.missingFields,
-      confidence: gap.confidence,
-      evidenceRefs: gap.evidenceRefs,
-      recoveryAttempts: gap.attempts,
-      remainingAttempts: gap.remainingAttempts,
-      assumptions: gap.assumptions,
-      omissions: gap.omissions,
-      affectedAcceptance: gap.affectedAcceptance,
-      dependencyClosure: gap.dependencyClosure,
-      implementation: implementation ? { status: implementation.status, cloneRoot: implementation.cloneRoot } : null,
-      userDecision: decisions.get(gap.id) || gap.userDecision,
-      choices: ["accept-as-is", "retry-or-fix", "provide-material", "replace", "omit", "leave-unresolved"],
-      unblockAction: gap.unblockAction,
-    };
-  });
-  const unresolvedGlobal = gaps.filter((gap) => gap.scope === "global");
-  const provisional = gaps.filter((gap) => gap.scope === "local" && !["accept-as-is", "replace", "omit"].includes(gap.userDecision?.decision));
-  const browserVerified = Boolean(gapReview?.acceptance?.passed && ["reviewed", "not-applicable"].includes(gapReview?.visualReview?.status));
-  const implementationExists = Boolean(ledger.units?.length);
-  const status = unresolvedGlobal.length ? "blocked" : provisional.length ? "done_with_gaps" : browserVerified ? "done" : qa || implementationExists ? "verification_pending" : "implementation_pending";
-  const report = {
-    schemaVersion: EXTRACTION_SCHEMA_VERSION,
-    kind: "final-report",
-    captureId: latest.captureId,
-    manifestHash: manifest.manifestHash,
-    status,
-    summary: {
-      totalGaps: gaps.length,
-      provisionalGaps: provisional.length,
-      globalBlockers: unresolvedGlobal.length,
-      acceptedUnits: manifest.specs.filter((spec) => spec.status === "accepted").length,
-      provisionalUnits: manifest.specs.filter((spec) => spec.status === "provisional").length,
-    },
-    gaps,
-    qa: qa || gapReview ? {
-      preflightScore: qa?.score ?? null,
-      warnings: qa?.warnings || [],
-      provisionalUnits: qa?.provisionalUnits || [],
-      browserReview: gapReview ? { iteration: gapReview.iteration, passed: Boolean(gapReview.acceptance?.passed), status: gapReview.visualReview?.status, blockingCount: gapReview.summary?.blockingCount } : null,
-    } : null,
-  };
-  assertValidArtifact(report, "final-report");
-  await writeJson(path.join(docs, "final-report.json"), report);
-  await writeText(path.join(docs, "final-report.md"), renderFinalReport(report));
-  return report;
-}
-
-export function renderFinalReport(report) {
-  const lines = [
-    "# Home-page reconstruction report",
-    "",
-    `- Status: \`${report.status}\``,
-    `- Frozen manifest: \`${report.manifestHash}\``,
-    `- Accepted units: ${report.summary.acceptedUnits}`,
-    `- Provisional units: ${report.summary.provisionalUnits}`,
-    `- Unresolved local gaps: ${report.summary.provisionalGaps}`,
-    `- Global blockers: ${report.summary.globalBlockers}`,
-    "",
-  ];
-  if (!report.gaps.length) {
-    lines.push("No extraction gaps remain. Browser-backed verification is still required before final clone acceptance.", "");
-  } else {
-    lines.push("## Gaps requiring review", "");
-    for (const gap of report.gaps) {
-      lines.push(
-        `### ${gap.unitId}`,
-        "",
-        `This unit could not be imported reliably because ${lowerFirst(gap.reason)}`,
-        "",
-        `- Gap: \`${gap.id}\` (${gap.scope}, ${gap.status}, confidence: ${gap.confidence})`,
-        `- Missing: ${gap.missingFields.join(", ") || "unspecified evidence"}`,
-        `- Attempts: ${gap.recoveryAttempts.length}; remaining budget: ${gap.remainingAttempts}`,
-        `- Provisional implementation: ${gap.implementation?.status || "not implemented"}${gap.implementation?.cloneRoot ? ` at \`${gap.implementation.cloneRoot}\`` : ""}`,
-        `- Assumptions: ${gap.assumptions.join("; ") || "none"}`,
-        `- Omissions: ${gap.omissions.join("; ") || "none"}`,
-        `- Affected checks: ${gap.affectedAcceptance.join(", ") || "none recorded"}`,
-        `- User decision: ${gap.userDecision ? `\`${gap.userDecision.decision}\`${gap.userDecision.note ? ` — ${gap.userDecision.note}` : ""}` : "pending"}`,
-        `- Available decisions: ${gap.choices.map((choice) => `\`${choice}\``).join(", ")}`,
-        "",
-      );
-    }
-  }
-  return `${lines.join("\n").trim()}\n`;
-}
-
-function lowerFirst(value) {
-  const text = String(value || "evidence was incomplete");
-  return `${text.charAt(0).toLowerCase()}${text.slice(1)}`;
-}
-
-async function optionalJson(filePath, fallback) {
-  try { return await readJson(filePath); } catch { return fallback; }
-}
-
-async function main() {
-  const args = parseArgs();
-  if (!args.out) throw new Error("--out is required");
-  console.log(JSON.stringify(await finalizeExtractionReport({ outputDir: path.resolve(String(args.out)) }), null, 2));
-}
-
-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/finalize-gap-review.mjs

@@ -1,180 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { docsDir, normalizeUrl, parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";
-import { renderGapAnalysisMarkdown, renderGapFixPlan } from "./lib/gap-analysis.mjs";
-import { finalizeExtractionReport } from "./finalize-extraction-report.mjs";
-
-async function main() {
-  const args = parseArgs();
-  const sourceUrl = normalizeUrl(args._[0] || args.url).toString();
-  const outputDir = resolveOutputDir(sourceUrl, args.out);
-  if (args.reviewed === true || args.reviewed === "true") throw new Error("--reviewed is no longer supported; write the required visual-review.json evidence beside the canonical iteration report");
-  const report = await finalizeGapReview({ outputDir });
-  if (args.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  else console.log(`[gap-analysis] visual review ${report.visualReview.status}; final acceptance ${report.acceptance.passed ? "passed" : "not yet passed"}`);
-}
-
-function requireNonEmptyString(value, label) {
-  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be a non-empty string`);
-  return value.trim();
-}
-
-function validateVisualReview({ review, report, reviewPath }) {
-  if (!review || typeof review !== "object" || Array.isArray(review)) throw new Error(`Visual review must be a JSON object: ${reviewPath}`);
-  if (!Array.isArray(review.pairs)) throw new Error(`Visual review must include a pairs array: ${reviewPath}`);
-  const expectedPairs = new Map((report.screenshotPairs || []).map((pair) => [pair.id, pair]));
-  const findingIds = new Set((report.findings || []).map((finding) => finding.id));
-  const seen = new Set();
-  const normalized = review.pairs.map((entry, index) => {
-    const prefix = `visual review pair ${index + 1}`;
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`${prefix} must be an object`);
-    const pairId = requireNonEmptyString(entry.pairId, `${prefix}.pairId`);
-    const pair = expectedPairs.get(pairId);
-    if (!pair) throw new Error(`${prefix} references unknown screenshot pair: ${pairId}`);
-    if (seen.has(pairId)) throw new Error(`Visual review has duplicate screenshot pair: ${pairId}`);
-    seen.add(pairId);
-    const viewport = requireNonEmptyString(entry.viewport, `${prefix}.viewport`);
-    if (viewport !== pair.viewport) throw new Error(`${prefix}.viewport must match ${pairId} (${pair.viewport})`);
-    const observation = requireNonEmptyString(entry.observation, `${prefix}.observation`);
-    const verdict = requireNonEmptyString(entry.verdict, `${prefix}.verdict`);
-    const entryFindingIds = Array.isArray(entry.findingIds) ? entry.findingIds.map((id) => requireNonEmptyString(id, `${prefix}.findingIds`)) : [];
-    if (new Set(entryFindingIds).size !== entryFindingIds.length) throw new Error(`${prefix}.findingIds contains duplicates`);
-    for (const id of entryFindingIds) if (!findingIds.has(id)) throw new Error(`${prefix} links unknown finding: ${id}`);
-    const rationale = typeof entry.rationale === "string" ? entry.rationale.trim() : "";
-    if (verdict === "no-identity-gap") {
-      if (entryFindingIds.length) throw new Error(`${prefix} cannot link findings for no-identity-gap`);
-      if (!rationale) throw new Error(`${prefix}.rationale is required for no-identity-gap`);
-    } else if (verdict === "findings-recorded") {
-      if (!entryFindingIds.length) throw new Error(`${prefix}.findingIds is required for findings-recorded`);
-    } else {
-      throw new Error(`${prefix}.verdict must be findings-recorded or no-identity-gap`);
-    }
-    return { pairId, viewport, observation, verdict, findingIds: entryFindingIds, rationale: rationale || null };
-  });
-  const missing = [...expectedPairs.keys()].filter((pairId) => !seen.has(pairId));
-  if (missing.length) throw new Error(`Visual review is incomplete: ${missing.join(", ")}`);
-  return normalized;
-}
-
-async function validateVisualProgress({ progress, report, progressPath }) {
-  if (!progress || typeof progress !== "object" || Array.isArray(progress)) throw new Error(`Visual progress proof must be a JSON object: ${progressPath}`);
-  if (!Array.isArray(progress.entries)) throw new Error(`Visual progress proof must include an entries array: ${progressPath}`);
-  const expectedFindingIds = new Set(report.visualProgress?.previousBlockingFindingIds || []);
-  const currentPairs = new Map((report.screenshotPairs || []).map((pair) => [pair.id, pair]));
-  const previousReportPath = report.visualProgress?.previousReportPath;
-  if (!previousReportPath) throw new Error("Visual progress proof is missing the prior canonical report path");
-  const previousReport = await readJson(previousReportPath);
-  const previousPairs = new Map((previousReport.screenshotPairs || []).map((pair) => [pair.id, pair]));
-  const seen = new Set();
-  const records = progress.entries.map((entry, index) => {
-    const prefix = `visual progress entry ${index + 1}`;
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`${prefix} must be an object`);
-    const priorFindingId = requireNonEmptyString(entry.priorFindingId, `${prefix}.priorFindingId`);
-    if (!expectedFindingIds.has(priorFindingId)) throw new Error(`${prefix} references unknown prior blocking finding: ${priorFindingId}`);
-    if (seen.has(priorFindingId)) throw new Error(`Visual progress proof has duplicate prior finding: ${priorFindingId}`);
-    seen.add(priorFindingId);
-    const target = requireNonEmptyString(entry.target, `${prefix}.target`);
-    const pairId = requireNonEmptyString(entry.pairId, `${prefix}.pairId`);
-    const currentPair = currentPairs.get(pairId);
-    const previousPair = previousPairs.get(pairId);
-    if (!currentPair || !previousPair) throw new Error(`${prefix}.pairId must exist in both the prior and current screenshot queues`);
-    const sourceScreenshotPath = requireNonEmptyString(entry.sourceScreenshotPath, `${prefix}.sourceScreenshotPath`);
-    const beforeResultScreenshotPath = requireNonEmptyString(entry.beforeResultScreenshotPath, `${prefix}.beforeResultScreenshotPath`);
-    const afterResultScreenshotPath = requireNonEmptyString(entry.afterResultScreenshotPath, `${prefix}.afterResultScreenshotPath`);
-    if (sourceScreenshotPath !== currentPair.source.path) throw new Error(`${prefix}.sourceScreenshotPath must match the canonical source screenshot for ${pairId}`);
-    if (beforeResultScreenshotPath !== previousPair.result.path) throw new Error(`${prefix}.beforeResultScreenshotPath must match the prior iteration result screenshot for ${pairId}`);
-    if (afterResultScreenshotPath !== currentPair.result.path) throw new Error(`${prefix}.afterResultScreenshotPath must match the current iteration result screenshot for ${pairId}`);
-    const beforeObservation = requireNonEmptyString(entry.beforeObservation, `${prefix}.beforeObservation`);
-    const afterObservation = requireNonEmptyString(entry.afterObservation, `${prefix}.afterObservation`);
-    const evidence = requireNonEmptyString(entry.evidence, `${prefix}.evidence`);
-    const verdict = requireNonEmptyString(entry.verdict, `${prefix}.verdict`);
-    if (!["improved", "no-visible-improvement", "regressed"].includes(verdict)) throw new Error(`${prefix}.verdict must be improved, no-visible-improvement, or regressed`);
-    return { priorFindingId, target, pairId, sourceScreenshotPath, beforeResultScreenshotPath, afterResultScreenshotPath, beforeObservation, afterObservation, verdict, evidence };
-  });
-  const missing = [...expectedFindingIds].filter((findingId) => !seen.has(findingId));
-  if (missing.length) throw new Error(`Visual progress proof is incomplete: ${missing.join(", ")}`);
-  return records;
-}
-
-export async function finalizeGapReview({ outputDir } = {}) {
-  const gapRoot = path.join(docsDir(outputDir), "gap-analysis");
-  const latest = await readJson(path.join(gapRoot, "latest.json"));
-  const reportPath = latest.paths?.reportJson;
-  if (!reportPath) throw new Error("Latest gap report does not include its canonical report path");
-  const report = await readJson(reportPath);
-  const reviewPath = path.join(path.dirname(reportPath), "visual-review.json");
-  const reviewRequired = Boolean(report.visualReview?.required || report.screenshotPairs?.length);
-  let reviewPairs = [];
-  let progressRecords = [];
-  if (reviewRequired) {
-    let review;
-    try {
-      review = await readJson(reviewPath);
-    } catch (error) {
-      throw new Error(`Missing required visual review evidence at ${reviewPath}. Open every source/result pair and write visual-review.json before finalizing. (${error.message})`);
-    }
-    reviewPairs = validateVisualReview({ review, report, reviewPath });
-    for (const pair of report.screenshotPairs || []) pair.reviewStatus = "reviewed";
-    report.visualReview.status = "reviewed";
-    report.visualReview.reviewedPairs = reviewPairs.map((entry) => entry.pairId);
-    report.visualReview.records = reviewPairs;
-    report.visualReview.artifactPath = reviewPath;
-    report.visualReview.reviewedAt = new Date().toISOString();
-  } else {
-    report.visualReview.status = "not-applicable";
-    report.visualReview.reviewedPairs = [];
-    report.visualReview.records = [];
-  }
-  if (report.visualProgress?.required) {
-    const progressPath = report.paths?.visualProgress || path.join(path.dirname(reportPath), "visual-progress.json");
-    let progress;
-    try {
-      progress = await readJson(progressPath);
-    } catch (error) {
-      throw new Error(`Missing required visual progress proof at ${progressPath}. Compare the prior and current result screenshots before finalizing. (${error.message})`);
-    }
-    progressRecords = await validateVisualProgress({ progress, report, progressPath });
-    report.visualProgress.status = "reviewed";
-    report.visualProgress.records = progressRecords;
-    report.visualProgress.artifactPath = progressPath;
-    report.visualProgress.reviewedAt = new Date().toISOString();
-  }
-  const open = (report.findings || []).filter((finding) => finding.status !== "resolved" && finding.status !== "accepted");
-  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
-  for (const finding of open) counts[finding.severity] = (counts[finding.severity] || 0) + 1;
-  report.summary.counts = counts;
-  report.summary.blockingCount = counts.critical + counts.high;
-  report.summary.findingCount = open.length;
-  report.summary.score = Math.max(0, Math.round(100 - counts.critical * 25 - counts.high * 10 - counts.medium * 3 - counts.low));
-  report.summary.finalAcceptance = report.summary.blockingCount === 0 && (!report.visualReview.required || report.visualReview.status === "reviewed");
-  if (report.summary.finalAcceptance && report.visualProgress?.required && progressRecords.some((record) => record.verdict !== "improved")) {
-    throw new Error("Cannot accept the iteration: a prior blocking finding was not proven improved by its before/after screenshot evidence");
-  }
-  report.acceptance.passed = report.summary.finalAcceptance;
-  report.acceptance.finalizedAt = new Date().toISOString();
-  await writeJson(reportPath, 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));
-  const manifestPath = path.join(path.dirname(reportPath), "iteration-manifest.json");
-  const manifest = await readJson(manifestPath);
-  manifest.status = "visual-review-complete";
-  manifest.visualReview = { artifactPath: reviewRequired ? reviewPath : null, reviewedPairs: reviewPairs.map((entry) => entry.pairId), reviewedAt: report.visualReview.reviewedAt || null };
-  manifest.visualProgress = { artifactPath: report.visualProgress?.artifactPath || null, reviewedAt: report.visualProgress?.reviewedAt || null, verdicts: progressRecords.map((entry) => ({ priorFindingId: entry.priorFindingId, verdict: entry.verdict })) };
-  await writeJson(manifestPath, manifest);
-  try {
-    await readJson(path.join(docsDir(outputDir), "extraction", "latest.json"));
-    await finalizeExtractionReport({ outputDir });
-  } catch (error) {
-    if (error?.code !== "ENOENT") throw error;
-  }
-  return report;
-}
-
-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/finalize-gap-review.test.mjs

@@ -1,98 +0,0 @@
-import assert from "node:assert/strict";
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import test from "node:test";
-import { finalizeGapReview } from "./finalize-gap-review.mjs";
-
-async function writeJson(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
-}
-
-async function fixture() {
-  const outputDir = await mkdtemp(path.join(os.tmpdir(), "gap-review-"));
-  const iterationDir = path.join(outputDir, "docs", "site-clone", "gap-analysis", "iterations", "001");
-  const reportPath = path.join(iterationDir, "gap-analysis.json");
-  const report = {
-    iteration: 1,
-    summary: { score: 90, findingCount: 1, counts: { critical: 0, high: 0, medium: 1, low: 0 }, blockingCount: 0, finalAcceptance: false },
-    findings: [{ id: "gap-001", severity: "medium", status: "open", category: "layout", message: "Example", scope: {}, repairHint: "Fix" }],
-    screenshotPairs: [{ id: "home-desktop", page: "/", viewport: "desktop", source: { path: "source.png" }, result: { path: "result.png" } }],
-    visualReview: { status: "pending", required: true, reviewedPairs: [], notes: [] },
-    fixOrder: [],
-    acceptance: { passed: false },
-    paths: { reportJson: reportPath, reportMarkdown: path.join(iterationDir, "gap-analysis.md"), fixPlan: path.join(iterationDir, "gap-fix-plan.md") },
-  };
-  await writeJson(reportPath, report);
-  await writeJson(path.join(outputDir, "docs", "site-clone", "gap-analysis", "latest.json"), report);
-  await writeJson(path.join(iterationDir, "iteration-manifest.json"), { iteration: 1, status: "comparison-complete-visual-review-pending" });
-  return { outputDir, iterationDir };
-}
-
-test("finalizeGapReview rejects a missing visual review artifact", async () => {
-  const { outputDir } = await fixture();
-  try {
-    await assert.rejects(() => finalizeGapReview({ outputDir }), /Missing required visual review evidence/);
-  } finally {
-    await rm(outputDir, { recursive: true, force: true });
-  }
-});
-
-test("finalizeGapReview records evidence and synchronizes the iteration manifest", async () => {
-  const { outputDir, iterationDir } = await fixture();
-  try {
-    await writeJson(path.join(iterationDir, "visual-review.json"), {
-      pairs: [{ pairId: "home-desktop", viewport: "desktop", observation: "The hero composition differs from the source.", verdict: "findings-recorded", findingIds: ["gap-001"] }],
-    });
-    const report = await finalizeGapReview({ outputDir });
-    assert.equal(report.visualReview.status, "reviewed");
-    assert.equal(report.visualReview.records[0].findingIds[0], "gap-001");
-    const manifest = JSON.parse(await (await import("node:fs/promises")).readFile(path.join(iterationDir, "iteration-manifest.json"), "utf8"));
-    assert.equal(manifest.status, "visual-review-complete");
-  } finally {
-    await rm(outputDir, { recursive: true, force: true });
-  }
-});
-
-test("finalizeGapReview requires traceable before/after proof after a prior blocking finding", async () => {
-  const { outputDir, iterationDir } = await fixture();
-  try {
-    const reportPath = path.join(iterationDir, "gap-analysis.json");
-    const report = JSON.parse(await (await import("node:fs/promises")).readFile(reportPath, "utf8"));
-    const previousDir = path.join(outputDir, "docs", "site-clone", "gap-analysis", "iterations", "000");
-    const previousReportPath = path.join(previousDir, "gap-analysis.json");
-    await writeJson(previousReportPath, {
-      iteration: 0,
-      findings: [{ id: "gap-previous", severity: "high", status: "open" }],
-      screenshotPairs: [{ id: "home-desktop", page: "/", viewport: "desktop", source: { path: "source.png" }, result: { path: "before.png" } }],
-      paths: { reportJson: previousReportPath },
-    });
-    report.visualProgress = { required: true, status: "pending", previousIteration: 0, previousReportPath, previousBlockingFindingIds: ["gap-previous"] };
-    report.paths.visualProgress = path.join(iterationDir, "visual-progress.json");
-    await writeJson(reportPath, report);
-    await writeJson(path.join(outputDir, "docs", "site-clone", "gap-analysis", "latest.json"), report);
-    await writeJson(path.join(iterationDir, "visual-review.json"), {
-      pairs: [{ pairId: "home-desktop", viewport: "desktop", observation: "The hero now matches.", verdict: "no-identity-gap", rationale: "No identity gap remains." }],
-    });
-    await assert.rejects(() => finalizeGapReview({ outputDir }), /Missing required visual progress proof/);
-    await writeJson(report.paths.visualProgress, {
-      entries: [{
-        priorFindingId: "gap-previous",
-        target: "Hero section",
-        pairId: "home-desktop",
-        sourceScreenshotPath: "source.png",
-        beforeResultScreenshotPath: "before.png",
-        afterResultScreenshotPath: "result.png",
-        beforeObservation: "The hero heading was misplaced.",
-        afterObservation: "The hero heading now aligns with the source.",
-        verdict: "improved",
-        evidence: "The same desktop screenshot pair shows the corrected heading alignment.",
-      }],
-    });
-    const finalized = await finalizeGapReview({ outputDir });
-    assert.equal(finalized.visualProgress.records[0].verdict, "improved");
-  } finally {
-    await rm(outputDir, { recursive: true, force: true });
-  }
-});

package/skills/wix-headless-replatform/scripts/finalize-migration-website.mjs

@@ -1,103 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { mkdir, rename, writeFile } from "node:fs/promises";
-import { parseArgs, readJson } from "./lib/common.mjs";
-
-async function writeJsonAtomic(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-  await rename(tempPath, filePath);
-}
-
-export async function createMigrationWebsiteCompletion({ handoffPath = null, projectDir = null, outputDir, releaseUrl, releaseNotApplicable = false, doneWithGaps = false, iteration = null }) {
-  if (!handoffPath && !projectDir) throw new Error("--handoff or --project-dir is required");
-  if (!outputDir) throw new Error("A migration frontend output directory is required");
-  const handoff = handoffPath ? await readJson(handoffPath) : null;
-  if (handoffPath && !handoff?.handoffFingerprint) throw new Error("website/handoff.json is missing handoffFingerprint; refresh the handoff first");
-  const gapPath = iteration
-    ? path.join(outputDir, "docs", "site-clone", "gap-analysis", "iterations", String(iteration).padStart(3, "0"), "gap-analysis.json")
-    : path.join(outputDir, "docs", "site-clone", "gap-analysis", "latest.json");
-  const gap = await readJson(gapPath);
-  const finalReportPath = path.join(outputDir, "docs", "site-clone", "final-report.json");
-  const finalReport = await readOptionalJson(finalReportPath);
-  if (finalReport?.status === "blocked") throw new Error("The frozen extraction final report contains a global blocker");
-  const effectiveDoneWithGaps = doneWithGaps || finalReport?.status === "done_with_gaps";
-  if (gap?.visualReview?.status !== "reviewed") {
-    throw new Error("Post-build gap review has not passed; run/finalize the gap loop before finalizing the website");
-  }
-  const findings = Array.isArray(gap.findings) ? gap.findings : [];
-  const unresolved = findings.filter((finding) => finding.status !== "resolved" && finding.status !== "accepted");
-  const unresolvedCritical = unresolved.filter((finding) => finding.severity === "critical").length;
-  const unresolvedHigh = unresolved.filter((finding) => finding.severity === "high").length;
-  if (!effectiveDoneWithGaps && (!gap?.acceptance?.passed || unresolvedCritical || unresolvedHigh)) throw new Error("Post-build gap review still has unresolved critical/high findings");
-  if (doneWithGaps && !iteration && !finalReport) throw new Error("--done-with-gaps requires --iteration or a frozen final report so the terminal evidence is explicit");
-  const automationState = await readJson(path.join(outputDir, "docs", "site-clone", "frontend-automation-state.json"));
-  const facelift = automationState?.checkpoints?.facelift;
-  if (!effectiveDoneWithGaps && facelift?.requested && facelift.status !== "accepted") {
-    throw new Error("Optional facelift was requested but has not been accepted; complete the separate facelift review first");
-  }
-  if (!releaseUrl && !releaseNotApplicable) throw new Error("--release-url is required unless --release-not-applicable is explicitly set");
-
-  const receipt = {
-    schemaVersion: 1,
-    status: effectiveDoneWithGaps ? "done_with_gaps" : unresolved.length ? "complete_with_warnings" : "complete",
-    handoffFingerprint: handoff?.handoffFingerprint || null,
-    extractionManifestHash: finalReport?.manifestHash || null,
-    frontendProjectDir: path.relative(projectDir || path.dirname(path.dirname(handoffPath)), outputDir) || ".",
-    phase: effectiveDoneWithGaps ? finalReport?.status === "done_with_gaps" ? "provisional_handoff" : "gap_cycle_cap" : "release",
-    gapAnalysis: {
-      latestIteration: gap.iteration,
-      cycleCap: doneWithGaps ? 5 : null,
-      screenshotReview: "complete",
-      unresolvedCritical,
-      unresolvedHigh,
-      residualFindings: unresolved.map((finding) => ({ id: finding.id, severity: finding.severity, message: finding.message })),
-    },
-    facelift: effectiveDoneWithGaps ? { status: "not_run", reason: finalReport?.status === "done_with_gaps" ? "provisional_units_remain" : "maximum_gap_cycles_reached" } : facelift?.requested ? { status: "accepted" } : { status: "not_requested" },
-    release: releaseNotApplicable ? { status: "not_applicable", url: null } : { status: "released", url: releaseUrl },
-    artifactRefs: [path.relative(projectDir || path.dirname(path.dirname(handoffPath)), gapPath), ...(finalReport ? [path.relative(projectDir || path.dirname(path.dirname(handoffPath)), finalReportPath)] : []), ...(gap.paths?.visualProgress ? [gap.paths.visualProgress] : []), ...(gap.visualReview?.artifactPath ? [gap.visualReview.artifactPath] : [])],
-    updatedAt: new Date().toISOString(),
-  };
-  const receiptPath = handoffPath
-    ? path.join(path.dirname(handoffPath), "completion.json")
-    : path.join(projectDir, "website", "completion.json");
-  await writeJsonAtomic(receiptPath, receipt);
-  return { receiptPath, receipt };
-}
-
-async function readOptionalJson(filePath) {
-  try { return await readJson(filePath); } catch (error) {
-    if (error?.code === "ENOENT") return null;
-    throw error;
-  }
-}
-
-async function main() {
-  const args = parseArgs();
-  const handoffPath = args.handoff ? path.resolve(String(args.handoff)) : null;
-  const projectDir = args["project-dir"] ? path.resolve(String(args["project-dir"])) : null;
-  const handoff = handoffPath ? await readJson(handoffPath) : null;
-  const outputDir = args.out
-    ? path.resolve(String(args.out))
-    : handoff?.destination?.frontendProjectDir
-      ? path.resolve(String(handoff.destination.frontendProjectDir))
-      : null;
-  const result = await createMigrationWebsiteCompletion({
-    handoffPath,
-    projectDir,
-    outputDir,
-    releaseUrl: args["release-url"] ? String(args["release-url"]) : null,
-    releaseNotApplicable: args["release-not-applicable"] === true || args["release-not-applicable"] === "true",
-    doneWithGaps: args["done-with-gaps"] === true || args["done-with-gaps"] === "true",
-    iteration: args.iteration ? Number(args.iteration) : null,
-  });
-  console.log(JSON.stringify({ ok: true, ...result }, null, 2));
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch((error) => {
-    console.error(error.stack || error.message);
-    process.exit(1);
-  });
-}