@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -0,0 +1,693 @@
+#!/usr/bin/env node
+'use strict';
+
+// Shopify private-data discovery, read through the Shopify CLI.
+//
+//   node scripts/shopify-discovery.js --project <migrations-root>/<project> --store <shop>.myshopify.com
+//        [--reread <entity> ...] [--restart] [--progress-log <path>]
+//
+// Runs the discovery steps in a fixed order. Each step records its result in
+// data/shopify-discovery/discovery-steps.json before the next starts, so a restart -- or a return
+// after a merchant question -- runs only the steps not yet recorded and reads nothing it already
+// captured. The last step writes data/shopify-discovery/source-coverage.json (rows: [] when
+// clean). All recorded state is bound to the one store it was read from: a run for a different
+// store stops with shopify_discovery_store_mismatch instead of mixing files, and --restart is the
+// explicit way to discard the capture and begin again. source-profile.md and source-schema.json are synthesized from the capture afterwards and
+// promoted with rp-discovery's promote-source-coverage.js --adapter shopify.
+//
+// Exit codes: 0 complete; 3 waiting on a merchant question (the run holds at
+// awaiting_user_action); 2 stopped (the printed code says why; recorded steps are kept);
+// 1 usage or unexpected error.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { createProgressLogger, parseProgressArgs } = require('../../../lib/progress-log.js');
+const { buildShopifyCoverageRows, buildCoverageFile, ADAPTER_RAW_DIRS, SOURCE_COVERAGE_FILE, writeJsonAtomic } = require('../../../lib/source-coverage.js');
+const { createUserAction, readUserAction } = require('../../../lib/user-actions.js');
+const bulk = require('../lib/shopify-bulk.js');
+const giftCards = require('../lib/shopify-gift-cards.js');
+const { createStoreExecutor, ShopifyCliError } = require('../lib/shopify-cli.js');
+const { ALL_READS, ORDER_WINDOW_READS, SAMPLE_LIMIT, operationName, at } = require('../lib/discovery-reads.js');
+const { ShopifySessionStop, assertConnectionReady, recordAuthExpired, runSessionCheck } = require('../lib/shopify-session.js');
+const protectedFields = require('../lib/shopify-protected-fields.js');
+
+const RAW_DIR = ADAPTER_RAW_DIRS.shopify;
+const STEPS_FILE = 'discovery-steps.json';
+const ENTITIES_DIR = 'entities';
+const STEPS_SCHEMA_VERSION = 1;
+// What discovery hands to the mapper once it has been synthesized and promoted. They live outside
+// the raw directory, so a restart cannot clear them: it refuses to switch stores once they exist.
+const HANDOFF_FILES = Object.freeze(['source-profile.md', 'source-schema.json', SOURCE_COVERAGE_FILE]);
+const STORE_PATTERN = /^[a-z0-9][a-z0-9-]*\.myshopify\.com$/;
+// Connection records, not capture: a restart keeps them. The staff-account record
+// outlives any capture -- the account exists until the owner removes it.
+const CONNECTION_FILES = Object.freeze(['session-receipt.json', 'staff-access.json']);
+const ORDER_WINDOW_FILE = 'order-window.json';
+const ORDER_WINDOW_DAYS = 60;
+
+class ShopifyDiscoveryStop extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'ShopifyDiscoveryStop';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Store identity -- every recorded artifact belongs to exactly one store
+// ---------------------------------------------------------------------------------------------
+
+function normalizeStore(store) {
+  const value = typeof store === 'string' ? store.trim().toLowerCase() : '';
+  if (!STORE_PATTERN.test(value)) {
+    throw new ShopifyDiscoveryStop('shopify_store_invalid', 'store must be the *.myshopify.com domain the Shopify CLI session is bound to');
+  }
+  return value;
+}
+
+function storeMismatch(recorded, store, what) {
+  return new ShopifyDiscoveryStop(
+    'shopify_discovery_store_mismatch',
+    `Shopify discovery data in this project (${what}) was read from ${recorded || 'an unrecorded store'}, not ${store}. Nothing was read or changed. Run discovery for ${recorded || 'the original store'}, or restart discovery with --restart to discard the recorded capture and read ${store} from scratch.`,
+    { recorded: recorded || null, store },
+  );
+}
+
+// ---------------------------------------------------------------------------------------------
+// Step state
+// ---------------------------------------------------------------------------------------------
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+async function readSteps(rawDir, now, store) {
+  const state = await readJson(path.join(rawDir, STEPS_FILE));
+  if (state && state.schemaVersion === STEPS_SCHEMA_VERSION && state.steps && typeof state.steps === 'object') return state;
+  return { schemaVersion: STEPS_SCHEMA_VERSION, platform: 'shopify', store, startedAt: now(), steps: {} };
+}
+
+// Refuse to continue on anything recorded for another store (or for none): the steps file, and
+// every entity file already on disk, which is what a resume would otherwise accept.
+async function assertBoundToStore(rawDir, store) {
+  const steps = await readJson(path.join(rawDir, STEPS_FILE));
+  if (steps && steps.store !== store) throw storeMismatch(steps.store, store, STEPS_FILE);
+  let names = [];
+  try {
+    names = await fs.readdir(path.join(rawDir, ENTITIES_DIR));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  for (const name of names.filter((entry) => entry.endsWith('.json'))) {
+    const record = await readJson(path.join(rawDir, ENTITIES_DIR, name));
+    if (record && record.store !== store) throw storeMismatch(record.store, store, `${ENTITIES_DIR}/${name}`);
+  }
+}
+
+// The store the recorded capture belongs to: the steps file's, else any entity file's, else none.
+async function recordedStore(rawDir) {
+  const steps = await readJson(path.join(rawDir, STEPS_FILE));
+  if (steps && typeof steps.store === 'string') return steps.store;
+  let names = [];
+  try {
+    names = await fs.readdir(path.join(rawDir, ENTITIES_DIR));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  for (const name of names.filter((entry) => entry.endsWith('.json'))) {
+    const record = await readJson(path.join(rawDir, ENTITIES_DIR, name));
+    if (record && typeof record.store === 'string') return record.store;
+  }
+  return null;
+}
+
+async function existingHandoffFiles(projectDir) {
+  const found = [];
+  for (const rel of HANDOFF_FILES) {
+    try {
+      await fs.access(path.join(projectDir, rel));
+      found.push(rel);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return found;
+}
+
+// --restart: discard the whole Shopify raw directory so the next run reads from scratch and no
+// file from the previous capture -- including files the technical steps add -- can survive by
+// omission from a list. The mapper's handoff (source-profile.md, source-schema.json and the
+// promoted coverage file) is outside that directory, so a restart that would leave the previous
+// store's handoff in place for a different store is refused: that project belongs to the first
+// store, and the other one needs its own migration project. A restart for the same store is
+// allowed. Questions the previous run asked are tied to it; while one is still pending the run is
+// holding at awaiting_user_action, so the restart also waits until it is answered.
+async function restartDiscovery(projectDir, rawDir, store) {
+  const handoff = await existingHandoffFiles(projectDir);
+  const previousStore = await recordedStore(rawDir);
+  if (handoff.length && previousStore !== store) {
+    throw new ShopifyDiscoveryStop(
+      'shopify_restart_blocked_handoff',
+      `this project already hands ${previousStore || 'an unrecorded store'}'s discovery to mapping (${handoff.join(', ')}), so ${store} cannot be read into it. Nothing was read or changed. Start a new migration project for ${store}.`,
+      { recorded: previousStore, store, handoff },
+    );
+  }
+  const previous = await readJson(path.join(rawDir, STEPS_FILE));
+  if (previous && previous.steps && previous.startedAt) {
+    for (const entry of Object.values(previous.steps)) {
+      for (const question of (entry.record && entry.record.questions) || []) {
+        try {
+          const action = await readUserAction(projectDir, questionRequestId(previous.startedAt, question.key));
+          if (action.status !== 'answered') {
+            throw new ShopifyDiscoveryStop('shopify_restart_blocked', `a merchant question from the previous discovery is still pending (${action.requestId}); answer it first, then restart`, { requestId: action.requestId });
+          }
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+      }
+    }
+  }
+  let names = [];
+  try {
+    names = await fs.readdir(rawDir);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  for (const name of names) {
+    if (CONNECTION_FILES.includes(name) || name.startsWith('staff-access.json.unreadable-')) continue;
+    await fs.rm(path.join(rawDir, name), { recursive: true, force: true });
+  }
+}
+
+async function writeSteps(rawDir, state) {
+  await writeJsonAtomic(path.join(rawDir, STEPS_FILE), state);
+}
+
+function entityFile(entity) {
+  return path.join(ENTITIES_DIR, `${entity}.json`);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Step 1 -- capture: one count (where one exists) and up to SAMPLE_LIMIT samples per entity
+// ---------------------------------------------------------------------------------------------
+
+function errorEntries(read, errors) {
+  return (errors || []).map((error) => ({
+    read,
+    code: (error && error.extensions && error.extensions.code) || 'GRAPHQL_ERROR',
+    message: String((error && error.message) || 'GraphQL error').slice(0, 500),
+  }));
+}
+
+// A read Shopify throttled on all its calls is a failed read of that entity: a
+// capture-failed row, never an empty entity. Every other CLI failure stops the step.
+async function readOrThrottled(execute, query, variables = null) {
+  try {
+    return await execute(query, variables);
+  } catch (error) {
+    if (error instanceof ShopifyCliError && error.code === 'shopify_throttled') {
+      return { data: null, errors: [{ message: 'Shopify throttled this read on every call (31 s of backoff)', extensions: { code: 'shopify_throttled' } }] };
+    }
+    throw error;
+  }
+}
+
+async function captureEntity(read, { execute: rawExecute, sampleLimit, store }) {
+  const execute = (query, variables) => readOrThrottled(rawExecute, query, variables);
+  const record = { entity: read.entity, store, scopes: read.scopes, reads: [], count: null, countPrecision: null, countExact: false, samples: [], sampleCount: 0, errors: [] };
+  if (read.count) {
+    const name = operationName(read.count);
+    record.reads.push(name);
+    const result = await execute(read.count);
+    if (result.errors && result.errors.length) {
+      record.errors.push(...errorEntries(name, result.errors));
+    } else {
+      const counted = at(result.data, read.countPath);
+      record.count = counted && Number.isInteger(counted.count) ? counted.count : null;
+      record.countPrecision = counted && typeof counted.precision === 'string' ? counted.precision : null;
+      // Only an EXACT answer is a record count. Anything else (AT_LEAST, a missing precision) is a
+      // lower bound at best: `count` keeps it, `countExact` says it is not the store's total.
+      record.countExact = record.count !== null && record.countPrecision === 'EXACT';
+      if (record.count === null) record.errors.push({ read: name, code: 'COUNT_MISSING', message: 'the count read returned no count' });
+    }
+  }
+  const name = operationName(read.sample);
+  record.reads.push(name);
+  const result = await execute(read.sample, /\$first\b/.test(read.sample) ? { first: sampleLimit } : null);
+  if (result.errors && result.errors.length) {
+    record.errors.push(...errorEntries(name, result.errors));
+  } else {
+    const value = at(result.data, read.samplePath);
+    if (value === undefined || value === null) {
+      record.errors.push({ read: name, code: 'SAMPLE_MISSING', message: 'the sample read returned nothing at its path' });
+    } else if (Array.isArray(value.nodes)) {
+      record.samples = value.nodes.slice(0, sampleLimit);
+    } else if (Array.isArray(value)) {
+      record.samples = value.slice(0, sampleLimit);
+    } else {
+      record.samples = [value];
+    }
+    record.sampleCount = record.samples.length;
+  }
+  return record;
+}
+
+async function captureStep(ctx) {
+  const failed = [];
+  const entities = [];
+  for (const read of ctx.reads) {
+    const rel = entityFile(read.entity);
+    const file = path.join(ctx.rawDir, rel);
+    let record = await readJson(file);
+    if (record && record.entity === read.entity && record.store !== ctx.store) {
+      throw storeMismatch(record.store, ctx.store, rel);
+    }
+    if (!record || record.entity !== read.entity) {
+      ctx.progress('Reading Shopify entity', { entity: read.entity });
+      record = { ...(await captureEntity(read, ctx)), capturedAt: ctx.now() };
+      await writeJsonAtomic(file, record);
+    }
+    entities.push({ entity: read.entity, count: record.count, countExact: record.countExact === true, sampleCount: record.sampleCount, file: rel });
+    if (record.errors.length) {
+      failed.push({ entity: read.entity, artifact: `${RAW_DIR}/${rel}`, reads: record.reads, errors: record.errors });
+    }
+  }
+  return { entities, failed };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Steps owned by the technical specs. Until a bundle ships a step's implementation, discovery
+// stops at it: a run that skipped it would look complete while missing what it checks.
+// ---------------------------------------------------------------------------------------------
+
+function unavailableStep(id, checks) {
+  return {
+    id,
+    run: async () => {
+      throw new ShopifyDiscoveryStop(
+        'shopify_discovery_step_unavailable',
+        `Shopify discovery step "${id}" (${checks}) is not available in this version of the Shopify adapter, so Shopify private-data discovery cannot finish. Recorded steps are kept; re-run discovery once the step ships.`,
+        { step: id },
+      );
+    },
+  };
+}
+
+const WITHHELD_DETAILS_STEP = Object.freeze({ id: 'withheld-details', run: protectedFields.runDiscoveryProbes });
+
+// ---------------------------------------------------------------------------------------------
+// Step 4 -- the order-history window
+// ---------------------------------------------------------------------------------------------
+
+// Through the CLI connector Shopify shows only the last ~60 days of orders, on every read path.
+// Orders are complete only when the shop itself is younger than the window and no imported
+// (back-dated) orders exist: the visible orders' dates are never used as proof.
+const IMPORTED_ORDERS_KEY = 'imported-orders';
+const ORDER_WINDOW_ROW_ID = 'shopify:orders-before-window';
+
+function orderWindowRow(evidence) {
+  return {
+    coverageId: ORDER_WINDOW_ROW_ID,
+    platform: 'shopify',
+    capability: 'commerce.orders',
+    sourceEntity: 'orders-before-window',
+    routes: ['orders'],
+    reason: 'auth-gated',
+    evidence,
+    recoverability: 'requires-development',
+    disposition: null,
+  };
+}
+
+function windowEvidencePointer(record, answer) {
+  const parts = [
+    `shopCreatedAt=${record.shopCreatedAt || 'unreadable'}`,
+    `windowStart=${record.windowStart}`,
+    'session-receipt.json grantedScopes lacks read_all_orders',
+  ];
+  if (record.backdatedOrder) parts.push(`order processedAt ${record.oldestProcessedAt} precedes shopCreatedAt`);
+  if (answer) parts.push(`imported orders: ${answer}`);
+  return parts.join('; ');
+}
+
+async function orderWindowStep(ctx) {
+  const [createdRead, oldestRead] = ORDER_WINDOW_READS;
+  const nowIso = ctx.now();
+  const windowStart = new Date(Date.parse(nowIso) - ORDER_WINDOW_DAYS * 24 * 60 * 60 * 1000).toISOString();
+  const record = { store: ctx.store, readAt: nowIso, windowDays: ORDER_WINDOW_DAYS, windowStart, shopCreatedAt: null, young: false, oldestProcessedAt: null, backdatedOrder: false, errors: [], rowRequired: true };
+  const created = await readOrThrottled(ctx.execute, createdRead.query);
+  const shopCreatedAt = created.data && created.data.shop && typeof created.data.shop.createdAt === 'string' ? created.data.shop.createdAt : null;
+  if (created.errors && created.errors.length) record.errors.push(...errorEntries(operationName(createdRead.query), created.errors));
+  if (shopCreatedAt && Number.isFinite(Date.parse(shopCreatedAt))) {
+    record.shopCreatedAt = shopCreatedAt;
+    record.young = Date.parse(shopCreatedAt) > Date.parse(windowStart);
+  } else if (!record.errors.length) {
+    record.errors.push({ read: operationName(createdRead.query), code: 'CREATED_AT_MISSING', message: 'shop.createdAt was not readable' });
+  }
+  if (record.young) {
+    const oldest = await readOrThrottled(ctx.execute, oldestRead.query);
+    if (oldest.errors && oldest.errors.length) {
+      record.errors.push(...errorEntries(operationName(oldestRead.query), oldest.errors));
+    } else {
+      const node = oldest.data && oldest.data.orders && Array.isArray(oldest.data.orders.nodes) ? oldest.data.orders.nodes[0] : null;
+      record.oldestProcessedAt = node && typeof node.processedAt === 'string' ? node.processedAt : null;
+      record.backdatedOrder = Boolean(record.oldestProcessedAt && Date.parse(record.oldestProcessedAt) < Date.parse(record.shopCreatedAt));
+      // A young store with no back-dated visible order: only the merchant can say whether orders
+      // were imported with dates Shopify keys the window on.
+      record.rowRequired = record.backdatedOrder;
+    }
+  }
+  await writeJsonAtomic(path.join(ctx.rawDir, ORDER_WINDOW_FILE), record);
+  const result = { ...record, file: ORDER_WINDOW_FILE };
+  if (record.young && !record.backdatedOrder && !record.errors.length) {
+    result.questions = [{
+      key: IMPORTED_ORDERS_KEY,
+      title: 'Imported Shopify orders',
+      prompt: 'Were orders imported into this Shopify store from another system?',
+      response: { mode: 'choice' },
+      choices: [
+        { id: 'no', label: 'No' },
+        { id: 'yes', label: 'Yes' },
+        { id: 'unknown', label: 'I don\'t know' },
+      ],
+      artifactRefs: [{ path: `${RAW_DIR}/${ORDER_WINDOW_FILE}`, mediaType: 'application/json' }],
+    }];
+  }
+  return result;
+}
+
+function orderWindowRows(record, answers) {
+  const asked = Array.isArray(record.questions) && record.questions.some((question) => question.key === IMPORTED_ORDERS_KEY);
+  if (asked) {
+    const answer = answers[IMPORTED_ORDERS_KEY];
+    const choice = answer && answer.answer ? answer.answer.choice : null;
+    if (choice === 'no') return [];
+    // `yes`, `unknown`, or no recorded answer: fail closed.
+    return [orderWindowRow({ artifact: answer ? answer.evidence : `${RAW_DIR}/${ORDER_WINDOW_FILE}`, pointer: windowEvidencePointer(record, choice || 'unanswered') })];
+  }
+  if (record.rowRequired === false) return [];
+  return [orderWindowRow({ artifact: `${RAW_DIR}/${ORDER_WINDOW_FILE}`, pointer: windowEvidencePointer(record, null) })];
+}
+
+const ORDER_WINDOW_STEP = Object.freeze({ id: 'order-window', run: orderWindowStep, rows: orderWindowRows });
+
+const GIFT_CARD_CENSUS_STEP = Object.freeze({
+  id: 'gift-card-census',
+  run: (ctx) => giftCards.giftCardCensusStep(ctx, bulk),
+  rows: (record) => record.rows || [],
+});
+
+// ---------------------------------------------------------------------------------------------
+// Step 5 -- questions to the merchant, raised by earlier steps as `record.questions[]`
+// ---------------------------------------------------------------------------------------------
+
+// Deterministic per discovery run and question, so a crash between creating the action and
+// recording it never asks twice.
+function questionRequestId(startedAt, key) {
+  const hex = crypto.createHash('sha256').update(`shopify-discovery\0${startedAt}\0${key}`).digest('hex');
+  return `uar_${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+async function ensureQuestion(ctx, question) {
+  const requestId = questionRequestId(ctx.state.startedAt, question.key);
+  try {
+    return await readUserAction(ctx.projectDir, requestId);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return createUserAction(ctx.projectDir, {
+    requestId,
+    kind: 'question',
+    stage: 'discovery',
+    title: question.title,
+    prompt: question.prompt,
+    response: { mode: question.response && question.response.mode ? question.response.mode : 'choice' },
+    choices: question.choices || [],
+    artifactRefs: question.artifactRefs || [],
+  });
+}
+
+async function questionsStep(ctx) {
+  const questions = [];
+  for (const [stepId, entry] of Object.entries(ctx.state.steps)) {
+    for (const question of (entry.record && entry.record.questions) || []) questions.push({ stepId, ...question });
+  }
+  const answers = {};
+  const pending = [];
+  for (const question of questions) {
+    const action = await ensureQuestion(ctx, question);
+    if (action.status === 'answered') {
+      answers[question.key] = { stepId: question.stepId, requestId: action.requestId, answer: action.answer, evidence: `orchestration/user-actions/${action.requestId}.json` };
+    } else {
+      pending.push(action.requestId);
+    }
+  }
+  if (pending.length) return { awaiting: pending };
+  return { answers };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Step 6 -- the coverage file and the raw-capture index
+// ---------------------------------------------------------------------------------------------
+
+function countCell(entry) {
+  if (entry.count === null) return '—';
+  return entry.countExact ? String(entry.count) : `≥ ${entry.count} (not exact)`;
+}
+
+function renderIndex(capture, rows, generatedAt) {
+  const lines = [
+    '# Shopify discovery capture',
+    '',
+    `Generated ${generatedAt}. Raw evidence only: \`source-profile.md\` and \`source-schema.json\` are synthesized from it.`,
+    '',
+    '| Entity | Count | Samples | File |',
+    '| --- | --- | --- | --- |',
+    ...capture.entities.map((entry) => `| ${entry.entity} | ${countCell(entry)} | ${entry.sampleCount} | \`${entry.file}\` |`),
+    '',
+    `Coverage rows: ${rows.length} (\`source-coverage.json\`).`,
+  ];
+  for (const row of rows) lines.push(`- \`${row.coverageId}\` — ${row.reason}`);
+  return `${lines.join('\n')}\n`;
+}
+
+async function coverageStep(ctx) {
+  const capture = ctx.state.steps.capture && ctx.state.steps.capture.record;
+  if (!capture) throw new ShopifyDiscoveryStop('shopify_discovery_state_invalid', 'the capture step is not recorded; re-run discovery');
+  const answers = (ctx.state.steps.questions && ctx.state.steps.questions.record && ctx.state.steps.questions.record.answers) || {};
+  const stepRows = [];
+  for (const step of ctx.steps) {
+    const entry = ctx.state.steps[step.id];
+    if (!entry || !entry.record || step.id === 'capture' || step.id === 'coverage') continue;
+    const rows = typeof step.rows === 'function' ? step.rows(entry.record, answers) : entry.record.rows;
+    if (Array.isArray(rows)) stepRows.push(...rows);
+  }
+  const generatedAt = ctx.now();
+  const rows = buildShopifyCoverageRows({ captureFailures: capture.failed, stepRows, rawDir: RAW_DIR });
+  const file = buildCoverageFile({ platform: 'shopify', adapter: 'shopify', rows, generatedAt });
+  await writeJsonAtomic(path.join(ctx.rawDir, 'source-coverage.json'), file);
+  await fs.writeFile(path.join(ctx.rawDir, 'README.md'), renderIndex(capture, file.rows, generatedAt), 'utf8');
+  return { rows: file.rows.map((row) => row.coverageId) };
+}
+
+// ---------------------------------------------------------------------------------------------
+// The sequence
+// ---------------------------------------------------------------------------------------------
+
+const DEFAULT_STEPS = Object.freeze([
+  { id: 'capture', run: captureStep },
+  WITHHELD_DETAILS_STEP,
+  GIFT_CARD_CENSUS_STEP,
+  ORDER_WINDOW_STEP,
+  { id: 'questions', run: questionsStep },
+  { id: 'coverage', run: coverageStep },
+]);
+
+// Forget what the named entities captured, so the next run reads exactly those again. The capture
+// and coverage records are re-derived; every other recorded step is kept.
+async function resetEntities(projectDir, rawDir, entities, now, store) {
+  if (!entities.length) return;
+  const known = new Set(ALL_READS.map((read) => read.entity));
+  for (const entity of entities) {
+    if (!known.has(entity)) throw new ShopifyDiscoveryStop('shopify_entity_unknown', `unknown Shopify entity ${entity}; known: ${[...known].join(', ')}`);
+    await fs.rm(path.join(rawDir, entityFile(entity)), { force: true });
+  }
+  const state = await readSteps(rawDir, now, store);
+  delete state.steps.capture;
+  delete state.steps.coverage;
+  if (await protectedFields.resetProbeEntities(projectDir, entities)) delete state.steps['withheld-details'];
+  await writeSteps(rawDir, state);
+}
+
+async function runDiscovery({
+  projectDir,
+  store,
+  execute,
+  steps = DEFAULT_STEPS,
+  reads = ALL_READS,
+  sampleLimit = SAMPLE_LIMIT,
+  reread = [],
+  restart = false,
+  now = () => new Date().toISOString(),
+  progress = () => {},
+  sessionCheck = async () => ({ ok: true }),
+} = {}) {
+  if (!projectDir) throw new Error('projectDir is required');
+  if (typeof execute !== 'function') throw new Error('execute is required');
+  const boundStore = normalizeStore(store);
+  const rawDir = path.join(projectDir, RAW_DIR);
+  if (restart) await restartDiscovery(projectDir, rawDir, boundStore);
+  // Bind before anything is read or reset: a different store's data is refused here, and the
+  // store is recorded in the steps file before the first read of a new run.
+  await assertBoundToStore(rawDir, boundStore);
+  await fs.mkdir(path.join(rawDir, ENTITIES_DIR), { recursive: true });
+  await resetEntities(projectDir, rawDir, reread, now, boundStore);
+  const state = await readSteps(rawDir, now, boundStore);
+  if (!state.steps || typeof state.steps !== 'object') state.steps = {};
+  await writeSteps(rawDir, state);
+
+  const ran = [];
+  for (const step of steps) {
+    if (state.steps[step.id] && state.steps[step.id].status === 'done') continue;
+    progress(`Shopify discovery step ${step.id}`, { step: step.id });
+    const ctx = { projectDir, rawDir, store: boundStore, execute, reads, sampleLimit, now, progress, state, steps, sessionCheck };
+    let record;
+    try {
+      record = await step.run(ctx);
+    } catch (error) {
+      // The connection lapsed: hold at a re-approval request. Recorded steps and
+      // captured entities are kept, so the resumed run reads only what is not yet captured.
+      if (error instanceof ShopifyCliError && error.code === 'source_auth_expired') {
+        const action = await recordAuthExpired(projectDir, { stage: 'discovery', store: boundStore });
+        throw new ShopifyDiscoveryStop('source_auth_expired', `the Shopify connection for ${boundStore} expired during discovery step ${step.id}. Re-approval request ${action.requestId} is pending: run the Shopify session check (with --connect if asked), then answer it and run discovery again. Finished reads are not repeated.`, { step: step.id, requestId: action.requestId });
+      }
+      throw error;
+    }
+    ran.push(step.id);
+    if (record && Array.isArray(record.awaiting)) {
+      return { status: 'awaiting_user_action', requestIds: record.awaiting, stepsRun: ran };
+    }
+    state.steps[step.id] = { status: 'done', completedAt: now(), record: record || {} };
+    await writeSteps(rawDir, state);
+  }
+  const coverage = state.steps.coverage && state.steps.coverage.record;
+  return { status: 'complete', stepsRun: ran, rows: coverage ? coverage.rows : [] };
+}
+
+// ---------------------------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { project: null, store: null, reread: [], restart: false, confirmWithheldExport: null, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--project') { args.project = argv[i + 1]; i += 1; }
+    else if (arg === '--store') { args.store = argv[i + 1]; i += 1; }
+    else if (arg === '--reread') { args.reread.push(argv[i + 1]); i += 1; }
+    else if (arg === '--restart') args.restart = true;
+    else if (arg === '--confirm-withheld-export') { args.confirmWithheldExport = argv[i + 1]; i += 1; }
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return args;
+}
+
+const USAGE = 'Usage: shopify-discovery.js --project <migrations-root>/<project> (--store <shop>.myshopify.com [--reread <entity> ...] [--restart] | --confirm-withheld-export owner-exported) [--progress-log <path>]\n';
+
+async function main() {
+  const parsed = parseProgressArgs(process.argv.slice(2));
+  const logger = createProgressLogger({ script: 'skills/wix-replatform/resources/rp-source-shopify/scripts/shopify-discovery.js', ...parsed.progress });
+  let args;
+  try {
+    args = parseArgs(parsed.args);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n${USAGE}`);
+    return 1;
+  }
+  if (args.help) { process.stdout.write(USAGE); return 0; }
+  if (!args.project || (!args.store && !args.confirmWithheldExport) || (args.store && args.confirmWithheldExport)) { process.stderr.write(USAGE); return 1; }
+  logger.start('Shopify discovery started', { phase: 'discovery' });
+  try {
+    if (args.confirmWithheldExport) {
+      try {
+        const confirmation = await protectedFields.confirmWithheldExport(path.resolve(args.project), args.confirmWithheldExport);
+        process.stdout.write(`${JSON.stringify({ ok: true, status: 'confirmed', file: protectedFields.WITHHELD_EXPORT_FILE, confirmation })}\n`);
+        logger.complete('Shopify withheld-details export confirmed', { phase: 'discovery' });
+        return 0;
+      } catch (error) {
+        throw new ShopifyDiscoveryStop('shopify_withheld_export_confirmation_failed', error.message);
+      }
+    }
+    const store = normalizeStore(args.store);
+    // Discovery starts only after a passing session check for this store, approved from a
+    // confirmed dedicated migration staff account.
+    await assertConnectionReady(path.resolve(args.project), store);
+    const execute = createStoreExecutor({ store });
+    const result = await runDiscovery({
+      projectDir: path.resolve(args.project),
+      store,
+      execute,
+      reread: args.reread,
+      restart: args.restart,
+      sessionCheck: async () => {
+        try {
+          await runSessionCheck({ projectDir: path.resolve(args.project), store, askFirstConnection: false });
+          return { ok: true };
+        } catch (error) {
+          if (error instanceof ShopifySessionStop || error instanceof ShopifyCliError) return { ok: false, error: { code: error.code, message: error.message } };
+          throw error;
+        }
+      },
+      progress: (message, fields) => logger.progress(message, { phase: 'discovery', ...fields }),
+    });
+    process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`);
+    logger.complete(`Shopify discovery ${result.status}`, { phase: 'discovery' });
+    return result.status === 'complete' ? 0 : 3;
+  } catch (error) {
+    if (error instanceof ShopifyDiscoveryStop || error instanceof ShopifyCliError || error instanceof ShopifySessionStop) {
+      process.stdout.write(`${JSON.stringify({ ok: false, status: 'stopped', code: error.code, message: error.message })}\n`);
+      logger.error(error.message, { phase: 'discovery' });
+      return 2;
+    }
+    throw error;
+  }
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    process.stderr.write(`${error.stack || error.message}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  RAW_DIR,
+  STEPS_FILE,
+  DEFAULT_STEPS,
+  HANDOFF_FILES,
+  ShopifyDiscoveryStop,
+  captureEntity,
+  captureStep,
+  questionsStep,
+  coverageStep,
+  unavailableStep,
+  orderWindowStep,
+  orderWindowRows,
+  WITHHELD_DETAILS_STEP,
+  ORDER_WINDOW_STEP,
+  GIFT_CARD_CENSUS_STEP,
+  ORDER_WINDOW_FILE,
+  CONNECTION_FILES,
+  questionRequestId,
+  runDiscovery,
+  normalizeStore,
+  parseArgs,
+};