@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-headless-replatform/scripts/generate-invoice-download-backend.mjs

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import path from "node:path";
+import { parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";
+
+// Generates the server-side backend that hands a member their preserved invoice document: a pure
+// handler, the Wix adapters that give it real data, and the route that wires them together.
+//
+// This is the one place the invoice feature can leak BETWEEN customers, so the shape is not
+// negotiable: the handler accepts an ORDER id and nothing else, checks that the calling member
+// can read that order, and resolves the private file id server-side. If it accepted a file id
+// from the client, any member could ask for another member's tax invoice by guessing or
+// harvesting one — and an invoice carries a name, an address and a purchase history.
+//
+// The preserved document is a PRIVATE Media file, so it is not reachable by URL without a
+// generated download link. That link is minted per request with an explicit short expiry: the
+// API's own default is 600 minutes, which is not short-lived for a tax document.
+//
+// The field names are read from the migration's own contract at GENERATION time rather than
+// written out here. Two copies of a field name is exactly the drift the contract adapter exists
+// to prevent, and this generator is the third consumer of it.
+const require = createRequire(import.meta.url);
+const invoiceContract = require("../../wix-replatform/resources/rp-target-wix/lib/order-invoice-contract.js");
+
+// The scaffold ships @wix/sdk, @wix/astro and @wix/essentials, and nothing else. Without these
+// the generated route imports modules that are not installed and the build fails — which is
+// better than the previous behaviour, where it built fine and answered 401 forever.
+export const REQUIRED_DEPENDENCIES = Object.freeze({
+  "@wix/ecom": "^1.0.0",
+  "@wix/media": "^1.0.0",
+  "@wix/members": "^1.0.0",
+  "@wix/essentials": "^1.0.6",
+});
+
+function handlerSource({ fileIdField, numberField, contractVersion }) {
+  return `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
+// Field names generated from order-invoice contract ${contractVersion}.
+//
+// Hands a signed-in member a short-lived download link for the invoice document preserved on one
+// of THEIR orders.
+//
+// The security contract, in order:
+//   1. A client-supplied file id is REJECTED outright. The client names an order; the server
+//      resolves the file. Accepting a file id would let any member fetch any member's invoice.
+//   2. The member must be authenticated.
+//   3. The order must be readable BY THAT MEMBER. Order scoping is the authorization boundary.
+//   4. The file id is read from the order's own extended fields, server-side.
+//   5. The download URL is minted with an explicit short expiry and is never logged.
+
+export const INVOICE_FILE_FIELD = ${JSON.stringify(fileIdField)};
+export const INVOICE_NUMBER_FIELD = ${JSON.stringify(numberField)};
+export const DOWNLOAD_EXPIRY_MINUTES = 10;
+
+export function createInvoiceDownloadHandler({ getMemberId, getOrderForMember, generateDownloadUrl }) {
+  if (typeof getMemberId !== "function") throw new Error("getMemberId is required");
+  if (typeof getOrderForMember !== "function") throw new Error("getOrderForMember is required");
+  if (typeof generateDownloadUrl !== "function") throw new Error("generateDownloadUrl is required");
+
+  return async function handleInvoiceDownload(request = {}) {
+    try {
+      return await respond(request);
+    } catch (error) {
+      // A dependency being down is not a refusal. Reported without detail — the member learns
+      // nothing about the order either way — but with a status a client may retry and monitoring
+      // can tell apart from a denial.
+      if (error && error.transient === true) return { status: 503, error: "service-temporarily-unavailable" };
+      throw error;
+    }
+  };
+
+  async function respond(request) {
+    const body = request.body && typeof request.body === "object" ? request.body : {};
+
+    // 1. The client may not name a file. Any attempt is refused rather than ignored, so a
+    //    misbuilt caller fails loudly instead of silently working for the wrong reason.
+    for (const forbidden of ["fileId", "file_id", "fileID", "mediaId", "media_id"]) {
+      if (Object.prototype.hasOwnProperty.call(body, forbidden)) {
+        return { status: 400, error: "client-supplied-file-id-rejected" };
+      }
+    }
+
+    const orderId = typeof body.orderId === "string" ? body.orderId.trim() : "";
+    if (!orderId) return { status: 400, error: "order-id-required" };
+
+    // 2. Authentication.
+    const memberId = await getMemberId(request);
+    if (!memberId) return { status: 401, error: "authentication-required" };
+
+    // 3. Authorization is the order read: if this member cannot read this order, there is nothing
+    //    to talk about. Never fall back to an unscoped order read.
+    const order = await getOrderForMember({ orderId, memberId });
+    if (!order) return { status: 403, error: "order-not-readable-by-member" };
+
+    // 4. Resolve the file server-side.
+    const namespaces = (order.extendedFields && order.extendedFields.namespaces) || {};
+    const fields = namespaces._user_fields || {};
+    const fileId = typeof fields[INVOICE_FILE_FIELD] === "string" ? fields[INVOICE_FILE_FIELD].trim() : "";
+    if (!fileId) return { status: 404, error: "no-preserved-invoice-for-order" };
+
+    // 5. Mint a short-lived link. The URL is returned to the caller and never logged.
+    const url = await generateDownloadUrl({ fileId, expirationInMinutes: DOWNLOAD_EXPIRY_MINUTES });
+    if (!url) return { status: 502, error: "download-url-unavailable" };
+
+    return {
+      status: 200,
+      url,
+      expiresInMinutes: DOWNLOAD_EXPIRY_MINUTES,
+      // The invoice number is the merchant's own reference and is safe to show. The file id is
+      // internal and is deliberately not echoed.
+      invoiceNumber: typeof fields[INVOICE_NUMBER_FIELD] === "string" ? fields[INVOICE_NUMBER_FIELD] : null,
+    };
+  }
+}
+`;
+}
+
+// The authorization logic, with no Wix import in it. Split out from the adapters deliberately:
+// a module that statically imports @wix/ecom cannot be loaded by a test without the whole SDK
+// installed, and "we could not test it" is how the previous version of this backend shipped a
+// seam that answered 401 to everything. What is left in the adapters file is wiring with no
+// branches in it.
+const AUTHORIZATION_SOURCE = `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
+//
+// Who may download which invoice. No Wix imports here on purpose, so this file can be run and
+// tested on its own; the adapters supply the four functions that talk to Wix.
+//
+// Two facts shape it, both from the API docs rather than assumed:
+//
+//   1. Get Order called with a MEMBER's identity returns the order only if that member placed it.
+//      That check is Wix's, not ours, and it is the authorization boundary.
+//   2. The migration's invoice fields are declared readable by \`apps\` and \`users\` — deliberately
+//      NOT by \`users-of-users\`, because they are merchant data. So the member-identity read that
+//      proves ownership does NOT return the field values, and a second, elevated read is needed
+//      to get them.
+//
+// So ownership is established by the unelevated read, and only then is anything elevated. The
+// rule is then checked a SECOND time, by us, against the elevated order's buyerInfo.
+//
+// Be precise about what that second check is worth. It is a second IMPLEMENTATION, not a second
+// source of evidence: both it and Wix's check rest on the same stored \`buyerInfo.memberId\`. It
+// catches an elevated read that answers about the wrong order, or a change in what elevation
+// returns. It does NOT catch an order attributed to the wrong member in the first place -- if the
+// import writes Alice's order with Bob's memberId, both checks agree and Bob gets Alice's
+// invoice. Correct \`buyerInfo.memberId\` on imported orders is a PREREQUISITE of this feature,
+// not something it can verify. An order carrying no memberId fails closed.
+
+// The SDK renames \`id\` to \`_id\`. Read both rather than pick one and be wrong on a version bump.
+export function orderIdOf(order) {
+  if (!order || typeof order !== "object") return null;
+  const value = order._id ?? order.id;
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+// Not every failure is a refusal. Collapsing them told a member "you are not allowed" during a
+// Wix outage, and left monitoring unable to tell a denial from a dependency being down.
+//
+// The Wix SDK throws \`SDKError\` carrying \`response.status\`. A 401, 403 or 404 is a real answer
+// to the question asked, and becomes \`null\` — indistinguishable, on purpose, so a prober cannot
+// learn from the difference between "not yours" and "does not exist". Anything else, including a
+// 5xx and a network error with no status at all, is us failing rather than the caller being
+// refused, and is raised so the route can say so.
+const DENIAL_STATUSES = new Set([401, 403, 404]);
+
+export class InvoiceBackendUnavailable extends Error {
+  constructor(status) {
+    super(\`the invoice backend could not reach Wix (status \${status ?? "unknown"})\`);
+    this.name = "InvoiceBackendUnavailable";
+    this.transient = true;
+    this.status = status ?? null;
+  }
+}
+
+async function orNull(operation) {
+  try {
+    return (await operation()) ?? null;
+  } catch (error) {
+    const status = error && error.response && error.response.status;
+    if (DENIAL_STATUSES.has(status)) return null;
+    throw new InvoiceBackendUnavailable(status);
+  }
+}
+
+export function createInvoiceAdapters({
+  getCurrentMember,
+  getOrderAsCaller,
+  getOrderElevated,
+  generateDownloadUrlElevated,
+}) {
+  for (const [name, fn] of Object.entries({ getCurrentMember, getOrderAsCaller, getOrderElevated, generateDownloadUrlElevated })) {
+    if (typeof fn !== "function") throw new Error(\`\${name} is required\`);
+  }
+
+  return {
+    async getMemberId() {
+      // \`getCurrentMember()\` resolves to \`{ member }\`, NOT to the member. The docs example shows
+      // a bare member object and is wrong; the published type is
+      // \`Promise<GetMyMemberResponse>\` with \`member?: Member\`. Reading \`_id\` off the response
+      // made every signed-in member resolve as anonymous, so the route answered 401 to everyone
+      // — the same failure as the \`locals\` seam it replaced, one layer in.
+      //
+      // Both shapes are accepted: the wrapper is what ships, the bare member is what the docs
+      // promise, and being wrong about which one arrives must not lock members out again.
+      const response = await orNull(getCurrentMember);
+      const member = (response && response.member) || response;
+      const id = member && (member._id ?? member.id);
+      return typeof id === "string" && id.length > 0 ? id : null;
+    },
+
+    async getOrderForMember({ orderId, memberId }) {
+      if (typeof orderId !== "string" || orderId.length === 0) return null;
+      if (typeof memberId !== "string" || memberId.length === 0) return null;
+
+      // 1. Wix's check. Nothing is elevated until this passes.
+      const asCaller = await orNull(() => getOrderAsCaller(orderId));
+      if (!asCaller || orderIdOf(asCaller) !== orderId) return null;
+
+      // 2. Our own read, elevated, because the fields are not member-readable.
+      const elevated = await orNull(() => getOrderElevated(orderId));
+      if (!elevated || orderIdOf(elevated) !== orderId) return null;
+
+      // 3. Our check, independent of Wix's. An order whose buyer is not this member is not this
+      //    member's order, and an order with no member buyer at all belongs to nobody who can ask
+      //    for it here. Email is never accepted as proof: it is changeable and guessable.
+      const buyerMemberId = elevated.buyerInfo && elevated.buyerInfo.memberId;
+      if (typeof buyerMemberId !== "string" || buyerMemberId !== memberId) return null;
+
+      return elevated;
+    },
+
+    async generateDownloadUrl({ fileId, expirationInMinutes }) {
+      if (typeof fileId !== "string" || fileId.length === 0) return null;
+      const result = await orNull(() => generateDownloadUrlElevated(fileId, { expirationInMinutes }));
+      const first = result && Array.isArray(result.downloadUrls) ? result.downloadUrls[0] : null;
+      const url = first && first.url;
+      return typeof url === "string" && url.length > 0 ? url : null;
+    },
+  };
+}
+`;
+
+const ADAPTERS_SOURCE = `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
+//
+// Wiring only. Every decision lives in invoice-download-authorization.mjs; this file exists to
+// name the four Wix calls, and there is deliberately no logic in it to get wrong.
+import { members } from "@wix/members";
+import { orders } from "@wix/ecom";
+import { files } from "@wix/media";
+import { auth } from "@wix/essentials";
+import { createInvoiceAdapters } from "./invoice-download-authorization.mjs";
+
+export const wixInvoiceAdapters = createInvoiceAdapters({
+  getCurrentMember: () => members.getCurrentMember(),
+  // Unelevated ON PURPOSE. This call running as the caller is the whole authorization mechanism.
+  getOrderAsCaller: (id) => orders.getOrder(id),
+  getOrderElevated: (id) => auth.elevate(orders.getOrder)(id),
+  generateDownloadUrlElevated: (fileId, options) => auth.elevate(files.generateFileDownloadUrl)(fileId, options),
+});
+`;
+
+const ROUTE_SOURCE = `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
+//
+// Thin transport wrapper. All authorization lives in the handler and the adapters; this file only
+// moves JSON.
+import { createInvoiceDownloadHandler } from "../../lib/invoice-download.mjs";
+import { wixInvoiceAdapters } from "../../lib/invoice-download-adapters.mjs";
+
+const handler = createInvoiceDownloadHandler(wixInvoiceAdapters);
+
+export async function POST({ request }) {
+  let body = {};
+  try {
+    body = await request.json();
+  } catch {
+    return new Response(JSON.stringify({ error: "invalid-json" }), { status: 400, headers: { "content-type": "application/json" } });
+  }
+
+  const result = await handler({ body });
+  const { status, ...payload } = result;
+  return new Response(JSON.stringify(payload), { status, headers: { "content-type": "application/json" } });
+}
+`;
+
+export function buildHandlerSource() {
+  return handlerSource({
+    fileIdField: invoiceContract.ROLES.fileId,
+    numberField: invoiceContract.ROLES.number,
+    contractVersion: invoiceContract.version(),
+  });
+}
+
+// Adds what the generated route imports. Merges rather than overwrites: the scaffold owns its own
+// versions, and a project that already pins one of these keeps its pin.
+export async function ensureInvoiceDependencies({ outputDir }) {
+  const packagePath = path.join(outputDir, "package.json");
+  let manifest;
+  try {
+    manifest = await readJson(packagePath);
+  } catch {
+    return { packagePath, added: [], skipped: "no package.json at the output dir" };
+  }
+  const dependencies = manifest.dependencies || {};
+  const added = [];
+  for (const [name, version] of Object.entries(REQUIRED_DEPENDENCIES)) {
+    if (!dependencies[name]) {
+      dependencies[name] = version;
+      added.push(name);
+    }
+  }
+  if (added.length === 0) return { packagePath, added };
+  manifest.dependencies = dependencies;
+  await writeJson(packagePath, manifest);
+  return { packagePath, added };
+}
+
+export async function generateInvoiceDownloadBackend({ outputDir }) {
+  const handlerPath = path.join(outputDir, "src", "lib", "invoice-download.mjs");
+  const authorizationPath = path.join(outputDir, "src", "lib", "invoice-download-authorization.mjs");
+  const adaptersPath = path.join(outputDir, "src", "lib", "invoice-download-adapters.mjs");
+  const routePath = path.join(outputDir, "src", "pages", "api", "invoice-download.mjs");
+  await writeText(handlerPath, HANDLER_SOURCE);
+  await writeText(authorizationPath, AUTHORIZATION_SOURCE);
+  await writeText(adaptersPath, ADAPTERS_SOURCE);
+  await writeText(routePath, ROUTE_SOURCE);
+  const dependencies = await ensureInvoiceDependencies({ outputDir });
+  return { handlerPath, authorizationPath, adaptersPath, routePath, dependencies };
+}
+
+async function main() {
+  const args = parseArgs();
+  const outputDir = resolveOutputDir(args._[0] || args.url, args.out);
+  const written = await generateInvoiceDownloadBackend({ outputDir });
+  if (args.json) process.stdout.write(`${JSON.stringify(written, null, 2)}\n`);
+}
+
+// Computed once so consumers -- the tests included -- read exactly the bytes that get written.
+export const HANDLER_SOURCE = buildHandlerSource();
+
+export { AUTHORIZATION_SOURCE, ADAPTERS_SOURCE, ROUTE_SOURCE };
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await main();
+}

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";
+import { classifyBackground, classifyCanvas, buildRegions, classifyComposition, relationshipsFor } from "./lib/layout-blueprint/classifiers.mjs";
+import { LAYOUT_VOCABULARY_VERSION, VOCABULARY } from "./lib/layout-blueprint/vocabulary.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const outputDir = resolveOutputDir(args._[0] || args.url, args.out);
+  const blueprint = await generateLayoutBlueprint({ outputDir });
+  if (args.json) process.stdout.write(`${JSON.stringify(blueprint, null, 2)}\n`);
+}
+
+export async function generateLayoutBlueprint({ outputDir, pages: suppliedPages, interactionMap: suppliedInteractionMap, sceneContract: suppliedSceneContract } = {}) {
+  const docs = docsDir(outputDir);
+  const [sourceMap, interactionMap, sceneContract] = await Promise.all([
+    suppliedPages ? null : readJson(path.join(docs, "source-map.json")),
+    suppliedInteractionMap || readJson(path.join(docs, "interaction-map.json")),
+    suppliedSceneContract || readJson(path.join(docs, "scene-contract.json")),
+  ]);
+  const pages = suppliedPages || sourceMap?.pages || interactionMap?.pages || [];
+  const pageBlueprints = pages.map((page) => ({
+    url: page.url,
+    area: page.area || "page",
+    sections: (page.sections || []).map((section) => buildSectionBlueprint({ page, section, sceneContract })),
+  }));
+  const blueprint = {
+    schemaVersion: 1,
+    vocabularyVersion: LAYOUT_VOCABULARY_VERSION,
+    generatedAt: new Date().toISOString(),
+    sourceUrl: interactionMap?.sourceUrl || pages[0]?.url || "",
+    vocabulary: VOCABULARY,
+    implementationOrder: ["canvas", "background-layers", "container", "regions", "relationships", "responsive-reflow", "ui-normalization"],
+    pages: pageBlueprints,
+  };
+  await writeJson(path.join(docs, "layout-blueprint.json"), blueprint);
+  await writeText(path.join(docs, "layout-blueprint.md"), renderLayoutBlueprintMarkdown(blueprint));
+  return blueprint;
+}
+
+export function buildSectionBlueprint({ page, section, sceneContract = {} }) {
+  const pagePrefix = `${page.area || "page"}-`;
+  const scene = (sceneContract.scenes || []).find((candidate) => candidate.sectionId === section.id && candidate.id.startsWith(pagePrefix));
+  const canvas = classifyCanvas(section, scene);
+  const background = classifyBackground(section, scene);
+  const regions = buildRegions(section).map((region) => ({
+    ...region,
+    ...(region.text ? { responsiveTextGeometry: responsiveTextSamples(page, region.text) } : {}),
+  }));
+  const composition = classifyComposition({ section, scene, background, regions });
+  const relationships = relationshipsFor(composition, regions);
+  const confidence = section.layoutEvidence ? "measured" : scene ? "scene-inferred" : "heuristic";
+  return {
+    sectionId: section.id,
+    sourceClassification: { kind: section.kind || "section", variant: section.variant || "generic" },
+    composition,
+    canvas,
+    background,
+    container: inferContainer(canvas, regions),
+    regions,
+    relationships,
+    responsive: {
+      strategy: composition === "rail" ? "retain-rail-with-touch-overflow" : composition === "split" ? "stack-at-narrow-width" : "preserve-composition",
+      observedViewports: section.layoutEvidence?.viewport ? [section.layoutEvidence.viewport] : [],
+      inferred: true,
+    },
+    identityLocks: {
+      composition,
+      backgroundKind: background.kind,
+      mediaRole: background.layers.some((layer) => layer.role === "media") ? "background" : section.capabilities?.hasMedia ? "content" : "none",
+      relationships,
+      textGeometry: regions.filter((region) => region.textGeometry).map((region) => ({ role: region.role, text: region.text, ...region.textGeometry, responsive: region.responsiveTextGeometry || [] })),
+      forbiddenConversions: forbiddenConversions(composition),
+    },
+    implementation: implementationRecipe(composition, canvas, background, regions),
+    evidence: {
+      confidence,
+      sourceDomRef: section.domRef || null,
+      sceneId: scene?.id || null,
+      sourceScreenshot: scene?.sourceScreenshot || null,
+      warnings: section.layoutEvidence ? [] : ["layout-evidence-unavailable; rerun extraction for measured region geometry"],
+    },
+  };
+}
+
+function responsiveTextSamples(page, text) {
+  const target = String(text || "").replace(/\s+/g, " ").trim();
+  return Object.entries(page.responsiveTextGeometry || {}).map(([viewport, samples]) => {
+    const match = (samples || []).find((sample) => String(sample.text || "").replace(/\s+/g, " ").trim() === target);
+    return match ? { viewport, ...match } : null;
+  }).filter(Boolean);
+}
+
+function inferContainer(canvas, regions) {
+  const content = regions.filter((region) => region.role !== "media" && region.normalizedRect);
+  if (!content.length) return { widthMode: canvas.widthMode === "bounded" ? "bounded" : "full", maxWidthPx: null, inlineInsetRatio: null };
+  const left = Math.min(...content.map((region) => region.normalizedRect.x));
+  const right = Math.max(...content.map((region) => region.normalizedRect.x + region.normalizedRect.width));
+  return {
+    widthMode: left > 0.04 || right < 0.96 ? "bounded" : "full",
+    maxWidthPx: null,
+    inlineInsetRatio: { start: Number(left.toFixed(3)), end: Number((1 - right).toFixed(3)) },
+  };
+}
+
+function forbiddenConversions(composition) {
+  const map = {
+    "layered-overlay": ["split", "stack"],
+    "scroll-narrative": ["split", "static-stack"],
+    rail: ["static-grid"],
+    split: ["layered-overlay"],
+  };
+  return map[composition] || [];
+}
+
+function implementationRecipe(composition, canvas, background, regions) {
+  const steps = [
+    `Create one section root with ${canvas.widthMode} width and ${canvas.heightMode} height behavior.`,
+    `Build background layers in declared order: ${background.layers.map((layer) => `${layer.role}:${layer.kind}`).join(" -> ") || "none"}.`,
+  ];
+  if (["layered-overlay", "scroll-narrative"].includes(composition)) steps.push("Use one positioning context; keep background layers full-bleed and place foreground regions above them. Do not create media and copy as peer columns.");
+  if (composition === "split") steps.push("Use peer media and content regions with their captured left/right relationship; stack only at the declared narrow reflow.");
+  if (composition === "rail") steps.push("Use a clipped viewport and max-content horizontal track; preserve shared item geometry and active-state behavior.");
+  if (regions.length) steps.push("Place semantic regions from normalized rectangles and placement anchors before fine typography or motion polish.");
+  if (regions.some((region) => region.textGeometry)) steps.push("Apply each important text region's measured inline size, max-width, line count, and wrap policy. A captured single-line desktop heading must stay one line at the canonical desktop viewport.");
+  if (background.layers.some((layer) => layer.policy === "fallback-only")) steps.push("Render fallback-only posters only until primary media is ready; never leave them visibly stacked behind playing media.");
+  return { steps };
+}
+
+function renderLayoutBlueprintMarkdown(contract) {
+  const pages = contract.pages.map((page) => `# ${page.url}\n\n${page.sections.map((section) => `## ${section.sectionId}: ${section.composition}\n\n- Canvas: \`${section.canvas.widthMode}/${section.canvas.heightMode}\`${section.canvas.pinned ? ", pinned" : ""}\n- Background: \`${section.background.kind}\` (${section.background.layers.map((layer) => `${layer.role}:${layer.kind}`).join(" -> ") || "none"})\n- Container: \`${section.container.widthMode}\`\n- Identity locks: ${section.identityLocks.relationships.join(", ") || "composition and media role"}\n- Forbidden conversions: ${section.identityLocks.forbiddenConversions.map((item) => `\`${item}\``).join(", ") || "none"}\n\nRegions:\n${section.regions.map((region) => `- \`${region.role}\` at \`${region.placement}\`: ${JSON.stringify(region.normalizedRect)}${region.textGeometry ? `; text geometry ${JSON.stringify(region.textGeometry)}` : ""}${region.text ? ` — ${region.text}` : ""}`).join("\n") || "- no measured regions"}\n\nBuild order:\n${section.implementation.steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}\n\nEvidence: \`${section.evidence.confidence}\`${section.evidence.sourceScreenshot ? `; screenshot \`${section.evidence.sourceScreenshot}\`` : ""}`).join("\n\n")}`).join("\n\n");
+  return `# Section layout blueprints\n\nControlled vocabulary version: ${contract.vocabularyVersion}. Implement each section independently. Composition and layer order are identity locks; UI normalization comes last.\n\n${pages}\n`;
+}
+
+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/generate-repeater-cms.mjs

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { docsDir, ensureDir, writeJson, writeText } from "./lib/common.mjs";
+
+export async function generateRepeaterCms({ outputDir, pages }) {
+  const collections = (pages || []).flatMap((page) => (page.repeaters || []).filter((r) => r.kind === "accordion-repeater").map((r, index) => plan(page, r, index)));
+  const docs = docsDir(outputDir);
+  await writeJson(path.join(docs, "repeater-cms.json"), { version: 1, collections });
+  await writeText(path.join(docs, "repeater-cms.md"), `# CMS repeater plan\n\n${collections.map((c) => `## ${c.displayName}\n\n- id: \`${c.id}\`\n- rows: ${c.items.length}\n- state: \`${JSON.stringify(c.state)}\`\n- fields: \`label\`, \`body\`, \`imagesJson\`, \`linksJson\`, \`sortOrder\`, \`initialExpanded\`, \`itemStructure\``).join("\n\n") || "No accordion repeaters extracted."}\n`);
+  if (collections.length) await install(outputDir);
+  return { collections };
+}
+function plan(page, repeater, index) { const id = `rpAccordion${slug(`${page.area}-${repeater.label || index + 1}`).split("-").map((p) => p[0]?.toUpperCase() + p.slice(1)).join("")}`; return { id, displayName: `RePlatform Accordion: ${repeater.label || index + 1}`, sourceUrl: page.url, state: repeater.state || {}, items: (repeater.items || []).map((item, i) => ({ sourceKey: `${id}-${i + 1}`, label: item.heading || `Item ${i + 1}`, body: (item.paragraphs || []).join("\n\n"), imagesJson: JSON.stringify(item.images || []), linksJson: JSON.stringify(item.links || []), sortOrder: i, initialExpanded: Boolean(item.initialExpanded), itemStructure: item.itemStructure || "text-only" })) }; }
+async function install(outputDir) {
+  const lib = path.join(outputDir, "src", "lib"), components = path.join(outputDir, "src", "components");
+  await ensureDir(lib); await ensureDir(components);
+  await generated(path.join(lib, "rp-repeater-cms.ts"), `// @generated-source wix-headless-replatform\nexport async function loadAccordionRows(itemsApi:any,dataCollectionId:string){const r=await itemsApi.queryDataItems({dataCollectionId}).ascending("data.sortOrder").find();return (r.items||[]).map((x:any)=>x.data||x).sort((a:any,b:any)=>a.sortOrder-b.sortOrder)}\n`);
+  await generated(path.join(components, "RpAccordion.astro"), `---\n// @generated-source wix-headless-replatform\nconst { rows, dataCollectionId, singleOpen = true } = Astro.props;\n---\n<section data-rp-accordion={singleOpen?'single':'multiple'} data-rp-collection={dataCollectionId}>{rows.map((row)=><details open={row.initialExpanded}><summary>{row.label}</summary><div>{row.body.split('\\n\\n').map((p)=><p>{p}</p>)}</div></details>)}</section>\n<script>\nimport { items } from '@wix/data';\nconst escapeHtml=(value)=>String(value).replace(/[&<>'\\"]/g,(char)=>({'&':'&amp;','<':'&lt;','>':'&gt;',\"'\":'&#39;','\\"':'&quot;'}[char]));\nconst renderRows=(root,rows)=>root.replaceChildren(...rows.map((row)=>{const detail=document.createElement('details');detail.open=Boolean(row.initialExpanded);detail.innerHTML=\`<summary>\${escapeHtml(row.label)}</summary><div>\${String(row.body||'').split('\\\\n\\\\n').map((paragraph)=>\`<p>\${escapeHtml(paragraph)}</p>\`).join('')}</div>\`;return detail;}));\ndocument.querySelectorAll('[data-rp-collection]').forEach(async(root)=>{try{const result=await items.queryDataItems({dataCollectionId:root.dataset.rpCollection}).ascending('data.sortOrder').find();const cmsRows=(result.items||[]).map((item)=>item.data||item).sort((a,b)=>a.sortOrder-b.sortOrder);if(cmsRows.length){renderRows(root,cmsRows);root.dataset.rpCmsBound='true';}}catch(error){console.warn('RePlatform accordion CMS read failed; using extracted fallback content.',error);}});\ndocument.querySelectorAll('[data-rp-accordion=\"single\"]').forEach((root)=>root.addEventListener('toggle',(event)=>{const current=event.target;if(current.tagName==='DETAILS'&&current.open)root.querySelectorAll('details[open]').forEach((item)=>{if(item!==current)item.open=false;});},true));\n</script>\n`, migrateLegacyAccordion);
+}
+async function generated(file,text,migrate) { try { const existing = await readFile(file,"utf8"); if (!existing.includes("@generated-source wix-headless-replatform")) { const migrated = migrate?.(existing); if (migrated && migrated !== existing) await writeText(file,migrated); return; } } catch {} await writeText(file,text); }
+function migrateLegacyAccordion(text) { const legacyImport = "import { createClient, OAuthStrategy } from '@wix/sdk';\nimport { items } from '@wix/data';"; const legacyQuery = "const client=createClient({modules:{items},auth:OAuthStrategy({clientId:import.meta.env.WIX_CLIENT_ID})});const result=await client.items.queryDataItems"; if (!text.includes(legacyImport) || !text.includes(legacyQuery)) return text; return text.replace(legacyImport, "import { items } from '@wix/data';").replace(legacyQuery, "const result=await items.queryDataItems"); }
+function slug(v) { return String(v).toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-|-$/g,"") || "accordion"; }

package/skills/wix-headless-replatform/scripts/generate-route-plan.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import path from "node:path";
+import {
+  classifyTemplate,
+  docsDir,
+  isDynamicArea,
+  isAssetLikeUrl,
+  normalizeUrl,
+  parseArgs,
+  readJson,
+  resolveOutputDir,
+  routePathFromUrl,
+  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 routes = await generateRoutePlan({ sourceUrl: url, outputDir });
+  await writeJson(path.join(docsDir(outputDir), "routes.json"), routes);
+  if (args.json) process.stdout.write(`${JSON.stringify(routes, null, 2)}\n`);
+}
+
+export async function generateRoutePlan({ sourceUrl, outputDir }) {
+  const dir = docsDir(outputDir);
+  const discovery = await safeRead(path.join(dir, "discovery.json"), { pages: [] });
+  const pages = (discovery.pages || []).filter((page) => page?.url && !isAssetLikeUrl(page.url));
+  const inScopeUrls = new Set((discovery.inScopePages || pages.filter((page) => page.inScope))
+    .filter((page) => page?.url && !isAssetLikeUrl(page.url))
+    .map((page) => page.url));
+  const routes = [];
+  const inScopeRoutes = [];
+  const preservedFallbackLinks = [];
+  const dynamicSeen = new Set();
+  for (const page of pages) {
+    const inScope = inScopeUrls.has(page.url) || discovery.scope !== "specific";
+    if (!inScope) {
+      const route = notMigratedRouteFor({ sourceUrl, page });
+      routes.push(route);
+      preservedFallbackLinks.push(route);
+      continue;
+    }
+    if (isDynamicArea(page.area)) {
+      const template = classifyTemplate(page.area);
+      if (dynamicSeen.has(template)) {
+        const existing = routes.find((route) => route.template === template);
+        existing?.representativeUrls?.push(page.url);
+        continue;
+      }
+      dynamicSeen.add(template);
+      const route = dynamicRouteFor(page, template);
+      routes.push(route);
+      inScopeRoutes.push(route);
+      continue;
+    }
+    if (page.area === "home" || inStaticScope(page.area)) {
+      const route = {
+        sourceUrl: page.url,
+        sourcePath: routePathFromUrl(sourceUrl, page.url),
+        targetRoute: routePathFromUrl(sourceUrl, page.url) || "/",
+        kind: "static",
+        area: page.area,
+        representativeUrls: [page.url],
+      };
+      routes.push(route);
+      inScopeRoutes.push(route);
+      continue;
+    }
+    const route = notMigratedRouteFor({ sourceUrl, page });
+    routes.push(route);
+    preservedFallbackLinks.push(route);
+  }
+  return {
+    sourceUrl,
+    routes,
+    inScopeRoutes,
+    preservedFallbackLinks,
+    dynamicRouteCount: routes.filter((route) => route.kind === "dynamic").length,
+    notMigratedCount: routes.filter((route) => route.kind === "not-migrated").length,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+function notMigratedRouteFor({ sourceUrl, page }) {
+  const sourcePath = routePathFromUrl(sourceUrl, page.url);
+  return {
+    sourceUrl: page.url,
+    sourcePath,
+    targetRoute: `/not-migrated?from=${encodeURIComponent(sourcePath)}`,
+    kind: "not-migrated",
+    area: page.area,
+    representativeUrls: [page.url],
+  };
+}
+
+function dynamicRouteFor(page, template) {
+  const config = {
+    "product-detail": { targetRoute: "/products/[slug]", dataSource: "wix-stores" },
+    "product-category": { targetRoute: "/categories/[slug]", dataSource: "wix-stores" },
+    "blog-post": { targetRoute: "/blog/[slug]", dataSource: "wix-blog" },
+    "blog-index": { targetRoute: "/blog", dataSource: "wix-blog" },
+    "cms-item": { targetRoute: "/content/[slug]", dataSource: "wix-cms" },
+    booking: { targetRoute: "/bookings/[slug]", dataSource: "wix-bookings" },
+    event: { targetRoute: "/events/[slug]", dataSource: "wix-events" },
+    "pricing-plan": { targetRoute: "/pricing", dataSource: "wix-pricing-plans" },
+  }[template] || { targetRoute: `/${page.area}/[slug]`, dataSource: "wix-sdk" };
+  return {
+    sourcePattern: patternFor(page),
+    sourcePath: page.path,
+    targetRoute: config.targetRoute,
+    kind: "dynamic",
+    area: page.area,
+    template,
+    dataSource: config.dataSource,
+    representativeUrls: [page.url],
+  };
+}
+
+function patternFor(page) {
+  const parts = String(page.path || "/").split("/").filter(Boolean);
+  if (parts.length <= 1) return page.path || "/";
+  return `/${parts.slice(0, -1).join("/")}/*`;
+}
+
+function inStaticScope(area) {
+  return ["about-contact", "legal", "docs", "other"].includes(area);
+}
+
+async function safeRead(filePath, fallback) {
+  try {
+    return await readJson(filePath);
+  } catch {
+    return fallback;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}