@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-quick-woocommerce/quick-mode.json

@@ -0,0 +1,91 @@
+{
+  "schemaVersion": 1,
+  "id": "quick-woocommerce",
+  "version": "1.1.0",
+  "platform": "woocommerce",
+  "minimumProbeConfidence": "high",
+  "requiredProbeStrategies": [
+    "wc.store.products",
+    "wp.posts"
+  ],
+  "publicAuth": "none",
+  "entities": [
+    {
+      "id": "product_category",
+      "route": "/wp-json/wc/store/v1/products/categories",
+      "target": "stores/category",
+      "dependsOn": []
+    },
+    {
+      "id": "product_tag",
+      "route": "/wp-json/wc/store/v1/products/tags",
+      "target": "stores/product-tag",
+      "dependsOn": []
+    },
+    {
+      "id": "blog_category",
+      "route": "/wp-json/wp/v2/categories",
+      "target": "blog/category",
+      "dependsOn": []
+    },
+    {
+      "id": "blog_tag",
+      "route": "/wp-json/wp/v2/tags",
+      "target": "blog/tag",
+      "dependsOn": []
+    },
+    {
+      "id": "post",
+      "route": "/wp-json/wp/v2/posts",
+      "target": "blog/post",
+      "dependsOn": [
+        "blog_category",
+        "blog_tag"
+      ]
+    },
+    {
+      "id": "product",
+      "route": "/wp-json/wc/store/v1/products",
+      "target": "stores/product",
+      "dependsOn": [
+        "product_category",
+        "product_tag"
+      ]
+    }
+  ],
+  "requiredWixCapabilities": [
+    "stores",
+    "blog"
+  ],
+  "excluded": [
+    "customers",
+    "members",
+    "orders",
+    "refunds",
+    "coupons",
+    "taxes",
+    "reviews",
+    "shipping",
+    "payments",
+    "plugin-data",
+    "draft-private-password-protected-content",
+    "unreferenced-media"
+  ],
+  "excludedCapabilities": {
+    "customers": "crm.contact",
+    "members": "identity.member",
+    "orders": "commerce.orders",
+    "refunds": "commerce.order-refunds",
+    "coupons": "commerce.coupons",
+    "taxes": "commerce.tax-settings",
+    "reviews": "commerce.product-reviews",
+    "shipping": "commerce.shipping-rate",
+    "payments": "commerce.order-payments",
+    "plugin-data": "source-scope.plugin-data",
+    "draft-private-password-protected-content": "source-scope.draft-private-password-protected-content",
+    "unreferenced-media": "source-scope.unreferenced-media"
+  },
+  "setupOperations": [
+    "blog-fallback-author"
+  ]
+}

package/skills/wix-replatform/resources/rp-quick-woocommerce/scripts/quick-mode.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+'use strict';
+
+// Public-only, read-only WooCommerce quick-mode capture. This deliberately contains no
+// credentials, browser automation, or fallback endpoint guessing.
+const capabilities = require('../../../lib/execution-capability');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const ADAPTER_DIR = path.resolve(__dirname, '..');
+const CONTRACT_PATH = path.join(ADAPTER_DIR, 'quick-mode.json');
+const CONTRACT = require(CONTRACT_PATH);
+const sourceCoverage = require(path.join(ADAPTER_DIR, '..', '..', 'lib', 'source-coverage.js'));
+const recovery = require(path.join(ADAPTER_DIR, '..', 'rp-quick-runtime', 'lib', 'limit-recovery.js'));
+const importProgress = require(path.join(ADAPTER_DIR, '..', 'rp-quick-runtime', 'lib', 'import-progress.js'));
+// On the public Store API this is a no-op — `src` there is already the original — so
+// the URLs produced here do not change. It is called anyway because naming an image field
+// directly is how a whole catalog once shipped as thumbnails: the same idiom got copied onto the
+// authenticated wc/v3 payload, where `src` can be the smallest crop.
+const { resolveImageUrls } = require(path.join(ADAPTER_DIR, '..', 'rp-source-wordpress', 'lib', 'wp-image-url.js'));
+const { composeProductDescription } = require(path.join(ADAPTER_DIR, '..', 'rp-target-wix', 'lib', 'wix-build.js'));
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+// A dry run never touches the live audit log.
+async function appendAudit(projectDir, entry, dryRun = false) {
+  if (dryRun) return;
+  const file = path.join(projectDir, 'logs', 'quick-mode-audit.ndjson');
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.appendFile(file, `${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}\n`, 'utf8');
+}
+function origin(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('sourceUrl must use http or https');
+  return url.origin;
+}
+function fingerprint(value) {
+  return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+async function projectContext(projectDir) {
+  const decisions = await readJson(path.join(projectDir, 'orchestration', 'decisions.json'));
+  const sourceUrl = decisions.sourceUrl && decisions.sourceUrl.value;
+  const sourcePlatform = decisions.sourcePlatform && decisions.sourcePlatform.value;
+  if (!sourceUrl) throw new Error('quick mode requires orchestration.decisions.sourceUrl');
+  if (sourcePlatform !== 'woocommerce') throw new Error(`quick WooCommerce adapter requires sourcePlatform=woocommerce (got ${sourcePlatform || 'missing'})`);
+  return { sourceUrl: origin(sourceUrl), decisions };
+}
+async function fetchCollection(baseUrl, route) {
+  const records = [];
+  const pages = [];
+  for (let page = 1; ; page += 1) {
+    const url = new URL(route, `${baseUrl}/`);
+    url.searchParams.set('page', String(page));
+    url.searchParams.set('per_page', '100');
+    const response = await fetch(url, { headers: { accept: 'application/json' } });
+    const text = await response.text();
+    let body;
+    try { body = text ? JSON.parse(text) : null; } catch { body = null; }
+    if (!response.ok || !Array.isArray(body)) {
+      return { ok: false, status: response.status, url: url.toString(), bodyType: Array.isArray(body) ? 'array' : typeof body, records, pages };
+    }
+    records.push(...body);
+    pages.push({ page, count: body.length, url: url.toString() });
+    const totalPages = Number(response.headers.get('x-wp-totalpages'));
+    if (Number.isFinite(totalPages) ? page >= totalPages : body.length < 100) break;
+  }
+  return { ok: true, records, pages };
+}
+async function preflight(projectDir) {
+  const { sourceUrl } = await projectContext(projectDir);
+  const checks = [];
+  for (const entity of CONTRACT.entities) {
+    const result = await fetchCollection(sourceUrl, entity.route);
+    checks.push({ entity: entity.id, route: entity.route, ok: result.ok, status: result.status || 200, url: result.url || result.pages[0]?.url || null, responseShape: result.ok ? 'array' : result.bodyType });
+  }
+  const out = { schemaVersion: 1, generatedAt: new Date().toISOString(), adapter: { id: CONTRACT.id, version: CONTRACT.version, fingerprint: fingerprint(CONTRACT) }, sourceUrl, status: checks.every((check) => check.ok) ? 'passed' : 'blocked', checks };
+  await writeJson(path.join(projectDir, 'quick-mode', 'preflight.json'), out);
+  return out;
+}
+async function plan(projectDir) {
+  const { sourceUrl } = await projectContext(projectDir);
+  const preflightResult = await readJson(path.join(projectDir, 'quick-mode', 'preflight.json'));
+  if (preflightResult.status !== 'passed') throw new Error('quick mode preflight must pass before planning');
+  const adapter = { id: CONTRACT.id, version: CONTRACT.version, fingerprint: fingerprint(CONTRACT) };
+  const generatedAt = new Date().toISOString();
+  // Every excluded[] capability becomes a declared-exclusion coverage row, checked by the same
+  // reconcile rule as a full run before the plan is written.
+  const coverage = await sourceCoverage.writeQuickPlanCoverage(projectDir, CONTRACT, { rawText: await fs.readFile(CONTRACT_PATH, 'utf8'), generatedAt });
+  const planResult = { schemaVersion: 1, generatedAt, managementImportMode: 'quick', adapter, sourceUrl, entities: CONTRACT.entities, requiredWixCapabilities: CONTRACT.requiredWixCapabilities, excluded: CONTRACT.excluded, excludedCapabilities: CONTRACT.excludedCapabilities, sourceAuth: 'none', sourceCoverageContract: coverage.sourceCoverageContract };
+  await writeJson(path.join(projectDir, 'quick-mode', 'plan.json'), planResult);
+  await writeJson(path.join(projectDir, 'execution', 'execution-manifest.json'), { schemaVersion: 1, generatedAt: planResult.generatedAt, managementImportMode: 'quick', adapter, extractCommand: 'rp-quick-woocommerce extract', importCommand: 'rp-quick-woocommerce import', entities: CONTRACT.entities.map((entity) => entity.id) });
+  return planResult;
+}
+async function extract(projectDir) {
+  const { sourceUrl } = await projectContext(projectDir);
+  const planResult = await readJson(path.join(projectDir, 'quick-mode', 'plan.json'));
+  if (planResult.adapter.fingerprint !== fingerprint(CONTRACT)) throw new Error('quick adapter contract changed; re-run preflight and plan');
+  const entities = {};
+  for (const entity of CONTRACT.entities) {
+    const result = await fetchCollection(sourceUrl, entity.route);
+    if (!result.ok) throw new Error(`${entity.id} extraction failed: ${result.status} ${result.url}`);
+    const file = path.join(projectDir, 'data', 'source-extract', `${entity.id}.ndjson`);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, result.records.map((record) => JSON.stringify(record)).join('\n') + (result.records.length ? '\n' : ''), 'utf8');
+    entities[entity.id] = { file: path.relative(projectDir, file), route: entity.route, recordCount: result.records.length, pages: result.pages };
+  }
+  const manifest = { schemaVersion: 1, generatedAt: new Date().toISOString(), managementImportMode: 'quick', adapter: planResult.adapter, sourceUrl, entities };
+  await writeJson(path.join(projectDir, 'data', 'source-extract', 'manifest.json'), manifest);
+  return manifest;
+}
+function nonEmpty(value) { const text = value == null ? '' : String(value).trim(); return text || undefined; }
+function text(value) { return String(value || '').replace(/<[^>]*>/g, '').replace(/&amp;/g, '&').replace(/&quot;/g, '"').trim(); }
+function slug(value) { return nonEmpty(value)?.toLowerCase().replace(/[_\s]+/g, '-').replace(/[^a-z0-9-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || undefined; }
+function price(value, minor = 2) { const n = Number(value); return Number.isFinite(n) ? (n / (10 ** Number(minor || 2))).toFixed(Number(minor || 2)) : '0.00'; }
+async function readLines(filePath) { const raw = await fs.readFile(filePath, 'utf8'); return raw.split(/\r?\n/).filter(Boolean).map(JSON.parse); }
+async function loadWixEnv(projectDir) {
+  const values = {};
+  try {
+    for (const line of (await fs.readFile(path.join(projectDir, 'config', 'wix.env'), 'utf8')).split(/\r?\n/)) {
+      const m = line.trim().match(/^([A-Z0-9_]+)=(.*)$/); if (m) values[m[1]] = m[2].replace(/^['"]|['"]$/g, '').trim();
+    }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return { ...values, ...process.env };
+}
+async function loadCrosswalk(projectDir) {
+  try { return await readJson(path.join(projectDir, 'state', 'crosswalk', 'quick-mode.json')); }
+  catch (error) { if (error.code === 'ENOENT') return {}; throw error; }
+}
+async function ensureFallbackAuthor(projectDir) {
+  const env = await loadWixEnv(projectDir);
+  if (env.WIX_BLOG_FALLBACK_MEMBER_ID) return { status: 'already_configured', memberId: env.WIX_BLOG_FALLBACK_MEMBER_ID };
+  if (!env.WIX_AUTH_TOKEN || !env.WIX_SITE_ID) throw new Error('WIX_AUTH_TOKEN and WIX_SITE_ID are required to provision the Blog fallback author');
+  const writers = require(path.join(ADAPTER_DIR, '..', 'rp-target-wix', 'lib', 'wix-writers.js'));
+  const dryRun = writers.createDryRunConfig(env, process.argv.slice(2)).dryRun;
+  if (dryRun) return { status: 'planned_dry_run', memberId: null };
+  const quickRun = capabilities.startQuickRun({ projectDir, adapterId: 'quick-woocommerce', siteId: env.WIX_SITE_ID, dryRun: false });
+  const wix = writers.createWixClient({ capability: capabilities.bindQuickSetup(quickRun, 'blog-fallback-author'), authToken: env.WIX_AUTH_TOKEN });
+  const projectId = path.basename(projectDir).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'migration';
+  const email = `replatform+${projectId}@wix.com`;
+  const listed = await writers.listMembers(wix, { limit: 100 });
+  let member = (listed.members || []).find((item) => String(item.loginEmail || '').toLowerCase() === email);
+  if (!member) member = await writers.ensureBlogFallbackAuthor(wix, { email, name: 'Imported content', slug: `imported-content-${projectId}` });
+  if (!member || !member.id) throw new Error('fallback Blog author was not created');
+  const configPath = path.join(projectDir, 'config', 'wix.env');
+  let raw = ''; try { raw = await fs.readFile(configPath, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, `${raw.replace(/\n?WIX_BLOG_FALLBACK_MEMBER_ID=.*(?:\n|$)/g, '\n').replace(/\s*$/, '\n')}WIX_BLOG_FALLBACK_MEMBER_ID=${member.id}\n`, 'utf8');
+  return { status: 'provisioned', memberId: member.id };
+}
+async function importData(projectDir) {
+  const planResult = await readJson(path.join(projectDir, 'quick-mode', 'plan.json'));
+  const manifest = await readJson(path.join(projectDir, 'data', 'source-extract', 'manifest.json'));
+  importProgress.assertQuickImportAdapter({ plan: planResult, manifest, current: { id: CONTRACT.id, version: CONTRACT.version, fingerprint: fingerprint(CONTRACT) } });
+  // Fail closed before any write: a stamped plan with a missing or unreconciled coverage file
+  // must not produce a completion summary.
+  await sourceCoverage.quickSummaryCoverage(projectDir);
+  const env = await loadWixEnv(projectDir);
+  if (!env.WIX_AUTH_TOKEN || !env.WIX_SITE_ID) throw new Error('WIX_AUTH_TOKEN and WIX_SITE_ID are required for quick import');
+  const writers = require(path.join(ADAPTER_DIR, '..', 'rp-target-wix', 'lib', 'wix-writers.js'));
+  const dryRun = writers.createDryRunConfig(env, process.argv.slice(2)).dryRun;
+  const quickRun = capabilities.startQuickRun({ projectDir, adapterId: 'quick-woocommerce', siteId: env.WIX_SITE_ID, dryRun });
+  const clientFor = (id) => writers.createWixClient({ capability: capabilities.bindQuickEntity(quickRun, id), authToken: env.WIX_AUTH_TOKEN });
+  let wix = clientFor('product_category');
+  const sourceDir = path.join(projectDir, 'data', 'source-extract');
+  const crosswalk = await loadCrosswalk(projectDir);
+  // Durable pre-write evidence, before the first destination create. Some
+  // crosswalk checkpoints are deferred (blog tags, products), so the crosswalk cannot serve.
+  if (!dryRun) await importProgress.writeQuickImportStartedMarker(projectDir, planResult.adapter);
+  const seen = (entity, sourceId) => crosswalk[entity] && crosswalk[entity][String(sourceId)];
+  const remember = (entity, sourceId, targetId) => { if (!dryRun) { crosswalk[entity] ||= {}; crosswalk[entity][String(sourceId)] = targetId; } };
+  const checkpointCrosswalk = async () => { if (!dryRun) await writeJson(path.join(projectDir, 'state', 'crosswalk', 'quick-mode.json'), crosswalk); };
+  const summary = { schemaVersion: 1, generatedAt: new Date().toISOString(), managementImportMode: 'quick', adapter: planResult.adapter, dryRun, imported: {}, recovered: 0, recoveryCounts: {}, excluded: CONTRACT.excluded };
+  const categoryIds = new Map(); const productTagIds = new Map(); const blogCategoryIds = new Map(); const blogTagIds = new Map();
+  const existingCategories = new Map((await writers.queryAllStoresCategories(wix)).map((item) => [slug(item.slug), item]));
+  for (const row of await readLines(path.join(sourceDir, 'product_category.ndjson'))) {
+    if (seen('product_category', row.id)) { categoryIds.set(String(row.id), seen('product_category', row.id)); continue; }
+    const sourceSlug = slug(row.slug); const existing = existingCategories.get(sourceSlug);
+    const target = existing || await writers.createStoresCategory(wix, { name: text(row.name), slug: sourceSlug, description: nonEmpty(text(row.description).slice(0, 600)), treeReference: writers.STORES_TREE_REFERENCE }); categoryIds.set(String(row.id), target.id);
+    remember('product_category', row.id, target.id); await checkpointCrosswalk();
+  }
+  summary.imported.product_category = categoryIds.size;
+  capabilities.finishQuickEntity(quickRun, 'product_category'); wix = clientFor('product_tag');
+  const existingProductTags = new Map(((await wix.send(writers.buildListStoresProductTagsRequest())).tags || []).map((item) => [slug(item.name), item]));
+  for (const row of await readLines(path.join(sourceDir, 'product_tag.ndjson'))) {
+    if (seen('product_tag', row.id)) { productTagIds.set(String(row.id), seen('product_tag', row.id)); continue; }
+    const key = slug(row.name); const existing = existingProductTags.get(key);
+    const response = existing || (await wix.send(writers.buildCreateStoresProductTagRequest(text(row.name)))).tag;
+    productTagIds.set(String(row.id), response.id); remember('product_tag', row.id, response.id); await checkpointCrosswalk();
+  }
+  summary.imported.product_tag = productTagIds.size;
+  capabilities.finishQuickEntity(quickRun, 'product_tag'); wix = clientFor('blog_category');
+  const existingBlogCategories = new Map(((await wix.send(writers.buildQueryBlogCategoriesRequest())).categories || []).map((item) => [slug(item.slug), item]));
+  for (const row of await readLines(path.join(sourceDir, 'blog_category.ndjson'))) { if (seen('blog_category', row.id)) { blogCategoryIds.set(String(row.id), seen('blog_category', row.id)); continue; } const existing = existingBlogCategories.get(slug(row.slug)); const created = existing || await writers.createBlogCategory(wix, { label: text(row.name), slug: slug(row.slug), description: nonEmpty(text(row.description)) }); blogCategoryIds.set(String(row.id), created.id); remember('blog_category', row.id, created.id); await checkpointCrosswalk(); }
+  summary.imported.blog_category = blogCategoryIds.size;
+  capabilities.finishQuickEntity(quickRun, 'blog_category'); wix = clientFor('blog_tag');
+  for (const row of await readLines(path.join(sourceDir, 'blog_tag.ndjson'))) { if (seen('blog_tag', row.id)) { blogTagIds.set(String(row.id), seen('blog_tag', row.id)); continue; } const created = await writers.createBlogTag(wix, { label: text(row.name) }); blogTagIds.set(String(row.id), created.id); remember('blog_tag', row.id, created.id); }
+  summary.imported.blog_tag = blogTagIds.size;
+  capabilities.finishQuickEntity(quickRun, 'blog_tag'); wix = clientFor('post');
+  const fallbackMemberId = env.WIX_BLOG_FALLBACK_MEMBER_ID;
+  if (!fallbackMemberId) throw new Error('setup must provision WIX_BLOG_FALLBACK_MEMBER_ID before importing blog posts');
+  let posts = 0;
+  for (const row of await readLines(path.join(sourceDir, 'post.ndjson'))) {
+    if (seen('post', row.id)) { posts += 1; continue; }
+    await appendAudit(projectDir, { phase: 'post', sourceId: String(row.id), state: 'creating_draft' }, dryRun);
+    const draft = await writers.createDraftPost(wix, { title: text(row.title?.rendered), memberId: fallbackMemberId, richContent: await writers.convertHtmlToRichContent(wix, row.content?.rendered || '<p></p>'), excerpt: text(row.excerpt?.rendered), slug: slug(row.slug), categoryIds: (row.categories || []).map((id) => blogCategoryIds.get(String(id))).filter(Boolean), tagIds: (row.tags || []).map((id) => blogTagIds.get(String(id))).filter(Boolean), firstPublishedDate: Number.isNaN(new Date(row.date).valueOf()) ? undefined : new Date(row.date).toISOString() });
+    await appendAudit(projectDir, { phase: 'post', sourceId: String(row.id), state: 'publishing_draft', targetId: draft.id }, dryRun);
+    if (!dryRun) await writers.publishDraftPost(wix, draft.id); remember('post', row.id, draft.id); posts += 1;
+    await checkpointCrosswalk(); await appendAudit(projectDir, { phase: 'post', sourceId: String(row.id), state: 'completed', targetId: draft.id }, dryRun);
+  }
+  summary.imported.post = posts;
+  capabilities.finishQuickEntity(quickRun, 'post'); wix = clientFor('product');
+  let products = 0;
+  // A process can stop after a product create succeeds but before the crosswalk is
+  // checkpointed. Build a complete destination slug index up front so a resumed run
+  // recovers that write instead of treating the source record as a new product.
+  const existingProducts = new Map(
+    (await writers.queryAllStoresProducts(wix)).map((item) => [slug(item.slug), item]),
+  );
+  const productRows = await readLines(path.join(sourceDir, 'product.ndjson'));
+  const productSlugCounts = new Map();
+  for (const row of productRows) {
+    const key = slug(row.slug);
+    productSlugCounts.set(key, (productSlugCounts.get(key) || 0) + 1);
+  }
+  for (const row of productRows) {
+    if (seen('product', row.id)) { products += 1; continue; }
+    const baseSlug = slug(row.slug);
+    const sourceSlug = productSlugCounts.get(baseSlug) > 1 ? `${baseSlug}-${row.id}` : baseSlug;
+    const actualPrice = price(row.prices?.price, row.prices?.currency_minor_unit); const regular = price(row.prices?.regular_price, row.prices?.currency_minor_unit);
+    const normalized = recovery.normalizeProduct({ sourceId: row.id, sku: nonEmpty(row.sku) || '', tagIds: (row.tags || []).map((tag) => productTagIds.get(String(tag.id))).filter(Boolean) });
+    const created = existingProducts.get(sourceSlug) || (productSlugCounts.get(baseSlug) > 1 && existingProducts.get(baseSlug)) || await writers.createStoresProduct(wix, { name: text(row.name), slug: sourceSlug, description: composeProductDescription({ description: row.description, shortDescription: row.short_description }), productType: 'PHYSICAL', visible: true, tags: { publicTags: { tagIds: normalized.tagIds } }, media: { itemsInfo: { items: resolveImageUrls(row.images).map(({ url, altText, displayName }) => ({ url, ...(altText ? { altText } : {}), ...(displayName ? { displayName } : {}) })) } }, variantsInfo: { variants: [{ visible: true, sku: normalized.sku || undefined, inStock: row.is_in_stock !== false, price: { actualPrice: { amount: actualPrice }, ...(Number(regular) > Number(actualPrice) ? { compareAtPrice: { amount: regular } } : {}) } }] } });
+    if (normalized.recoveries.length) { if (!dryRun) await recovery.appendRecoveries(projectDir, planResult.adapter, row.id, normalized.recoveries); recovery.recordRecoveredRecord(summary, normalized.recoveries); }
+    const targets = (row.categories || []).map((category) => categoryIds.get(String(category.id))).filter(Boolean); if (targets.length) await writers.bulkAddItemToCategories(wix, { productId: created.id, categoryIds: targets }); remember('product', row.id, created.id); products += 1;
+  }
+  summary.imported.product = products;
+  capabilities.finishQuickEntity(quickRun, 'product');
+  if (!dryRun) await writeJson(path.join(projectDir, 'state', 'crosswalk', 'quick-mode.json'), crosswalk);
+  Object.assign(summary, await sourceCoverage.quickSummaryCoverage(projectDir));
+  await recovery.writeFinalReport(projectDir, summary, { dryRun });
+  await writeJson(path.join(projectDir, 'execution', dryRun ? 'dry-run-completion-report.json' : 'completion-report.json'), summary);
+  return summary;
+}
+async function main() {
+  const [command, projectDirArg] = process.argv.slice(2);
+  if (!command || !projectDirArg || !['preflight', 'plan', 'setup-author', 'extract', 'import'].includes(command)) throw new Error('Usage: quick-mode.js <preflight|plan|setup-author|extract|import> <projectDir>');
+  const result = await ({ preflight, plan, 'setup-author': ensureFallbackAuthor, extract, import: importData })[command](path.resolve(projectDirArg));
+  process.stdout.write(`${JSON.stringify({ ok: true, command, status: result.status || 'completed' })}\n`);
+}
+main().catch((error) => { process.stderr.write(`${error.message}\n`); process.exit(1); });

package/skills/wix-replatform/resources/rp-setup-discovery/SKILL.md

@@ -9,6 +9,35 @@ description: >-
 
 Determine the Wix-side setup required before import can run safely.
 
+## Declaring user-defined extended fields
+
+When a mapping needs a source-only value on a native Wix record, declare it as a setup
+requirement rather than letting a writer improvise one. The requirement and the step that
+executes it are a fixed pair:
+
+- the requirement is `kind: "extendedFieldSchema"` in `setup/setup-requirements.json`, carrying
+  `schemaKind`, `targetRef`, `fqdn`, `namespace: "_user_fields"`, and its `fields`;
+- the plan step that provisions it is **`provision-extended-fields`** in `setup/setup-plan.json`.
+
+Emit both or neither. A requirement with no matching step provisions nothing, and every writer
+that needs those fields then refuses its write — correct, but the run fails late and for a
+confusing reason. `rp-execute-setup` fails closed on that mismatch rather than proceeding.
+
+Supported targets, and nothing else:
+
+| Target | `schemaKind` | `fqdn` / surface | Types |
+| --- | --- | --- | --- |
+| eCommerce Order | `data-extension-schema` | `wix.ecom.*.order` | `string` (needs `maxLength`) |
+| Product | `data-extension-schema` | `wix.stores.catalog.*.product` (filterable) | `string` |
+| Contact (default) | `data-extension-schema` | `wix.contacts.*.contact`, `contactWriteSurface: "contacts-v5"` | `string` |
+| Contact (legacy, explicit opt-in only) | `crm-contact-extended-field` | `contactWriteSurface: "contacts-v4"`, no `fqdn`/`namespace`; fields carry `displayName` + `dataType` | `TEXT` |
+
+Checkout, Bookings, Booking Services and nested order subrecords (`extensionPoint`) are refused
+before any network call — route such fields to CMS. Use `permissionsPreset: "migration-internal"`
+(Wix users and apps read, Wix users write, no visitor access); visitor exposure is a manual
+dashboard change by the site owner afterwards, never a setup default. Never emit both contact
+surfaces for one field, and never plan a V4 fallback for a V5 contact field.
+
 ## Purpose
 
 This skill analyzes the approved mapping artifacts and derives environment prerequisites
@@ -23,6 +52,23 @@ permissions, and any other target-system configuration dependencies.
 - `migrations/<project>/orchestration/approvals.json`
 - any Wix environment constraints or destination account details provided by the user
 
+For `managementImportMode=quick`, replace the mapping inputs above with
+`migrations/<project>/quick-mode/plan.json`. Its `requiredWixCapabilities` and entity graph are
+the setup authority. Generate the same setup artifacts and standing notification/Catalog-V3
+requirements; do not demand a mapping plan or ask an agent to infer additional quick entities.
+When the plan includes blog posts, add an automatable dedicated fallback Blog author member,
+persist its ID as `WIX_BLOG_FALLBACK_MEMBER_ID`, and disclose the attribution policy in the
+setup summary. This is mandatory setup, never a user decision or import blocker.
+
+Generate the quick-mode setup artifacts deterministically:
+
+```bash
+node skills/wix-replatform/resources/rp-setup-discovery/scripts/quick-setup-plan.js <projectDir>
+```
+
+The adapter declares its entity graph and capabilities; this shared generator owns universal
+destination setup policy and must not infer additional import entities.
+
 ## Workflow
 
 1. Confirm the mapping review checkpoint has been accepted, then read the mapping plan and
@@ -34,8 +80,26 @@ permissions, and any other target-system configuration dependencies.
 3. Determine which Wix apps must be installed or enabled.
 4. Determine which SMC collections must exist.
 5. Determine which extended-fields schemas, references, enums, or validation rules must exist.
-6. Capture dependency ordering where setup steps depend on each other.
+6. Capture dependency ordering where setup steps depend on each other. Every setup step
+   declares its canonical `entityRefs`. Where imports consume a setup-produced value,
+   declare optional `referenceKeys: [{ ref, sourceStableKey, paths: string[] }]` for that
+   step. Each ref must be in its `entityRefs`; keys come from the reviewed source mapping,
+   and paths name the exact dependent payload fields. Never invent a target ID in the plan.
+   Keep every setup-produced dependency `task-complete`, even when its target value is
+   used on individual records.
 7. Write a setup artifact that downstream execution can verify.
+8. Bind `setup/setup-plan.json` to the mapping plan it was derived from (a no-op when the
+   project has no plugin coverage):
+
+   ```bash
+   node skills/wix-replatform/scripts/cms-fallback.js stamp-plan --project-dir <project> --plan setup
+   ```
+
+   It copies `mapping-plan.json` `inputs.cmsFallbackDigest` into `setup-plan.json`
+   `inputs.cmsFallbackDigest`. The router treats a setup plan without it, or with a different
+   one, as stale (`setup_plan_stale_cms_fallback`) and routes back here before any setup or
+   import step. Create CMS collections only for capabilities the mapping plan maps to CMS: a
+   recognized capability whose CMS fallback is pending or declined gets no collection.
 
 ## Artifact to create or update
 
@@ -96,13 +160,15 @@ exist in Wix with the names/types you state — never invent them.
 
 - Verify at the moment you write the requirement; do not defer it. Verify **enum
   values**, not just names: confirm each `Field.type` against the Create Data Collection
-  schema. (Common trap: there is no `SLUG` type — a Wix slug is a `TEXT` field.)
+  schema. (`SLUG` **does** exist in that enum, documented for dynamic page URLs. Use `TEXT` for
+  a preserved source slug held as identity/SEO data and `SLUG` when the target generates the
+  dynamic-page URL from it — never record `SLUG` as a type that does not exist.)
 - If a Wix tool surface such as Wix MCP is available, use it as a fast verification aid.
 - If no Wix tool surface is available, rely on `rp-target-wix`'s verified contracts plus
   published Wix REST/SDK documentation and conservative, known-good names, and mark the
   requirement `unverified` so a human confirms it before `rp-execute-setup` runs.
 
-## Standing requirement: mute site notifications (spec 0012)
+## Standing requirement: mute site notifications
 
 Emit a **`mute-site-notifications`** requirement into `setup/setup-plan.json` and
 `setup/setup-requirements.json` whenever mute is in effect:
@@ -149,13 +215,17 @@ Do not assert "manual" / "cannot self-provision" by assumption — check the API
 - Enabling a Wix app (Blog, Members, etc.) **is** automatable via the App Installation
   API; classify it automatable and cite the method. (Common trap: do not mark Blog or
   Members "cannot self-provision" — both are installable via the API.)
-- When the migration carries a product catalog, emit a **`stores-catalog-v3` requirement**
-  alongside the Wix Stores app install: expected state `catalogVersion: V3_CATALOG`, verified
-  read-only via `GET https://www.wixapis.com/stores/v3/provision/version`, severity
-  **blocker**, automation mode `automatable` (it is provisioned by scaffolding the site from
-  the `commerce` template — see `replatform` → "Headless site creation"). A Stores install
-  alone does not imply V3; a `blank`-scaffolded site comes up `V1_CATALOG` and cannot be
-  converted, so this must be a first-class requirement rather than an assumption.
+- Catalog V3 is guaranteed at provisioning regardless of scaffold template
+  so a Wix Stores install on a site this
+  run created needs no separate catalog-version requirement — do not emit one. This
+  guarantee does not extend to an existing site this run did not create: when
+  `WIX_SITE_STRATEGY=existing` and the migration carries a product catalog, still emit the
+  **`stores-catalog-v3` requirement** alongside the Wix Stores app install — expected state
+  `catalogVersion: V3_CATALOG`, verified read-only via
+  `GET https://www.wixapis.com/stores/v3/provision/version`, severity **blocker**,
+  automation mode `automatable`. A pre-existing site's catalog version predates this
+  guarantee, so it must still be confirmed rather than assumed (see `rp-execute-setup` →
+  "A `V1_CATALOG` verdict is terminal here").
 - Creating CMS collections is automatable; enabling Wix Data itself is automatable by
   installing the **Wix Data app `appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4`** via the
   App Installation API, after which `POST /wix-data/v2/collections` creates NATIVE

package/skills/wix-replatform/resources/rp-setup-discovery/scripts/quick-setup-plan.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+async function readJson(file) { return JSON.parse(await fs.readFile(file, 'utf8')); }
+async function writeJson(file, value) { await fs.mkdir(path.dirname(file), { recursive: true }); await fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8'); }
+function envValue(text, key) { const match = text.match(new RegExp(`^${key}=(.*)$`, 'm')); return match ? match[1].trim() : null; }
+async function siteStrategy(projectDir) { try { return envValue(await fs.readFile(path.join(projectDir, 'config', 'wix.env'), 'utf8'), 'WIX_SITE_STRATEGY'); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } }
+function requirementsFor(plan, strategy) {
+  const capabilities = new Set(plan.requiredWixCapabilities || []);
+  const hasPosts = (plan.entities || []).some((entity) => entity.id === 'post');
+  const result = [];
+  if (strategy === 'new') result.push({ id: 'mute-site-notifications', order: 10, severity: 'blocker', automation: 'automatable', expected: 'site notifications are muted', verification: 'getSiteMuteState returns muted=true' });
+  if (capabilities.has('stores')) result.push({ id: 'wix-stores', order: 20, severity: 'blocker', automation: 'automatable', expected: 'Wix Stores is installed', verification: 'app installation state is enabled' });
+  if (capabilities.has('stores') && strategy === 'existing') result.push({ id: 'stores-catalog-v3', order: 30, severity: 'blocker', automation: 'automatable', expected: 'catalogVersion is V3_CATALOG', verification: 'GET /stores/v3/provision/version' });
+  if (capabilities.has('blog')) result.push({ id: 'wix-blog', order: 40, severity: 'blocker', automation: 'automatable', expected: 'Wix Blog is installed', verification: 'app installation state is enabled' });
+  if (hasPosts) result.push({ id: 'blog-fallback-author', order: 50, severity: 'blocker', automation: 'automatable', expected: 'dedicated fallback Blog member exists and WIX_BLOG_FALLBACK_MEMBER_ID is persisted', verification: 'member lookup and config key status' });
+  return result;
+}
+async function main() {
+  const projectDir = process.argv[2] && path.resolve(process.argv[2]);
+  if (!projectDir) throw new Error('Usage: quick-setup-plan.js <projectDir>');
+  const plan = await readJson(path.join(projectDir, 'quick-mode', 'plan.json'));
+  if (plan.managementImportMode !== 'quick' || !plan.adapter || !Array.isArray(plan.entities)) throw new Error('quick-mode/plan.json is not a valid quick plan');
+  const strategy = await siteStrategy(projectDir);
+  if (!strategy) throw new Error('WIX_SITE_STRATEGY is required before quick setup discovery');
+  const requirements = requirementsFor(plan, strategy);
+  const generatedAt = new Date().toISOString();
+  const common = { schemaVersion: 1, generatedAt, managementImportMode: 'quick', adapter: plan.adapter, sourcePlan: 'quick-mode/plan.json', siteStrategy: strategy, requirements };
+  await writeJson(path.join(projectDir, 'setup', 'setup-plan.json'), { ...common, steps: requirements.map((requirement) => ({ ...requirement, action: requirement.id })) });
+  await writeJson(path.join(projectDir, 'setup', 'setup-requirements.json'), common);
+  // setup-blockers.json is no longer seeded here: execute-setup.js is the sole writer of
+  // real blocker content (empty on full success, populated on a genuine failure), so a
+  // permanent blockers:[] stub written before setup ever runs would otherwise let a stale
+  // "no blockers" file survive a later failure. Its absence before setup runs is itself the
+  // correct "setup hasn't run yet" signal.
+  await writeJson(path.join(projectDir, 'setup', 'llm-handoff.json'), { schemaVersion: 1, generatedAt, needsLlm: false, reason: 'Quick setup requirements are derived from the adapter contract.' });
+  await fs.mkdir(path.join(projectDir, 'setup', 'review'), { recursive: true });
+  await fs.writeFile(path.join(projectDir, 'setup', 'review', 'setup-summary.md'), `# Quick setup summary\n\n${requirements.map((item) => `- ${item.id}: ${item.expected}`).join('\n')}\n`, 'utf8');
+  console.log(JSON.stringify({ ok: true, requirements: requirements.map((item) => item.id) }));
+}
+main().catch((error) => { console.error(error.message); process.exit(1); });

package/skills/wix-replatform/resources/rp-source-csv/SKILL.md

@@ -100,6 +100,9 @@ There is **no acquisition-mode fork and no credentials request** for a CSV run.
      drift, mapping hints, entities and relations. **This is what `rp-discovery` synthesizes
      `source-schema.json` from.**
    - `raw-capture.json` — per-column detail plus head/tail samples.
+   - `source-coverage.json` — always written (`rows: []` when clean): one row per file with an
+     unknown role and per stream whose layout halted, so the decision a halt asks for cannot
+     disappear. `rp-discovery` promotes it.
    - `<role>--<entity>.md` — one per entity.
 
 4. **Honor the halt.** When the capture reports `halt: true` (ambiguous layout, unknown file

package/skills/wix-replatform/resources/rp-source-csv/scripts/csv-discovery.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { createProgressLogger, parseProgressArgs } = require('../../../lib/progress-log.js');
+const { buildCsvCoverageRows, buildCoverageFile, ADAPTER_RAW_DIRS } = require('../../../lib/source-coverage.js');
 
 // Parse, dialect detection, and type sniffing live in the shared adapter lib so
 // the bulk-extract reader generated by rp-import-codegen inherits exactly the
@@ -844,6 +845,22 @@ async function capture(args) {
   };
 }
 
+// A file with an unknown role and a stream whose layout halted to a decision are
+// both inputs this capture could not turn into entities. Always written, `rows: []` when clean.
+function sourceCoveragePayload(result) {
+  return buildCoverageFile({
+    platform: 'csv',
+    adapter: 'csv',
+    generatedAt: result.generatedAt,
+    rows: buildCsvCoverageRows({
+      sourceFiles: result.sourceFiles,
+      streams: result.streams,
+      csvInputRoot: result.csvInputRoot,
+      rawDir: ADAPTER_RAW_DIRS.csv,
+    }),
+  });
+}
+
 function commonDirectory(files) {
   if (files.length === 0) {
     return process.cwd();
@@ -868,6 +885,7 @@ async function writeOutputs(outDir, result) {
 
   await fs.writeFile(path.join(outDir, 'fileset.json'), `${JSON.stringify(filesetPayload(result), null, 2)}\n`, 'utf8');
   await fs.writeFile(path.join(outDir, 'raw-capture.json'), `${JSON.stringify(rawCapturePayload(result), null, 2)}\n`, 'utf8');
+  await fs.writeFile(path.join(outDir, 'source-coverage.json'), `${JSON.stringify(sourceCoveragePayload(result), null, 2)}\n`, 'utf8');
   progress?.progress('Wrote CSV discovery machine capture', { phase: 'discovery', step: 'write-artifact', artifact: path.join(outDir, 'fileset.json') });
 
   let entityCount = 0;
@@ -890,7 +908,7 @@ async function writeOutputs(outDir, result) {
 async function main() {
   const parsed = parseProgressArgs(process.argv.slice(2));
   progress = createProgressLogger({
-    script: 'skills/replatform/resources/rp-source-csv/scripts/csv-discovery.js',
+    script: 'skills/wix-replatform/resources/rp-source-csv/scripts/csv-discovery.js',
     ...parsed.progress,
   });
   progress.start('CSV discovery started', { phase: 'discovery' });
@@ -945,5 +963,7 @@ module.exports = {
   renderEntityFile,
   filesetPayload,
   rawCapturePayload,
+  sourceCoveragePayload,
   capture,
+  writeOutputs,
 };