@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/resources/rp-source-wordpress/lib/blocked-data-handlers.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const checkoutFieldCsvParser = require('./checkout-field-csv-parser.js');
+const wixWpPluginV2Client = require('./wix-wp-plugin-v2-client.js');
+
+const handlers = Object.freeze({
+  // wix-wp-plugin-v2 is the only bridge-plugin-style handler this repo ships --
+  // the earlier per-case fixed adapters are fully retired from the skill. One handler,
+  // reusable across ANY db-only or admin-page-only entity that has no
+  // REST route at all: a profile's fulfillment supplies its own `table`, not its own
+  // handler. Exposes both of wix-wp-plugin-v2's routes -- discoverStructure (schema only)
+  // and queryStructure (real row data) -- see wix-wp-plugin-v2-client.js's header comment
+  // for why pulling real row data through this handler is still a separate per-entity
+  // decision, not implied by schema-discoverability.
+  'wix-wp-plugin-v2': Object.freeze({
+    kind: 'structure-bridge-plugin',
+    version: wixWpPluginV2Client.HANDLER_VERSION,
+    discoverStructure: wixWpPluginV2Client.discoverStructure,
+    queryStructure: wixWpPluginV2Client.queryStructure,
+    // What a caller needs to build a legal request against a key/value table: every value
+    // column that stays unreachable until its own key column is pinned.
+    guardedValueColumns: wixWpPluginV2Client.guardedValueColumns,
+    selfTest: require('./wix-wp-plugin-v2-client.test-fixture.js'),
+  }),
+  // Generic across any checkout-field-editor-style WooCommerce plugin (ThemeHigh's
+  // Checkout Field Editor today, any other vendor tomorrow) — the parser only validates
+  // this pipeline's own canonical CSV shape, never a vendor-specific export format or
+  // meta-key convention. A second such plugin's profile can point its own
+  // blocked[].fulfillment.handlerId at this same id and reuse it unchanged.
+  'checkout-field-csv': Object.freeze({
+    kind: 'csv-upload',
+    version: checkoutFieldCsvParser.HANDLER_VERSION,
+    parse: checkoutFieldCsvParser.parse,
+    selfTest: require('./checkout-field-csv-parser.test-fixture.js'),
+  }),
+});
+
+function getHandler(handlerId) {
+  return handlers[handlerId] || null;
+}
+
+async function testOne(handler) {
+  if (typeof handler.selfTest !== 'function') return { ready: false, reason: 'handler-self-test-missing' };
+  try {
+    // The whole handler is passed, not one arbitrarily-chosen capability, so a self-test
+    // can exercise every capability its handler actually offers (e.g. wix-wp-plugin-v2's
+    // discoverStructure AND queryStructure) -- a self-test that only ever received
+    // discoverStructure would report readiness even if queryStructure were broken.
+    const passed = await handler.selfTest(handler);
+    return passed === true ? { ready: true, reason: null } : { ready: false, reason: 'handler-self-test-failed' };
+  } catch (error) {
+    return { ready: false, reason: 'handler-self-test-failed', error: error.message };
+  }
+}
+
+async function testHandler(handlerId) {
+  const handler = getHandler(handlerId);
+  return handler ? testOne(handler) : { ready: false, reason: 'handler-not-registered' };
+}
+
+// wix-wp-plugin-v2 (structure-bridge-plugin) has no manifest/case/productionReady concept
+// to check against -- a passing
+// self-test IS readiness. This is the only bridge-plugin-style kind this repo has left, so
+// there is no other branch here; a future second such kind would add its own, not overload
+// this one.
+async function fulfillmentReadiness(fulfillment, { registry = handlers } = {}) {
+  const handler = fulfillment && registry[fulfillment.handlerId];
+  if (!handler) return { ready: false, reason: 'handler-not-registered' };
+  if (handler.kind !== fulfillment.kind) return { ready: false, reason: 'handler-kind-mismatch' };
+  return testOne(handler);
+}
+
+module.exports = { handlers, getHandler, testHandler, fulfillmentReadiness };

package/skills/wix-replatform/resources/rp-source-wordpress/lib/checkout-field-csv-parser.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const fsp = require('node:fs/promises');
+
+const HANDLER_VERSION = '1.2.0';
+
+const VALID_TYPES = new Set(['text', 'textarea', 'select', 'radio', 'checkbox', 'multiselect', 'date', 'heading']);
+const CHOICE_TYPES = new Set(['select', 'radio', 'multiselect']);
+const REQUIRED_COLUMNS = ['meta_key', 'label', 'type', 'section', 'required', 'options', 'enabled', 'sort_order'];
+const YES_NO_VALUES = new Set(['yes', 'no']);
+
+// RFC4180 field splitter: a field starting with `"` is quoted, a doubled `""` inside a quoted
+// field is one literal quote, and a comma only splits outside quotes. Returns null (never a
+// partially-split row) when a quote is left unterminated, so a malformed row is caught rather
+// than silently mis-split.
+function splitCsvLine(line) {
+  const cells = [];
+  let current = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const char = line[i];
+    if (inQuotes) {
+      if (char === '"') {
+        if (line[i + 1] === '"') { current += '"'; i += 1; } else { inQuotes = false; }
+      } else {
+        current += char;
+      }
+    } else if (char === '"' && current.length === 0) {
+      inQuotes = true;
+    } else if (char === ',') {
+      cells.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+  if (inQuotes) return null;
+  cells.push(current);
+  return cells.map((cell) => cell.trim());
+}
+
+// Pure over its input string — no I/O — so it can be exercised directly by a self-test or a
+// direct unit test without touching disk.
+function parseCsvText(csvText) {
+  if (typeof csvText !== 'string' || csvText.trim().length === 0) {
+    return { reconciled: false, reason: 'empty-input' };
+  }
+
+  const lines = csvText.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  if (lines.length < 1) return { reconciled: false, reason: 'empty-input' };
+
+  const headerCells = splitCsvLine(lines[0]);
+  if (!headerCells) return { reconciled: false, reason: 'malformed-row', rowNumber: 1 };
+  const header = headerCells.map((cell) => cell.toLowerCase());
+  for (const column of REQUIRED_COLUMNS) {
+    if (!header.includes(column)) return { reconciled: false, reason: 'missing-column', column };
+  }
+
+  const seenKeys = new Set();
+  const fields = [];
+  let headingCount = 0;
+
+  for (let i = 1; i < lines.length; i += 1) {
+    const cells = splitCsvLine(lines[i]);
+    if (!cells) return { reconciled: false, reason: 'malformed-row', rowNumber: i + 1 };
+    const row = {};
+    header.forEach((column, index) => { row[column] = cells[index] !== undefined ? cells[index] : ''; });
+
+    if (row.type === 'heading') {
+      headingCount += 1;
+      continue;
+    }
+    if (!VALID_TYPES.has(row.type)) return { reconciled: false, reason: 'unrecognized-type', row };
+    if (!row.meta_key) return { reconciled: false, reason: 'missing-meta-key', row };
+    if (seenKeys.has(row.meta_key)) return { reconciled: false, reason: 'duplicate-meta-key', row };
+    if (CHOICE_TYPES.has(row.type) && !row.options) return { reconciled: false, reason: 'missing-options-for-choice-type', row };
+    const requiredValue = row.required.toLowerCase();
+    if (!YES_NO_VALUES.has(requiredValue)) return { reconciled: false, reason: 'invalid-required-value', row };
+    const enabledValue = row.enabled.toLowerCase();
+    if (!YES_NO_VALUES.has(enabledValue)) return { reconciled: false, reason: 'invalid-enabled-value', row };
+    const sortOrder = Number(row.sort_order);
+    if (!Number.isFinite(sortOrder)) return { reconciled: false, reason: 'invalid-sort-order', row };
+
+    seenKeys.add(row.meta_key);
+    fields.push({
+      metaKey: row.meta_key,
+      label: row.label,
+      fieldType: row.type,
+      section: row.section,
+      required: requiredValue === 'yes',
+      options: row.options ? row.options.split('|').map((option) => option.trim()).filter(Boolean) : [],
+      enabled: enabledValue === 'yes',
+      sortOrder,
+    });
+  }
+
+  // A CSV is read whole in one pass, never paginated, so by the time every row above has
+  // validated cleanly there is nothing left to reconcile against — sourceCount and
+  // expectedTotal are trivially the same value. Kept as two fields (not folded into one)
+  // because resolveBlockedDataRequest's resultReconciles() requires both, matching the
+  // paginated-fetch shape every other fulfillment kind reports.
+  const dataRowCount = lines.length - 1;
+  return { reconciled: true, fields, headingCount, sourceCount: dataRowCount, expectedTotal: dataRowCount };
+}
+
+// The handler entry point blocked-data-requests.js's attemptFulfillment() actually calls:
+// handler.parse({ inputPath, ...handlerContext }). It has already confirmed inputPath exists
+// before calling this. `readFile` is injectable so a self-test can exercise this exact entry
+// point without touching disk.
+async function parse({ inputPath, readFile = (p) => fsp.readFile(p, 'utf8') } = {}) {
+  const csvText = await readFile(inputPath);
+  return parseCsvText(csvText);
+}
+
+module.exports = { HANDLER_VERSION, parse, parseCsvText, VALID_TYPES, CHOICE_TYPES };

package/skills/wix-replatform/resources/rp-source-wordpress/lib/checkout-field-csv-parser.test-fixture.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const VALID_CSV = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'gift_message,"Gift ""message""",textarea,additional,no,,yes,10',
+  'delivery_instructions,Delivery instructions,text,additional,no,,yes,20',
+  'preferred_contact_method,Preferred contact method,radio,additional,yes,"Email|Phone|SMS",yes,30',
+  'section_heading,Additional details,heading,additional,no,,yes,5',
+].join('\n');
+
+const BAD_CSV_DUPLICATE_KEY = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'gift_message,Gift message,textarea,additional,no,,yes,10',
+  'gift_message,Gift message again,text,additional,no,,yes,20',
+].join('\n');
+
+const BAD_CSV_MISSING_OPTIONS = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'preferred_contact_method,Preferred contact method,radio,additional,yes,,yes,30',
+].join('\n');
+
+const BAD_CSV_UNTERMINATED_QUOTE = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'gift_message,"Gift message,textarea,additional,no,,yes,10',
+].join('\n');
+
+const BAD_CSV_INVALID_REQUIRED = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'gift_message,Gift message,textarea,additional,yse,,yes,10',
+].join('\n');
+
+const BAD_CSV_INVALID_ENABLED = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'gift_message,Gift message,textarea,additional,no,,maybe,10',
+].join('\n');
+
+const BAD_CSV_INVALID_SORT_ORDER = [
+  'meta_key,label,type,section,required,options,enabled,sort_order',
+  'gift_message,Gift message,textarea,additional,no,,yes,abc',
+].join('\n');
+
+// `parse` here is the handler's real entry point — parse({ inputPath, readFile }) — the exact
+// shape blocked-data-requests.js's attemptFulfillment() calls, not the internal pure text
+// parser, so this self-test actually exercises the contract a real resolveBlockedDataRequest()
+// run depends on.
+async function selfTest({ parse }) {
+  const readFile = (csvByPath) => async (inputPath) => {
+    if (!(inputPath in csvByPath)) throw new Error(`fixture readFile: no CSV registered for ${inputPath}`);
+    return csvByPath[inputPath];
+  };
+
+  const valid = await parse({ inputPath: '/fake/valid.csv', readFile: readFile({ '/fake/valid.csv': VALID_CSV }) });
+  if (!valid.reconciled) throw new Error('fixture: valid CSV did not reconcile');
+  if (!Number.isInteger(valid.expectedTotal) || valid.sourceCount !== valid.expectedTotal) {
+    throw new Error('fixture: sourceCount/expectedTotal must be present and equal for a fully-read CSV');
+  }
+  if (valid.headingCount !== 1) throw new Error('fixture: heading row was not counted separately');
+  if (valid.fields.length !== 3) throw new Error('fixture: expected 3 non-heading fields');
+  if (valid.fields[0].label !== 'Gift "message"') {
+    throw new Error(`fixture: escaped double-quote in a quoted label was not unescaped correctly, got ${JSON.stringify(valid.fields[0].label)}`);
+  }
+  const contactMethod = valid.fields.find((field) => field.metaKey === 'preferred_contact_method');
+  if (!contactMethod || contactMethod.options.length !== 3 || contactMethod.options[1] !== 'Phone') {
+    throw new Error('fixture: pipe-delimited options did not parse correctly');
+  }
+  if (valid.fields.find((field) => field.fieldType === 'heading')) {
+    throw new Error('fixture: heading row leaked into the returned field list');
+  }
+
+  const duplicate = await parse({ inputPath: '/fake/dup.csv', readFile: readFile({ '/fake/dup.csv': BAD_CSV_DUPLICATE_KEY }) });
+  if (duplicate.reconciled) throw new Error('fixture: duplicate meta_key should not reconcile');
+
+  const missingOptions = await parse({ inputPath: '/fake/missing-options.csv', readFile: readFile({ '/fake/missing-options.csv': BAD_CSV_MISSING_OPTIONS }) });
+  if (missingOptions.reconciled) throw new Error('fixture: choice-type row with no options should not reconcile');
+
+  const unterminated = await parse({ inputPath: '/fake/unterminated.csv', readFile: readFile({ '/fake/unterminated.csv': BAD_CSV_UNTERMINATED_QUOTE }) });
+  if (unterminated.reconciled) throw new Error('fixture: an unterminated quote must not reconcile, not be silently mis-split');
+
+  const invalidRequired = await parse({ inputPath: '/fake/invalid-required.csv', readFile: readFile({ '/fake/invalid-required.csv': BAD_CSV_INVALID_REQUIRED }) });
+  if (invalidRequired.reconciled) throw new Error('fixture: required="yse" (not yes/no) must not reconcile — must not silently coerce to false');
+
+  const invalidEnabled = await parse({ inputPath: '/fake/invalid-enabled.csv', readFile: readFile({ '/fake/invalid-enabled.csv': BAD_CSV_INVALID_ENABLED }) });
+  if (invalidEnabled.reconciled) throw new Error('fixture: enabled="maybe" (not yes/no) must not reconcile — must not silently coerce to false');
+
+  const invalidSortOrder = await parse({ inputPath: '/fake/invalid-sort-order.csv', readFile: readFile({ '/fake/invalid-sort-order.csv': BAD_CSV_INVALID_SORT_ORDER }) });
+  if (invalidSortOrder.reconciled) throw new Error('fixture: sort_order="abc" (not a number) must not reconcile — must not silently coerce to 0');
+
+  return true;
+}
+
+module.exports = selfTest;