@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/lib/product-media-deferral.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// Deterministic construction and reporting for a product gallery that the source
+// media records could not confirm. Generated importers call these helpers instead of cloning the
+// journal row and completion-action contracts into each project.
+
+const { foldAttemptsBySourceKey } = require('./local-state.js');
+
+const WRITE_SPEC_ID = 'stores-product-media-guard';
+const OPERATION = 'confirm-product-pictures';
+const ACTION_CODE = 'product-pictures-deferred';
+const FAILURE_REASONS = new Set(['no-source-id', 'no-source-record', 'source-unreadable']);
+
+function requireString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function buildProductMediaFailureRow({
+  confirmation,
+  attemptId,
+  sourceStableKey,
+  sourceId,
+  targetId,
+  runId,
+  phase = 'import',
+} = {}) {
+  if (!confirmation || confirmation.confirmed !== false || !FAILURE_REASONS.has(confirmation.reason)) {
+    throw new TypeError('buildProductMediaFailureRow: confirmation must be a failed confirmPictures result');
+  }
+  const reason = confirmation.reason;
+  const source = requireString(String(sourceId == null ? '' : sourceId), 'sourceId');
+  const target = requireString(String(targetId == null ? '' : targetId), 'targetId');
+  return {
+    schemaVersion: 1,
+    attemptId: requireString(attemptId, 'attemptId'),
+    sourceStableKey: requireString(sourceStableKey, 'sourceStableKey'),
+    writeSpecId: WRITE_SPEC_ID,
+    operation: OPERATION,
+    targetEntityType: 'product',
+    status: 'failed_retryable',
+    runId: requireString(runId, 'runId'),
+    phase: requireString(phase, 'phase'),
+    failure: {
+      sourceId: source,
+      targetEntityId: target,
+      operation: OPERATION,
+      httpStatus: null,
+      errorCode: null,
+      scopeGroupName: null,
+      outcome: 'failed_retryable',
+      message: `Product media deferred: ${reason}`,
+      reason,
+    },
+  };
+}
+
+function productPicturesDeferredAction(rows) {
+  if (!Array.isArray(rows)) throw new TypeError('productPicturesDeferredAction: rows must be an array');
+  const latest = foldAttemptsBySourceKey(rows);
+  let affectedCount = 0;
+  for (const row of latest.values()) {
+    if (row.writeSpecId === WRITE_SPEC_ID && row.status === 'failed_retryable') affectedCount += 1;
+  }
+  if (affectedCount === 0) return null;
+  return {
+    code: ACTION_CODE,
+    severity: 'medium',
+    entity: 'products',
+    affectedCount,
+    deadlineReason: 'the source is the only place the original can be recovered while it is still the system of record',
+    action: 'Requires Import Operator. For no-source-id and no-source-record, correct the picture at the source (upload the original, or attach it to the product so a media record exists) and re-run the product extract. For source-unreadable, wait until the source answers. Then resume with the failed-only selector. The rows and reasons are in the ledger.',
+  };
+}
+
+function withProductPicturesDeferredAction(completionInput = {}, rows = []) {
+  if (!completionInput || typeof completionInput !== 'object' || Array.isArray(completionInput)) {
+    throw new TypeError('withProductPicturesDeferredAction: completionInput must be an object');
+  }
+  const existing = completionInput.operatorActions;
+  if (existing !== undefined && !Array.isArray(existing)) {
+    throw new TypeError('withProductPicturesDeferredAction: operatorActions must be an array');
+  }
+  const operatorActions = (existing || []).filter((action) => !action || action.code !== ACTION_CODE);
+  const action = productPicturesDeferredAction(rows);
+  if (action) operatorActions.push(action);
+  return { ...completionInput, operatorActions };
+}
+
+module.exports = {
+  buildProductMediaFailureRow,
+  productPicturesDeferredAction,
+  withProductPicturesDeferredAction,
+};

package/skills/wix-replatform/lib/progress-log.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 
@@ -89,13 +90,28 @@ function createProgressLogger(options = {}) {
       event,
       status: statusForEvent(event),
       seq,
+      // `host`/`pid` give a health-check reader a script-agnostic, same-machine liveness signal
+      // straight from the record itself -- the existing state/.lock/ owner-claim check only ever
+      // covers a process that calls withStateLock (import writers), so a read-only script (e.g.
+      // a generated run-extract.js) that never acquires that lock had no way to be corroborated
+      // as live once its heartbeat went stale. `host` is encoded the same way local-state.js's
+      // lock-claim filenames already are, so a reader only ever trusts a pid on ITS OWN machine.
+      // BUG FIX: `...fields` must spread BEFORE `host`/`pid`, not after --
+      // a caller-supplied heartbeat field literally named `host` or `pid` must never be able to
+      // shadow this record's own true liveness identity.
       ...fields,
+      host: Buffer.from(os.hostname()).toString('base64url'),
+      pid: process.pid,
       message: String(message || event),
     };
     fs.appendFileSync(progressLog, `${JSON.stringify(record)}\n`, { encoding: 'utf8', flag: 'a' });
-    if (event !== 'heartbeat') {
-      lastProgressAt = Date.now();
-    }
+    // BUG FIX: this used to only reset on a NON-heartbeat event, so once
+    // the ticker's own `elapsed >= heartbeatIntervalMs` check first became true, `lastProgressAt`
+    // never moved again and every subsequent tick re-fired a heartbeat -- flooding the log at the
+    // ticker's poll rate (capped at 5s) instead of the configured interval. A heartbeat IS
+    // progress (proof the process is alive and looking), so it must reset the clock the same as
+    // any other event.
+    lastProgressAt = Date.now();
     if (event === 'start') {
       started = true;
     }

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

@@ -0,0 +1,184 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const state = require('./read-back-state');
+const contract = require('./read-back-contract');
+const {
+  requireOperatorIdentity
+} = require('./operator-identity');
+const {
+  loadArtifacts,
+  updateApprovalObject
+} = require('./orchestration-state');
+async function gatedEntities(projectDir) {
+  let files;
+  try {
+    files = await fs.readdir(path.join(projectDir, 'mapping/entity-decisions'));
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+  const result = [];
+  for (const name of files) if (name.endsWith('.json') && Object.hasOwn(contract.DOMAINS, name.slice(0, -5))) {
+    const d = await state.readJson(projectDir, `mapping/entity-decisions/${name}`);
+    if (d.readBackContract) result.push(name.slice(0, -5));
+  }
+  return result.sort();
+}
+async function applyApproval(projectDir, request, answer, {
+  identity = requireOperatorIdentity
+} = {}) {
+  const type = request.effect?.approvalType;
+  const status = {
+    approved: 'approved',
+    approve: 'approved',
+    declined: 'rejected',
+    reject: 'rejected'
+  }[answer.choice];
+  if (!['mapping', 'execution'].includes(type) || !status) throw new Error('Unsupported approval choice/type');
+  return state.locked(projectDir, async () => {
+    const artifacts = await loadArtifacts(projectDir);
+    const entities = type === 'mapping' ? await gatedEntities(projectDir) : [];
+    const bindingDigests = {};
+    if (status === 'approved') for (const entity of entities) {
+      Object.assign(bindingDigests, contract.bindings(projectDir, entity));
+      const decision = await state.readJson(projectDir, `mapping/entity-decisions/${entity}.json`);
+      const omissions = (decision.fieldDispositions || []).filter(d => d.status === 'notMigrated');
+      const gate = await state.load(projectDir);
+      const history = [...gate.observedLosses, ...Object.values(gate.runs).flatMap(r => Object.values(r.entities || {}).flatMap(e => [...(e.attemptedPaths || []), ...(e.settlements || []).filter(x => x.status !== 'passed')]))];
+      for (const d of omissions) if (history.some(h => (!h.entity || h.entity === entity) && [...(h.sourcePaths || []), h.writePath, h.intendedTargetPath].includes(d.path || d.sourcePath || d.targetPath))) throw new Error('Attempted or observed loss cannot become approved omission');
+    }
+    for (const [p, h] of Object.entries(bindingDigests)) if (!request.artifactRefs?.some(r => r.path === p && String(r.sha256).replace(/^sha256:/, '') === h)) throw new Error(`Missing or stale read-back approval reference: ${p}`);
+    const artifactRefs = await require('./user-actions').approvalArtifactRefs(projectDir, { approvalType: type, status, decidedBy: 'user', artifactRefs: request.artifactRefs, requireRequestRef: true });
+    // Freshness is checked again under the state lock, not just by the caller's earlier check.
+    if (!(type === 'mapping' && status === 'rejected') && require('./user-actions').staleArtifactRefs(projectDir, request).length) throw new Error('user_action_stale: approval inputs changed');
+    const approvedBy = status === 'approved' && entities.length ? identity() : null;
+    updateApprovalObject(artifacts.approvals, type, status, {
+      artifactRefs,
+      notes: request.title,
+      decidedBy: 'user'
+    });
+    if (approvedBy) Object.assign(artifacts.approvals[type], {
+      approvedBy,
+      requestId: request.requestId,
+      bindingDigests
+    });
+    await state.atomic(projectDir, 'orchestration/approvals.json', artifacts.approvals);
+    return artifacts.approvals[type];
+  });
+}
+function omissionDigest(omissions) {
+  return contract.digest(omissions.map(({
+    path,
+    kind,
+    recordCount,
+    approvedBy
+  }) => ({
+    path,
+    kind,
+    recordCount,
+    approvedBy
+  })));
+}
+async function acknowledge(projectDir, request, answer, {
+  identity = requireOperatorIdentity
+} = {}) {
+  if (request.effect?.kind !== 'read-back-omission-ack' || request.kind !== 'manual_action' || request.response?.mode !== 'none' || answer.acknowledged !== true) throw new Error('Invalid omission acknowledgement');
+  const {
+    runId,
+    entity,
+    omissionSetDigest
+  } = request.effect;
+  contract.entityKey(entity);
+  return state.update(projectDir, async gate => {
+    const omissions = gate.runs[runId]?.entities?.[entity]?.approvedOmissions;
+    if (!omissions || omissionDigest(omissions) !== omissionSetDigest || omissions.some(o => o.merchantAcknowledgement?.requestId !== request.requestId)) throw new Error('Omission acknowledgement binding changed');
+    const pending = omissions.filter(o => o.merchantAcknowledgement.status !== 'acknowledged');
+    if (!pending.length) return;
+    if (require('./user-actions').staleArtifactRefs(projectDir, request).length) throw new Error('Omission acknowledgement artifact binding changed');
+    const recordedBy = identity();
+    for (const o of pending) o.merchantAcknowledgement = {
+      status: 'acknowledged',
+      requestId: request.requestId,
+      answeredAt: new Date().toISOString(),
+      recordedBy,
+      ...(answer.note ? {
+        note: answer.note
+      } : {})
+    };
+  });
+}
+// Called at gate load and report generation to heal effect-before-answer crash/restore windows.
+async function recoverAcknowledgements(projectDir, options = {}) {
+  const {
+    listUserActions,
+    readUserAction
+  } = require('./user-actions');
+  const rows = await listUserActions(projectDir, {
+    status: 'answered'
+  });
+  for (const row of rows) {
+    const r = await readUserAction(projectDir, row.requestId);
+    if (r.effect?.kind === 'read-back-omission-ack') await acknowledge(projectDir, r, r.answer, options);
+  }
+}
+async function createAcknowledgement(projectDir, runId, entity) {
+  const gate = await state.load(projectDir),
+    item = gate.runs[runId]?.entities?.[entity];
+  if (!item?.approvedOmissions?.length || item.approvedOmissions.every(o => o.merchantAcknowledgement?.status === 'acknowledged')) return;
+  const {
+      createUserAction,
+      readUserAction
+    } = require('./user-actions'),
+    {
+      randomUUID
+    } = require('node:crypto');
+  let req = item.pendingAcknowledgementRequest;
+  if (!req) {
+    const requestId = item.approvedOmissions[0].merchantAcknowledgement?.requestId || `uar_${randomUUID()}`,
+      omissions = item.approvedOmissions;
+    req = {
+      requestId,
+      kind: 'manual_action',
+      stage: 'completion',
+      title: `Acknowledge omitted ${entity} fields`,
+      prompt: `Tell the merchant these fields were not migrated before launch: ${omissions.map(o => `${o.path} (${o.recordCount} records)`).join(', ')}`,
+      response: {
+        mode: 'none'
+      },
+      artifactRefs: Object.entries(item.bindingDigests || contract.bindings(projectDir, entity)).map(([p, sha256]) => ({
+        path: p,
+        sha256
+      })),
+      effect: {
+        kind: 'read-back-omission-ack',
+        runId,
+        entity,
+        omissionSetDigest: omissionDigest(omissions)
+      }
+    };
+    await state.update(projectDir, g => {
+      const e = g.runs[runId].entities[entity];
+      e.pendingAcknowledgementRequest = req;
+      for (const o of e.approvedOmissions) o.merchantAcknowledgement = {
+        status: 'pending',
+        requestId
+      };
+    });
+  }
+  try {
+    await readUserAction(projectDir, req.requestId);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+    await createUserAction(projectDir, req);
+  }
+}
+module.exports = {
+  applyApproval,
+  gatedEntities,
+  acknowledge,
+  recoverAcknowledgements,
+  createAcknowledgement,
+  omissionDigest
+};

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

@@ -0,0 +1,136 @@
+'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
+};