@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,120 +0,0 @@
-'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

@@ -1,170 +0,0 @@
-'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

@@ -1,203 +0,0 @@
-'use strict';
-
-const SCHEMA_VERSION = 1;
-
-const TASK_KIND = new Set(['setup', 'extract', 'import']);
-const TASK_STATUS = new Set(['pending', 'running', 'completed', 'blocked', 'failed', 'skipped']);
-const CROSSWALK_AUTHORITY = new Set(['local']);
-const CMS_MIRROR_MODE = new Set(['none', 'download', 'upload', 'download-and-upload']);
-const URL_PRESERVATION_PATHS = [
-  'basePathsPath',
-  'ledgerPath',
-  'redirectsPath',
-  'unresolvedPath',
-];
-
-function createManifest({ projectId, planVersion, tasks = [], generatedArtifacts = [], llmHandoff = null, timestamp = new Date().toISOString(), mappingPlanDigest }) {
-  return {
-    schemaVersion: SCHEMA_VERSION,
-    ...(mappingPlanDigest ? { mappingPlanDigest } : {}),
-    projectId,
-    planVersion,
-    generatedAt: timestamp,
-    generatedArtifacts,
-    tasks,
-    llmHandoff,
-  };
-}
-
-function validateManifest(manifest, producerInputs = null) {
-  const errors = [];
-  if (!manifest || typeof manifest !== 'object') {
-    errors.push('manifest must be an object');
-    return { ok: false, errors };
-  }
-  if (manifest.schemaVersion !== SCHEMA_VERSION) {
-    errors.push(`schemaVersion must be ${SCHEMA_VERSION}`);
-  }
-  if (!manifest.projectId || typeof manifest.projectId !== 'string') {
-    errors.push('projectId must be a non-empty string');
-  }
-  if (!manifest.planVersion || typeof manifest.planVersion !== 'string') {
-    errors.push('planVersion must be a non-empty string');
-  }
-  if (!Array.isArray(manifest.generatedArtifacts)) {
-    errors.push('generatedArtifacts must be an array');
-  }
-  if (!Array.isArray(manifest.tasks) || manifest.tasks.length === 0) {
-    errors.push('tasks must be a non-empty array');
-  } else {
-    const ids = new Set();
-    for (const task of manifest.tasks) {
-      if (!task || typeof task !== 'object') {
-        errors.push('task must be an object');
-        continue;
-      }
-      if (!task.id || typeof task.id !== 'string') {
-        errors.push('task.id must be a non-empty string');
-      } else if (ids.has(task.id)) {
-        errors.push(`duplicate task id: ${task.id}`);
-      } else {
-        ids.add(task.id);
-      }
-      if (!TASK_KIND.has(task.kind)) {
-        errors.push(`task.kind invalid for ${task.id || '<unknown>'}`);
-      }
-      if (task.status && !TASK_STATUS.has(task.status)) {
-        errors.push(`task.status invalid for ${task.id || '<unknown>'}`);
-      }
-      if (!Array.isArray(task.dependsOn)) {
-        errors.push(`task.dependsOn must be an array for ${task.id || '<unknown>'}`);
-      }
-      if (!Array.isArray(task.artifactRefs)) {
-        errors.push(`task.artifactRefs must be an array for ${task.id || '<unknown>'}`);
-      }
-      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;
-  }
-  const label = task.id || '<unknown>';
-  if (task.kind !== 'import') {
-    errors.push(`task.urlPreservation is only allowed for import tasks in ${label}`);
-  }
-  const policy = task.urlPreservation;
-  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
-    errors.push(`task.urlPreservation must be an object for ${label}`);
-    return;
-  }
-  if (policy.enabled !== undefined && typeof policy.enabled !== 'boolean') {
-    errors.push(`task.urlPreservation.enabled must be a boolean for ${label}`);
-  }
-  if (policy.applyRedirects === true) {
-    errors.push(`task.urlPreservation.applyRedirects must be false until website-builder redirect application is supported for ${label}`);
-  }
-  if (policy.applyRedirects !== undefined && typeof policy.applyRedirects !== 'boolean') {
-    errors.push(`task.urlPreservation.applyRedirects must be a boolean for ${label}`);
-  }
-  if (policy.enabled === true) {
-    for (const field of URL_PRESERVATION_PATHS) {
-      if (!policy[field] || typeof policy[field] !== 'string') {
-        errors.push(`task.urlPreservation.${field} required when enabled for ${label}`);
-      }
-    }
-    if (policy.applyRedirects !== false) {
-      errors.push(`task.urlPreservation.applyRedirects must be false when enabled for ${label}`);
-    }
-  }
-}
-
-function hasServerAssignedNativeTargetIds(task) {
-  return task.targetIdAssignment === 'server' ||
-    task.targetIdAssignment === 'server-assigned' ||
-    task.nativeTargetIds === 'server-assigned' ||
-    task.targetIdsServerAssigned === true;
-}
-
-function validateCmsMirror(task, state, errors) {
-  if (!state.cmsMirror || typeof state.cmsMirror !== 'object') {
-    return;
-  }
-  const mode = state.cmsMirror.mode;
-  if (!CMS_MIRROR_MODE.has(mode)) {
-    errors.push(`task.state.cmsMirror.mode invalid for ${task.id || '<unknown>'}`);
-    return;
-  }
-  if (mode !== 'none') {
-    if (!state.cmsMirror.collectionId || typeof state.cmsMirror.collectionId !== 'string') {
-      errors.push(`task.state.cmsMirror.collectionId required when CMS mirror is enabled for ${task.id || '<unknown>'}`);
-    }
-    if (!state.cmsMirror.setupRequirementId || typeof state.cmsMirror.setupRequirementId !== 'string') {
-      errors.push(`task.state.cmsMirror.setupRequirementId required when CMS mirror is enabled for ${task.id || '<unknown>'}`);
-    }
-  }
-}
-
-function validateImportTaskState(task, errors) {
-  const state = task.state;
-  if (!state || typeof state !== 'object') {
-    if (hasServerAssignedNativeTargetIds(task)) {
-      errors.push(`task.state required for server-assigned native target IDs in ${task.id || '<unknown>'}`);
-    }
-    return;
-  }
-  if (state.crosswalkAuthority === 'cms') {
-    errors.push(`task.state.crosswalkAuthority must not be cms for ${task.id || '<unknown>'}`);
-  }
-  if (state.crosswalkAuthority !== undefined && !CROSSWALK_AUTHORITY.has(state.crosswalkAuthority)) {
-    errors.push(`task.state.crosswalkAuthority invalid for ${task.id || '<unknown>'}`);
-  }
-  if (hasServerAssignedNativeTargetIds(task) && (!state.crosswalkPath || typeof state.crosswalkPath !== 'string')) {
-    errors.push(`task.state.crosswalkPath required for server-assigned native target IDs in ${task.id || '<unknown>'}`);
-  }
-  if (state.attemptJournalPath !== undefined && typeof state.attemptJournalPath !== 'string') {
-    errors.push(`task.state.attemptJournalPath must be a string for ${task.id || '<unknown>'}`);
-  }
-  validateCmsMirror(task, state, errors);
-}
-
-function nextPendingTask(manifest, completedIds = new Set()) {
-  const done = completedIds instanceof Set ? completedIds : new Set(completedIds || []);
-  for (const task of manifest.tasks || []) {
-    if (task.status === 'completed' || done.has(task.id)) {
-      continue;
-    }
-    const deps = Array.isArray(task.dependsOn) ? task.dependsOn : [];
-    if (deps.every((dep) => done.has(dep))) {
-      return task;
-    }
-  }
-  return null;
-}
-
-module.exports = {
-  SCHEMA_VERSION,
-  createManifest,
-  validateManifest,
-  validateManifestForProject,
-  nextPendingTask,
-};

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

@@ -1,195 +0,0 @@
-'use strict';
-
-const fs = require('node:fs/promises');
-const path = require('node:path');
-const { validateManifest } = require('./execution-manifest.js');
-const {
-  attemptJournalPath,
-  crosswalkPath,
-  dryRunCrosswalkPath,
-  loadCrosswalk,
-  rebuildCrosswalkIndexes,
-  seedCrosswalkFromCmsMirror,
-  wixRequestCapturesPath,
-} = require('./local-state.js');
-const { initUrlPreservationState } = require('./url-preservation-state.js');
-
-function importTasks(manifest) {
-  return (manifest.tasks || [])
-    .filter((task) => task && task.kind === 'import')
-    .sort((a, b) => Number(hasDownloadMirror(b)) - Number(hasDownloadMirror(a)));
-}
-
-function hasDownloadMirror(task) {
-  const mirror = task.state && task.state.cmsMirror;
-  if (!mirror || mirror.mode === 'none') {
-    return false;
-  }
-  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);
-}
-
-async function pathExists(filePath) {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch (error) {
-    if (error && error.code === 'ENOENT') {
-      return false;
-    }
-    throw error;
-  }
-}
-
-async function ensureEmptyNdjson(filePath) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  if (!(await pathExists(filePath))) {
-    await fs.writeFile(filePath, '', 'utf8');
-    return true;
-  }
-  return false;
-}
-
-async function readMirrorRowsFromMap(task, rowsByTaskId) {
-  if (!rowsByTaskId || !Object.prototype.hasOwnProperty.call(rowsByTaskId, task.id)) {
-    return undefined;
-  }
-  return rowsByTaskId[task.id];
-}
-
-async function prepareExecutionState(projectDir, manifest, options = {}) {
-  const validation = validateManifest(manifest);
-  if (!validation.ok) {
-    return {
-      ok: false,
-      status: 'blocked',
-      errors: validation.errors,
-      actions: [],
-    };
-  }
-
-  const actions = [];
-  const errors = [];
-  const mirrorRowsByTaskId = options.cmsMirrorRowsByTaskId || {};
-  const dryRun = options.dryRun === true;
-
-  if (dryRun) {
-    const requestCapturesCreated = await ensureEmptyNdjson(wixRequestCapturesPath(projectDir));
-    actions.push({
-      action: requestCapturesCreated ? 'initialized_wix_request_captures' : 'kept_wix_request_captures',
-      path: 'state/attempts/wix-request-captures.ndjson',
-    });
-    const dryRunCrosswalkCreated = await ensureEmptyNdjson(dryRunCrosswalkPath(projectDir));
-    actions.push({
-      action: dryRunCrosswalkCreated ? 'initialized_dry_run_crosswalk' : 'kept_dry_run_crosswalk',
-      path: 'state/crosswalk/dry-run-crosswalk.ndjson',
-    });
-  }
-
-  for (const task of importTasks(manifest)) {
-    if (task.urlPreservation && task.urlPreservation.enabled === true) {
-      const urlActions = await initUrlPreservationState(projectDir);
-      for (const action of urlActions) {
-        actions.push({
-          taskId: task.id,
-          ...action,
-        });
-      }
-    }
-
-    if (!hasLocalCrosswalk(task)) {
-      continue;
-    }
-
-    const localPath = crosswalkPath(projectDir);
-    const localExists = await pathExists(localPath);
-
-    if (localExists) {
-      await loadCrosswalk(projectDir);
-      await rebuildCrosswalkIndexes(projectDir);
-      actions.push({
-        taskId: task.id,
-        action: 'rebuilt_crosswalk_indexes',
-        path: task.state.crosswalkPath,
-      });
-    } else if (hasDownloadMirror(task)) {
-      let rows = await readMirrorRowsFromMap(task, mirrorRowsByTaskId);
-      if (rows === undefined && typeof options.downloadCmsMirrorRows === 'function') {
-        rows = await options.downloadCmsMirrorRows(task);
-      }
-      if (rows === undefined) {
-        errors.push(`CMS mirror download configured for ${task.id}, but no CMS mirror rows provider was supplied`);
-        continue;
-      }
-      const seeded = await seedCrosswalkFromCmsMirror(projectDir, rows);
-      actions.push({
-        taskId: task.id,
-        action: seeded.seeded ? 'seeded_crosswalk_from_cms_mirror' : 'skipped_cms_seed',
-        ...seeded,
-      });
-    } else {
-      await ensureEmptyNdjson(localPath);
-      await rebuildCrosswalkIndexes(projectDir);
-      actions.push({
-        taskId: task.id,
-        action: 'initialized_empty_crosswalk',
-        path: task.state.crosswalkPath,
-      });
-    }
-
-    if (task.state.attemptJournalPath) {
-      const created = await ensureEmptyNdjson(attemptJournalPath(projectDir));
-      actions.push({
-        taskId: task.id,
-        action: created ? 'initialized_attempt_journal' : 'kept_attempt_journal',
-        path: task.state.attemptJournalPath,
-      });
-    }
-
-  }
-
-  if (errors.length) {
-    return {
-      ok: false,
-      status: 'blocked',
-      errors,
-      actions,
-    };
-  }
-
-  return {
-    ok: true,
-    status: 'ready',
-    errors: [],
-    actions,
-  };
-}
-
-module.exports = {
-  prepareExecutionState,
-  hasDownloadMirror,
-  hasUploadMirror,
-};