1#!/usr/bin/env node
2'use strict';
3
4// Shopify private-data discovery, read through the Shopify CLI.
5//
6//   node scripts/shopify-discovery.js --project <migrations-root>/<project> --store <shop>.myshopify.com
7//        [--reread <entity> ...] [--restart] [--progress-log <path>]
8//
9// Runs the discovery steps in a fixed order. Each step records its result in
10// data/shopify-discovery/discovery-steps.json before the next starts, so a restart -- or a return
11// after a merchant question -- runs only the steps not yet recorded and reads nothing it already
12// captured. The locale step writes data/shopify-discovery/source-locale.json (currency, time
13// zone, language, country; a value Shopify did not give is an explicit unknown). The last step
14

shopify-discovery.js on GitHub

// 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 { regionalStep } = require('../lib/shopify-regional.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 });

// Not a coverage row source: a regional value is a field of the store, and an unknown one is

// recorded in the regional file itself.

const REGIONAL_STEP = Object.freeze({ id: 'regional', run: regionalStep });

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.`,

'',

'| --- | --- | --- | --- |',

...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,

REGIONAL_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;

delete state.steps.regional;

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,

REGIONAL_STEP,

ORDER_WINDOW_FILE,

CONNECTION_FILES,

questionRequestId,

runDiscovery,

normalizeStore,

parseArgs,

};