@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/execution-capability.js

@@ -0,0 +1,120 @@
+'use strict';
+
+// Authority is object identity, never serialized fields or request metadata.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const registry = new WeakMap();
+const clients = new WeakMap();
+const projects = new Map();
+const finishedRuns = new WeakMap();
+let processMark;
+const adapters = Object.freeze({
+  'quick-woocommerce': '../resources/rp-quick-woocommerce/quick-mode.json',
+  'quick-shopify': '../resources/rp-quick-shopify/quick-mode.json',
+});
+function fail(code) { throw Object.assign(new Error(code), { code }); }
+function digest(bytes) { return crypto.createHash('sha256').update(bytes).digest('hex'); }
+function read(projectDir, name) { return JSON.parse(fs.readFileSync(path.join(projectDir, name), 'utf8')); }
+function readIfPresent(projectDir, name) { try { return read(projectDir, name); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } }
+function enter(mark) {
+  if (processMark && processMark !== mark) fail('CAPABILITY_MARK_CONFLICT');
+  processMark = mark;
+}
+function deepFreeze(value) { if (value && typeof value === 'object' && !Object.isFrozen(value)) { for (const child of Object.values(value)) deepFreeze(child); Object.freeze(value); } return value; }
+function issue(kind, context, extra = {}) {
+  const capability = Object.freeze({ kind, siteId: context.siteId, runId: context.runId,
+    projectDir: context.projectDir, dryRun: context.dryRun, ...extra });
+  registry.set(capability, deepFreeze({ ...context, ...extra, kind }));
+  if (context.projectDir) projects.set(path.resolve(context.projectDir), capability);
+  return capability;
+}
+function context(input) {
+  if (!input || typeof input.siteId !== 'string' || !input.siteId.trim()) fail('CAPABILITY_SITE_REQUIRED');
+  if (!input.projectDir) fail('CAPABILITY_PROJECT_REQUIRED');
+  return { projectDir: path.resolve(input.projectDir), siteId: input.siteId,
+    runId: input.runId || crypto.randomUUID(), dryRun: input.dryRun === true };
+}
+function inspect(capability) { return registry.get(capability) || null; }
+function requireKind(capability, kind) {
+  const value = inspect(capability);
+  if (!value || value.kind !== kind) fail('EXECUTION_CAPABILITY_REQUIRED');
+  return value;
+}
+function startSetupRun(input) {
+  const ctx = context(input);
+  const bytes = fs.readFileSync(path.join(ctx.projectDir, 'setup/setup-plan.json'));
+  const plan = JSON.parse(bytes);
+  if (!require('./setup-verification').validatePlanShape(plan).ok) fail('SETUP_PLAN_INVALID');
+  const importRefs = new Set((readIfPresent(ctx.projectDir, 'execution/execution-manifest.json')?.tasks || []).filter(task => task.kind === 'import').flatMap(task => task.entityRefs || []));
+  const forbidden = new Set(['ecom/order', 'stores/product', 'crm/contact', 'stores/coupon', 'gift-cards/gift-card', 'gift-cards/gift-card-product']);
+  for (const step of plan.steps) if ((step.entityRefs || []).some(ref => forbidden.has(ref) || importRefs.has(ref))) fail('SETUP_IMPORT_ENTITY_REFUSED');
+  enter('setup');
+  return issue('setup-run', { ...ctx, plan, planDigest: digest(bytes) });
+}
+function bindSetupStep(run, stepId) {
+  const ctx = requireKind(run, 'setup-run');
+  if (digest(fs.readFileSync(path.join(ctx.projectDir, 'setup/setup-plan.json'))) !== ctx.planDigest) fail('SETUP_PLAN_CHANGED');
+  const step = ctx.plan.steps.find(item => item.id === stepId);
+  if (!step) fail('SETUP_STEP_UNKNOWN');
+  return issue('setup-step', ctx, { stepId, step });
+}
+function validateQuickContract(contract) {
+  const ids = new Set((contract.entities || []).map(entity => entity.id));
+  if (ids.size !== contract.entities?.length) fail('quick_contract_invalid');
+  for (const entity of contract.entities) {
+    if ((entity.dependsOn || []).some(id => !ids.has(id))) fail(`quick_contract_dependency_external:${entity.id}`);
+    if (entity.auxiliaryTargets && (contract.id !== 'quick-shopify' || entity.id !== 'product' ||
+      JSON.stringify(entity.auxiliaryTargets) !== JSON.stringify(['stores/product-tag', 'stores/inventory-item']))) fail('quick_contract_auxiliary_invalid');
+  }
+  return contract;
+}
+function startQuickRun(input) {
+  if (!input || input.contract || !Object.hasOwn(adapters, input.adapterId)) fail('QUICK_ADAPTER_UNREGISTERED');
+  const ctx = context(input);
+  const contract = validateQuickContract(JSON.parse(fs.readFileSync(path.resolve(__dirname, adapters[input.adapterId]), 'utf8')));
+  enter('quick');
+  const run = issue('quick-run', { ...ctx, adapterId: input.adapterId, contract });
+  finishedRuns.set(run, new Set()); return run;
+}
+function bindQuickEntity(run, entityId) {
+  const ctx = requireKind(run, 'quick-run');
+  const entity = ctx.contract.entities.find(row => row.id === entityId);
+  if (!entity) fail('CAPABILITY_ENTITY_MISMATCH');
+  if (entity.dependsOn.some(id => !finishedRuns.get(run).has(id))) fail('QUICK_DEPENDENCY_NOT_FINISHED');
+  return issue('quick-entity', ctx, { entityId, target: entity.target, auxiliaryTargets: entity.auxiliaryTargets || [] });
+}
+function finishQuickEntity(run, entityId) {
+  const ctx = requireKind(run, 'quick-run');
+  if (!ctx.contract.entities.some(row => row.id === entityId)) fail('CAPABILITY_ENTITY_MISMATCH');
+  finishedRuns.get(run).add(entityId);
+}
+function bindQuickSetup(run, operation) {
+  const ctx = requireKind(run, 'quick-run');
+  if (!(ctx.contract.setupOperations || []).includes(operation)) fail('CAPABILITY_ENTITY_MISMATCH');
+  return issue('quick-setup', ctx, { operation });
+}
+function startDevProbe({ siteId, confirmation, dryRun = false } = {}) {
+  if (confirmation !== 'i-own-this-site') fail('DEV_PROBE_CONFIRMATION_REQUIRED');
+  if (typeof siteId !== 'string' || !siteId.trim()) fail('CAPABILITY_SITE_REQUIRED');
+  enter('probe');
+  return issue('dev-probe', { siteId, runId: crypto.randomUUID(), dryRun: dryRun === true });
+}
+function startImportRun(input) {
+  const ctx = context(input);
+  const inputs = require('./dependency-readiness').validateImportInputs(ctx.projectDir);
+  enter('import');
+  return issue('import-run', { ...ctx, ...inputs });
+}
+function bindTask({ runCapability, taskId }) {
+  const ctx = requireKind(runCapability, 'import-run');
+  const task = ctx.manifest.tasks.find(row => row.id === taskId && row.kind === 'import');
+  if (!task) fail('DEPENDENCY_TASK_MISMATCH');
+  return issue('import-task', ctx, { taskId, task });
+}
+function registerClient(client, capability) { clients.set(client, inspect(capability)); }
+function clientContext(client) { return clients.get(client) || null; }
+function projectContext(projectDir) { return inspect(projects.get(path.resolve(projectDir))); }
+module.exports = { startSetupRun, bindSetupStep, startQuickRun, bindQuickEntity, finishQuickEntity,
+  bindQuickSetup, startDevProbe, startImportRun, bindTask, inspect, requireKind, fail, digest,
+  registerClient, clientContext, projectContext, validateQuickContract };

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

@@ -0,0 +1,170 @@
+'use strict';
+
+// The writer for `execution-log.md`. Three rules hold this file together, and every one of them is load-bearing:
+//
+//  1. APPEND-ONLY. A resumed or recovery pass adds entries; it never truncates or regenerates
+//     the file. A chronology that a later pass can rewrite is not a chronology.
+//  2. PER-ENTRY runId. Every entry carries the run that wrote it, so a second pass's entries are
+//     distinguishable from the first pass's without inferring anything from timestamps.
+//  3. NON-AUTHORITATIVE. `execution/completion-report.json` is the final outcome and
+//     `execution/review/completion-summary.md` is rendered from that report. Nothing here is a
+//     count anyone may read back. This module therefore exposes no aggregation helper at all --
+//     the cheapest way to keep a derived count out of shipped code is to ship no way to derive
+//     one.
+//
+// This is NOT a heartbeat. `lib/progress-log.js` writes liveness to a caller-supplied path, which
+// in practice may be a temp file outside the project; that contract is unchanged.
+// `appendExecutionLog` always writes inside the project directory.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const EXECUTION_LOG_FILE = 'execution-log.md';
+
+const HEADER = [
+  '# Execution Log',
+  '',
+  'Chronology of this migration run: what ran, in what order, and where the run stopped or',
+  'resumed. Append-only -- later passes add lines, never rewrite them.',
+  '',
+  '**Not authoritative for counts.** The final outcome is',
+  '`execution/completion-report.json`; the human-readable account is',
+  '`execution/review/completion-summary.md`, rendered from that report. Never read a final',
+  'number out of this file.',
+  '',
+].join('\n');
+
+const ENTRY_FIELDS = new Set(['at', 'runId', 'phase', 'event', 'detail', 'artifacts']);
+
+// A handoff, a summary and this log all get attached to pull requests and pasted into chat. The
+// same confidentiality rule applies to all three: counts, ids, reason codes and artifact paths --
+// never record values. An email address is the one record value that reliably survives a careless
+// template (`imported customer ${record.email}`), so it is rejected outright rather than trusted
+// to reviewer discipline.
+const EMAIL_SHAPED = /[\w.+-]+@[\w-]+\.[\w.-]+/;
+
+function requireString(value, field) {
+  if (!value || typeof value !== 'string') {
+    throw new Error(`execution log entry ${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function assertNoRecordValues(value, field) {
+  if (EMAIL_SHAPED.test(value)) {
+    throw new Error(
+      `execution log entry ${field} looks like it carries a record value (email address); `
+      + 'the execution log records counts, ids, reason codes and artifact paths only',
+    );
+  }
+  return value;
+}
+
+function executionLogPath(projectDir) {
+  return path.join(projectDir, EXECUTION_LOG_FILE);
+}
+
+function normalizeExecutionLogEntry(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('execution log entry must be an object');
+  }
+  for (const key of Object.keys(input)) {
+    if (!ENTRY_FIELDS.has(key)) {
+      throw new Error(`unknown execution log entry field: ${key}`);
+    }
+  }
+  const runId = requireString(input.runId, 'runId');
+  const phase = requireString(input.phase, 'phase');
+  const event = requireString(input.event, 'event');
+  const detail = assertNoRecordValues(requireString(input.detail, 'detail'), 'detail');
+  const at = input.at === undefined || input.at === null ? new Date().toISOString() : requireString(input.at, 'at');
+  const artifacts = input.artifacts === undefined || input.artifacts === null ? [] : input.artifacts;
+  if (!Array.isArray(artifacts)) {
+    throw new Error('execution log entry artifacts must be an array');
+  }
+  return {
+    at,
+    runId,
+    phase,
+    event,
+    detail,
+    artifacts: artifacts.map((artifact, index) => assertNoRecordValues(
+      requireString(artifact, `artifacts[${index}]`),
+      `artifacts[${index}]`,
+    )),
+  };
+}
+
+function renderExecutionLogEntry(entry) {
+  const artifacts = entry.artifacts.length ? ` | artifacts: ${entry.artifacts.join(', ')}` : '';
+  return `- ${entry.at} | run ${entry.runId} | ${entry.phase} | ${entry.event} | ${entry.detail}${artifacts}`;
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+// `fs.appendFile` rather than read-modify-write: there is no code path here that can truncate the
+// file, not even a crash between the read and the write.
+async function appendExecutionLog(projectDir, entry) {
+  const normalized = normalizeExecutionLogEntry(entry);
+  const filePath = executionLogPath(projectDir);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const existed = await pathExists(filePath);
+  const line = renderExecutionLogEntry(normalized);
+  await fs.appendFile(filePath, existed ? `${line}\n` : `${HEADER}${line}\n`, 'utf8');
+  return { path: EXECUTION_LOG_FILE, entry: normalized, line, createdFile: !existed };
+}
+
+async function executionLogExists(projectDir) {
+  return pathExists(executionLogPath(projectDir));
+}
+
+// Reads entries back for orchestration and tests -- for "did this event happen, and in what
+// order", never for a count. Deliberately returns rows, not totals.
+async function readExecutionLogEntries(projectDir) {
+  const filePath = executionLogPath(projectDir);
+  let text;
+  try {
+    text = await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { exists: false, entries: [] };
+    throw error;
+  }
+  const entries = [];
+  for (const rawLine of text.split('\n')) {
+    if (!rawLine.startsWith('- ')) continue;
+    const parts = rawLine.slice(2).split(' | ');
+    if (parts.length < 5) continue;
+    const [at, runField, phase, event, ...rest] = parts;
+    if (!runField.startsWith('run ')) continue;
+    const artifactsPart = rest.length > 1 && rest[rest.length - 1].startsWith('artifacts: ')
+      ? rest.pop().slice('artifacts: '.length)
+      : null;
+    entries.push({
+      at,
+      runId: runField.slice('run '.length),
+      phase,
+      event,
+      detail: rest.join(' | '),
+      artifacts: artifactsPart ? artifactsPart.split(', ') : [],
+    });
+  }
+  return { exists: true, entries };
+}
+
+module.exports = {
+  EXECUTION_LOG_FILE,
+  executionLogPath,
+  normalizeExecutionLogEntry,
+  renderExecutionLogEntry,
+  appendExecutionLog,
+  executionLogExists,
+  readExecutionLogEntries,
+};

package/skills/wix-replatform/lib/execution-manifest.js

@@ -13,9 +13,10 @@ const URL_PRESERVATION_PATHS = [
   'unresolvedPath',
 ];
 
-function createManifest({ projectId, planVersion, tasks = [], generatedArtifacts = [], llmHandoff = null, timestamp = new Date().toISOString() }) {
+function createManifest({ projectId, planVersion, tasks = [], generatedArtifacts = [], llmHandoff = null, timestamp = new Date().toISOString(), mappingPlanDigest }) {
   return {
     schemaVersion: SCHEMA_VERSION,
+    ...(mappingPlanDigest ? { mappingPlanDigest } : {}),
     projectId,
     planVersion,
     generatedAt: timestamp,
@@ -25,7 +26,7 @@ function createManifest({ projectId, planVersion, tasks = [], generatedArtifacts
   };
 }
 
-function validateManifest(manifest) {
+function validateManifest(manifest, producerInputs = null) {
   const errors = [];
   if (!manifest || typeof manifest !== 'object') {
     errors.push('manifest must be an object');
@@ -74,12 +75,28 @@ function validateManifest(manifest) {
       validateUrlPreservation(task, errors);
       if (task.kind === 'import') {
         validateImportTaskState(task, errors);
+        if (!Array.isArray(task.entityRefs) || !task.entityRefs.length || new Set(task.entityRefs).size !== task.entityRefs.length) errors.push(`task.entityRefs required:${task.id}`);
+        if (!Array.isArray(task.dependencyEdges)) errors.push(`dependency_edges_required:${task.id}`);
+        if (!Array.isArray(task.dependencyRefs)) errors.push(`dependency_refs_required:${task.id}`);
+        if (!/^[a-f0-9]{64}$/.test(manifest.mappingPlanDigest || '')) errors.push('mapping_plan_digest_required');
       }
     }
   }
+  if (producerInputs && Array.isArray(manifest.tasks)) { const binding = require('./dependency-readiness').bindDependencyProducers({ manifest, ...producerInputs }); errors.push(...binding.errors); }
   return { ok: errors.length === 0, errors };
 }
 
+async function validateManifestForProject(projectDir) {
+  const fs = require('node:fs/promises'), path = require('node:path');
+  const readiness = require('./dependency-readiness');
+  const manifest = JSON.parse(await fs.readFile(path.join(projectDir, 'execution/execution-manifest.json'), 'utf8'));
+  const setupPlan = JSON.parse(await fs.readFile(path.join(projectDir, 'setup/setup-plan.json'), 'utf8'));
+  const adapter = await readiness.loadDependencyDispositions(projectDir);
+  const validation = validateManifest(manifest, { setupPlan, dispositions: adapter.dispositions });
+  try { readiness.validateImportInputs(projectDir); } catch (error) { validation.errors.push(error.message); validation.ok = false; }
+  return validation;
+}
+
 function validateUrlPreservation(task, errors) {
   if (task.urlPreservation === undefined) {
     return;
@@ -181,5 +198,6 @@ module.exports = {
   SCHEMA_VERSION,
   createManifest,
   validateManifest,
+  validateManifestForProject,
   nextPendingTask,
 };

package/skills/wix-replatform/lib/execution-state.js

@@ -28,6 +28,26 @@ function hasDownloadMirror(task) {
   return mirror.mode === 'download' || mirror.mode === 'download-and-upload' || mirror.downloadBeforeRun === true;
 }
 
+// The POST-execution counterpart of hasDownloadMirror, and the
+// gate the generated snapshot pass is run behind. Before this existed, `upload` and the upload
+// half of `download-and-upload` were accepted by validateCmsMirror and reached no code path at
+// all, so a mirror the owner asked for stayed empty by construction.
+//
+// `none` (and an absent cmsMirror) means NOTHING: no collection reads, no writes, and no empty
+// pass reported as a success. Site storage is a shared, plan-based allowance, and a migration's
+// ledger can be a meaningful fraction of a smaller plan's entire quota, so the mirror is spent
+// only when the approved plan actually asked for it.
+//
+// Note this is deliberately NOT `!hasDownloadMirror`: `download` seeds before the run and
+// uploads nothing afterwards, and `downloadBeforeRun` is a download-side flag only.
+function hasUploadMirror(task) {
+  const mirror = task && task.state && task.state.cmsMirror;
+  if (!mirror || mirror.mode === 'none') {
+    return false;
+  }
+  return mirror.mode === 'upload' || mirror.mode === 'download-and-upload';
+}
+
 function hasLocalCrosswalk(task) {
   return Boolean(task.state && task.state.crosswalkPath);
 }
@@ -170,4 +190,6 @@ async function prepareExecutionState(projectDir, manifest, options = {}) {
 
 module.exports = {
   prepareExecutionState,
+  hasDownloadMirror,
+  hasUploadMirror,
 };

package/skills/wix-replatform/lib/expectations-ledger.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const LEDGER_FILE = 'EXPECTATIONS.md';
+
+const STARTER = `# Migration expectations
+
+Use this file to record anything you expected the migration to do differently: a
+surprising question, a mapping you expected, or an outcome that did not match your
+intent. Write freely anywhere in this document.
+
+You can also tell the agent: \`add to expectations: <your note>\`. It will preserve
+your note and add safe references to the current migration context. Do not put passwords,
+tokens, customer data, or other secrets here.
+`;
+
+function ledgerPath(projectDir) {
+  return path.join(path.resolve(projectDir), LEDGER_FILE);
+}
+
+async function ensureLedger(projectDir) {
+  const file = ledgerPath(projectDir);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  try {
+    await fs.writeFile(file, STARTER, { encoding: 'utf8', flag: 'wx' });
+    return { file, created: true };
+  } catch (error) {
+    if (error.code === 'EEXIST') return { file, created: false };
+    throw error;
+  }
+}
+
+function redactSensitiveText(value) {
+  return String(value || '')
+    .replace(/\b(bearer)\s+[A-Za-z0-9._~+/=-]{8,}/gi, '$1 [REDACTED]')
+    .replace(/\b(password|passwd|secret|token|api[-_ ]?key|authorization|cookie)\b\s*([:=])\s*[^\s,;]+/gi, '$1$2[REDACTED]');
+}
+
+function safeArtifactRef(projectDir, ref) {
+  if (!ref) return null;
+  const root = path.resolve(projectDir);
+  const candidate = path.resolve(root, ref);
+  const relative = path.relative(root, candidate);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return relative || '.';
+}
+
+function nextId(contents) {
+  const ids = [...contents.matchAll(/^##\s+E-(\d+)\b/gm)].map((match) => Number(match[1]));
+  return `E-${String((ids.length ? Math.max(...ids) : 0) + 1).padStart(3, '0')}`;
+}
+
+function formatContext(projectDir, context = {}) {
+  const lines = [];
+  for (const [label, value] of [
+    ['Stage', context.phase],
+    ['State', context.state],
+    ['Active resource', context.resource],
+    ['Source', context.source],
+    ['Target', context.target],
+    ['Decision or approval', context.decision],
+  ]) {
+    if (value) lines.push(`- ${label}: ${redactSensitiveText(value)}`);
+  }
+  for (const ref of context.artifactRefs || []) {
+    const safeRef = safeArtifactRef(projectDir, ref);
+    if (safeRef) lines.push(`- Artifact: \`${safeRef}\``);
+  }
+  return lines.length ? lines.join('\n') : '- No reliable run context was available when this was captured.';
+}
+
+async function appendExpectation(projectDir, expectation, context = {}, now = new Date()) {
+  if (!String(expectation || '').trim()) throw new Error('expectation is required');
+  const { file } = await ensureLedger(projectDir);
+  const contents = await fs.readFile(file, 'utf8');
+  const id = nextId(contents);
+  const original = String(expectation).trim();
+  const note = redactSensitiveText(original).trim();
+  const heading = note === original ? 'User expectation (verbatim)' : 'User expectation (sensitive values redacted)';
+  const entry = `\n## ${id} — ${now.toISOString()}\n\n### ${heading}\n\n${note}\n\n### Context captured by the agent\n\n${formatContext(projectDir, context)}\n`;
+  await fs.appendFile(file, entry, 'utf8');
+  return { file, id, redacted: note !== original };
+}
+
+module.exports = {
+  LEDGER_FILE,
+  STARTER,
+  ledgerPath,
+  ensureLedger,
+  redactSensitiveText,
+  safeArtifactRef,
+  nextId,
+  appendExpectation,
+};

package/skills/wix-replatform/lib/generated-plugin-handoff.js

@@ -0,0 +1,140 @@
+'use strict';
+
+// Exact generated wiring, not a JavaScript analyzer. Configuration comes from the
+// canonical source/mapping artifacts, never from generated --describe output.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const VERSION = 1;
+const FILES = ['src/import/plugin-handoff.js', 'src/import/run-import.js', 'src/extract/run-extract.js'];
+const HELPERS = ['plugin-entity-read-plan.js', 'structure-bridge-reader.js', 'wix-wp-plugin-v2-client.js'];
+const digest = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+function canonicalEntities(projectDir) {
+  const read = (name) => fs.existsSync(path.join(projectDir, name)) ? JSON.parse(fs.readFileSync(path.join(projectDir, name), 'utf8')) : {};
+  const schema = read('source-schema.json');
+  const mapping = read('mapping/mapping-plan.json');
+  const rows = (value) => Array.isArray(value) ? value : Object.entries(value || {}).filter(([, row]) => row && typeof row === 'object').map(([key, row]) => ({ sourceEntityRef: key, ...row }));
+  const sources = rows(schema.entities);
+  const decisions = require('./website-handoff.js').readEntityMappings(mapping);
+  const referenceOf = (row) => row.sourceEntityRef || row.ref || row.entity || row.sourceEntity || row.entityKey || (typeof row.source === 'string' ? row.source : null);
+  const planned = new Set(decisions.filter((row) => row.targetRef && !['excluded', 'declined', 'pending', 'deferred', 'manual', 'blocked', 'unsupported'].includes(row.status))
+    .map((row) => referenceOf(row)));
+  const combined = new Map(sources.map((row) => [referenceOf(row), row]));
+  for (const decision of decisions) {
+    const key = referenceOf(decision);
+    if (!key) throw new Error('mapping entity lacks identity');
+    const source = combined.get(key) || {};
+    combined.set(key, { ...source, ...decision, sourceMeta: { ...decision.sourceMeta, ...source.sourceMeta } });
+  }
+  return [...combined].filter(([key]) => key).map(([key, row]) => ({
+    sourceEntityRef: key, sourceEntity: row.sourceEntity || row.entityKey || row.entity || (typeof row.source === 'string' ? row.source : key),
+    sourceType: row.sourceType || null,
+    sourceTypes: row.sourceTypes || null,
+    bridgeDesignated: Boolean(row.bridgeDesignated || row.sourceMeta?.extractionPlan || row.fulfillment?.kind === 'structure-bridge-plugin'),
+    sourceMeta: row.sourceMeta?.extractionPlan ? { extractionPlan: row.sourceMeta.extractionPlan } : {},
+    sourcePrerequisites: row.sourcePrerequisites || [],
+    importPlanned: planned.has(key),
+  })).sort((a, b) => a.sourceEntityRef.localeCompare(b.sourceEntityRef));
+}
+function templates(entities) {
+  const config = JSON.stringify({ version: VERSION, entities }, null, 2);
+  const wiring = `'use strict';\nconst runtime = require('../lib/plugin-entity-read-plan.js');\nconst config = ${config};\nmodule.exports = { config, run: (kind, projectDir, args) => runtime.runGeneratedPluginEntrypoint({ kind, projectDir, entities: config.entities }, args) };\n`;
+  const entry = (kind, directory) => `'use strict';\nconst path = require('node:path');\nconst handoff = require('${directory}plugin-handoff.js');\nhandoff.run('${kind}', path.resolve(__dirname, '../..'), process.argv.slice(2)).catch((error) => { console.error(error.message); process.exitCode = 1; });\n`;
+  return { [FILES[0]]: wiring, [FILES[1]]: entry('import', './'), [FILES[2]]: entry('extract', '../import/') };
+}
+function moduleSourceDir() { return path.resolve(__dirname, '../resources/rp-source-wordpress/lib'); }
+function vendorSharedDependencies(projectDir) {
+  const visited = new Set();
+  function copy(file) {
+    if (visited.has(file)) return;
+    visited.add(file);
+    const source = fs.readFileSync(file, 'utf8');
+    const destination = noSymlinks(projectDir, `src/lib/${path.basename(file)}`);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(file, destination);
+    for (const match of source.matchAll(/require\(['"](.\/[^'"]+)['"]\)/g)) copy(require.resolve(path.resolve(path.dirname(file), match[1])));
+  }
+  copy(path.join(__dirname, 'import-recovery.js'));
+  copy(path.join(__dirname, 'import-readiness-contract.js'));
+}
+function noSymlinks(projectDir, relativePath) {
+  let cursor = path.resolve(projectDir);
+  for (const token of relativePath.split('/')) {
+    cursor = path.join(cursor, token);
+    if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink()) throw new Error('generated handoff symlink refused');
+  }
+  return cursor;
+}
+function validateDispatchMapping(projectDir) {
+  const file = path.join(projectDir, 'mapping/mapping-plan.json');
+  const mapping = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+  const rows = require('./website-handoff.js').readEntityMappings(mapping);
+  for (const row of rows) {
+    if (!row.targetRef && !['excluded', 'declined', 'pending', 'deferred', 'manual', 'blocked', 'unsupported'].includes(row.status)) {
+      throw new Error('mapping targetRef is missing; normalize the declared legacy target before emitting dispatch, never drop its scope');
+    }
+  }
+}
+function emitPluginHandoff(projectDir) {
+  const entities = canonicalEntities(projectDir);
+  validateDispatchMapping(projectDir);
+  if (!entities.some((entity) => entity.bridgeDesignated)) throw new Error('no canonical bridge entities');
+  const emitted = templates(entities);
+  // Inspect every destination before any mutation. Existing project entrypoints must be
+  // deliberately adapted, never silently replaced by adding one bridge entity.
+  for (const [name, expected] of Object.entries(emitted)) {
+    const file = noSymlinks(projectDir, name);
+    if (!fs.existsSync(file)) continue;
+    const existing = fs.readFileSync(file, 'utf8');
+    let owned = existing === expected;
+    if (!owned && name === FILES[0]) {
+      try {
+        const match = existing.match(/const config = ([\s\S]*?);\nmodule.exports =/);
+        const config = JSON.parse(match[1]);
+        owned = config.version === VERSION && existing === templates(config.entities)[name];
+      } catch { /* Unrecognized wiring belongs to the project. */ }
+    }
+    if (!owned) throw new Error(`refusing to overwrite non-template entrypoint: ${name}; preserve its ordering, self-check, heartbeat and ledger in the project adapter before deliberately replacing it`);
+  }
+  for (const [name, text] of Object.entries(emitted)) {
+    const file = noSymlinks(projectDir, name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text);
+  }
+  for (const helper of HELPERS) {
+    const file = noSymlinks(projectDir, `src/lib/${helper}`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.copyFileSync(path.join(moduleSourceDir(), helper), file);
+  }
+  vendorSharedDependencies(projectDir);
+  return { version: VERSION, files: FILES };
+}
+function verifyPluginHandoff(projectDir, selection = {}) {
+  const entities = canonicalEntities(projectDir);
+  const selected = require(path.join(moduleSourceDir(), 'plugin-entity-read-plan.js')).selectPluginEntities(entities, selection);
+  const byRef = new Map(entities.map((entity) => [entity.sourceEntityRef, entity]));
+  const closure = new Map();
+  const visit = (entity, stack = new Set()) => {
+    if (stack.has(entity.sourceEntityRef)) throw new Error('cyclic source prerequisites');
+    if (closure.has(entity.sourceEntityRef)) return;
+    closure.set(entity.sourceEntityRef, entity);
+    for (const ref of entity.sourcePrerequisites) {
+      const source = byRef.get(ref);
+      if (!source) throw new Error('missing canonical source prerequisite');
+      visit(source, new Set([...stack, entity.sourceEntityRef]));
+    }
+  };
+  selected.forEach((entity) => visit(entity));
+  if (![...closure.values()].some((entity) => entity.bridgeDesignated)) return { applicable: false, entities: [] };
+  validateDispatchMapping(projectDir);
+  for (const [name, expected] of Object.entries(templates(entities))) {
+    const file = noSymlinks(projectDir, name);
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== expected) throw new Error(`generated plugin handoff differs from committed template: ${name}`);
+  }
+  for (const helper of HELPERS) {
+    const file = noSymlinks(projectDir, `src/lib/${helper}`);
+    if (!fs.existsSync(file) || digest(fs.readFileSync(file)) !== digest(fs.readFileSync(path.join(moduleSourceDir(), helper)))) throw new Error(`changed vendored plugin helper: ${helper}`);
+  }
+  return { applicable: true, entities: [...closure.values()] };
+}
+module.exports = { VERSION, FILES, HELPERS, canonicalEntities, emitPluginHandoff, verifyPluginHandoff, templates };

package/skills/wix-replatform/lib/import-readiness-contract.js

@@ -0,0 +1,23 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+function files(root) {
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true }).flatMap(entry => entry.isDirectory() ? files(path.join(root, entry.name)) : /\.[cm]?js$/.test(entry.name) ? [path.join(root, entry.name)] : []);
+}
+function verifyReadinessContract(projectDir, descriptor) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(projectDir, 'execution/execution-manifest.json'), 'utf8'));
+  const expected = manifest.tasks.filter(task => task.kind === 'import').map(task => ({ taskId: task.id, edges: task.dependencyEdges.map(({ ref, mode }) => ({ ref, mode })).sort((a, b) => a.ref.localeCompare(b.ref)) })).sort((a, b) => a.taskId.localeCompare(b.taskId));
+  const reported = descriptor.dependencyReadiness?.tasks?.map(task => ({ taskId: task.taskId, edges: task.edges.map(({ ref, mode }) => ({ ref, mode })).sort((a, b) => a.ref.localeCompare(b.ref)) })).sort((a, b) => a.taskId.localeCompare(b.taskId));
+  const errors = [];
+  if (JSON.stringify(expected) !== JSON.stringify(reported)) errors.push('dependency_readiness_descriptor_mismatch');
+  for (const file of files(path.join(projectDir, 'src')).filter(file => !/^(?:lib|extract)[/\\]/.test(path.relative(path.join(projectDir, 'src'), file)))) {
+    const text = fs.readFileSync(file, 'utf8'), relative = path.relative(projectDir, file);
+    if (/\b(?:startSetupRun|bindSetupStep|startQuickRun|startDevProbe|createWixSetupExecutor)\b|execution-capability(?:\.js)?/.test(text)) errors.push(`execution_capability_bypass:${relative}`);
+    // Vendored shared libraries live outside the generated transform directory. Generated
+    // transforms must obtain references through gate-owned resolvers, not read local evidence.
+    if (/crosswalk|loadCrosswalk|readEntityCrosswalk|local-state|data[\\/]source-extract/.test(text) && !/(?:^|\/)run-import\.[cm]?js$/.test(relative)) errors.push(`dependency_reference_bypass:${relative}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+module.exports = { verifyReadinessContract, files };