@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-headless-replatform/scripts/replay-extraction.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readdir } from "node:fs/promises";
+import { assembleExtraction } from "./assemble-extraction.mjs";
+import { docsDir, parseArgs, readJson, writeJson } from "./lib/common.mjs";
+import { EXTRACTION_SCHEMA_VERSION, semanticHash, verifyFrozenManifest } from "./lib/extraction-contract.mjs";
+import { CONTENT_EXTRACTION_SEMANTICS_VERSION } from "./lib/content-boundary.mjs";
+
+const REQUIRED_PACKET_TYPES = new Set([
+  "page", "assets", "seo", "tokens", "interaction-map", "scene-contract",
+  "layout-blueprint", "ui-normalization", "control-state-contract", "visual-assets",
+]);
+
+export async function replayExtraction({ outputDir, captureId, decisionPatches = [] }) {
+  const docs = docsDir(outputDir);
+  const latest = captureId ? null : await readJson(path.join(docs, "extraction", "latest.json"));
+  const sourceCaptureId = captureId || latest.captureId;
+  const sourceDir = path.join(docs, "extraction", sourceCaptureId);
+  const integrity = await verifyFrozenManifest(sourceDir);
+  if (!integrity.ok) throw new Error(`Cannot replay corrupt extraction: ${integrity.failures.join("; ")}`);
+  const pageResolution = await readJson(path.join(sourceDir, "page-resolution.spec.json"));
+  const pageCapture = await readJson(path.join(sourceDir, "page-capture.spec.json"));
+  const capturedContentSemantics = pageCapture.extensions?.["wix.replatform.content-boundary"]?.semanticsVersion;
+  if (capturedContentSemantics !== CONTENT_EXTRACTION_SEMANTICS_VERSION) {
+    throw new Error(`Capture ${sourceCaptureId} uses obsolete content-extraction semantics (${capturedContentSemantics || "unversioned"}); recapture the source page before replay.`);
+  }
+  const packetDir = path.join(sourceDir, "observations", "packets");
+  const packetFiles = (await readdir(packetDir)).filter((name) => name.endsWith(".packet.json")).sort();
+  const packets = new Map();
+  for (const file of packetFiles) {
+    const packet = await readJson(path.join(packetDir, file));
+    if (packet.schemaVersion !== EXTRACTION_SCHEMA_VERSION || packet.kind !== "observation-packet") {
+      throw new Error(`Invalid observation packet: ${file}`);
+    }
+    if (packet.sourceFingerprint !== pageCapture.sourceFingerprint) {
+      throw new Error(`Packet source fingerprint changed: ${file}`);
+    }
+    packets.set(packet.packetType, packet.payload);
+  }
+  const missing = [...REQUIRED_PACKET_TYPES].filter((type) => !packets.has(type));
+  if (missing.length) throw new Error(`Replay requires missing packet type(s): ${missing.join(", ")}`);
+  const page = structuredClone(packets.get("page"));
+  for (const [name, screenshotRef] of Object.entries(page.screenshots || {})) {
+    page.screenshots[name] = path.join(sourceDir, "observations", screenshotRef);
+  }
+  const packetHashes = integrity.manifest.observationRefs
+    .filter((entry) => entry.ref.startsWith("observations/packets/"))
+    .map((entry) => ({ ref: entry.ref, hash: entry.hash }));
+  const replayKey = semanticHash({
+    sourceCaptureId,
+    sourceFingerprint: pageCapture.sourceFingerprint,
+    packetHashes,
+    decisionPatches,
+  }).slice(0, 12);
+  const replayCaptureId = `${sourceCaptureId}-replay-${replayKey}`;
+  const result = await assembleExtraction({
+    outputDir,
+    requestedUrl: pageResolution.source.requestedUrl,
+    resolvedUrl: pageResolution.source.resolvedUrl,
+    canonicalUrl: pageResolution.source.canonicalUrl,
+    page,
+    assets: packets.get("assets"),
+    seo: packets.get("seo"),
+    tokens: packets.get("tokens"),
+    interactionMap: packets.get("interaction-map"),
+    sceneContract: packets.get("scene-contract"),
+    layoutBlueprint: packets.get("layout-blueprint"),
+    uiNormalization: packets.get("ui-normalization"),
+    controlStateContract: packets.get("control-state-contract"),
+    visualAssets: packets.get("visual-assets"),
+    sourceFingerprint: pageCapture.sourceFingerprint,
+    sourceFingerprintIncludesContentSemantics: true,
+    captureId: replayCaptureId,
+    decisionPatches,
+    pageResolutionArtifact: pageResolution,
+  });
+  const sourceHashes = new Map(integrity.manifest.specs.map((entry) => [entry.id, entry.hash]));
+  const changedSpecs = result.manifest.specs
+    .filter((entry) => sourceHashes.get(entry.id) !== entry.hash)
+    .map((entry) => ({ id: entry.id, before: sourceHashes.get(entry.id) || null, after: entry.hash }));
+  const report = {
+    schemaVersion: EXTRACTION_SCHEMA_VERSION,
+    sourceCaptureId,
+    replayCaptureId,
+    sourceFingerprint: pageCapture.sourceFingerprint,
+    reopenedSource: false,
+    packetCount: packetFiles.length,
+    changedSpecs,
+    manifestHash: result.manifest.manifestHash,
+  };
+  await writeJson(path.join(result.extractionDir, "replay-report.json"), report);
+  return { ...result, replayReport: report };
+}
+
+async function main() {
+  const args = parseArgs();
+  if (!args.out) throw new Error("--out is required");
+  const patches = args["decision-patches"] ? await readJson(path.resolve(String(args["decision-patches"]))) : [];
+  const result = await replayExtraction({
+    outputDir: path.resolve(String(args.out)),
+    captureId: args.capture ? String(args.capture) : undefined,
+    decisionPatches: Array.isArray(patches) ? patches : patches.patches || [],
+  });
+  console.log(JSON.stringify(result.replayReport, 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/resolve-home-page.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, normalizeUrl, parseArgs, resolveOutputDir, writeJson } from "./lib/common.mjs";
+import { EXTRACTION_SCHEMA_VERSION, createGap, freezeSpec } from "./lib/extraction-contract.mjs";
+
+const LOCALE_SEGMENT = /^[a-z]{2}(?:-[a-z]{2})?$/i;
+
+export async function resolveHomePage(requestedUrl, { fetchImpl = fetch } = {}) {
+  const requested = normalizeUrl(requestedUrl);
+  requested.search = "";
+  const candidate = homeCandidate(requested);
+  let response;
+  try {
+    response = await fetchImpl(candidate, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(15_000),
+      headers: { accept: "text/html,application/xhtml+xml", "user-agent": "wix-headless-replatform/0083" },
+    });
+  } catch (error) {
+    const gap = createGap({
+      id: "gap:page-resolution:navigation",
+      ownerUnitId: "page-resolution:home",
+      scope: "global",
+      missingFields: ["source.resolvedUrl"],
+      reason: `Home-page candidate could not be resolved: ${error.message}`,
+      evidenceRefs: [],
+      unblockAction: "Provide a reachable public home-page URL or restore source availability.",
+    });
+    return { artifact: null, gaps: [gap] };
+  }
+  if (!response.ok) {
+    const gap = createGap({
+      id: "gap:page-resolution:http",
+      ownerUnitId: "page-resolution:home",
+      scope: "global",
+      missingFields: ["source.resolvedUrl"],
+      reason: `Home-page candidate returned HTTP ${response.status}.`,
+      evidenceRefs: [],
+      unblockAction: "Provide a public home-page URL that returns a successful HTML response.",
+    });
+    return { artifact: null, gaps: [gap] };
+  }
+  const resolved = normalizeUrl(response.url || candidate);
+  resolved.hash = "";
+  const html = await response.text();
+  const canonical = extractCanonical(html, resolved) || resolved.toString();
+  const artifact = freezeSpec({
+    schemaVersion: EXTRACTION_SCHEMA_VERSION,
+    kind: "page-resolution",
+    id: "page-resolution:home",
+    pageKey: "home",
+    destinationRoute: "/",
+    status: "accepted",
+    source: {
+      requestedUrl: requested.toString(),
+      candidateUrl: candidate,
+      resolvedUrl: resolved.toString(),
+      canonicalUrl: canonical,
+      redirectsFollowed: requested.toString() !== resolved.toString(),
+    },
+    evidence: [{ kind: "read-only-navigation", responseStatus: response.status }],
+    gapRefs: [],
+  });
+  return { artifact, gaps: [] };
+}
+
+function homeCandidate(requested) {
+  const parts = requested.pathname.split("/").filter(Boolean);
+  const localePrefix = parts[0] && LOCALE_SEGMENT.test(parts[0]) ? `/${parts[0]}/` : "/";
+  return new URL(localePrefix, requested.origin).toString();
+}
+
+function extractCanonical(html, baseUrl) {
+  const match = String(html).match(/<link\b[^>]*rel=["'][^"']*canonical[^"']*["'][^>]*href=["']([^"']+)["'][^>]*>|<link\b[^>]*href=["']([^"']+)["'][^>]*rel=["'][^"']*canonical[^"']*["'][^>]*>/i);
+  const href = match?.[1] || match?.[2];
+  if (!href) return null;
+  try { return new URL(href, baseUrl).toString(); } catch { return null; }
+}
+
+async function main() {
+  const args = parseArgs();
+  const sourceUrl = args._[0] || args.url;
+  if (!sourceUrl) throw new Error("source URL is required");
+  const outputDir = resolveOutputDir(sourceUrl, args.out);
+  const result = await resolveHomePage(sourceUrl);
+  const target = path.join(docsDir(outputDir), "page-resolution.spec.json");
+  await writeJson(target, result.artifact || { schemaVersion: EXTRACTION_SCHEMA_VERSION, kind: "page-resolution", gaps: result.gaps });
+  if (result.gaps.some((gap) => gap.scope === "global")) {
+    const error = new Error(result.gaps[0].reason);
+    error.code = "PAGE_RESOLUTION_BLOCKED";
+    throw error;
+  }
+  console.log(JSON.stringify({ path: target, resolvedUrl: result.artifact.source.resolvedUrl, hash: result.artifact.hash }, null, 2));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main().catch((error) => { console.error(error.stack || error.message); process.exit(1); });