@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-replatform/resources/rp-target-wix/lib/wix-build.js

@@ -1,388 +0,0 @@
-'use strict';
-
-// rp-target-wix — the DETERMINISTIC canonical -> Wix payload builder.
-//
-// Replaces the per-project, LLM-authored `src/import/transforms/to-wix.js`. Everything in here is
-// vendor-independent: it consumes a CANONICAL record (see wix-target-spec.js CANONICAL_FIELDS) and
-// emits a Wix Stores V3 create body. Nothing about Shopify, Woo, Magento or BigCommerce appears —
-// that asymmetry is exactly why this layer never needed to be regenerated per run.
-//
-// Scalar placement is driven by the spec (payloadPath / wrap / coerce). The four structural
-// builders — variants, options, media, seoData — are spec-*declared* (`via`) but hand-implemented,
-// because a fully declarative encoding of "variants reference option choices BY NAME" would be a
-// worse artifact than the twenty lines it replaces. The spec still owns WHICH canonical fields
-// route through them, so coverage reporting stays complete.
-
-const { inventoryForVariant } = require('./stores-inventory.js');
-const { STORES_V3_TARGET, CATEGORY_TARGET, CANONICAL_FIELDS } = require('./wix-target-spec.js');
-
-// --- coercion --------------------------------------------------------------
-// Money must be an OBJECT ({ amount: '20.00' }); a bare number 400s. Decimal STRINGS avoid float
-// drift on amounts that came out of a CSV as text in the first place.
-function money(amount) {
-  const n = Number(amount);
-  if (!Number.isFinite(n)) throw new Error(`money: "${amount}" is not a finite number`);
-  return { amount: n.toFixed(2) };
-}
-
-// Wix rejects a slug containing ^!“”$%&'*+,.:;<>=?@\/()[]{}_|` ~#. Vendors mint illegal ones
-// routinely — Shopify turns a decimal size into an underscore (ph-5_5), which 400s the whole
-// bulk batch, so this runs on EVERY slug rather than being a vendor quirk.
-//
-// CORRECTED 2026-09-27: this used to collapse to `[^a-z0-9-]+` — an ASCII allowlist that also
-// stripped every non-Latin letter (Hebrew, Chinese, Cyrillic, ...), silently sanitizing an
-// all-non-Latin slug down to near-empty. Confirmed live: non-Latin (e.g. Hebrew)
-// product slugs written via direct PATCH read back byte-identical (see
-// domains/stores/entities/product.json's wordpress-percent-encoded-slug pitfall, which only
-// documents Wix stripping literal '%', never a non-Latin-letter rejection). Stripping non-Latin
-// letters here would otherwise silently defeat decodeWpSlug's percent-decode for every non-Latin
-// source site: decode restores the real non-Latin text, then this function threw it away again.
-//
-// REWRITTEN 2026-09-29: a hand
-// enumerated punctuation BLOCKLIST is what the comment above still describes Wix's actual rule as
-// -- but successive checks each found a DIFFERENT class of character neither this
-// blocklist nor its two follow-on patches (C0/C1 control bytes, then Cf zero-width/format chars)
-// happened to cover, most recently other Unicode symbols/punctuation entirely outside all three
-// enumerations (™, §, •, an em dash, ½, ...). A blocklist enumeration is structurally incomplete
-// by construction -- there is always a next uncovered class -- so this is now the other shape of
-// the same rule, an ALLOWLIST of what to KEEP: Unicode letters (\p{L}, live-verified safe: the non-Latin
-// slugs above), combining marks (\p{M}, so a decomposed accented letter written as base +
-// combining accent, e.g. "e" + U+0301, survives as one unit instead of splitting into a hyphen),
-// and decimal digits (\p{Nd} specifically, not the broader \p{N} -- Unicode "Other Number" also
-// covers vulgar fractions and Roman numerals like "½"/"Ⅷ", which are exactly the kind of
-// symbol-shaped character this rewrite exists to stop assuming is a safe slug character just
-// because it happens to be a "number"). Everything outside that set -- known punctuation, control
-// bytes, format chars, or a class nobody has hit yet -- becomes a hyphen. An allowlist by category
-// is exhaustive; a blocklist enumeration cannot be, which is the whole reason this needed a 4th
-// patch after three were already shipped.
-const WIX_SLUG_ILLEGAL_CHARS = /[^\p{L}\p{M}\p{Nd}-]/gu;
-function toWixSlug(raw) {
-  const slug = String(raw == null ? '' : raw)
-    .toLowerCase()
-    .replace(/[\s_]+/g, '-')
-    .replace(WIX_SLUG_ILLEGAL_CHARS, '-')
-    .replace(/-{2,}/g, '-')
-    .replace(/^-+|-+$/g, '');
-  // Non-empty is not enough: \p{M} combining marks (kept above for a decomposed accented
-  // letter, base + combining accent) also cover invisible marks like emoji variation selectors
-  // (U+FE0F etc), so an emoji/symbol-only title -- "heavy black heart" + VS-16, say -- can
-  // sanitize to a slug made of nothing but an invisible character. Require the survivor to carry
-  // at least one actual letter or digit; anything else is the same "no usable slug" case as
-  // sanitizing to empty, and gets the same deterministic-source-id-fallback treatment from the
-  // caller.
-  if (!slug || !/[\p{L}\p{Nd}]/u.test(slug)) {
-    throw new Error(`toWixSlug: "${raw}" sanitizes to an empty slug`);
-  }
-  return slug;
-}
-
-function coerceBoolean(value, fallback) {
-  if (value === true || value === false) return value;
-  if (value == null || value === '') return fallback;
-  const s = String(value).trim().toLowerCase();
-  if (['true', '1', 'yes', 'y', 'active', 'published', 'enabled', 'visible'].includes(s)) return true;
-  if (['false', '0', 'no', 'n', 'draft', 'archived', 'disabled', 'hidden'].includes(s)) return false;
-  return fallback;
-}
-
-const COERCE = { slug: toWixSlug, money, boolean: coerceBoolean };
-
-function isBlank(value) {
-  return value == null || value === '' || (Array.isArray(value) && value.length === 0);
-}
-
-// Classification is deliberately based on visible text, while the value returned to Wix retains
-// its source HTML. WooCommerce descriptions regularly contain empty wrappers, &nbsp;, or the
-// stock "Lorem ipsum" filler; importing any of those is equivalent to importing no copy.
-function normalizedDescriptionText(value) {
-  return String(value == null ? '' : value)
-    .replace(/<!--[\s\S]*?-->/g, ' ')
-    .replace(/<[^>]*>/g, ' ')
-    .replace(/&(nbsp|#0*160|#x0*a0);/gi, ' ')
-    .replace(/&(amp|quot|#0*39|#x0*27);/gi, ' ')
-    .normalize('NFKC')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function isPlaceholderDescription(value) {
-  return normalizedDescriptionText(value).toLowerCase().startsWith('lorem ipsum');
-}
-
-// Wix Stores has one product description, whereas WooCommerce supplies a short, above-the-fold
-// body and a long body. Preserve each non-placeholder source body in source reading order. The
-// horizontal rule is intentional content structure, not a visual approximation with blank lines.
-function composeProductDescription({ description, shortDescription } = {}) {
-  const long = normalizedDescriptionText(description) && !isPlaceholderDescription(description) ? description : undefined;
-  const short = normalizedDescriptionText(shortDescription) && !isPlaceholderDescription(shortDescription) ? shortDescription : undefined;
-  if (short && long) return `${short}\n<hr />\n${long}`;
-  return short || long;
-}
-
-// --- structural builders ---------------------------------------------------
-// Option definitions are derived from the variants' own choices, so a value that never occurs
-// cannot produce a phantom choice. Order is first-seen, which preserves the source's ordering.
-function buildOptions(product) {
-  const names = product.optionNames || [];
-  return names.map((name) => {
-    const seen = new Map();
-    for (const variant of product.variants || []) {
-      for (const choice of variant.choices || []) {
-        if (choice.optionName === name && !seen.has(choice.choiceName)) {
-          seen.set(choice.choiceName, { choiceType: 'CHOICE_TEXT', name: choice.choiceName });
-        }
-      }
-    }
-    return { name, optionRenderType: 'TEXT_CHOICES', choicesSettings: { choices: [...seen.values()] } };
-  });
-}
-
-// A variant references its option choices BY NAME; the API returns server-assigned choice ids.
-// An empty `choices: []` is the correct encoding of "this product has no real options" — it must
-// produce a single default variant, never a synthetic one-choice option.
-function buildVariants(product, { inStock } = {}) {
-  return (product.variants || []).map((variant) => {
-    const out = {
-      visible: coerceBoolean(variant.visible, true),
-      choices: (variant.choices || []).map((choice) => ({
-        optionChoiceNames: {
-          optionName: choice.optionName,
-          choiceName: choice.choiceName,
-          renderType: 'TEXT_CHOICES',
-        },
-      })),
-      price: buildVariantPrice(variant),
-    };
-    const inventory = inventoryForVariant(variant, { inStock });
-    if (inventory) out.inventoryItem = inventory;
-    if (!isBlank(variant.sku)) out.sku = String(variant.sku);
-    // Weight is expected already converted to the site's unit by the adapter; the canonical field
-    // carries a number, not a unit-bearing string.
-    if (!isBlank(variant.weight)) out.physicalProperties = { weight: Number(variant.weight) };
-    return out;
-  });
-}
-
-// Implements STORES_V3_TARGET.priceResolution.
-//
-// Two vendor idioms converge here. Shopify ships (price, compareAtPrice); Woo / Magento /
-// BigCommerce ship (regular price, sale price) — which the overlays map to
-// (variant.price, variant.discountedPrice). Wix models `actualPrice` (charged) plus
-// `compareAtPrice` (strike-through), so a sale price has to be PROMOTED to actualPrice and the
-// regular price demoted to the strike-through. Getting this backwards silently overcharges every
-// discounted product, which is why the rule lives in the spec instead of being re-decided per run.
-//
-// TRAP (verified): Wix rejects compareAtPrice <= actualPrice. Vendors write 0.00 — and Woo writes
-// an empty cell — to mean "no discount", so a not-strictly-greater compare-at is DROPPED.
-function buildVariantPrice(variant) {
-  const listPrice = Number(variant.price);
-  const discounted = variant.discountedPrice;
-
-  let actual = listPrice;
-  let compare = variant.compareAtPrice;
-  if (!isBlank(discounted) && Number(discounted) > 0 && Number(discounted) < listPrice) {
-    actual = Number(discounted);
-    compare = listPrice;
-  }
-
-  const out = { actualPrice: money(actual) };
-  if (!isBlank(compare) && Number(compare) > actual) out.compareAtPrice = money(compare);
-  return out;
-}
-
-// External URLs on media.itemsInfo.items[] are the preferred path: Wix ingests them server-side in
-// the background, avoiding the throttled Media Manager pre-import. The FIRST item becomes the
-// product's main media, so caller-side ordering matters.
-// TRAP: reading these back needs `?fields=MEDIA_ITEMS_INFO`; a plain GET returns only media.main
-// and looks empty even on a successful ingest.
-//
-// The url this emits is a REQUEST TO FETCH, not a stored file. Wix returns 200 before it has
-// fetched anything, and a failed background fetch drops the item and leaves the product with an
-// EMPTY gallery — silently, and after the old image was already replaced. A caller
-// that writes this media and trusts the 200 has not finished; use
-// `patchStoresProductMediaVerified` or run an equivalent read-back sweep.
-//
-// `image.url` MUST arrive already resolved to the source's original, maximum-resolution file and
-// already percent-encoded. Wix copies exactly the one file this URL points at and
-// generates every derivative from it, with no way to raise the quality afterwards — so a crop
-// passed here is that product's permanent ceiling. Do not "helpfully" reach back to a raw source
-// field such as `src` here; the source adapter owns that choice and knows which of the several
-// URLs the source offered is the biggest.
-function buildMedia(product) {
-  const items = (product.images || [])
-    .filter((image) => image && image.fetchable !== false && !isBlank(image.url))
-    .map((image) => ({
-      url: image.url,
-      ...(isBlank(image.altText) ? {} : { altText: image.altText }),
-      ...(isBlank(image.displayName) ? {} : { displayName: image.displayName }),
-    }));
-  return items.length ? { itemsInfo: { items } } : null;
-}
-
-// A product that carries `seoEvidence` (an evidence-contract source such as Yoast on
-// WooCommerce) emits a tag ONLY for a proven per-field override, or for the owner's explicit
-// `materialize` choice via `seoPlan` (rp-target-wix/lib/product-seo.js planProductSeo). Its
-// `seoTitle`/`seoDescription` are ignored: on such sources those are rendered template output,
-// and writing them turns an inherited pattern into a hard per-product override. A proven override
-// is written even when it equals the product name.
-//
-// A product WITHOUT `seoEvidence` is the legacy CSV path (Shopify/Magento/BigCommerce SEO
-// columns are authored per-product values): unchanged, including the duplicate-of-name skip.
-function buildSeoData(product, { seoPlan } = {}) {
-  if (product.seoEvidence !== undefined && product.seoEvidence !== null) {
-    let tags;
-    if (seoPlan) {
-      if (seoPlan.productId !== undefined && product.sourceId != null && String(seoPlan.productId) !== String(product.sourceId)) {
-        throw new Error(`buildSeoData: seoPlan for ${seoPlan.productId} passed for product ${product.sourceId}`);
-      }
-      tags = seoPlan.tags;
-    } else {
-      tags = [];
-      const ev = product.seoEvidence;
-      if (ev.title && ev.title.state === 'override' && !isBlank(ev.title.value)) tags.push({ type: 'title', children: String(ev.title.value) });
-      if (ev.description && ev.description.state === 'override' && !isBlank(ev.description.value)) {
-        tags.push({ type: 'meta', props: { name: 'description', content: String(ev.description.value) } });
-      }
-    }
-    return tags.length ? { tags: tags.map((tag) => JSON.parse(JSON.stringify(tag))) } : null;
-  }
-  const tags = [];
-  if (!isBlank(product.seoTitle) && String(product.seoTitle).trim() !== String(product.name || '').trim()) {
-    tags.push({ type: 'title', children: String(product.seoTitle) });
-  }
-  if (!isBlank(product.seoDescription)) {
-    tags.push({ type: 'meta', props: { name: 'description', content: String(product.seoDescription) } });
-  }
-  return tags.length ? { tags } : null;
-}
-
-// --- product ---------------------------------------------------------------
-function setPath(target, path, value) {
-  const parts = path.split('.');
-  let cursor = target;
-  for (let i = 0; i < parts.length - 1; i += 1) {
-    cursor[parts[i]] = cursor[parts[i]] || {};
-    cursor = cursor[parts[i]];
-  }
-  cursor[parts[parts.length - 1]] = value;
-}
-
-// `sourceDeclaredOptionNames` says which options the SOURCE declared, independent of
-// whether any variant choices could be resolved from them. `choices: []` must keep meaning "no
-// real options", so a product that declared options yet built none is a LOST-options product,
-// and it throws unless the caller passes the user's own recorded decision for THIS product. The
-// decision is bound twice (key and value both name `product.sourceId`), so product A's entry can
-// never be replayed for B, even by rebuilding the key from B's id.
-function isValidOptionLossDecision(product, decision) {
-  if (!decision || typeof decision !== 'object') return false;
-  const { key, entry } = decision;
-  const sourceId = product.sourceId == null ? '' : String(product.sourceId);
-  if (!sourceId.trim() || key !== `optionLoss:${sourceId}`) return false;
-  if (!entry || typeof entry !== 'object' || entry.source !== 'user') return false;
-  const value = entry.value;
-  if (!value || typeof value !== 'object') return false;
-  if (value.accept !== 'default-variant' || value.sourceProductId !== sourceId) return false;
-  const declared = product.sourceDeclaredOptionNames;
-  const accepted = value.declaredOptionNames;
-  return (
-    Array.isArray(accepted) &&
-    accepted.length === declared.length &&
-    accepted.every((name, index) => name === declared[index])
-  );
-}
-
-function assertDeclaredOptionsResolved(product, options, optionLossDecision) {
-  const declared = product.sourceDeclaredOptionNames;
-  if (declared === undefined || declared === null) return;
-  if (!Array.isArray(declared)) {
-    throw new Error(`buildProduct: "${product.name}" sourceDeclaredOptionNames must be an array of option names`);
-  }
-  if (!declared.length || options.length) return;
-  if (isValidOptionLossDecision(product, optionLossDecision)) return;
-  throw new Error(
-    `buildProduct: "${product.name}" (${product.sourceId}) declared options [${declared.join(', ')}] but resolved to zero; record the loss in mapping-gaps.json (no valid human optionLoss decision for this product).`,
-  );
-}
-
-// Builds the Stores V3 create body from a canonical product record.
-// Explicit variant stock wins. A caller may supply an approved fallback for missing stock;
-// there is no implicit availability default. Codegen reports variants without stock evidence.
-function buildProduct(product, { inStock, target = STORES_V3_TARGET, optionLossDecision, seoPlan } = {}) {
-  if (isBlank(product.name)) throw new Error('buildProduct: product.name is required');
-  const body = { ...target.constants };
-  const composedDescription = composeProductDescription(product);
-
-  // Spec-driven scalars.
-  for (const [canonicalPath, fieldSpec] of Object.entries(target.fields)) {
-    if (!fieldSpec.payloadPath) continue; // structural: handled below
-    const key = canonicalPath.replace(/^product\./, '');
-    let value = canonicalPath === 'product.description' ? composedDescription : product[key];
-    const def = CANONICAL_FIELDS[canonicalPath] || {};
-    if (isBlank(value) && def.default !== undefined) value = def.default;
-    if (isBlank(value) && typeof value !== 'boolean') continue;
-    if (fieldSpec.coerce && COERCE[fieldSpec.coerce]) value = COERCE[fieldSpec.coerce](value);
-    else if (def.kind === 'boolean') value = coerceBoolean(value, def.default);
-    // A spec-declared length cap is enforced here rather than truncated: silently shortening a
-    // description is exactly the invisible data loss this pipeline exists to avoid, and the caller
-    // is the one who can decide between truncating, splitting into an info section, or skipping.
-    if (fieldSpec.maxLength && typeof value === 'string' && value.length > fieldSpec.maxLength) {
-      throw new Error(
-        `buildProduct: "${product.name}" has a ${value.length}-character ${canonicalPath} but Wix caps ${fieldSpec.payloadPath} at ${fieldSpec.maxLength}. Truncate it, move the overflow into an info section, or skip the field — and record the loss in mapping-gaps.json.`,
-      );
-    }
-    setPath(body, fieldSpec.payloadPath, fieldSpec.wrap ? fieldSpec.wrap(value) : value);
-  }
-
-  // Structural builders, declared in the spec via `via`.
-  const options = buildOptions(product);
-  assertDeclaredOptionsResolved(product, options, optionLossDecision);
-  if (options.length) body.options = options;
-  const media = buildMedia(product);
-  if (media) body.media = media;
-  const seoData = buildSeoData(product, { seoPlan });
-  if (seoData) body.seoData = seoData;
-  body.variantsInfo = { variants: buildVariants(product, { inStock }) };
-  if (!body.variantsInfo.variants.length) {
-    throw new Error(`buildProduct: "${product.name}" produced no variant; every Wix product needs at least one`);
-  }
-  return body;
-}
-
-// --- category --------------------------------------------------------------
-// Categories are created depth-ascending so a parent id is always resolvable. Dedupe against a
-// live site must key on name + PARENT, never name alone: a real tree repeats a name at different
-// depths (e.g. "Accessories" under two different parents).
-function buildCategory(category, { categoryIdByPath = new Map(), target = CATEGORY_TARGET } = {}) {
-  if (isBlank(category.name)) throw new Error('buildCategory: category.name is required');
-  const body = { ...target.constants };
-  for (const [canonicalPath, fieldSpec] of Object.entries(target.fields)) {
-    if (!fieldSpec.payloadPath) continue;
-    const key = canonicalPath.replace(/^category\./, '');
-    let value = category[key];
-    const def = CANONICAL_FIELDS[canonicalPath] || {};
-    if (isBlank(value) && def.default !== undefined) value = def.default;
-    if (isBlank(value) && typeof value !== 'boolean') continue;
-    if (def.kind === 'boolean') value = coerceBoolean(value, def.default);
-    setPath(body, fieldSpec.payloadPath, value);
-  }
-  const parentId = category.parentPath ? categoryIdByPath.get(category.parentPath) : null;
-  if (parentId) body.parentCategory = { id: parentId };
-  return body;
-}
-
-module.exports = {
-  money,
-  toWixSlug,
-  WIX_SLUG_ILLEGAL_CHARS,
-  coerceBoolean,
-  normalizedDescriptionText,
-  isPlaceholderDescription,
-  composeProductDescription,
-  buildOptions,
-  buildVariants,
-  buildVariantPrice,
-  buildMedia,
-  buildSeoData,
-  buildProduct,
-  buildCategory,
-};

package/skills/wix-replatform/resources/rp-target-wix/lib/wix-target-spec.js

@@ -1,255 +0,0 @@
-'use strict';
-
-// rp-target-wix — the DECLARATIVE Wix target spec.
-//
-// This module is the single source of truth for two things the pipeline used to re-derive with an
-// LLM on every run:
-//
-//   1. CANONICAL_FIELDS — the vendor-neutral vocabulary a source adapter maps its columns onto.
-//      A vendor overlay's `columnMap[].wixTarget` MUST name a field in here; anything else is a
-//      typo or an unmodelled concept, and `validateCanonicalPath` catches it at load time instead
-//      of at import time.
-//
-//   2. STORES_V3_TARGET — how each canonical field lands in a real Wix Stores V3 payload, plus
-//      every trap learned by live call. This is vendor-independent: Shopify, WooCommerce, Magento
-//      and BigCommerce all converge here, so it is written ONCE and tested ONCE.
-//
-// Why declarative: the mapping between a canonical field and a Wix payload path is data, and
-// treating it as data means the resolver can compute coverage (which Wix fields are fed, which
-// source columns are orphaned) BEFORE any code runs. That coverage report is what shrinks the
-// agentic step from "author the whole mapping" to "decide the residue".
-//
-// Provenance markers carried per field:
-//   verified   — exercised by a real successful write against a live site
-//   unverified — shape derived from docs/schema only; must be surfaced in execution plans
-
-// --- canonical vocabulary --------------------------------------------------
-// `kind` drives deterministic coercion. `entity` says which canonical record holds it.
-const CANONICAL_FIELDS = {
-  // product scalars
-  'product.name': { entity: 'product', kind: 'string', required: true },
-  'product.description': { entity: 'product', kind: 'html' },
-  'product.slug': { entity: 'product', kind: 'slug' },
-  'product.brand': { entity: 'product', kind: 'string' },
-  'product.visible': { entity: 'product', kind: 'boolean', default: true },
-  'product.productType': { entity: 'product', kind: 'string' },
-  'product.seoTitle': { entity: 'product', kind: 'string' },
-  'product.seoDescription': { entity: 'product', kind: 'string' },
-  // Per-field SEO override evidence ({ title|description|focusKeyword: { state, value? } }).
-  // When present it, not seoTitle/seoDescription, decides which product SEO tags are written.
-  'product.seoEvidence': { entity: 'product', kind: 'object' },
-  'product.ribbon': { entity: 'product', kind: 'string' },
-  // product collections
-  'product.categoryPath': { entity: 'product', kind: 'string' },
-  'product.tags': { entity: 'product', kind: 'stringList' },
-  'product.images': { entity: 'product', kind: 'mediaList' },
-  // variant scalars
-  'variant.sku': { entity: 'variant', kind: 'string' },
-  'variant.price': { entity: 'variant', kind: 'money', required: true },
-  'variant.compareAtPrice': { entity: 'variant', kind: 'money' },
-  'variant.cost': { entity: 'variant', kind: 'money' },
-  'variant.barcode': { entity: 'variant', kind: 'string' },
-  'variant.weight': { entity: 'variant', kind: 'weight' },
-  'variant.weightUnit': { entity: 'variant', kind: 'string' },
-  'variant.inventoryQuantity': { entity: 'variant', kind: 'integer' },
-  'variant.inventoryPolicy': { entity: 'variant', kind: 'string' },
-  'variant.inventoryTracked': { entity: 'variant', kind: 'boolean' },
-  'variant.requiresShipping': { entity: 'variant', kind: 'boolean' },
-  'variant.taxable': { entity: 'variant', kind: 'boolean' },
-  'variant.visible': { entity: 'variant', kind: 'boolean', default: true },
-  // variant options — positional in every vendor's flat CSV, normalized to choices[]
-  'variant.option1.name': { entity: 'variant', kind: 'string', optionSlot: 1, role: 'optionName' },
-  'variant.option1.value': { entity: 'variant', kind: 'string', optionSlot: 1, role: 'optionValue' },
-  'variant.option2.name': { entity: 'variant', kind: 'string', optionSlot: 2, role: 'optionName' },
-  'variant.option2.value': { entity: 'variant', kind: 'string', optionSlot: 2, role: 'optionValue' },
-  'variant.option3.name': { entity: 'variant', kind: 'string', optionSlot: 3, role: 'optionName' },
-  'variant.option3.value': { entity: 'variant', kind: 'string', optionSlot: 3, role: 'optionValue' },
-  // identity — never a Wix field; carried for the crosswalk and dedupe
-  'product.sourceId': { entity: 'product', kind: 'string', identity: true },
-  'category.sourceId': { entity: 'category', kind: 'string', identity: true },
-  'variant.parentRef': { entity: 'variant', kind: 'string', identity: true },
-  // NORMALIZED adapter output, not a source column. The flat CSV carries positional option slots
-  // (variant.option1.name/value …); the adapter collapses them into these two structures, which are
-  // what the options/variants builders actually consume. They are never overlay-mappable — an
-  // overlay that claimed them would be describing a column that does not exist.
-  'product.optionNames': { entity: 'product', kind: 'stringList', normalized: true },
-  'variant.choices': { entity: 'variant', kind: 'choiceList', normalized: true },
-  // Structural signal, never a payload value: the option names the SOURCE declared,
-  // set only by an adapter that can tell declared options from resolved ones. When present and
-  // non-empty, buildProduct refuses a product whose built options list is empty, so a lost
-  // option set is reported instead of flattening to a silent default variant. Absent = inert.
-  'product.sourceDeclaredOptionNames': { entity: 'product', kind: 'stringList', normalized: true },
-  // secondary description — vendors that ship both a long and a short body
-  'product.shortDescription': { entity: 'product', kind: 'string' },
-  // The vendor idiom for "price after discount". See STORES_V3_TARGET.priceResolution: Wix models
-  // actualPrice (charged) + compareAtPrice (strike-through), so a regular/sale pair has to be
-  // resolved into that shape rather than mapped field-for-field.
-  'variant.discountedPrice': { entity: 'variant', kind: 'money' },
-  'variant.inStock': { entity: 'variant', kind: 'boolean' },
-  'variant.width': { entity: 'variant', kind: 'dimension' },
-  'variant.height': { entity: 'variant', kind: 'dimension' },
-  'variant.length': { entity: 'variant', kind: 'dimension' },
-  'variant.image': { entity: 'variant', kind: 'string' },
-  // image sub-record — assembles into product.images (kind mediaList)
-  'image.url': { entity: 'image', kind: 'string', assemblesInto: 'product.images' },
-  'image.altText': { entity: 'image', kind: 'string', assemblesInto: 'product.images' },
-  'image.position': { entity: 'image', kind: 'integer', assemblesInto: 'product.images' },
-  // tag sub-record
-  'tag.name': { entity: 'tag', kind: 'string' },
-  // category
-  'category.name': { entity: 'category', kind: 'string', required: true },
-  'category.description': { entity: 'category', kind: 'string' },
-  'category.parentPath': { entity: 'category', kind: 'string' },
-  'category.path': { entity: 'category', kind: 'string', identity: true },
-  'category.visible': { entity: 'category', kind: 'boolean', default: true },
-};
-
-function validateCanonicalPath(path) {
-  return Object.prototype.hasOwnProperty.call(CANONICAL_FIELDS, path);
-}
-
-function canonicalFieldsFor(entity) {
-  return Object.entries(CANONICAL_FIELDS)
-    .filter(([, def]) => def.entity === entity)
-    .map(([path]) => path);
-}
-
-// --- Wix Stores V3 target --------------------------------------------------
-// `payloadPath` is where the value lands in the create body. `via` names the structural builder
-// when a field cannot be expressed as a plain path assignment (nested arrays, name-based choice
-// references). Traps are recorded next to the field they bite.
-const STORES_V3_TARGET = {
-  entity: 'product',
-  endpoint: 'POST /stores/v3/bulk/products-with-inventory/create',
-  provenance: 'verified',
-  // TRAP (verified 2026-07-29): the per-item results of this endpoint are nested under
-  // `productResults`, unlike its flat sibling /stores/v3/bulk/products/create. Reading
-  // `response.results` yields undefined AFTER the products are created.
-  responseResultsPath: 'productResults.results',
-  responseMetadataPath: 'productResults.bulkActionMetadata',
-  fields: {
-    'product.name': { payloadPath: 'name', provenance: 'verified' },
-    'product.description': {
-      payloadPath: 'plainDescription',
-      provenance: 'verified',
-      maxLength: 16000,
-      // Lands as `plainDescription`, NOT `description`. Per the Products V3 schema
-      // plainDescription is "Product description in HTML ... then converted to rich content" —
-      // the same conversion the Ricos endpoint performed, run server-side for free. `description`
-      // proper is a Ricos DOCUMENT OBJECT, so sending HTML there is a type error.
-      //
-      // TRAP: "plainDescription is ignored when a value is also passed to the description field."
-      // Setting both is a silent no-op on a 200 response; the writer rejects it.
-      // TRAP: hard cap of 16000 chars. The old Ricos path chunked at 28k and merged, so it was
-      // effectively unbounded — long Woo/Magento bodies that used to survive now need truncation
-      // or an info section, recorded in mapping-gaps.json.
-      note: 'html-string-converted-to-ricos-by-wix',
-    },
-    // WooCommerce and some other source platforms expose a second, shopper-facing short body.
-    // Wix has one description field, so wix-build composes it with product.description before
-    // emitting plainDescription. Keeping this declared makes coverage honest: the field lands,
-    // but never as a separate target property.
-    'product.shortDescription': { via: 'descriptionComposition', provenance: 'unverified' },
-    'product.slug': { payloadPath: 'slug', provenance: 'verified', coerce: 'slug' },
-    'product.brand': {
-      payloadPath: 'brand',
-      provenance: 'verified',
-      wrap: (value) => ({ name: value }),
-      note: 'brand is declared INLINE by name; bulk create resolves or creates it in the same request',
-    },
-    'product.visible': { payloadPath: 'visible', provenance: 'verified' },
-    'product.seoTitle': { via: 'seoData', provenance: 'verified' },
-    'product.seoDescription': { via: 'seoData', provenance: 'verified' },
-    // Create-time persistence of seoData is NOT live-verified (canary pending);
-    // product-seo.js reconciles a dropped create with a revision-protected PATCH.
-    'product.seoEvidence': { via: 'seoData', provenance: 'unverified' },
-    'product.images': { via: 'media', provenance: 'verified' },
-    'variant.price': { via: 'variants', provenance: 'verified' },
-    'variant.compareAtPrice': { via: 'variants', provenance: 'verified' },
-    'variant.sku': { via: 'variants', provenance: 'verified' },
-    'variant.weight': { via: 'variants', provenance: 'verified' },
-    'variant.visible': { via: 'variants', provenance: 'verified' },
-    'variant.inStock': { via: 'variants', provenance: 'verified' },
-    'variant.inventoryQuantity': { via: 'variants', provenance: 'verified' },
-    'variant.inventoryTracked': { via: 'variants', provenance: 'verified' },
-    'variant.option1.name': { via: 'options', provenance: 'verified' },
-    'variant.option1.value': { via: 'options', provenance: 'verified' },
-    'variant.option2.name': { via: 'options', provenance: 'verified' },
-    'variant.option2.value': { via: 'options', provenance: 'verified' },
-    'variant.option3.name': { via: 'options', provenance: 'verified' },
-    'variant.option3.value': { via: 'options', provenance: 'verified' },
-  },
-  // Constants the API demands regardless of source.
-  constants: {
-    productType: 'PHYSICAL',
-    // TRAP (verified): a PHYSICAL product requires an EMPTY physicalProperties object at product
-    // level. Omitting it 400s.
-    physicalProperties: {},
-  },
-  // Vendors express price as either (price, compareAt) like Shopify or (regular, sale) like Woo /
-  // Magento / BigCommerce. Wix models `actualPrice` (what is charged) + `compareAtPrice` (the
-  // strike-through), so the pair must be RESOLVED, not mapped field-for-field. Encoding the rule
-  // here once removes the single most repeated per-run judgement call.
-  priceResolution: {
-    rule: 'when variant.discountedPrice is present and strictly less than variant.price, it becomes actualPrice and variant.price becomes compareAtPrice; otherwise variant.price is actualPrice and variant.compareAtPrice is the strike-through',
-    dropCompareAtUnlessGreater: true,
-    note: 'vendors write 0.00 (and Woo writes an empty sale price) to mean "no discount"; Wix rejects compareAtPrice <= actualPrice',
-  },
-  // Canonical fields Wix Stores V3 has no home for. Naming them here is what lets the resolver
-  // report an honest "mapped but will not land" instead of silently dropping them.
-  unsupported: {
-    'product.tags': 'Wix Stores V3 has no product-tag field; a tag taxonomy must become categories or a CMS field.',
-    'tag.name': 'Same as product.tags — no native product-tag target in Stores V3.',
-    'product.sourceId': 'Identity only: tracked in the crosswalk, not written to Wix (no client-settable id).',
-    'variant.parentRef': 'Identity only: used to attach a variation row to its parent during extract.',
-    'variant.inStock': 'Fed into inventoryItem.inStock by the variants builder rather than mapped directly.',
-    'variant.image': 'Per-variant media needs Wix media ids, which only exist after ingestion; requires a follow-up patch.',
-    'variant.width': 'Dimension fields on the V3 variant create shape are unverified; not mapped rather than guessed.',
-    'variant.height': 'Dimension fields on the V3 variant create shape are unverified; not mapped rather than guessed.',
-    'variant.length': 'Dimension fields on the V3 variant create shape are unverified; not mapped rather than guessed.',
-    'image.url': 'Assembled into product.images by the adapter, then emitted via the media builder.',
-    'image.altText': 'Assembled into product.images by the adapter, then emitted via the media builder.',
-    'image.position': 'Ordering signal only: the first media item becomes the product main media.',
-    'category.path': 'Identity only: the dedupe key and crosswalk key, not a Wix field.',
-    'product.productType': 'Source product-type strings are a taxonomy, not the Wix productType enum (PHYSICAL/DIGITAL).',
-    'product.ribbon': 'Ribbon is a separate inline entity; not modelled by this spec version.',
-    'variant.cost': 'Cost sits behind the MERCHANT_DATA fieldset and is not settable on bulk create.',
-    'variant.barcode': 'No barcode field on the V3 variant create shape.',
-    'variant.inventoryPolicy': 'V3 models availability, not Shopify-style deny/continue policy.',
-    'variant.requiresShipping': 'Implied by productType PHYSICAL; not separately settable.',
-    'variant.taxable': 'Tax behaviour is a site-level/tax-group concern, not a variant field.',
-    'variant.weightUnit': 'Weight is sent in the site weight unit; the source unit only drives conversion.',
-  },
-};
-
-const CATEGORY_TARGET = {
-  entity: 'category',
-  endpoint: 'POST /categories/v1/categories',
-  provenance: 'verified',
-  // TRAP (verified): treeReference is TOP-LEVEL, a sibling of `category`. Nesting it 400s
-  // "treeReference must not be empty".
-  treeReferenceIsTopLevel: true,
-  fields: {
-    'category.name': { payloadPath: 'name', provenance: 'verified' },
-    'category.description': { payloadPath: 'description', provenance: 'verified' },
-    'category.visible': { payloadPath: 'visible', provenance: 'verified' },
-    'category.parentPath': {
-      via: 'parentRef',
-      provenance: 'verified',
-      note: 'resolved through the crosswalk to parentCategory.id; requires depth-ascending create order',
-    },
-  },
-  constants: {},
-  unsupported: {},
-};
-
-const TARGETS = { product: STORES_V3_TARGET, category: CATEGORY_TARGET };
-
-module.exports = {
-  CANONICAL_FIELDS,
-  STORES_V3_TARGET,
-  CATEGORY_TARGET,
-  TARGETS,
-  validateCanonicalPath,
-  canonicalFieldsFor,
-};