@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/resources/rp-quick-runtime/lib/import-progress.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// Shared by both rp-quick-<platform> adapters (producers) and by
+// lib/orchestration-router.js (consumer), so the quick manifest rule and the start-marker
+// path live in one place.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const QUICK_IMPORT_STARTED_MARKER = 'state/quick-import-started.json';
+const MARKER_SCHEMA_VERSION = 1;
+
+// The quick manifest written by `quick-mode.js plan`. It is deliberately not the full-mode
+// `validateManifest` shape (no projectId/planVersion/tasks).
+function validateQuickExecutionManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { ok: false, errors: ['quick execution manifest must be an object'] };
+  }
+  if (manifest.schemaVersion !== undefined && manifest.schemaVersion !== 1) errors.push('schemaVersion must be absent or 1');
+  if (manifest.managementImportMode !== 'quick') errors.push("managementImportMode must be 'quick'");
+  if (typeof manifest.importCommand !== 'string' || !manifest.importCommand.trim()) errors.push('importCommand must be a non-empty string');
+  if (!Array.isArray(manifest.entities)) errors.push('entities must be an array');
+  return { ok: errors.length === 0, errors };
+}
+
+// Before the marker or any destination write, the loaded plan's adapter must be
+// exactly the adapter's current contract `{ id, version, fingerprint }`, and the extract
+// manifest must carry that same adapter. This is what makes the marker's copied `adapter` the
+// current adapter-contract identity rather than whatever a stale or edited plan says.
+const ADAPTER_KEYS = ['id', 'version', 'fingerprint'];
+function sameAdapter(left, right) {
+  return Boolean(left && typeof left === 'object' && right && typeof right === 'object')
+    && ADAPTER_KEYS.every((key) => typeof left[key] === 'string' && left[key] !== '' && left[key] === right[key]);
+}
+function assertQuickImportAdapter({ plan, manifest, current }) {
+  if (!sameAdapter(current, current)) throw new Error('quick adapter contract is missing id, version, or fingerprint');
+  if (!sameAdapter(plan && plan.adapter, current)) throw new Error('quick adapter contract changed; re-run preflight and plan');
+  if (!sameAdapter(manifest && manifest.adapter, current)) throw new Error('extraction does not match quick plan; re-extract');
+}
+
+// Durable pre-write evidence that a live quick import began. Written once, before the first
+// destination create/update, never on a dry run, and never rewritten on resume: an existing
+// marker keeps describing the first live attempt. `adapter` is the plan's own
+// `{ id, version, fingerprint }`, already checked by `assertQuickImportAdapter` to equal the
+// loaded adapter contract, copied verbatim.
+//
+// Publication is atomic and no-replace: the complete JSON is written and fsynced to a
+// uniquely named temp file, then hard-linked to the marker path. `link` fails with EEXIST
+// when a marker already exists, so concurrent first attempts cannot replace each other and
+// a reader never sees a partial marker. The loser is an unchanged resume.
+async function writeQuickImportStartedMarker(projectDir, adapter) {
+  const markerPath = path.join(projectDir, QUICK_IMPORT_STARTED_MARKER);
+  const unchanged = { written: false, path: QUICK_IMPORT_STARTED_MARKER };
+  try {
+    await fs.access(markerPath);
+    return unchanged;
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+  const { id, version, fingerprint } = adapter || {};
+  const marker = { schemaVersion: MARKER_SCHEMA_VERSION, adapter: { id, version, fingerprint }, startedAt: new Date().toISOString() };
+  await fs.mkdir(path.dirname(markerPath), { recursive: true });
+  const tempPath = `${markerPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  const handle = await fs.open(tempPath, 'wx');
+  try {
+    await handle.writeFile(`${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await fs.link(tempPath, markerPath);
+    return { written: true, path: QUICK_IMPORT_STARTED_MARKER };
+  } catch (error) {
+    if (error && error.code === 'EEXIST') return unchanged;
+    throw error;
+  } finally {
+    await fs.rm(tempPath, { force: true });
+  }
+}
+
+module.exports = {
+  QUICK_IMPORT_STARTED_MARKER,
+  assertQuickImportAdapter,
+  validateQuickExecutionManifest,
+  writeQuickImportStartedMarker,
+};

package/skills/wix-replatform/resources/rp-quick-runtime/lib/limit-recovery.js

@@ -0,0 +1,36 @@
+'use strict';
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const STORES_PRODUCT_TAGS_MAX = 100;
+const STORES_CATEGORIES_MAX = 1000;
+const STORES_SKU_MAX = 40;
+function truncate(value, limit, sourceId) { const chars = Array.from(String(value || '')); if (chars.length <= limit) return String(value || ''); const suffix = `-${crypto.createHash('sha256').update(String(sourceId)).digest('hex').slice(0, 7)}`; return `${chars.slice(0, Math.max(0, limit - suffix.length)).join('')}${suffix}`; }
+function normalizeProduct({ sourceId, sku, tagIds = [] }) { const recoveries = []; const uniqueTags = [...new Set(tagIds)].slice(0, STORES_PRODUCT_TAGS_MAX); if (tagIds.length > uniqueTags.length) recoveries.push({ code: 'stores_product_tag_count', field: 'tags.publicTags.tagIds', action: 'capped', originalCount: tagIds.length, finalCount: uniqueTags.length }); const nextSku = truncate(sku, STORES_SKU_MAX, sourceId); if (nextSku !== sku) recoveries.push({ code: 'stores_variant_sku_length', field: 'variants.sku', action: 'trimmed_with_source_suffix', originalLength: Array.from(String(sku)).length, finalLength: Array.from(nextSku).length }); return { sku: nextSku, tagIds: uniqueTags, recoveries }; }
+async function appendRecoveries(projectDir, adapter, sourceId, recoveries) { if (!recoveries.length) return; const file = path.join(projectDir, 'execution', 'quick-limit-recoveries.ndjson'); await fs.mkdir(path.dirname(file), { recursive: true }); await fs.appendFile(file, recoveries.map((r) => JSON.stringify({ adapter, sourceId: String(sourceId), outcome: 'written_with_loss', ...r })).join('\n') + '\n'); }
+function recordRecoveredRecord(summary, recoveries) { if (!recoveries.length) return; summary.recovered = (summary.recovered || 0) + 1; summary.recoveryCounts ||= {}; for (const item of recoveries) summary.recoveryCounts[item.code] = (summary.recoveryCounts[item.code] || 0) + 1; }
+const LIVE_FINAL_REPORT = 'execution/quick-mode-final-report.md';
+const DRY_RUN_FINAL_REPORT = 'execution/dry-run-final-report.md';
+// Temp file + rename so a reader (or a crash) never sees a half-written report.
+async function writeFileAtomic(file, content) { await fs.mkdir(path.dirname(file), { recursive: true }); const temp = `${file}.${process.pid}.tmp`; await fs.writeFile(temp, content); await fs.rename(temp, file); }
+function renderFinalReport(summary) {
+  const rows = Object.entries(summary.recoveryCounts || {}).map(([code, count]) => `- ${code}: ${count}`).join('\n') || '- None';
+  let out = `# Quick-mode final report\n\nImported with deterministic recovery: ${summary.recovered || 0}\n\n## Target-limit recoveries\n\n${rows}\n`;
+  const collections = summary.excludedCollections || [];
+  if (collections.length) out += `\n## Collections not migrated\n\nThese source collections held no imported product, so no category was created. Recreate any the merchant still needs.\n\n${collections.map((c) => `- ${c.title || c.handle} (${c.handle}, source id ${c.sourceId})`).join('\n')}\n`;
+  const unverified = (summary.writtenUnverified && summary.writtenUnverified.product) || [];
+  if (unverified.length) out += `\n## Products to check\n\nThese products are on Wix with stock and categories, but a field differs from the source. Compare each with the source, then fix or accept it.\n\n${unverified.map((p) => `- ${p.name || p.sourceId} (source id ${p.sourceId}, Wix id ${p.targetId}): ${(p.failedFields || []).join(', ') || 'unspecified field'}`).join('\n')}\n`;
+  if (summary.inventory) out += `\n## Inventory\n\nStatus: ${summary.inventory.status}. Verified complete: ${summary.inventory.complete}. See ${summary.dryRun ? 'execution/dry-run-inventory-report.json' : 'state/inventory-report.json'}.\n`;
+  return out;
+}
+// A dry run owns its own report path so it can never overwrite, or stand in for, the live one.
+async function writeFinalReport(projectDir, summary, { dryRun = false } = {}) {
+  const relative = dryRun ? DRY_RUN_FINAL_REPORT : LIVE_FINAL_REPORT;
+  await writeFileAtomic(path.join(projectDir, relative), renderFinalReport(summary));
+  summary.finalReport = relative;
+}
+// Categories this run still has to create: not already crosswalked and not already on Wix by slug.
+function countCategoriesToCreate({ rows, seen, existingSlugs, slugOf }) {
+  return rows.filter((row) => { if (seen(row.id)) return false; try { return !existingSlugs.has(slugOf(row.handle)); } catch { return false; } }).length;
+}
+module.exports = { STORES_PRODUCT_TAGS_MAX, STORES_CATEGORIES_MAX, STORES_SKU_MAX, LIVE_FINAL_REPORT, DRY_RUN_FINAL_REPORT, truncate, normalizeProduct, appendRecoveries, recordRecoveredRecord, renderFinalReport, writeFinalReport, writeFileAtomic, countCategoriesToCreate };

package/skills/wix-replatform/resources/rp-quick-shopify/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: rp-quick-shopify
+description: Runs the bounded deterministic public Shopify catalog quick-import adapter after a qualifying source probe.
+---
+
+# rp-quick-shopify
+
+Use only when the router selected this resource for `managementImportMode=quick` and the
+source probe identified `shopify` with high confidence. This adapter imports only the catalog
+entity graph declared in `quick-mode.json`: public products, collections, product tags, product
+media, variants, and collection membership. It reads them through the store's **tokenless
+Storefront GraphQL API** (`POST /api/<storefrontApiVersion>/graphql.json`, no access token) at the
+API version pinned in `quick-mode.json`. One paginated product query carries each product's
+variants, images, and collection memberships, so a store with thousands of collections still
+needs only a handful of requests. It never uses credentials, a Storefront or Admin access token,
+browser extraction, page scraping, app endpoints, or an LLM mapping step.
+
+Run the adapter from the repository root:
+
+```bash
+node skills/wix-replatform/resources/rp-quick-shopify/scripts/quick-mode.js preflight <projectDir>
+node skills/wix-replatform/resources/rp-quick-shopify/scripts/quick-mode.js plan <projectDir>
+node skills/wix-replatform/resources/rp-quick-shopify/scripts/quick-mode.js extract <projectDir>
+node skills/wix-replatform/resources/rp-quick-shopify/scripts/quick-mode.js import <projectDir> [--dry-run]
+node skills/wix-replatform/resources/rp-quick-shopify/scripts/quick-mode.js request-reverify <projectDir>
+node skills/wix-replatform/resources/rp-quick-shopify/scripts/quick-mode.js reverify <projectDir>
+```
+
+`plan` also writes `discovery/source-coverage.json`: one `adapter-excluded` row per `excluded[]`
+entry, each dispositioned as the adapter's declared exclusion and carrying the committed
+`excludedCapabilities` translation from `quick-mode.json` (a target capability, or
+`source-scope.<name>` when Wix has none). The plan refuses if that translation is missing, extra,
+duplicated or outside both namespaces, and stamps `sourceCoverageContract: 1` in
+`quick-mode/plan.json`. `import` refuses to write its completion summary when the plan is
+missing or unstamped, or its coverage file is missing or does not reconcile (a declared
+exclusion must name an `excluded[]` entry of the committed contract, with its committed
+capability); re-run `plan` to fix any of these. The summary carries `sourceCoverage[]` and
+`sourceCoverageStatus`.
+
+`preflight` pages through the product and collection connections (completing any product whose
+variants, images, or collections exceed the first nested page) and stores the capture that
+`extract` reuses, before `plan` writes the authoritative quick plan and execution manifest. HTTP
+429, 5xx, `THROTTLED`, dropped connections, and hung calls are retried: one first call plus at
+most six retries per request, each call time-limited, and every wait (including a server-requested
+`Retry-After`, as seconds or an HTTP date) capped at 30 seconds. Any other error is a real answer
+and blocks at once. When retries run out, `quick-mode/preflight.json` records a blocked check
+with the connection, page, status, error codes and `attempts`. Normal setup discovery/execution and execution approval remain mandatory before
+import. An inaccessible (e.g. password-protected), malformed, or changed endpoint is a durable
+blocker: do not substitute a browser, credentials, or a different endpoint; create a durable
+choice between stopping and standard mode instead. The standard-mode choice must carry this
+effect so the CLI applies the user's selection before it resumes:
+
+```json
+{"kind":"decision","key":"managementImportMode","choices":{"switch_to_standard":"standard"}}
+```
+
+Records are normalized to the storefront-JSON row shape the import consumes (numeric legacy ids,
+`body_html`, `variants[].option1..3`, `variants[].available`, `images[].src`), so crosswalks keyed
+by Shopify id stay valid across adapter versions. A dry run writes only
+`execution/dry-run-completion-report.json`, `execution/dry-run-final-report.md`,
+`execution/dry-run-inventory-report.json` and `execution/dry-run-category-capacity.json`; it
+never creates or changes a live artifact (the live completion, final and inventory reports, the
+crosswalk, the limit-recovery log, the capacity file, the import-started marker or a re-check
+file), so the router still sends the project to the live import afterwards.
+
+Extraction persists the raw records and membership edges. Only collections that contain at
+least one extracted product become categories (`manifest.entities.collection.excludedEmptyCount`
+counts the rest): Wix Stores allows at most 1,000 categories per site, including the built-in
+All Products category. Import checks that limit against the destination's current categories
+before its first write and refuses, naming both counts, rather than creating categories up to
+the cap and stranding the remaining memberships. The check counts only categories still to be
+created (ones already crosswalked or already on the destination by slug are reused) plus the
+built-in All Products category, and records `quick-mode/category-capacity.json`. When it is
+`blocked`, nothing was written and the router returns `quick_mode_category_capacity_blocked`:
+create a durable choice between `free_destination_categories_and_retry` (the operator frees
+categories on the destination, then the import is re-run and rewrites the file as `passed`) and
+`stop`. A dry run cannot see the destination, so it applies the same rule with the built-in
+category as the floor and reports the real headroom as unknown. Collections left out for having
+no imported product are listed by name in the completion report (`excludedCollections`) and the
+final report, so the operator can recreate any the merchant still needs. Import uses the shared Stores V3
+runtime, durable crosswalks, and checkpoints. The shared writer validates the product option and
+variant payload; a record that cannot be represented safely is skipped and reported rather than
+collapsed to a different product shape.
+
+Quick mode maps each public Shopify variant's explicit `available` boolean to untracked
+`inStock`; a missing or non-boolean value is a reported gap, never implicit availability.
+Products created with the standalone endpoint are followed by shared inventory reconciliation.
+Match returned variants by their option/choice identities, not response order or SKU. On
+resume, keep the product crosswalk and reconcile stock for existing products too.
+
+A product that exists on the destination with uniquely correlated variants but fails a field
+read-back (for example a description fragment Wix dropped) is still reported as skipped and
+listed in the summary's `writtenUnverified.product` (`sourceId`, `targetId`, `name`,
+`failedFields`), but its stock is reconciled and its category memberships are written: both
+depend only on product and variant identity, and a for-sale item must not be left with the wrong
+stock because of an unrelated field. The run stays `partial` and the final report lists each such
+product under "Products to check". A product whose variants do not correlate one-to-one gets no
+stock and no category link, and is reported as a gap.
+
+After the operator fixes or accepts those differences, `request-reverify` records a request
+(`quick-mode/reverify-request.json`; refused when the live completion report lists none) and the
+router returns `quick_mode_reverification_required` for a finished partial import. `reverify`
+(refuses `--dry-run`) re-reads each listed product once with the import's read-back comparison and
+only ever reads from Wix. It first stages its complete result in
+`quick-mode/reverification-staged.json`, then publishes it by replay — completion report, final
+report, then the receipt `quick-mode/reverification.json` — so a crash at any step is finished by
+the next routing step without re-reading Wix. Once the receipt matches the request the same
+request never routes again; a later fix needs a new request.
+
+The post-create read retries a transient 404 briefly (the product can be unreadable for a moment
+after its create); a failed create is never retried inline, because resume reuses it by slug.
+
+`state/inventory-report.json` accounts for all extracted variants (including gaps) and
+requires default-location Inventory and Catalog read-back before completion. An inventory
+failure leaves the quick completion report partial even when all product IDs exist.
+An empty inventory census is `no-data` with `complete:false`; an extraction count that
+differs from its manifest blocks before writes. Dry runs write a separate simulated
+inventory report and cannot complete or overwrite a live inventory checkpoint.
+
+Setup scope: the quick setup router verifies the normal setup receipt (including required
+notification protection and Stores provisioning). Its deterministic setup plan does not
+run an inventory write canary. Do not report inventory create/update grants as preverified
+from that receipt; a denied inventory write remains partial in the persisted stock report.

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

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "id": "quick-shopify",
+  "version": "2.0.0",
+  "platform": "shopify",
+  "minimumProbeConfidence": "high",
+  "requiredProbeStrategies": [
+    "shopify.products"
+  ],
+  "publicAuth": "none",
+  "sourceApi": "storefront-graphql-tokenless",
+  "storefrontApiVersion": "2026-10",
+  "entities": [
+    {
+      "id": "collection",
+      "route": "POST /api/{storefrontApiVersion}/graphql.json collections(first:250, after)",
+      "target": "stores/category",
+      "dependsOn": []
+    },
+    {
+      "id": "product",
+      "route": "POST /api/{storefrontApiVersion}/graphql.json products(first:250, after) { variants images collections }",
+      "target": "stores/product",
+      "dependsOn": [],
+      "auxiliaryTargets": [
+        "stores/product-tag",
+        "stores/inventory-item"
+      ]
+    },
+    {
+      "id": "collection_product",
+      "route": "products(...).collections in the product query; no per-collection requests",
+      "target": "stores/category-membership",
+      "dependsOn": [
+        "collection",
+        "product"
+      ]
+    }
+  ],
+  "requiredWixCapabilities": [
+    "stores"
+  ],
+  "fieldMatrix": {
+    "product": [
+      "id",
+      "handle",
+      "title",
+      "body_html",
+      "vendor",
+      "product_type",
+      "tags",
+      "published_at",
+      "images",
+      "options",
+      "variants.id",
+      "variants.title",
+      "variants.sku",
+      "variants.price",
+      "variants.compare_at_price",
+      "variants.available",
+      "variants.option1",
+      "variants.option2",
+      "variants.option3"
+    ],
+    "collection": [
+      "id",
+      "handle",
+      "title",
+      "body_html"
+    ]
+  },
+  "excluded": [
+    "customers",
+    "members",
+    "orders",
+    "abandoned-checkouts",
+    "discounts",
+    "gift-cards",
+    "subscriptions",
+    "inventory-locations-and-quantities",
+    "shipping",
+    "taxes",
+    "payments",
+    "markets",
+    "metafields",
+    "metaobjects",
+    "files",
+    "themes",
+    "navigation",
+    "pages",
+    "blogs",
+    "reviews",
+    "search-configuration",
+    "apps",
+    "private-content",
+    "collection-ordering"
+  ],
+  "excludedCapabilities": {
+    "customers": "crm.contact",
+    "members": "identity.member",
+    "orders": "commerce.orders",
+    "abandoned-checkouts": "source-scope.abandoned-checkouts",
+    "discounts": "commerce.coupons",
+    "gift-cards": "commerce.gift-cards",
+    "subscriptions": "commerce.subscription-contracts",
+    "inventory-locations-and-quantities": "commerce.inventory",
+    "shipping": "commerce.shipping-rate",
+    "taxes": "commerce.tax-settings",
+    "payments": "commerce.order-payments",
+    "markets": "source-scope.markets",
+    "metafields": "source-scope.metafields",
+    "metaobjects": "source-scope.metaobjects",
+    "files": "media.file",
+    "themes": "source-scope.themes",
+    "navigation": "source-scope.navigation",
+    "pages": "source-scope.pages",
+    "blogs": "content.blog-post",
+    "reviews": "commerce.product-reviews",
+    "search-configuration": "source-scope.search-configuration",
+    "apps": "source-scope.apps",
+    "private-content": "source-scope.private-content",
+    "collection-ordering": "source-scope.collection-ordering"
+  }
+}