@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-headless-replatform/scripts/lib/common.mjs

@@ -0,0 +1,329 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_VIEWPORTS = [
+  { name: "desktop", width: 1920, height: 1080 },
+  { name: "tablet", width: 834, height: 1112 },
+  { name: "mobile", width: 390, height: 844 },
+];
+
+export const DISCOVERY_LIMITS = {
+  home: { maxUrls: 1, maxDepth: 0 },
+  blog: { maxUrls: 50, maxDepth: 3, representativePosts: 3 },
+  ecommerce: { maxUrls: 75, maxDepth: 3, representativeProducts: 3, representativeCategories: 3 },
+  full: { maxUrls: 150, maxDepth: 3 },
+  specific: { maxUrls: 150, maxDepth: 1 },
+};
+
+export function parseArgs(argv = process.argv.slice(2)) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      args._.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      args[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+export function normalizeUrl(value) {
+  if (!value) throw new Error("Missing URL");
+  const withProtocol = /^https?:\/\//i.test(value) ? value : `https://${value}`;
+  const url = new URL(withProtocol);
+  url.hash = "";
+  return url;
+}
+
+export function sameOrigin(sourceUrl, candidate) {
+  try {
+    return new URL(candidate, sourceUrl).origin === new URL(sourceUrl).origin;
+  } catch {
+    return false;
+  }
+}
+
+export function normalizeDiscoveredUrl(sourceUrl, href) {
+  try {
+    const url = new URL(href, sourceUrl);
+    if (!/^https?:$/.test(url.protocol)) return null;
+    url.hash = "";
+    if (url.pathname !== "/" && url.pathname.endsWith("/")) {
+      url.pathname = url.pathname.slice(0, -1);
+    }
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+const NON_PAGE_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+  ".svg",
+  ".ico",
+  ".bmp",
+  ".avif",
+  ".mp4",
+  ".webm",
+  ".mov",
+  ".m4v",
+  ".mp3",
+  ".wav",
+  ".ogg",
+  ".pdf",
+  ".zip",
+  ".rar",
+  ".7z",
+  ".tar",
+  ".gz",
+  ".xml",
+  ".json",
+  ".txt",
+  ".css",
+  ".js",
+  ".mjs",
+  ".map",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+]);
+
+export function isAssetLikeUrl(urlValue) {
+  try {
+    const url = new URL(urlValue);
+    const pathname = url.pathname.toLowerCase();
+    const extension = path.extname(pathname);
+    if (NON_PAGE_EXTENSIONS.has(extension)) return true;
+    return pathname.includes("/wp-content/uploads/");
+  } catch {
+    return false;
+  }
+}
+
+export function projectNameFromUrl(urlValue) {
+  const url = normalizeUrl(urlValue);
+  let host = url.hostname.toLowerCase().replace(/^www\./, "");
+  const parts = host.split(".");
+  if (parts.length === 2) host = parts[0];
+  return kebab(host);
+}
+
+export function kebab(value) {
+  return String(value || "site")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-") || "site";
+}
+
+export function resolveOutputDir(urlValue, out) {
+  if (out) return path.normalize(out);
+  return path.join("projects", projectNameFromUrl(urlValue));
+}
+
+export function docsDir(outputDir) {
+  return path.join(outputDir, "docs", "site-clone");
+}
+
+export async function ensureDir(dir) {
+  await mkdir(dir, { recursive: true });
+}
+
+export async function writeJson(filePath, data) {
+  await ensureDir(path.dirname(filePath));
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+export async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+export async function writeText(filePath, data) {
+  await ensureDir(path.dirname(filePath));
+  await writeFile(filePath, data, "utf8");
+}
+
+export async function fetchText(url, options = {}) {
+  const timeoutMs = Number(options.timeoutMs || 5000);
+  const response = await fetch(url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: {
+      "user-agent": "site-clone-skill/1.0 (+https://wix-headless.dev)",
+      accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+      ...options.headers,
+    },
+  });
+  if (!response.ok) throw new Error(`Fetch failed ${response.status} for ${url}`);
+  return response.text();
+}
+
+export function extractLinks(html, baseUrl) {
+  const links = [];
+  const pattern = /<a\b[^>]*href\s*=\s*["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
+  let match;
+  while ((match = pattern.exec(html))) {
+    const url = normalizeDiscoveredUrl(baseUrl, match[1]);
+    if (!url) continue;
+    links.push({
+      url,
+      text: stripTags(match[2]).replace(/\s+/g, " ").trim(),
+    });
+  }
+  return dedupeBy(links, (link) => link.url);
+}
+
+export function stripTags(value) {
+  return String(value || "")
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .trim();
+}
+
+export function classifyUrl(urlValue) {
+  const url = new URL(urlValue);
+  const pathValue = url.pathname.toLowerCase();
+  const joined = `${pathValue} ${url.search.toLowerCase()}`;
+  if (isAssetLikeUrl(urlValue)) return "asset";
+  if (pathValue === "/" || pathValue === "") return "home";
+  if (/(\/products?\/|\/product\/|\/shop\/[^/]+|[?&]product=)/.test(joined)) return "product";
+  if (/(\/collections?\/|\/categories?\/|\/category\/|\/shop\/?$|\/store\/?$)/.test(joined)) return "product-category";
+  if (/(\/blog\/[^/]+|\/posts?\/[^/]+|\/article\/)/.test(joined)) return "blog-post";
+  if (/(\/blog\/?$|\/news\/?$|\/articles\/?$)/.test(joined)) return "blog-index";
+  if (/(\/booking|\/bookings|\/appointments?|\/schedule)/.test(joined)) return "bookings";
+  if (/(\/events?\/|\/event\/)/.test(joined)) return "events";
+  if (/(\/pricing|\/plans|\/membership)/.test(joined)) return "pricing";
+  if (/(\/docs|\/documentation|\/help|\/support|\/kb)/.test(joined)) return "docs";
+  if (/(\/about|\/contact|\/team|\/company)/.test(joined)) return "about-contact";
+  if (/(\/privacy|\/terms|\/legal|\/cookies?)/.test(joined)) return "legal";
+  if (/(\/cms|\/resources?|\/guides?|\/case-stud)/.test(joined)) return "cms-content";
+  return "other";
+}
+
+export function classifyTemplate(area) {
+  const dynamic = {
+    product: "product-detail",
+    "product-category": "product-category",
+    "blog-post": "blog-post",
+    "blog-index": "blog-index",
+    "cms-content": "cms-item",
+    bookings: "booking",
+    events: "event",
+    pricing: "pricing-plan",
+  };
+  return dynamic[area] || area;
+}
+
+export function isDynamicArea(area) {
+  return [
+    "product",
+    "product-category",
+    "blog-post",
+    "blog-index",
+    "cms-content",
+    "bookings",
+    "events",
+    "pricing",
+  ].includes(area);
+}
+
+export function countBy(items, keyFn) {
+  const counts = {};
+  for (const item of items) {
+    const key = keyFn(item);
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+export function dedupeBy(items, keyFn) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const key = keyFn(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+export function slugForUrl(urlValue) {
+  const url = new URL(urlValue);
+  return kebab(`${url.hostname}${url.pathname === "/" ? "-home" : url.pathname}`);
+}
+
+export function routePathFromUrl(sourceUrl, targetUrl) {
+  const url = new URL(targetUrl, sourceUrl);
+  return `${url.pathname}${url.search}` || "/";
+}
+
+export function selectWixTemplate(scope, counts = {}) {
+  if (scope === "ecommerce" || counts.product || counts["product-category"]) return "commerce";
+  if (counts.bookings) return "scheduler";
+  if (counts.events || counts.pricing) return "registration";
+  return "blank";
+}
+
+export function businessNameFromProject(projectName) {
+  return projectName
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export function wixFolderNameFromProject(projectName) {
+  return kebab(projectName);
+}
+
+export function wixBusinessNameFromProject(projectName) {
+  const value = businessNameFromProject(wixFolderNameFromProject(projectName));
+  return value || "Site";
+}
+
+export function limitRepresentativePages(pages, scope) {
+  const limits = DISCOVERY_LIMITS[scope] || DISCOVERY_LIMITS.full;
+  const counts = {};
+  return pages.filter((page) => {
+    if (page.area === "asset") return false;
+    const area = page.area;
+    if (area === "product") {
+      counts.product = (counts.product || 0) + 1;
+      return counts.product <= (limits.representativeProducts || 3);
+    }
+    if (area === "product-category") {
+      counts["product-category"] = (counts["product-category"] || 0) + 1;
+      return counts["product-category"] <= (limits.representativeCategories || 3);
+    }
+    if (area === "blog-post") {
+      counts["blog-post"] = (counts["blog-post"] || 0) + 1;
+      return counts["blog-post"] <= (limits.representativePosts || 3);
+    }
+    return true;
+  });
+}

package/skills/wix-headless-replatform/scripts/lib/component-capabilities.mjs

@@ -0,0 +1,121 @@
+export const COMPONENT_CAPABILITIES_SCHEMA_VERSION = "component-capabilities/1";
+
+const TOP_LEVEL_FIELDS = new Set([
+  "$schema", "schemaVersion", "component", "contract", "axes", "slots", "states",
+  "defaultComposition", "compositions", "unsupportedCompositions", "constraints", "evidenceRefs",
+]);
+const SLOT_KINDS = new Set(["text", "icon", "url", "action", "media", "content", "boolean", "number"]);
+
+export function validateComponentCapabilities(manifest, expected = {}) {
+  const errors = [];
+  if (!isObject(manifest)) return { ok: false, errors: ["capability manifest must be an object"] };
+  for (const field of Object.keys(manifest)) if (!TOP_LEVEL_FIELDS.has(field)) errors.push(`unknown top-level field: ${field}`);
+  if (manifest.schemaVersion !== COMPONENT_CAPABILITIES_SCHEMA_VERSION) errors.push(`schemaVersion must be ${COMPONENT_CAPABILITIES_SCHEMA_VERSION}`);
+  if (!isObject(manifest.component) || !manifest.component.name || !manifest.component.revision) errors.push("component name and revision are required");
+  if (!isObject(manifest.contract) || !manifest.contract.name || !manifest.contract.version) errors.push("contract name and version are required");
+  rejectUnknown(manifest.component, new Set(["name", "revision"]), "component", errors);
+  rejectUnknown(manifest.contract, new Set(["name", "version"]), "contract", errors);
+  if (expected.name && manifest.component?.name !== expected.name) errors.push(`component name must be ${expected.name}`);
+  if (expected.revision && manifest.component?.revision !== expected.revision) errors.push(`component revision must be ${expected.revision}`);
+  if (expected.contract && manifest.contract?.name !== expected.contract) errors.push(`contract name must be ${expected.contract}`);
+
+  const axes = uniqueNamed(manifest.axes, "axis", errors);
+  for (const axis of axes) {
+    if (!Array.isArray(axis.values) || !axis.values.length || axis.values.some((value) => typeof value !== "string")) errors.push(`axis ${axis.name} requires string values`);
+    if (new Set(axis.values || []).size !== (axis.values || []).length) errors.push(`axis ${axis.name} values must be unique`);
+    if (!axis.values?.includes(axis.default)) errors.push(`axis ${axis.name} default must be one of its values`);
+    rejectUnknown(axis, new Set(["name", "values", "default", "description"]), `axis ${axis.name}`, errors);
+  }
+  const slots = uniqueNamed(manifest.slots, "slot", errors);
+  for (const slot of slots) {
+    if (!SLOT_KINDS.has(slot.kind)) errors.push(`slot ${slot.name} has unsupported kind ${slot.kind}`);
+    rejectUnknown(slot, new Set(["name", "kind", "description"]), `slot ${slot.name}`, errors);
+  }
+  uniqueStrings(manifest.states, "states", errors);
+  const compositions = uniqueNamed(manifest.compositions, "composition", errors);
+  const compositionNames = new Set(compositions.map((entry) => entry.name));
+  const slotNames = new Set(slots.map((entry) => entry.name));
+  if (!compositionNames.has(manifest.defaultComposition)) errors.push("defaultComposition must name a supported composition");
+  for (const composition of compositions) {
+    uniqueStrings(composition.requiredSlots, `composition ${composition.name} requiredSlots`, errors);
+    for (const slot of composition.requiredSlots || []) if (!slotNames.has(slot)) errors.push(`composition ${composition.name} references unknown slot ${slot}`);
+    rejectUnknown(composition, new Set(["name", "requiredSlots", "description"]), `composition ${composition.name}`, errors);
+  }
+  const unsupported = uniqueNamed(manifest.unsupportedCompositions, "unsupported composition", errors);
+  for (const entry of unsupported) {
+    if (!entry.reason) errors.push(`unsupported composition ${entry.name} requires a reason`);
+    if (compositionNames.has(entry.name)) errors.push(`composition ${entry.name} cannot be both supported and unsupported`);
+    rejectUnknown(entry, new Set(["name", "reason"]), `unsupported composition ${entry.name}`, errors);
+  }
+  const constraints = uniqueNamed(manifest.constraints, "constraint", errors, "id");
+  for (const constraint of constraints) {
+    if (!constraint.description) errors.push(`constraint ${constraint.id} requires a description`);
+    uniqueStrings(constraint.appliesTo, `constraint ${constraint.id} appliesTo`, errors);
+    uniqueStrings(constraint.requires, `constraint ${constraint.id} requires`, errors);
+    rejectUnknown(constraint, new Set(["id", "description", "appliesTo", "requires"]), `constraint ${constraint.id}`, errors);
+  }
+  uniqueStrings(manifest.evidenceRefs, "evidenceRefs", errors, { minimum: 1 });
+  return { ok: errors.length === 0, errors };
+}
+
+export function resolveCapabilityBinding(manifest, requirements = {}) {
+  const validation = validateComponentCapabilities(manifest);
+  if (!validation.ok) return { ok: false, reasons: validation.errors };
+  const reasons = [];
+  const axes = Object.fromEntries(manifest.axes.map((axis) => [axis.name, requirements.axes?.[axis.name] ?? axis.default]));
+  for (const [name, value] of Object.entries(requirements.axes || {})) {
+    const axis = manifest.axes.find((entry) => entry.name === name);
+    if (!axis) reasons.push(`unsupported-axis:${name}`);
+    else if (!axis.values.includes(value)) reasons.push(`unsupported-axis-value:${name}=${value}`);
+  }
+  const compositionName = requirements.composition || manifest.defaultComposition;
+  const composition = manifest.compositions.find((entry) => entry.name === compositionName);
+  if (!composition) reasons.push(`unsupported-composition:${compositionName}`);
+  const availableSlots = new Set(requirements.availableSlots || []);
+  for (const slot of requirements.requiredSlots || []) {
+    if (!manifest.slots.some((entry) => entry.name === slot)) reasons.push(`unsupported-slot:${slot}`);
+  }
+  for (const slot of composition?.requiredSlots || []) if (!availableSlots.has(slot)) reasons.push(`missing-slot:${slot}`);
+  for (const state of requirements.requiredStates || []) if (!manifest.states.includes(state)) reasons.push(`unsupported-state:${state}`);
+
+  const selectedTokens = new Set([
+    `composition:${compositionName}`,
+    ...Object.entries(axes).map(([name, value]) => `axis:${name}=${value}`),
+    ...[...availableSlots].map((slot) => String(slot).startsWith("slot:") ? slot : `slot:${slot}`),
+  ]);
+  for (const constraint of manifest.constraints) {
+    if ((constraint.appliesTo || []).every((token) => selectedTokens.has(token))) {
+      for (const token of constraint.requires || []) if (!selectedTokens.has(token)) reasons.push(`constraint:${constraint.id}:${token}`);
+    }
+  }
+  return {
+    ok: reasons.length === 0,
+    reasons: [...new Set(reasons)],
+    binding: { axes, composition: compositionName, availableSlots: [...availableSlots].sort() },
+  };
+}
+
+function uniqueNamed(value, label, errors, key = "name") {
+  if (!Array.isArray(value)) {
+    errors.push(`${label}s must be an array`);
+    return [];
+  }
+  const entries = value.filter((entry) => isObject(entry));
+  if (entries.length !== value.length) errors.push(`${label}s must contain objects`);
+  const names = entries.map((entry) => entry[key]);
+  if (names.some((name) => typeof name !== "string" || !name)) errors.push(`${label}s require ${key}`);
+  if (new Set(names).size !== names.length) errors.push(`${label} ${key}s must be unique`);
+  return entries;
+}
+
+function uniqueStrings(value, label, errors, { minimum = 0 } = {}) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry)) errors.push(`${label} must contain strings`);
+  else if (new Set(value).size !== value.length) errors.push(`${label} must be unique`);
+  if ((value?.length || 0) < minimum) errors.push(`${label} must contain at least ${minimum} item(s)`);
+}
+
+function rejectUnknown(value, allowed, label, errors) {
+  for (const field of Object.keys(value || {})) if (!allowed.has(field)) errors.push(`${label} has unknown field ${field}`);
+}
+
+function isObject(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }