@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/lib/shipping-option-stage.js

@@ -0,0 +1,354 @@
+'use strict';
+
+// rp-target-wix — the shipping-option part of the import's shipping stage, as
+// deterministic code. A generated importer calls runShippingOptionStage after its delivery regions
+// exist, and the finished-project audit (rp-execute-import/scripts/shipping-estimate-audit.js)
+// calls runShippingEstimateAudit. Neither ever POSTs or PATCHes a crosswalked option.
+//
+// What it guarantees, in order:
+//   1. the estimate resolution (execution/shipping-estimates.json) is written before any write;
+//   2. every crosswalked option takes the read-only path first (crosswalk wins over every attempt
+//      state and pass mode), including recorded missing-target decisions;
+//   3. unresolved rows are recovered (read back), never re-sent;
+//   4. creates happen only on a complete per-region snapshot, advanced only with known ids;
+//   5. the completion fragment is built from the CURRENT state, so each run replaces the last.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const s = require('./shipping-build.js');
+const w = require('./wix-writers.js');
+const local = require('../../../lib/local-state.js');
+const recovery = require('../../../lib/import-recovery.js');
+
+const EXTRACT_FILE = 'data/source-extract/shipping-zone.ndjson';
+const EXTRACT_MANIFEST = 'data/source-extract/shipping-zone.manifest.json';
+const DECISIONS_FILE = 'orchestration/decisions.json';
+const COMPLETION_REPORT = 'execution/completion-report.json';
+const COMPLETION_SUMMARY = 'execution/completion-summary.md';
+const PASS_MODES = ['unfiltered', 'missing-only', 'unresolved-only', 'failed-only'];
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(temp, filePath);
+}
+
+// The shipping stage refuses to run on an in-progress or unmanifested extract.
+async function readShippingZoneExtract(projectDir, { required = true } = {}) {
+  const file = path.join(projectDir, EXTRACT_FILE);
+  const manifest = path.join(projectDir, EXTRACT_MANIFEST);
+  const [hasFile, hasManifest] = await Promise.all([exists(file), exists(manifest)]);
+  if (!hasFile || !hasManifest) {
+    if (!required) return null;
+    throw new Error(`shipping stage: ${EXTRACT_FILE} and ${EXTRACT_MANIFEST} must both exist (a .tmp extract is still in progress)`);
+  }
+  const text = await fs.readFile(file, 'utf8');
+  return text.split(/\r?\n/).filter((line) => line.trim()).map((line, index) => {
+    try {
+      return JSON.parse(line);
+    } catch (error) {
+      throw new Error(`${EXTRACT_FILE}:${index + 1} invalid NDJSON: ${error.message}`);
+    }
+  });
+}
+
+async function readDecisions(projectDir) {
+  const decisions = await readJsonIfExists(path.join(projectDir, DECISIONS_FILE));
+  return decisions && typeof decisions === 'object' && !Array.isArray(decisions) ? decisions : {};
+}
+
+async function readSiteLanguage(wix) {
+  try {
+    return s.siteLanguageFromProperties(await w.getSiteProperties(wix));
+  } catch {
+    return null; // a failed read is treated as an unsupported language: no invented text
+  }
+}
+
+function shippingAttemptRows(rows) {
+  return (rows || []).filter((row) => row && row.sourceEntityType === 'shipping-option');
+}
+
+function latestShippingAttempts(rows) {
+  return recovery.foldAttemptsBySource(shippingAttemptRows(rows));
+}
+
+function shippingCrosswalk(bySource) {
+  const out = {};
+  for (const [key, row] of Object.entries(bySource || {})) if (row && row.targetEntityType === s.SHIPPING_OPTION_TARGET_TYPE) out[key] = row;
+  return out;
+}
+
+async function writeEstimates(projectDir, resolution, fragment, audit) {
+  const document = {
+    ...(resolution || { schemaVersion: 1, siteLanguage: null, options: [], ignoredDecisions: [] }),
+    legacy: (audit && audit.legacyBlank) || [],
+    items: (fragment && fragment.items) || [],
+  };
+  await writeJsonAtomic(path.join(projectDir, s.SHIPPING_ESTIMATES_FILE), document);
+  return document;
+}
+
+async function persistUpserts(projectDir, audit) {
+  for (const row of (audit && audit.crosswalkUpserts) || []) await local.upsertCrosswalkRow(projectDir, row);
+}
+
+function passFilters(passMode) {
+  if (!PASS_MODES.includes(passMode)) throw new Error(`shipping stage: passMode must be one of ${PASS_MODES.join(', ')}`);
+  return {
+    missingOnly: passMode === 'missing-only',
+    unresolvedOnly: passMode === 'unresolved-only',
+    failedOnly: passMode === 'failed-only',
+  };
+}
+
+// Routing for a record with NO crosswalk row. `--missing-only` routes like
+// an unfiltered pass here: it differs only in skipping crosswalked records, which never reach this
+// function. Never creates an option whose latest row is unresolved or failed_terminal.
+function routeFor(latest, passMode) {
+  const normal = passMode === 'unfiltered' || passMode === 'missing-only';
+  if (!latest) return normal ? 'create' : 'skip';
+  if (latest.status === 'imported') return 'skip';
+  if (latest.status === 'started' || latest.status === 'succeeded_unverified') return passMode === 'failed-only' ? 'skip' : 'recover';
+  if (latest.status === 'failed_retryable') return normal || passMode === 'failed-only' ? 'create' : 'skip';
+  return 'skip'; // failed_terminal (including NOT_FOUND) and anything else: the operator decides
+}
+
+// Only a zone with destinations can have a delivery region, so only those can carry options.
+function writableZonePlans(zones) {
+  return s.planShippingZones(zones).filter((plan) => plan.destinations.length > 0 && plan.shippingOptions.length > 0);
+}
+
+async function runShippingOptionStage(wix, {
+  projectDir,
+  regionIdByZone = {},
+  sourceSystem = 'wordpress',
+  runId,
+  phase = 'import',
+  passMode = 'unfiltered',
+  writeSpecId = 'ecom/shipping-option',
+  newAttemptId = () => crypto.randomUUID(),
+} = {}) {
+  if (!projectDir) throw new Error('runShippingOptionStage: projectDir is required');
+  if (!runId) throw new Error('runShippingOptionStage: runId is required');
+  const filters = passFilters(passMode);
+  const zones = await readShippingZoneExtract(projectDir);
+  const zonePlans = writableZonePlans(zones);
+  const decisions = await readDecisions(projectDir);
+  const siteLanguage = await readSiteLanguage(wix);
+  const resolution = s.planShippingEstimates({ zonePlans, decisions, siteLanguage });
+  await writeEstimates(projectDir, resolution, null, null);
+  const resolutionByKey = new Map(resolution.options.map((option) => [option.optionKey, option]));
+
+  // Planned payloads, keyed by the raw option key.
+  const planned = [];
+  for (const plan of zonePlans) {
+    const zoneId = String(plan.zone.id);
+    for (const option of plan.shippingOptions) {
+      const optionKey = s.shippingOptionKey(zoneId, option);
+      const deliveryRegionId = regionIdByZone[zoneId];
+      if (!deliveryRegionId) throw new Error(`runShippingOptionStage: no delivery region id for zone ${zoneId}; create regions before options`);
+      const estimate = resolutionByKey.get(optionKey);
+      planned.push({
+        id: optionKey,
+        optionKey,
+        zoneId,
+        deliveryRegionId,
+        input: s.buildShippingOptionInput(option.classified, { deliveryRegionId, estimatedDeliveryTime: estimate.text, rates: option.rates }),
+      });
+    }
+  }
+
+  // Crosswalk first, for EVERY linked option and every pass mode: read-only, never a POST.
+  const preRunCrosswalk = await local.loadCrosswalk(projectDir);
+  let journal = await local.loadAttemptJournal(projectDir);
+  const audit = await s.auditShippingEstimates(wix, {
+    crosswalkBySource: shippingCrosswalk(preRunCrosswalk.bySource),
+    attemptRows: journal.rows,
+    resolution,
+    decisions,
+  });
+  await persistUpserts(projectDir, audit);
+
+  const selection = recovery.selectImportRecords(planned, {
+    sourceSystem,
+    filters: { ...filters, entity: 'shipping-option' },
+    crosswalkBySource: preRunCrosswalk.bySource,
+    attemptRows: journal.rows,
+  });
+
+  const readBack = { ...audit.readBack };
+  const results = [];
+  const regions = new Map();
+  const ctxFor = (record, attemptId, reconcile) => ({
+    attemptId,
+    sourceSystem,
+    sourceId: record.optionKey,
+    sourceStableKey: recovery.sourceStableKey(sourceSystem, 'shipping-option', record.optionKey),
+    writeSpecId,
+    runId,
+    phase,
+    ...(reconcile ? { reconcile } : {}),
+  });
+
+  const routed = selection.selected
+    .filter((entry) => !entry.existing)
+    .map((entry) => ({ ...entry, route: routeFor(entry.latestAttempt, passMode) }));
+
+  // 1. Recover unresolved rows first: read back, never re-send.
+  for (const entry of routed.filter((item) => item.route === 'recover')) {
+    const record = entry.record;
+    const latest = entry.latestAttempt;
+    const result = await w.recoverShippingOption(wix, latest, record.input, { decisions });
+    if (result.outcome === 'shipping-option-recovery-incomplete') {
+      results.push({ optionKey: record.optionKey, route: 'recover', outcome: result.outcome });
+      continue; // the row stays exactly as it was
+    }
+    const { attempt, crosswalk } = s.shippingOptionWriteRecord(result, ctxFor(record, latest.attemptId, latest.reconcile));
+    await local.markAttempt(projectDir, latest.attemptId, { ...attempt, failure: attempt.failure });
+    if (crosswalk) await local.appendCrosswalkRow(projectDir, crosswalk);
+    if (result.outcome === 'shipping-option-created' && result.stored) readBack[record.optionKey] = result.stored;
+    results.push({ optionKey: record.optionKey, route: 'recover', outcome: result.outcome, status: attempt.status });
+  }
+
+  // 2. Creates, on a complete per-region snapshot advanced only with known ids.
+  for (const entry of routed.filter((item) => item.route === 'create')) {
+    const record = entry.record;
+    const regionId = record.deliveryRegionId;
+    if (!regions.has(regionId)) {
+      const scan = await w.queryAllShippingOptions(wix, { deliveryRegionId: regionId });
+      regions.set(regionId, { complete: scan.complete, ids: new Set(scan.options.map((option) => option.id)), unprovable: false });
+    }
+    const region = regions.get(regionId);
+    if (!region.complete || region.unprovable) {
+      const errorCode = region.complete ? 'REGION_SNAPSHOT_UNPROVABLE' : 'SNAPSHOT_INCOMPLETE';
+      const reason = region.complete
+        ? 'an earlier create in this region had an unknown outcome; the region is rescanned next run'
+        : 'the region snapshot scan was incomplete; nothing is created in this region this run';
+      const { attempt } = s.shippingOptionWriteRecord({ outcome: 'shipping-option-not-attempted', id: null, errorCode, reason }, ctxFor(record, newAttemptId(), { deliveryRegionId: regionId }));
+      await local.appendAttempt(projectDir, attempt);
+      results.push({ optionKey: record.optionKey, route: 'create', outcome: 'not-attempted', errorCode });
+      continue;
+    }
+    const attemptId = newAttemptId();
+    const reconcile = { deliveryRegionId: regionId, preWriteTargetIds: [...region.ids] };
+    // The start half of the shared start/terminal pair: written BEFORE the POST, so a crash
+    // mid-write leaves a `started` row carrying the snapshot recovery needs.
+    const ctx = ctxFor(record, attemptId, reconcile);
+    await local.appendAttempt(projectDir, {
+      schemaVersion: 1,
+      attemptId,
+      sourceSystem,
+      sourceEntityType: 'shipping-option',
+      sourceId: ctx.sourceId,
+      sourceStableKey: ctx.sourceStableKey,
+      writeSpecId,
+      runId,
+      phase,
+      operation: s.SHIPPING_OPTION_OPERATION,
+      targetEntityType: s.SHIPPING_OPTION_TARGET_TYPE,
+      status: 'started',
+      reconcile,
+      updatedAt: new Date().toISOString(),
+    });
+    const result = await w.createShippingOptionVerified(wix, record.input);
+    const { attempt, crosswalk } = s.shippingOptionWriteRecord(result, ctx);
+    await local.markAttempt(projectDir, attemptId, { ...attempt, failure: attempt.failure });
+    if (crosswalk) await local.appendCrosswalkRow(projectDir, crosswalk);
+    if (result.id) region.ids.add(result.id);
+    if (result.outcome === 'shipping-option-unknown') region.unprovable = true;
+    if (result.outcome === 'shipping-option-created' && result.stored) readBack[record.optionKey] = result.stored;
+    results.push({ optionKey: record.optionKey, route: 'create', outcome: result.outcome, status: attempt.status });
+  }
+
+  journal = await local.loadAttemptJournal(projectDir);
+  const latestAttempts = latestShippingAttempts(journal.rows);
+  const fragment = s.shippingEstimateCompletionFragment({ resolution, readBack, latestAttempts, audit, projectDir });
+  const estimates = await writeEstimates(projectDir, resolution, fragment, audit);
+  return { resolution, estimates, fragment, audit, results, selection: selection.summary };
+}
+
+// --- Finished projects -----------------------------------------------------------
+// Replaces the shipping rows of an already-written completion report and regenerates the
+// post-execution handoff. Every other part of the report is kept as written: the report's own
+// rows are already the final record of that run, and re-deriving them could double rows the
+// writer joined (source coverage) or derived (voucher/coverage-check actions). The merged rows go
+// through createCompletionReport's own operator-action normalization before they are written.
+async function rebuildCompletionWithFragment(projectDir, fragment) {
+  const { createCompletionReport, renderCompletionSummary } = require('../../../lib/completion-report.js');
+  const { generatePostExecutionHandoff } = require('../../../lib/website-handoff.js');
+  const reportPath = path.join(projectDir, COMPLETION_REPORT);
+  const report = await readJsonIfExists(reportPath);
+  if (!report) return { completionReport: null, handoff: { ok: false, reason: 'missing_completion_report' } };
+  const merged = s.mergeShippingEstimateCompletion(report, fragment);
+  const normalized = createCompletionReport({ operatorActions: merged.operatorActions, lastWriteAt: report.lastWriteAt || null }).operatorActions;
+  const rebuilt = { ...report, operatorActions: normalized };
+  await writeJsonAtomic(reportPath, rebuilt);
+  await fs.writeFile(path.join(projectDir, COMPLETION_SUMMARY), renderCompletionSummary(rebuilt), 'utf8');
+  // Rewriting import outcomes also refreshes the discovered-set join before its handoff.
+  if (rebuilt.managementImportMode !== 'quick') {
+    await require('../../../lib/discovered-set-status.js').buildDiscoveredSetStatus(projectDir);
+  }
+  const handoff = await generatePostExecutionHandoff(projectDir, { runId: report.runId || null });
+  return { completionReport: rebuilt, handoff };
+}
+
+async function runShippingEstimateAudit(wix, { projectDir } = {}) {
+  if (!projectDir) throw new Error('runShippingEstimateAudit: projectDir is required');
+  const decisions = await readDecisions(projectDir);
+  const zones = await readShippingZoneExtract(projectDir, { required: false });
+  const siteLanguage = await readSiteLanguage(wix);
+  const resolution = zones ? s.planShippingEstimates({ zonePlans: writableZonePlans(zones), decisions, siteLanguage }) : null;
+  const crosswalk = await local.loadCrosswalk(projectDir);
+  const journal = await local.loadAttemptJournal(projectDir);
+  const audit = await s.auditShippingEstimates(wix, {
+    crosswalkBySource: shippingCrosswalk(crosswalk.bySource),
+    attemptRows: journal.rows,
+    resolution,
+    decisions,
+  });
+  await persistUpserts(projectDir, audit);
+  const latestAttempts = latestShippingAttempts(journal.rows);
+  const fragment = s.shippingEstimateCompletionFragment({ resolution, readBack: audit.readBack, latestAttempts, audit, projectDir });
+  const previous = await readJsonIfExists(path.join(projectDir, s.SHIPPING_ESTIMATES_FILE));
+  const base = resolution || (previous ? { ...previous } : null);
+  const estimates = await writeEstimates(projectDir, base, fragment, audit);
+  const rebuilt = await rebuildCompletionWithFragment(projectDir, fragment);
+  return { resolution, audit, fragment, estimates, ...rebuilt };
+}
+
+async function listShippingEstimateItems(projectDir, code) {
+  const document = await readJsonIfExists(path.join(projectDir, s.SHIPPING_ESTIMATES_FILE));
+  return ((document && document.items) || []).filter((item) => !code || item.code === code);
+}
+
+module.exports = {
+  EXTRACT_FILE,
+  EXTRACT_MANIFEST,
+  PASS_MODES,
+  readShippingZoneExtract,
+  runShippingOptionStage,
+  runShippingEstimateAudit,
+  rebuildCompletionWithFragment,
+  listShippingEstimateItems,
+};

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

@@ -0,0 +1,134 @@
+'use strict';
+
+const { isBlank } = require('./value-utils.js');
+
+// rp-target-wix — the DETERMINISTIC WooCommerce store-settings -> Wix Site Properties builder.
+// Companion to tax-build.js/shipping-build.js; implements domains/site/entities/
+// business-contact.json's mappingGuidance as code.
+//
+// Input is the raw WooCommerce shape from GET /wc/v3/settings/general: a flat array of
+// {id, label, value, ...} records. Already-fetched — per this codebase's "transform takes shaped
+// input, fetching is the caller's job" convention.
+//
+// That route is NOT part of the default discovery sweep: it classifies as a setup surface, so it
+// is only read deliberately. It also needs the WordPress application password rather than the
+// store's own consumer key.
+
+const ZIP_MAX_LENGTH = 20;
+
+function settingsToMap(settings) {
+  const map = {};
+  for (const setting of settings || []) {
+    if (!setting || typeof setting.id !== 'string') continue;
+    map[setting.id] = setting.value;
+  }
+  return map;
+}
+
+function trimmed(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+// WooCommerce packs country and state into ONE setting: `woocommerce_default_country` is either
+// `IL` or `COUNTRY:STATE` (e.g. `US:CA`) — the same encoding a shipping zone's `state`-type
+// location uses. Wix takes them as two separate fields, and storing `US:CA` as `country` does not
+// error; it just matches nothing. Splitting is not optional.
+function splitDefaultCountry(value) {
+  const raw = trimmed(value);
+  if (!raw) return { country: '', state: '' };
+  const [country, state] = raw.split(':');
+  return { country: trimmed(country).toUpperCase(), state: trimmed(state).toUpperCase() };
+}
+
+// --- WooCommerce general settings -> Wix businessContact.address --------------------------------
+// Deliberately NOT done here:
+//   - Splitting a house number out of the address line. The source field is one free-text value
+//     with no structure guarantee — some shops put the number first, some last, some have none at
+//     all. Wix has a separate `streetNumber`, which is exactly the invitation to guess. A wrong
+//     split is worse than no split: it looks deliberate. The whole line goes in `street`.
+//   - Geocoding. `coordinates` and `googleFormattedAddress` are real fields with no source
+//     counterpart; inventing a latitude asserts a precision the source never had.
+function buildBusinessAddress(settings) {
+  const map = settingsToMap(settings);
+  const notes = [];
+
+  const street = trimmed(map.woocommerce_store_address);
+  const apartmentNumber = trimmed(map.woocommerce_store_address_2);
+  const city = trimmed(map.woocommerce_store_city);
+  const { country, state } = splitDefaultCountry(map.woocommerce_default_country);
+  let zip = trimmed(map.woocommerce_store_postcode);
+
+  if (zip.length > ZIP_MAX_LENGTH) {
+    notes.push(`Source postcode "${zip}" exceeds Wix's ${ZIP_MAX_LENGTH}-character limit for zip and was dropped rather than truncated — a truncated postcode is wrong data that looks right. Set it by hand.`);
+    zip = '';
+  }
+  if (!country) {
+    notes.push('Source has no store country (woocommerce_default_country is empty) — Wix needs an ISO 3166-1 alpha-2 country code, and there is nothing to derive one from.');
+  }
+  if (!street && !city && !zip) {
+    notes.push('Source has no street, city or postcode — there is no address here to migrate.');
+  }
+
+  const address = {
+    ...(street ? { street } : {}),
+    ...(apartmentNumber ? { apartmentNumber } : {}),
+    ...(city ? { city } : {}),
+    ...(state ? { state } : {}),
+    ...(country ? { country } : {}),
+    ...(zip ? { zip } : {}),
+    isPhysical: true,
+  };
+
+  const hasAnything = Boolean(street || city || zip || country);
+  return { address: hasAnything ? address : null, notes };
+}
+
+// The payload for wix-writers.js's updateBusinessContact. Only `address` is ever populated here:
+// WooCommerce's general settings carry no business email/phone/fax, and the writer derives its
+// field mask from the payload's own keys — so an address-only payload can never clear the
+// merchant's own contact details. That is the whole reason this returns a narrow object rather
+// than a full BusinessContactData with empty strings in it.
+function buildBusinessContactInput(settings) {
+  const { address, notes } = buildBusinessAddress(settings);
+  if (!address) return { businessContact: null, notes };
+  return { businessContact: { address }, notes };
+}
+
+// --- Report-only settings ----------------------------------------------------------------------
+// Each of these changes what a buyer can do, and none is written by this pipeline. Surfacing them
+// with the source value beside the destination's current value is what turns "we didn't migrate
+// it" from an invisible omission into a decision the merchant can make in one look.
+const REPORT_ONLY_SETTINGS = [
+  ['woocommerce_currency', 'Store currency', 'Wix prices in the site\'s payment currency; a mismatch means every price is displayed in a currency the merchant never chose.'],
+  ['woocommerce_allowed_countries', 'Which countries may buy', 'Combined with the specific-countries list below. A store that sells to one country only will otherwise become a store that sells everywhere.'],
+  ['woocommerce_specific_allowed_countries', 'Specific selling countries', 'Only meaningful when the setting above is "specific".'],
+  ['woocommerce_ship_to_countries', 'Which countries may be shipped to', 'Empty means "inherit the selling countries". Interacts with the delivery regions built from the source shipping zones.'],
+  ['woocommerce_calc_taxes', 'Tax calculation on/off', 'A source with tax calculation OFF should not arrive with tax being calculated, and vice versa.'],
+  ['woocommerce_enable_coupons', 'Coupons on/off', 'A store with coupons disabled at source should not arrive accepting them.'],
+  ['woocommerce_currency_pos', 'Currency symbol position', 'Display only.'],
+  ['woocommerce_price_thousand_sep', 'Thousands separator', 'Display only.'],
+  ['woocommerce_price_decimal_sep', 'Decimal separator', 'Display only.'],
+  ['woocommerce_price_num_decimals', 'Decimal places', 'Display only.'],
+];
+
+function collectReportOnlySettings(settings) {
+  const map = settingsToMap(settings);
+  const rows = [];
+  for (const [id, label, why] of REPORT_ONLY_SETTINGS) {
+    if (!(id in map)) continue;
+    const value = map[id];
+    if (isBlank(value) && id !== 'woocommerce_ship_to_countries') continue;
+    rows.push({ id, label, sourceValue: String(value ?? ''), why });
+  }
+  return rows;
+}
+
+module.exports = {
+  ZIP_MAX_LENGTH,
+  REPORT_ONLY_SETTINGS,
+  settingsToMap,
+  splitDefaultCountry,
+  buildBusinessAddress,
+  buildBusinessContactInput,
+  collectReportOnlySettings,
+};