@wix/agent-skills 1.33.1 → 1.34.0

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

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+'use strict';
+
+// The Shopify extract step: reads the full store through Shopify's bulk export, one
+// dataset at a time, and writes the extract files the import step consumes.
+//
+//   node scripts/shopify-extract.js --project <migrations-root>/<project> [--store <shop>.myshopify.com]
+//        [--retry-failed] [--catch-up] [--progress-log <path>]
+//
+// The store defaults to SHOPIFY_SHOP_DOMAIN in config/source.shopify.env. Run the Shopify session
+// check first: the extract refuses to start without a passing one.
+//
+//   (no flag)        start the extract, or resume it from data/source-extract/extract-manifest.json.
+//                    A manifest that says `complete` with its final files present skips the read.
+//   --retry-failed   Import Operator recovery: send every stopping dataset (each `failed` entry, each
+//                    unattributed `denied` entry, and the datasets whose exact count check stopped
+//                    the extract) back to `pending` and read it again. Nothing else is reset.
+//   --catch-up       a source catch-up rerun: archive the `complete` manifest as
+//                    extract-manifest.<T_prev>.json and read the whole store again with a new
+//                    snapshot time. A manifest that is not complete is resumed instead.
+//
+// Output: data/source-extract/<entity>.ndjson, data/source-extract/extract-manifest.json.
+// Exit codes: 0 complete; 3 waiting on a question (shopify_bulk_overdue: answer it, run again);
+// 2 stopped (the printed code says why; finished datasets are kept); 1 usage error.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { createProgressLogger, parseProgressArgs } = require('../../../lib/progress-log.js');
+const { readEnvFile } = require('../../../lib/config-env.js');
+const { SHOPIFY_SOURCE_ENV } = require('../../../lib/source-access.js');
+const { createStoreExecutor, ShopifyCliError } = require('../lib/shopify-cli.js');
+const session = require('../lib/shopify-session.js');
+const bulk = require('../lib/shopify-bulk.js');
+const protectedFields = require('../lib/shopify-protected-fields.js');
+const giftCards = require('../lib/shopify-gift-cards.js');
+
+const USAGE = 'Usage: shopify-extract.js --project <migrations-root>/<project> [--store <shop>.myshopify.com] [--retry-failed] [--catch-up] [--progress-log <path>]\n';
+
+function parseArgs(argv) {
+  const args = { project: null, store: null, retryFailed: false, catchUp: false, 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 === '--retry-failed') args.retryFailed = true;
+    else if (arg === '--catch-up') args.catchUp = true;
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return args;
+}
+
+async function configuredDomain(projectDir) {
+  let values;
+  try {
+    values = await readEnvFile(path.join(projectDir, SHOPIFY_SOURCE_ENV));
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new session.ShopifySessionStop('shopify_shop_domain_missing', `${SHOPIFY_SOURCE_ENV} is missing; record SHOPIFY_SHOP_DOMAIN=<shop>.myshopify.com there or pass --store.`);
+    throw error;
+  }
+  if (!values.SHOPIFY_SHOP_DOMAIN) throw new session.ShopifySessionStop('shopify_shop_domain_missing', `SHOPIFY_SHOP_DOMAIN is missing from ${SHOPIFY_SOURCE_ENV}.`);
+  return values.SHOPIFY_SHOP_DOMAIN;
+}
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+// The previous complete manifest is kept as extract-manifest.<T_prev>.json (':' replaced by
+// '-' so the name is valid on every platform), and the catch-up starts a fresh manifest.
+async function archiveCompleteManifest(manifestPath, knownPrevious = null) {
+  const previous = knownPrevious || await readJson(manifestPath);
+  if (!previous || previous.status !== 'complete') return null;
+  const stamp = String(previous.snapshotTime || 'unknown').replace(/:/g, '-');
+  const archived = path.join(path.dirname(manifestPath), `extract-manifest.${stamp}.json`);
+  try {
+    await fs.access(archived);
+    throw new session.ShopifySessionStop('shopify_extract_archive_exists', `${path.basename(archived)} already exists; the previous extract was already archived. Nothing was changed.`);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  await fs.rename(manifestPath, archived);
+  return archived;
+}
+
+// A crash can land after the complete manifest was renamed but before the new catch-up manifest
+// was created. Recover its sidecar ownership from the newest archive so the replacement run still
+// removes outputs that no longer exist; no archived record is ever modified.
+async function latestArchivedManifest(manifestPath) {
+  const dir = path.dirname(manifestPath);
+  const prefix = `${path.basename(manifestPath, '.json')}.`;
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  const candidates = [];
+  for (const name of names.filter((candidate) => candidate.startsWith(prefix) && candidate.endsWith('.json'))) {
+    const file = path.join(dir, name);
+    const manifest = await readJson(file);
+    if (!manifest || manifest.status !== 'complete') continue;
+    const time = Date.parse(manifest.snapshotTime || manifest.completedAt || '');
+    candidates.push({ file, manifest, time: Number.isFinite(time) ? time : -Infinity });
+  }
+  candidates.sort((a, b) => b.time - a.time || b.file.localeCompare(a.file));
+  return candidates[0] || null;
+}
+
+// The denial path's session check: passes only when the connection is live and holds
+// every required scope. A failure is data to the runner, not an exception.
+function defaultSessionCheck({ projectDir, store }) {
+  return async () => {
+    try {
+      await session.runSessionCheck({ projectDir, store, askFirstConnection: false });
+      return { ok: true };
+    } catch (error) {
+      if (error instanceof session.ShopifySessionStop || error instanceof ShopifyCliError) return { ok: false, error: { code: error.code, message: error.message } };
+      throw error;
+    }
+  };
+}
+
+async function runExtract({
+  projectDir,
+  store,
+  execute,
+  retryFailed = false,
+  catchUp = false,
+  now = () => Date.now(),
+  sessionCheck = defaultSessionCheck({ projectDir, store }),
+  ...runnerOptions
+} = {}) {
+  if (!projectDir) throw new Error('projectDir is required');
+  if (typeof execute !== 'function') throw new Error('execute is required');
+  const normalizedStore = session.normalizeDomain(store);
+  const outputDir = path.join(projectDir, bulk.RAW_EXTRACT_DIR);
+  const manifestPath = path.join(outputDir, bulk.EXTRACT_MANIFEST_FILE);
+  const stagingDir = path.join(outputDir, 'staging');
+  let existing = await readJson(manifestPath);
+  let archived = null;
+  let previousSidecars = [];
+  let sameStore = !existing;
+  if (existing && existing.store) {
+    try {
+      sameStore = session.normalizeDomain(existing.store) === normalizedStore;
+    } catch {
+      sameStore = false;
+    }
+  }
+  // Store binding is checked before the only destructive catch-up action. A mismatch stays in
+  // place for the runner to report, so neither the manifest nor any final file is changed.
+  if (catchUp && sameStore && existing && existing.status === 'complete') {
+    previousSidecars = Array.isArray(existing.sidecars) ? existing.sidecars : [];
+    archived = await archiveCompleteManifest(manifestPath, existing);
+    existing = null;
+  } else if (catchUp && !existing) {
+    const recovered = await latestArchivedManifest(manifestPath);
+    if (recovered) {
+      let recoveredStore = null;
+      try {
+        recoveredStore = session.normalizeDomain(recovered.manifest.store);
+      } catch {
+        recoveredStore = null;
+      }
+      if (recoveredStore !== normalizedStore) {
+        return {
+          status: 'stopped',
+          code: 'shopify_extract_store_mismatch',
+          message: `${path.basename(recovered.file)} was read from ${recovered.manifest.store || 'an unrecorded store'}, not ${normalizedStore}. Nothing was read or changed.`,
+          details: { recorded: recovered.manifest.store || null, store: normalizedStore },
+        };
+      }
+      archived = recovered.file;
+      previousSidecars = Array.isArray(recovered.manifest.sidecars) ? recovered.manifest.sidecars : [];
+    }
+  }
+  giftCards.registerGiftCardHandlers(bulk);
+  const snapshotTime = existing && existing.snapshotTime ? existing.snapshotTime : new Date(now()).toISOString();
+  const probeState = await protectedFields.readProbeState(projectDir);
+  const protectedOptions = protectedFields.createBulkOptions({ projectDir, sessionCheck, probeState });
+  const project = protectedOptions.project;
+  // Texts are only used for a new manifest; a resumed one keeps what each query was last sent.
+  const queries = existing ? null : bulk.QUERY_NAMES.map((name) => ({ name, entity: bulk.entityOf(name), text: bulk.generateQueryText(name, { snapshotTime, project }) }));
+  const suppliedHandlers = runnerOptions.handlers || {};
+  const handlers = {
+    ...protectedOptions.handlers,
+    ...suppliedHandlers,
+    failed: { ...(protectedOptions.handlers.failed || {}), ...(suppliedHandlers.failed || {}), byQuery: { ...((protectedOptions.handlers.failed || {}).byQuery || {}), ...((suppliedHandlers.failed || {}).byQuery || {}) } },
+    reassemble: { ...(protectedOptions.handlers.reassemble || {}), ...(suppliedHandlers.reassemble || {}) },
+  };
+  const { handlers: _ignoredHandlers, deniedReset: suppliedDeniedReset, ...remainingRunnerOptions } = runnerOptions;
+  const runner = bulk.createBulkRunner({
+    projectDir,
+    store: normalizedStore,
+    caller: 'extract',
+    manifestPath,
+    stagingDir,
+    outputDir,
+    queries,
+    snapshotTime,
+    execute,
+    retryFailed,
+    previousSidecars,
+    sessionCheck,
+    handlers,
+    deniedReset: suppliedDeniedReset || protectedOptions.deniedReset,
+    now,
+    ...remainingRunnerOptions,
+  });
+  const result = await runner.run();
+  return { ...result, ...(archived ? { archived: path.relative(projectDir, archived) } : {}) };
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const parsed = parseProgressArgs(argv);
+  const logger = createProgressLogger({ script: 'skills/wix-replatform/resources/rp-source-shopify/scripts/shopify-extract.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) { process.stderr.write(USAGE); return 1; }
+  const projectDir = path.resolve(args.project);
+  logger.start('Shopify extract started', { phase: 'execution' });
+  try {
+    const store = session.normalizeDomain(args.store || await configuredDomain(projectDir));
+    // The extract starts only after a passing session check for this store, approved from a
+    // confirmed dedicated migration staff account.
+    await session.assertConnectionReady(projectDir, store);
+    const execute = createStoreExecutor({ store });
+    const result = await runExtract({
+      projectDir,
+      store,
+      execute,
+      retryFailed: args.retryFailed,
+      catchUp: args.catchUp,
+      progress: (message, fields) => logger.progress(message, { phase: 'execution', ...fields }),
+    });
+    const ok = result.status === 'complete';
+    print({
+      ok,
+      status: result.status,
+      ...(result.code ? { code: result.code, message: result.message } : {}),
+      ...(result.details && result.details.requestIds ? { requestIds: result.details.requestIds } : {}),
+      ...(result.archived ? { archived: result.archived } : {}),
+      ...(result.skipped ? { skipped: true } : {}),
+      manifest: `${bulk.RAW_EXTRACT_DIR}/${bulk.EXTRACT_MANIFEST_FILE}`,
+    });
+    logger.complete(`Shopify extract ${result.status}`, { phase: 'execution' });
+    if (ok) return 0;
+    return result.status === 'awaiting_user_action' ? 3 : 2;
+  } catch (error) {
+    if (error instanceof session.ShopifySessionStop || error instanceof ShopifyCliError) {
+      print({ ok: false, status: 'stopped', code: error.code, message: error.message });
+      logger.error(error.message, { phase: 'execution' });
+      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 = { main, parseArgs, runExtract, archiveCompleteManifest, defaultSessionCheck };

package/skills/wix-replatform/resources/rp-source-shopify/scripts/shopify-gift-card-remedy.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+'use strict';
+
+// Record merchant-provided gift-card remedies and export the current owed-card list.
+// This script never creates a Wix card and never contacts a holder.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { readEnvFile } = require('../../../lib/config-env.js');
+const { SHOPIFY_SOURCE_ENV } = require('../../../lib/source-access.js');
+const { writeJsonAtomic } = require('../../../lib/source-coverage.js');
+const { createStoreExecutor } = require('../lib/shopify-cli.js');
+const session = require('../lib/shopify-session.js');
+const gift = require('../lib/shopify-gift-cards.js');
+
+const COLUMNS = Object.freeze(['id', 'wixGiftCardId', 'replacementAmount', 'currency', 'holderNotifiedOn', 'notificationConfirmedBy']);
+const USAGE = 'Usage: shopify-gift-card-remedy.js <export|activity-stopped|record-replacements|keep-redeeming> --project <project> [--at <ISO> | --evidence <file.csv> | --until <YYYY-MM-DD>] [--by <name>]\n';
+
+function parseArgs(argv) {
+  const out = { command: argv[0] || null, project: null, at: null, evidence: null, until: null, by: null, help: false };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') out.help = true;
+    else if (['--project', '--at', '--evidence', '--until', '--by'].includes(arg)) { out[arg.slice(2)] = argv[i + 1]; i += 1; }
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return out;
+}
+
+function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let quoted = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') { field += '"'; i += 1; }
+      else if (ch === '"') quoted = false;
+      else field += ch;
+    } else if (ch === '"') quoted = true;
+    else if (ch === ',') { row.push(field); field = ''; }
+    else if (ch === '\n') { row.push(field.replace(/\r$/, '')); rows.push(row); row = []; field = ''; }
+    else field += ch;
+  }
+  if (quoted) throw new Error('CSV has an unterminated quoted field');
+  if (field.length || row.length) { row.push(field.replace(/\r$/, '')); rows.push(row); }
+  return rows.filter((entry) => entry.some((value) => value !== ''));
+}
+
+function validDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(value || ''))) return false;
+  const date = new Date(`${value}T00:00:00.000Z`);
+  return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
+function csvCell(value) {
+  const text = value === null || value === undefined ? '' : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+async function readRemedy(projectDir) {
+  return gift.readJson(path.join(projectDir, gift.REMEDY_FILE), { replacements: [] });
+}
+
+async function writeRemedy(projectDir, value) {
+  await writeJsonAtomic(path.join(projectDir, gift.REMEDY_FILE), value);
+}
+
+async function recordActivityStopped(projectDir, { at, by, now = () => new Date().toISOString() } = {}) {
+  if (!Number.isFinite(Date.parse(at))) throw new Error('--at must be an ISO timestamp');
+  if (!by) throw new Error('--by is required');
+  const record = { activityStoppedAt: new Date(at).toISOString(), recordedBy: by, recordedAt: now() };
+  await writeJsonAtomic(path.join(projectDir, gift.ACTIVITY_FILE), record);
+  return record;
+}
+
+async function shopTimezone(execute) {
+  const result = await execute('query RpGiftCardShopTimezone { shop { ianaTimezone } }');
+  if (result.errors && result.errors.length) throw new Error(`Shopify shop timezone could not be read: ${result.errors.map((error) => error.message).join('; ')}`);
+  const timezone = result.data && result.data.shop && result.data.shop.ianaTimezone;
+  if (typeof timezone !== 'string' || !timezone) throw new Error('Shopify shop timezone was missing');
+  // Make Intl validate the IANA identifier now, before changing any file.
+  gift.dateInTimezone(new Date(), timezone);
+  return timezone;
+}
+
+async function recordReplacements(projectDir, { evidence, by, execute, now = () => new Date().toISOString() } = {}) {
+  if (!evidence) throw new Error('--evidence is required');
+  if (!by) throw new Error('--by is required');
+  if (typeof execute !== 'function') throw new Error('a Shopify executor is required');
+  const timezone = await shopTimezone(execute);
+  const today = gift.dateInTimezone(new Date(now()), timezone);
+  const rows = parseCsv(await fs.readFile(evidence, 'utf8'));
+  if (!rows.length || rows[0].length !== COLUMNS.length || !rows[0].every((value, index) => value === COLUMNS[index])) {
+    throw new Error(`CSV columns must be exactly ${COLUMNS.join(',')}`);
+  }
+  const { latest } = await gift.giftCardReads(projectDir);
+  if (!latest) throw new Error('no successful gift-card read exists');
+  const cards = new Map(gift.summarizeCards(latest.cards).owed.map((card) => [card.id, card]));
+  const seen = new Set();
+  const replacements = [];
+  for (let index = 1; index < rows.length; index += 1) {
+    if (rows[index].length !== COLUMNS.length) throw new Error(`CSV row ${index + 1} has ${rows[index].length} columns, expected ${COLUMNS.length}`);
+    const candidate = Object.fromEntries(COLUMNS.map((column, at) => [column, rows[index][at]]));
+    const card = cards.get(candidate.id);
+    if (!card) throw new Error(`CSV row ${index + 1}: id is not an owed card in the latest read`);
+    if (seen.has(candidate.id)) throw new Error(`CSV row ${index + 1}: duplicate id ${candidate.id}`);
+    seen.add(candidate.id);
+    if (!candidate.wixGiftCardId || !candidate.holderNotifiedOn || !candidate.notificationConfirmedBy) throw new Error(`CSV row ${index + 1}: Wix card id and holder-notification evidence are required`);
+    if (!validDate(candidate.holderNotifiedOn) || candidate.holderNotifiedOn > today) throw new Error(`CSV row ${index + 1}: holderNotifiedOn must be a valid date no later than today in ${timezone}`);
+    const amount = gift.decimal(candidate.replacementAmount);
+    if (amount.units <= 0n) throw new Error(`CSV row ${index + 1}: replacementAmount must be above zero`);
+    if (candidate.currency !== card.balance.currencyCode) throw new Error(`CSV row ${index + 1}: currency must be ${card.balance.currencyCode}`);
+    replacements.push({ ...candidate, recordedBy: by, recordedAt: now() });
+  }
+  if (!replacements.length) throw new Error('CSV must contain at least one owed-card replacement');
+  const remedy = await readRemedy(projectDir);
+  const merged = new Map(((remedy && remedy.replacements) || []).map((row) => [row.id, row]));
+  replacements.forEach((row) => merged.set(row.id, row));
+  const next = { ...remedy, ianaTimezone: timezone, replacements: [...merged.values()].sort((a, b) => a.id.localeCompare(b.id)) };
+  await writeRemedy(projectDir, next);
+  return next;
+}
+
+async function keepRedeeming(projectDir, { until, by, execute, now = () => new Date().toISOString() } = {}) {
+  if (!validDate(until)) throw new Error('--until must be a YYYY-MM-DD calendar date');
+  if (!by) throw new Error('--by is required');
+  if (typeof execute !== 'function') throw new Error('a Shopify executor is required');
+  const timezone = await shopTimezone(execute);
+  const remedy = await readRemedy(projectDir);
+  const next = { ...remedy, replacements: Array.isArray(remedy.replacements) ? remedy.replacements : [], keepRedeemingUntil: until, keepRedeemingRecordedBy: by, keepRedeemingRecordedAt: now(), ianaTimezone: timezone };
+  await writeRemedy(projectDir, next);
+  return next;
+}
+
+async function exportOwed(projectDir) {
+  const { latest } = await gift.giftCardReads(projectDir);
+  if (!latest) throw new Error('no successful gift-card read exists');
+  const summary = gift.summarizeCards(latest.cards);
+  const state = await gift.evaluateGiftCardCutover(projectDir);
+  const uncleared = new Set((state.uncleared || summary.owed).map((card) => card.id));
+  const lines = [['id', 'lastCharacters', 'balance', 'currency', 'enabled', 'expiresOn', 'replaced']];
+  for (const card of summary.owed) {
+    const replaced = state.finalRead && !uncleared.has(card.id) ? 'yes' : 'no';
+    lines.push([card.id, card.lastCharacters || '', card.balance.amount, card.balance.currencyCode, card.enabled ? 'true' : 'false', card.expiresOn || '', replaced]);
+  }
+  const text = `${lines.map((row) => row.map(csvCell).join(',')).join('\n')}\n`;
+  const file = path.join(projectDir, gift.OWED_CSV_FILE);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(temp, text, 'utf8');
+  await fs.rename(temp, file);
+  return { file: gift.OWED_CSV_FILE, rows: summary.owed.length };
+}
+
+async function configuredStore(projectDir) {
+  const values = await readEnvFile(path.join(projectDir, SHOPIFY_SOURCE_ENV));
+  if (!values.SHOPIFY_SHOP_DOMAIN) throw new Error(`SHOPIFY_SHOP_DOMAIN is missing from ${SHOPIFY_SOURCE_ENV}`);
+  return session.normalizeDomain(values.SHOPIFY_SHOP_DOMAIN);
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let args;
+  try { args = parseArgs(argv); } catch (error) { process.stderr.write(`${error.message}\n${USAGE}`); return 1; }
+  if (args.help) { process.stdout.write(USAGE); return 0; }
+  if (!args.project || !['export', 'activity-stopped', 'record-replacements', 'keep-redeeming'].includes(args.command)) { process.stderr.write(USAGE); return 1; }
+  const projectDir = path.resolve(args.project);
+  try {
+    let result;
+    if (args.command === 'export') result = await exportOwed(projectDir);
+    else if (args.command === 'activity-stopped') result = await recordActivityStopped(projectDir, args);
+    else {
+      const store = await configuredStore(projectDir);
+      await session.assertConnectionReady(projectDir, store);
+      const execute = createStoreExecutor({ store });
+      result = args.command === 'record-replacements'
+        ? await recordReplacements(projectDir, { ...args, execute })
+        : await keepRedeeming(projectDir, { ...args, execute });
+    }
+    process.stdout.write(`${JSON.stringify({ ok: true, command: args.command, ...result })}\n`);
+    return 0;
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ ok: false, command: args.command, code: error.code || 'shopify_gift_card_remedy_invalid', message: error.message })}\n`);
+    return 2;
+  }
+}
+
+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 = { COLUMNS, parseArgs, parseCsv, validDate, csvCell, recordActivityStopped, shopTimezone, recordReplacements, keepRedeeming, exportOwed, main };

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

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+
+// The Shopify session check. Run from rp-source-shopify:
+//
+//   node scripts/shopify-session-check.js --project <migrations-root>/<project> [--install] [--connect]
+//   node scripts/shopify-session-check.js --project <dir> --confirm-staff-removal owner-removed-account
+//   node scripts/shopify-session-check.js --project <dir> --repair-staff-access
+//
+// The store is SHOPIFY_SHOP_DOMAIN in config/source.shopify.env.
+//
+//   (no flag)   Node.js >= 22.12, the adapter's CLI 4.8.3, the connection, the scope readback and
+//               the API-version canary; writes data/shopify-discovery/session-receipt.json.
+//   --install   the operator consents to installing (or reinstalling) the adapter's own CLI 4.8.3
+//               into ~/.replatform/tools; nothing is installed without it.
+//   --connect   starts the browser approval (`store auth` with the derived scope list) through the
+//               adapter's CLI with self-update off, then runs the check. Never type a bare
+//               `shopify store auth`: that process would run without CI and could upgrade a
+//               machine-wide Shopify CLI.
+//
+// Exit codes: 0 the check passed and the connection is confirmed as a dedicated migration staff
+// account; 3 the first-connection question is pending (answer it, then run again); 2 stopped (the
+// printed code says why; also every refused confirmation or repair); 1 usage error.
+
+const path = require('node:path');
+const { readEnvFile } = require('../../../lib/config-env.js');
+const { SHOPIFY_SOURCE_ENV } = require('../../../lib/source-access.js');
+const { ShopifyCliError } = require('../lib/shopify-cli.js');
+const session = require('../lib/shopify-session.js');
+
+const USAGE = 'Usage: shopify-session-check.js --project <migrations-root>/<project> [--install] [--connect] | --confirm-staff-removal owner-removed-account | --repair-staff-access\n';
+
+function parseArgs(argv) {
+  const args = { project: null, install: false, connect: false, confirm: null, repair: false, 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 === '--install') args.install = true;
+    else if (arg === '--connect') args.connect = true;
+    else if (arg === '--confirm-staff-removal') { args.confirm = argv[i + 1] || ''; i += 1; }
+    else if (arg === '--repair-staff-access') args.repair = true;
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  if ((args.confirm !== null) + args.repair > 1) throw new Error('--confirm-staff-removal and --repair-staff-access are separate commands');
+  return args;
+}
+
+async function configuredDomain(projectDir) {
+  let values;
+  try {
+    values = await readEnvFile(path.join(projectDir, SHOPIFY_SOURCE_ENV));
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new session.ShopifySessionStop('shopify_shop_domain_missing', `${SHOPIFY_SOURCE_ENV} is missing; record SHOPIFY_SHOP_DOMAIN=<shop>.myshopify.com there.`);
+    throw error;
+  }
+  if (!values.SHOPIFY_SHOP_DOMAIN) throw new session.ShopifySessionStop('shopify_shop_domain_missing', `SHOPIFY_SHOP_DOMAIN is missing from ${SHOPIFY_SOURCE_ENV}.`);
+  return session.normalizeDomain(values.SHOPIFY_SHOP_DOMAIN);
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+async function main(argv = process.argv.slice(2), options = {}) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n${USAGE}`);
+    return 1;
+  }
+  if (args.help) { process.stdout.write(USAGE); return 0; }
+  if (!args.project) { process.stderr.write(USAGE); return 1; }
+  const projectDir = path.resolve(args.project);
+  try {
+    const domain = await configuredDomain(projectDir);
+    if (args.confirm !== null) {
+      const entry = session.confirmStaffRemoval(projectDir, domain, args.confirm);
+      print({ ok: true, status: 'staff_removal_confirmed', shopDomain: entry.shopDomain, confirmedAt: entry.confirmedAt });
+      return 0;
+    }
+    if (args.repair) {
+      const result = await session.repairStaffAccess(projectDir, domain);
+      print({ ok: true, status: result.changed ? 'staff_record_rebuilt' : 'staff_record_unchanged', ...(result.setAside ? { setAside: path.relative(projectDir, result.setAside) } : {}) });
+      return 0;
+    }
+    const result = await session.runSessionCheck({ projectDir, store: domain, install: args.install, connect: args.connect, ...options });
+    const confirmed = result.firstConnection.answer === 'dedicated-account';
+    print({
+      ok: true,
+      status: confirmed ? 'passed' : 'awaiting_user_action',
+      receipt: 'data/shopify-discovery/session-receipt.json',
+      shopDomain: result.receipt.shopDomain,
+      grantedScopes: result.receipt.grantedScopes,
+      ...(confirmed ? {} : { requestId: result.firstConnection.requestId, message: 'Discovery does not start until the first-connection question is answered dedicated-account.' }),
+    });
+    return confirmed ? 0 : 3;
+  } catch (error) {
+    if (error instanceof session.ShopifySessionStop || error instanceof ShopifyCliError) {
+      print({ ok: false, status: 'stopped', code: error.code, message: error.message, ...(error.details && error.details.missingScopes ? { missingScopes: error.details.missingScopes } : {}) });
+      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 = { main, parseArgs };