@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/lib/read-back-comparison.js

@@ -1,136 +0,0 @@
-'use strict';
-
-const {
-  isDeepStrictEqual
-} = require('node:util');
-const {
-  canonical,
-  populated,
-  domainContract
-} = require('./read-back-contract');
-const old = require('./write-verification');
-const empty = v => !populated(v);
-function decimal(v) {
-  if (typeof v !== 'string' && typeof v !== 'number') return null;
-  const m = /^([+-]?)(\d+)(?:\.(\d+))?$/.exec(String(v));
-  if (!m) return null;
-  const whole = m[2].replace(/^0+(?=\d)/, ''),
-    fraction = (m[3] || '').replace(/0+$/, '');
-  return `${m[1] === '-' && (whole !== '0' || fraction) ? '-' : ''}${whole}${fraction ? '.' + fraction : ''}`;
-}
-function memberProjection(value) {
-  const m = value.member || value,
-    c = value.contact;
-  if (!c) return m;
-  return {
-    ...m,
-    contact: {
-      firstName: c.name?.first,
-      lastName: c.name?.last,
-      phones: [c.phone?.phone, ...(c.additionalPhones || []).map(p => p.phone)].filter(v => v !== undefined),
-      addresses: (c.addresses || []).map(a => a.address)
-    }
-  };
-}
-function compareEntity(entity, expected, rawActual) {
-  const e = expected[entity] || expected,
-    a = entity === 'member' ? memberProjection(rawActual) : rawActual[entity] || rawActual,
-    checks = [];
-  const readPath = p => {
-    p = canonical(p);
-    if (entity !== 'member') return p;
-    if (p === 'contact.firstName') return 'contact.name.first';
-    if (p === 'contact.lastName') return 'contact.name.last';
-    if (p.startsWith('contact.addresses[].')) return p.replace('contact.addresses[].', 'contact.addresses[].address.');
-    return p.startsWith('contact.') ? p : `member.${p}`;
-  };
-  function add(p, wanted, actual, matches) {
-    checks.push({
-      writePath: canonical(`${entity}.${p}`),
-      readPath: readPath(p),
-      matches,
-      kind: matches ? 'verified' : empty(actual) && !empty(wanted) ? 'dropped' : 'changed'
-    });
-  }
-  const serverOwned = domainContract(entity).readBackProjection.serverOwned;
-  function walk(wanted, actual, p) {
-    const server = serverOwned.find(row => row.path === `${entity}.${canonical(p)}`);
-    if (server) {
-      checks.push({
-        writePath: server.path,
-        readPath: canonical(p),
-        matches: true,
-        kind: 'unverifiable',
-        reason: server.reason
-      });
-      return;
-    }
-    if (empty(wanted)) {
-      add(p, wanted, actual, empty(actual));
-      return;
-    }
-    if (Array.isArray(wanted) && /^media\.itemsInfo\.items$/.test(p) && entity === 'product') {
-      const result = old.compareProjection(wanted, actual, {
-        path: p
-      });
-      const landed = Array.isArray(actual) && actual.every(item => item?.image?.id && item.mediaType !== 'UNKNOWN_MEDIA_TYPE');
-      add(p, wanted, actual, result.verified && landed);
-      return;
-    }
-    if (p === 'plainDescription' && entity === 'product') {
-      add(p, wanted, actual, old.compareProjection(wanted, actual, {
-        path: p
-      }).verified);
-      return;
-    }
-    if (Array.isArray(wanted)) {
-      if (!Array.isArray(actual)) {
-        for (const item of wanted) walk(item, undefined, `${p}[]`);
-        return;
-      }
-      if (entity === 'member' && p === 'contact.phones') {
-        const left = [...new Set(wanted)].sort(),
-          right = [...new Set(actual)].sort();
-        add(p, wanted, actual, isDeepStrictEqual(left, right));
-        return;
-      }
-      if (entity === 'member' && p === 'contact.addresses' || entity === 'order' && p === 'appliedDiscounts') {
-        const subset = (w, a) => w && typeof w === 'object' ? Array.isArray(w) ? Array.isArray(a) && w.length === a.length && w.every((v, i) => subset(v, a[i])) : Object.entries(w).every(([k, v]) => subset(v, a?.[k])) : isDeepStrictEqual(w, a);
-        const remaining = [...actual];
-        if (wanted.length !== actual.length) add(`${p}[]`, wanted, actual, false);
-        for (const value of wanted) {
-          const at = remaining.findIndex(candidate => subset(value, candidate));
-          walk(value, at < 0 ? undefined : remaining.splice(at, 1)[0], `${p}[]`);
-        }
-        return;
-      }
-      if (entity === 'order' && p === 'lineItems') {
-        for (const item of wanted) {
-          const matches = actual.filter(x => x.id === item.id);
-          if (!item.id || matches.length !== 1) add(`${p}[]`, item, null, false);else walk(item, matches[0], `${p}[]`);
-        }
-        return;
-      }
-      add(p, wanted, actual, wanted.length === actual.length);
-      wanted.forEach((v, i) => walk(v, actual[i], `${p}[${i}]`));
-      return;
-    }
-    if (wanted && typeof wanted === 'object') {
-      for (const [k, v] of Object.entries(wanted)) walk(v, actual?.[k], p ? `${p}.${k}` : k);
-      return;
-    }
-    let equal = isDeepStrictEqual(wanted, actual);
-    if (/(^|\.)(loginEmail|email)$/.test(p)) equal = old.email(wanted) === old.email(actual);else if (/(Date|At)$/.test(p) && typeof wanted === 'string' && Number.isFinite(Date.parse(wanted))) equal = Number.isFinite(Date.parse(actual)) && Date.parse(wanted) === Date.parse(actual);else if (/(^|\.)(amount|price|priceBeforeDiscount|priceAfterDiscount|total|subtotal|taxAmount|discountAmount)$/.test(p) && decimal(wanted) !== null) equal = decimal(wanted) === decimal(actual);
-    add(p, wanted, actual, equal);
-  }
-  walk(e, a, '');
-  return {
-    verified: checks.length > 0 && checks.every(c => c.matches),
-    checks
-  };
-}
-module.exports = {
-  compareEntity,
-  memberProjection,
-  decimal
-};

package/skills/wix-replatform/lib/read-back-contract.js

@@ -1,243 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const {
-  hashArtifact
-} = require('./artifact-freshness');
-const state = require('./read-back-state');
-const {
-  GUID
-} = require('./operator-identity');
-const DOMAINS = {
-  order: 'ecom',
-  member: 'members',
-  contact: 'crm',
-  product: 'stores'
-};
-const canonical = p => String(p).replace(/\[\d+\]/g, '[]');
-const digest = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
-const populated = v => v !== undefined && v !== null && v !== '' && !(typeof v === 'object' && Object.keys(v).length === 0);
-const compareKeys = (a, b) => Buffer.compare(Buffer.from(String(a)), Buffer.from(String(b)));
-function entityKey(entity) {
-  if (!Object.hasOwn(DOMAINS, entity)) throw new Error('Unsupported read-back entity');
-  return entity;
-}
-function domainPath(entity) {
-  return path.join(__dirname, '../resources/rp-target-wix/domains', DOMAINS[entityKey(entity)], 'entities', `${entity}.json`);
-}
-function domainContract(entity) {
-  const file = domainPath(entity);
-  const d = JSON.parse(fs.readFileSync(file, 'utf8'));
-  return {
-    intendedFields: d.intendedFields,
-    readBackProjection: d.readBackProjection,
-    domainDigest: hashArtifact(path.dirname(file), path.basename(file))
-  };
-}
-function bindingPaths(entity) {
-  entityKey(entity);
-  return ['mapping/mapping-plan.json', `mapping/entity-decisions/${entity}.json`, 'mapping/mapping-resolution.json', `execution/read-back-inventory/${entity}.json`];
-}
-function bindings(projectDir, entity) {
-  return Object.fromEntries(bindingPaths(entity).map(p => {
-    const hash = hashArtifact(projectDir, p);
-    if (!hash) throw new Error(`read-back binding missing: ${p}`);
-    return [p, hash];
-  }));
-}
-function leafPaths(value, prefix = '', out = new Set()) {
-  if (!populated(value)) return out;
-  if (Array.isArray(value)) {
-    for (const item of value) leafPaths(item, `${prefix}[]`, out);
-  } else if (value && typeof value === 'object') {
-    for (const [k, v] of Object.entries(value)) leafPaths(v, prefix ? `${prefix}.${k}` : k, out);
-  } else if (prefix) out.add(prefix);
-  return out;
-}
-function valuesAt(value, dotted) {
-  const tokens = canonical(dotted).replace(/\[\]/g, '.[]').split('.').filter(Boolean);
-  let values = [value];
-  for (const t of tokens) values = t === '[]' ? values.flatMap(v => Array.isArray(v) ? v : []) : values.map(v => v?.[t]);
-  return values;
-}
-// The generated reader feeds its existing extract stream once. Values are not written to the inventory.
-async function inventory(projectDir, entity, records, {
-  sourceKey = r => r.id,
-  buildWrite = r => r,
-  rows = []
-} = {}) {
-  entityKey(entity);
-  const preparationStarted = performance.now();
-  const sourcePaths = Object.create(null),
-    writePaths = Object.create(null),
-    perRecord = [],
-    seen = new Set();
-  for await (const record of records) {
-    const id = sourceKey(record);
-    if (id === undefined || id === null || String(id) === '' || seen.has(String(id))) throw new Error('Read-back inventory requires unique stable source keys');
-    seen.add(String(id));
-    const source = leafPaths(record),
-      sent = leafPaths(await buildWrite(record));
-    const fields = [...new Set(rows.filter(row => (row.sourcePaths || []).some(p => valuesAt(record, p).some(populated)) || sent.has(row.writePath)).map(row => canonical(row.writePath)))].sort(compareKeys);
-    for (const p of source) sourcePaths[p] = (sourcePaths[p] || 0) + 1;
-    for (const p of fields) writePaths[p] = (writePaths[p] || 0) + 1;
-    perRecord.push({
-      sourceId: String(id),
-      writePaths: fields
-    });
-  }
-  perRecord.sort((a, b) => compareKeys(a.sourceId, b.sourceId));
-  const result = {
-    schemaVersion: 1,
-    entity,
-    sourcePaths,
-    writePaths,
-    records: perRecord
-  };
-  await state.atomic(projectDir, `execution/read-back-inventory/${entity}.json`, result);
-  Object.defineProperty(result, 'preparationMs', {
-    value: performance.now() - preparationStarted
-  });
-  return result;
-}
-function cover(inv, {
-  ceiling = 10,
-  existing = []
-} = {}) {
-  if (!Number.isInteger(ceiling) || ceiling < 10 || ceiling > 30) throw new Error('Canary ceiling must be a recorded user integer from 10 to 30');
-  const records = [...inv.records].sort((a, b) => compareKeys(a.sourceId, b.sourceId));
-  const universe = Object.keys(inv.writePaths).sort(compareKeys),
-    left = new Set(universe),
-    selected = [],
-    coveredBy = {};
-  const add = r => {
-    selected.push(r.sourceId);
-    for (const p of r.writePaths) if (left.delete(p)) coveredBy[p] = r.sourceId;
-  };
-  for (const id of existing) {
-    const row = records.find(r => r.sourceId === id);
-    if (!row) throw new Error('A previously written canary is missing from the inventory');
-    add(row);
-  }
-  while (left.size) {
-    const candidates = records.filter(r => !selected.includes(r.sourceId)).map(r => ({
-      row: r,
-      gain: r.writePaths.filter(p => left.has(p)).length
-    })).sort((a, b) => b.gain - a.gain || compareKeys(a.row.sourceId, b.row.sourceId));
-    if (!candidates[0]?.gain) break;
-    add(candidates[0].row);
-  }
-  return {
-    universeDigest: digest({
-      universe,
-      records
-    }),
-    ceiling,
-    canarySourceIds: selected,
-    coveredBy,
-    requiredCount: selected.length,
-    uncoveredPaths: selected.length > ceiling ? universe.filter(p => !selected.slice(0, ceiling).some(id => records.find(r => r.sourceId === id).writePaths.includes(p))) : [...left],
-    status: selected.length > ceiling || left.size ? 'coverage-exceeds-ceiling' : 'covered'
-  };
-}
-function mappingRows(plan, entity) {
-  const raw = plan.entityMappings || plan.entityDecisions || plan.mappings || plan.entities || [];
-  const entities = Array.isArray(raw) ? raw : Object.entries(raw).map(([key, v]) => ({
-    sourceEntity: key,
-    ...v
-  }));
-  const entry = entities.find(e => [e.entity, e.sourceEntity, e.name, e.target?.entity].includes(entity));
-  return entry?.fieldMappings || entry?.fields || entry?.mappingRows || [];
-}
-function validApproval(approval, current, request) {
-  return approval?.status === 'approved' && approval.decidedBy === 'user' && GUID.test(approval.approvedBy?.userId || '') && Boolean(approval.approvedBy?.displayName?.trim()) && approval.requestId === request?.requestId && ['pending', 'answered'].includes(request?.status) && Object.entries(current).every(([p, h]) => approval.bindingDigests?.[p] === h && request.artifactRefs?.some(r => r.path === p && String(r.sha256).replace(/^sha256:/, '') === h));
-}
-async function validate(projectDir, entity, {
-  decision,
-  plan,
-  inv,
-  approval,
-  request
-} = {}) {
-  entityKey(entity);
-  decision ||= await state.readJson(projectDir, `mapping/entity-decisions/${entity}.json`);
-  plan ||= await state.readJson(projectDir, 'mapping/mapping-plan.json');
-  inv ||= await state.readJson(projectDir, `execution/read-back-inventory/${entity}.json`);
-  approval ||= (await state.readJson(projectDir, 'orchestration/approvals.json', {})).mapping;
-  if (!request && approval?.requestId) {
-    try {
-      request = await require('./user-actions').readUserAction(projectDir, approval.requestId);
-    } catch {/* invalid approval */}
-  }
-  const errors = [],
-    contract = domainContract(entity),
-    copied = decision.readBackContract;
-  if (!copied || copied.domainDigest !== contract.domainDigest || digest(copied.intendedFields) !== digest(contract.intendedFields) || digest(copied.readBackProjection) !== digest(contract.readBackProjection)) errors.push('read-back domain contract stale or missing');
-  if (!inv || inv.entity !== entity || !Array.isArray(inv.records)) errors.push('read-back inventory missing; check not run');
-  const rows = mappingRows(plan, entity),
-    dispositions = decision.fieldDispositions || [];
-  const gate = await state.load(projectDir),
-    history = [...gate.observedLosses, ...Object.values(gate.runs).flatMap(run => Object.values(run.entities || {}).flatMap(e => [...(e.attemptedPaths || []), ...(e.settlements || []).filter(s => s.status !== 'passed')]))];
-  const requirements = [...Object.keys(inv?.sourcePaths || {}).map(p => ({
-    kind: 'source',
-    path: p
-  })), ...(contract.intendedFields || []).filter(f => f.sourcePaths.some(p => Object.keys(inv?.sourcePaths || {}).some(k => k === p || k.startsWith(p + '.') || k.startsWith(p + '[]')))).map(f => ({
-    kind: 'intended',
-    path: f.targetPath
-  }))];
-  let current;
-  try {
-    current = bindings(projectDir, entity);
-  } catch (e) {
-    errors.push(e.message);
-  }
-  for (const requirement of requirements) {
-    const matches = dispositions.filter(d => canonical(d.path || d.sourcePath || d.targetPath) === requirement.path && (!d.kind || d.kind === requirement.kind));
-    if (matches.length !== 1) {
-      errors.push(`Disposition missing or duplicate: ${requirement.kind}:${requirement.path}`);
-      continue;
-    }
-    const d = matches[0];
-    if (d.status === 'mapped') {
-      const row = d.mappingRef === undefined || d.mappingRef === null ? null : rows.find((r, i) => r.id !== undefined && r.id === d.mappingRef || r.mappingRef !== undefined && r.mappingRef === d.mappingRef || String(i) === String(d.mappingRef));
-      if (!row || (requirement.kind === 'source' ? !row.sourcePaths?.includes(requirement.path) : canonical(row.writePath) !== requirement.path) || !row.readPath && !row.unverifiableReason) errors.push(`Mapping does not cover ${requirement.path}`);
-    } else if (d.status === 'notMigrated') {
-      if (history.some(h => (!h.entity || h.entity === entity) && (h.sourcePaths?.includes(requirement.path) || h.writePath === requirement.path || h.intendedTargetPath === requirement.path))) errors.push(`Attempted or observed-loss path cannot be omitted: ${requirement.path}`);
-      if (!current || !validApproval(approval, current, request)) errors.push(`Identified exact-binding approval missing: ${requirement.path}`);
-    } else errors.push(`Unknown disposition: ${requirement.path}`);
-  }
-  const serverOwned = contract.readBackProjection?.serverOwned || [];
-  for (const f of contract.intendedFields || []) if (serverOwned.some(p => (typeof p === 'string' ? p : p.path) === f.targetPath)) errors.push(`Intended field cannot be server-owned: ${f.targetPath}`);
-  for (const r of rows) if (!r.sourcePaths?.length || !r.writePath || !r.readPath && !r.unverifiableReason) errors.push('Mapping row missing read-back declaration');
-  return {
-    valid: !errors.length,
-    errors,
-    contract,
-    rows,
-    inventory: inv,
-    decision,
-    approval,
-    bindingDigests: current
-  };
-}
-module.exports = {
-  DOMAINS,
-  entityKey,
-  canonical,
-  digest,
-  populated,
-  compareKeys,
-  domainPath,
-  domainContract,
-  bindingPaths,
-  bindings,
-  leafPaths,
-  valuesAt,
-  inventory,
-  cover,
-  mappingRows,
-  validApproval,
-  validate
-};

package/skills/wix-replatform/lib/read-back-extract.js

@@ -1,118 +0,0 @@
-'use strict';
-
-// Extracts are read once; only the current record is buffered, never the whole array.
-const fs = require('node:fs');
-const MAX_RECORD_BYTES = 16 * 1024 * 1024;
-function fail(code) {
-  return Object.assign(new Error(code), {
-    code
-  });
-}
-function parseRecord(text, maxRecordBytes) {
-  if (Buffer.byteLength(text) > maxRecordBytes) throw fail('extract_record_too_large');
-  let record;
-  try {
-    record = JSON.parse(text);
-  } catch {
-    throw fail('extract_json_invalid');
-  }
-  if (!record || typeof record !== 'object' || Array.isArray(record)) throw fail('extract_record_invalid');
-  return record;
-}
-async function* readExtract(file, {
-  format = 'auto',
-  maxRecordBytes = MAX_RECORD_BYTES
-} = {}) {
-  if (!['auto', 'json', 'ndjson'].includes(format) || !Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1) throw fail('extract_options_invalid');
-  const stream = fs.createReadStream(file, {
-    encoding: 'utf8',
-    highWaterMark: 64 * 1024
-  });
-  let selected = format === 'auto' ? null : format;
-  let buffer = '',
-    depth = 0,
-    quoted = false,
-    escaped = false,
-    opened = false,
-    closed = false,
-    expect = 'first',
-    recordBytes = 0;
-  try {
-    for await (let chunk of stream) {
-      if (!opened && !buffer && chunk.charCodeAt(0) === 0xfeff) chunk = chunk.slice(1);
-      if (!selected) {
-        const first = chunk.search(/\S/);
-        if (first < 0) continue;
-        selected = chunk[first] === '[' ? 'json' : 'ndjson';
-      }
-      if (selected === 'ndjson') {
-        // Bound every partial line before reading the next chunk.
-        let start = 0;
-        for (let i = 0; i < chunk.length; i += 1) {
-          if (chunk[i] !== '\n') continue;
-          buffer += chunk.slice(start, i);
-          if (buffer.trim()) yield parseRecord(buffer, maxRecordBytes);
-          buffer = '';
-          start = i + 1;
-        }
-        buffer += chunk.slice(start);
-        if (Buffer.byteLength(buffer) > maxRecordBytes) throw fail('extract_record_too_large');
-        continue;
-      }
-      for (const ch of chunk) {
-        if (closed) {
-          if (/\S/.test(ch)) throw fail('extract_json_trailing_data');
-          continue;
-        }
-        if (!opened) {
-          if (/\s/.test(ch)) continue;
-          if (ch !== '[') throw fail('extract_json_array_required');
-          opened = true;
-          continue;
-        }
-        if (!buffer) {
-          if (/\s/.test(ch)) continue;
-          if (ch === ']') {
-            if (expect === 'value') throw fail('extract_json_invalid');
-            closed = true;
-            continue;
-          }
-          if (expect === 'comma') {
-            if (ch !== ',') throw fail('extract_json_invalid');
-            expect = 'value';
-            continue;
-          }
-          if (ch !== '{') throw fail('extract_record_invalid');
-          buffer = '{';
-          depth = 1;
-          quoted = false;
-          escaped = false;
-          recordBytes = 1;
-          continue;
-        }
-        buffer += ch;
-        recordBytes += Buffer.byteLength(ch);
-        if (recordBytes > maxRecordBytes) throw fail('extract_record_too_large');
-        if (quoted) {
-          if (escaped) escaped = false;else if (ch === '\\') escaped = true;else if (ch === '"') quoted = false;
-        } else if (ch === '"') quoted = true;else if (ch === '{' || ch === '[') depth += 1;else if (ch === '}' || ch === ']') depth -= 1;
-        if (depth === 0) {
-          yield parseRecord(buffer, maxRecordBytes);
-          buffer = '';
-          expect = 'comma';
-        }
-        if (depth < 0) throw fail('extract_json_invalid');
-      }
-    }
-    if (selected === 'json' && (!opened || !closed || buffer)) throw fail('extract_json_incomplete');
-    if (selected === 'ndjson' && buffer.trim()) yield parseRecord(buffer, maxRecordBytes);
-    // Empty NDJSON is a valid empty extract; empty JSON is never a valid array.
-    if (format === 'json' && !opened) throw fail('extract_json_incomplete');
-  } finally {
-    stream.destroy();
-  }
-}
-module.exports = {
-  MAX_RECORD_BYTES,
-  readExtract
-};