@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/runVmScript.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * Generic NON-interactive in-VM script runner.
+ *
+ * Boots the same VM the online suite uses and runs
+ * `dist/scripts/<name>.js [args]` inside it, headed under Xvfb :99 (the
+ * Cloudflare-passing config the tests use), with TEST_IN_CONTAINER=true.
+ * This is how the store-setup scripts that drive a browser — installApp,
+ * createStores — run: in the VM, never on the host. (For the INTERACTIVE
+ * human-login flow, see runVmAuth.ts, which adds VNC.)
+ *
+ * Usage (wired via package.json):
+ *   node --import tsx .../runVmScript.ts <script-name> [-- <args…>]
+ * e.g.
+ *   npm run test:online:install -- --shop my-store.myshopify.com
+ *     → runVmScript installApp --shop my-store.myshopify.com
+ *
+ * Shares the node_modules volume + tarball-manifest extraFile with runVm /
+ * runVmAuth, and keys on a static warmupTag (rarely-run flow; bump on
+ * warmup-script or VM-runtime changes).
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { prepareOciArchive, envFileArgs } from '@essential-apps/shopify-test-core';
+
+const repoRoot = process.cwd();
+
+/** Resolve the VM image source the same way runVm.ts / runVmAuth.ts do. */
+async function imageSourceOptions(): Promise<Record<string, unknown>> {
+  const mode = process.env['TEST_ONLINE_VM_IMAGE_SOURCE'] ?? 'oci-archive';
+  if (mode === 'registry') return {};
+  const ref =
+    process.env['TEST_ONLINE_VM_IMAGE'] ?? 'essential-apps/shopify-test-vm:latest';
+  if (mode === 'oci-archive') {
+    const prep = await prepareOciArchive(ref);
+    if (prep.freshlySaved) {
+      console.error(
+        `[runVmScript] saved ${ref} → ${prep.archivePath} (${(prep.sizeBytes / 1024 / 1024).toFixed(1)} MB)`,
+      );
+    }
+    return { source: 'oci-archive', sourcePath: prep.archivePath };
+  }
+  if (mode === 'oci-layout') {
+    const sourcePath = process.env['TEST_ONLINE_VM_IMAGE_LAYOUT_PATH'];
+    if (!sourcePath) {
+      throw new Error(
+        `TEST_ONLINE_VM_IMAGE_SOURCE=oci-layout requires TEST_ONLINE_VM_IMAGE_LAYOUT_PATH`,
+      );
+    }
+    return { source: 'oci-layout', sourcePath };
+  }
+  throw new Error(
+    `TEST_ONLINE_VM_IMAGE_SOURCE=${mode} not recognised. Valid: oci-archive | oci-layout | registry`,
+  );
+}
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(repoRoot, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      `No package.json at ${pkgPath}. Run this from the consuming app's repo root.`,
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+  if (!pkg.name) throw new Error(`package.json at ${pkgPath} has no \`name\` field.`);
+  return pkg.name.replace(/^@[^/]+\//, '');
+}
+
+/** Single-quote-escape an arg for safe interpolation into `sh -c`. */
+function shq(arg: string): string {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
+async function main(): Promise<void> {
+  const scriptName = process.argv[2];
+  const scriptArgs = process.argv.slice(3);
+  if (!scriptName || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(scriptName)) {
+    console.error(
+      `Usage: runVmScript <script-name> [args…]\n` +
+        `  <script-name> must be a bare script name (e.g. installApp), no path.`,
+    );
+    process.exit(1);
+  }
+
+  const appName = readAppName();
+  const linuxModulesVolume =
+    process.env['TEST_LINUX_NODE_MODULES_VOLUME'] ??
+    resolve(homedir(), `.cache/${appName}-test/node_modules.img`);
+  mkdirSync(resolve(linuxModulesVolume, '..'), { recursive: true });
+  const tarballManifest = resolve(
+    repoRoot,
+    'vendor/essential-apps-shopify-test/.tarball-manifest',
+  );
+  const tarballManifestExists = existsSync(tarballManifest);
+  const ref =
+    process.env['TEST_ONLINE_VM_IMAGE'] ?? 'essential-apps/shopify-test-vm:latest';
+  const platform = process.env['TEST_ONLINE_VM_PLATFORM'] ?? 'linux/arm64';
+
+  console.error(`[runVmScript] baking image…`);
+  const tBake = performance.now();
+  const { Image } = await import('@supermachine/core');
+  const imageOpts = await imageSourceOptions();
+  const image = await Image.build({
+    ref,
+    memoryMib: Number(process.env['TEST_ONLINE_VM_MEMORY_MIB'] ?? 8192),
+    vcpus: Number(process.env['TEST_ONLINE_VM_VCPUS'] ?? 4),
+    cmd: ['sleep', 'infinity'],
+    env: { SKIP_OFFLINE_HOST_HIJACK: '1' },
+    platform,
+    mounts: [{ hostPath: repoRoot, guestTag: 'workspace', guestPath: '/workspace' }],
+    volumes: [
+      {
+        hostPath: linuxModulesVolume,
+        guestPath: '/workspace/node_modules',
+        sizeMib: 4096,
+      },
+    ],
+    extraFiles: tarballManifestExists
+      ? [{ hostPath: tarballManifest, guestPath: '/etc/.shopify-test-tarball-manifest' }]
+      : [],
+    // Static tag (rarely-run setup flow). Bump on warmup-script / VM-runtime
+    // changes. Kept distinct from runVm's online-v15 (manifest-keyed) and
+    // runVmAuth's online-v4 so a tweak here can't disturb those snapshots.
+    warmupTag: 'online-script-v1',
+    // @ts-expect-error — @supermachine/core's BuildOptions type doesn't declare
+    // `warmup`, but the runtime accepts it (matches runVm/runVmAuth).
+    warmup: async (vm: {
+      exec: (opts: { argv: string[]; timeoutMs?: number }) => Promise<{
+        exitCode: number;
+        stdout: Buffer;
+        stderr: Buffer;
+      }>;
+    }) => {
+      const r = await vm.exec({
+        argv: [
+          'sh',
+          '-c',
+          `
+          set -e
+          NM_FS=\$(stat -f -c %T /workspace/node_modules 2>/dev/null || stat --file-system --format=%T /workspace/node_modules)
+          echo "[warmup] /workspace/node_modules FS type: \$NM_FS"
+          if [ "\$NM_FS" = "virtiofs" ] || [ "\$NM_FS" = "fuse.virtiofs" ]; then
+            echo "FATAL: /workspace/node_modules is \$NM_FS — auto-mount broken"
+            exit 1
+          fi
+          cd /workspace
+          rm -rf node_modules/* node_modules/.[!.]* 2>/dev/null || true
+          if ! npm install --legacy-peer-deps --engine-strict=false > /tmp/npm-install.log 2>&1; then
+            echo "--- npm install FAILED - last 40 lines ---"
+            tail -40 /tmp/npm-install.log
+            exit 1
+          fi
+          tail -10 /tmp/npm-install.log
+          if ! grep -q "^127.0.0.1.*localhost" /etc/hosts; then
+            echo "127.0.0.1 localhost" >> /etc/hosts
+            echo "::1 localhost" >> /etc/hosts
+          fi
+        `,
+        ],
+        timeoutMs: 15 * 60 * 1000,
+      });
+      if (r.exitCode !== 0) {
+        console.error('[runVmScript.warmup] failed:', r.stdout.toString(), r.stderr.toString());
+        throw new Error(`warmup failed (exit ${r.exitCode})`);
+      }
+    },
+    ...imageOpts,
+  });
+  console.error(
+    `[runVmScript] bake: ${((performance.now() - tBake) / 1000).toFixed(1)} s`,
+  );
+
+  const pool = await image.pool({ min: 1, max: 1, restoreOnRelease: false });
+  const vm = await pool.acquire();
+
+  let cleanupPromise: Promise<void> | null = null;
+  const cleanup = (): Promise<void> => {
+    if (cleanupPromise) return cleanupPromise;
+    cleanupPromise = (async () => {
+      await vm.release().catch(() => undefined);
+      await pool.shutdown().catch(() => undefined);
+    })();
+    return cleanupPromise;
+  };
+  let signalCount = 0;
+  const onSignal = (sig: NodeJS.Signals): void => {
+    signalCount += 1;
+    if (signalCount >= 2) process.exit(130);
+    console.error(`\n[runVmScript] received ${sig}, cleaning up…`);
+    cleanup()
+      .catch(() => undefined)
+      .finally(() => process.exit(130));
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  try {
+    // Post-restore sanity + start Xvfb :99 so headed patchright (the
+    // CF-passing config) has a display. Browser launches in the guest
+    // still go through assertInVm(), which passes because we set
+    // TEST_IN_CONTAINER=true on the spawned process below.
+    const setup = await vm.exec({
+      argv: [
+        'sh',
+        '-c',
+        `
+        mountpoint -q /workspace/node_modules || { echo "FATAL: /workspace/node_modules not mounted"; exit 1; }
+        BASE=/workspace/node_modules/@essential-apps/shopify-test-runner/dist
+        if [ -f "\$BASE/scripts/${scriptName}.js" ]; then S="\$BASE/scripts/${scriptName}.js"; else S="\$BASE/probes/${scriptName}.js"; fi
+        ls "\$S" >/dev/null \
+          || { echo "FATAL: ${scriptName}.js missing in volume (checked scripts/ and probes/) — snapshot/volume out of sync"; exit 1; }
+        pkill -x Xvfb 2>/dev/null || true
+        rm -f /tmp/.X11-unix/X99 /tmp/.X99-lock
+        sleep 0.3
+        nohup Xvfb :99 -screen 0 1600x1000x24 -nolisten tcp -ac >/var/log/xvfb.log 2>&1 &
+        for _ in $(seq 1 50); do [ -e /tmp/.X11-unix/X99 ] && break; sleep 0.1; done
+        [ -e /tmp/.X11-unix/X99 ] || { echo "FATAL: Xvfb :99 did not start"; cat /var/log/xvfb.log; exit 1; }
+        echo "[runVmScript] Xvfb :99 up."
+      `,
+      ],
+      timeoutMs: 30_000,
+    });
+    if (setup.exitCode !== 0) {
+      console.error(`[runVmScript] setup failed:\n${setup.stdout.toString()}${setup.stderr.toString()}`);
+      throw new Error('VM setup failed');
+    }
+
+    const argsStr = scriptArgs.map(shq).join(' ');
+    console.error(`[runVmScript] running ${scriptName} ${argsStr} in the VM…`);
+    const child = await vm.spawn({
+      argv: [
+        'sh',
+        '-c',
+        `cd /workspace && BASE=node_modules/@essential-apps/shopify-test-runner/dist; if [ -f "\$BASE/scripts/${scriptName}.js" ]; then S="\$BASE/scripts/${scriptName}.js"; else S="\$BASE/probes/${scriptName}.js"; fi; DISPLAY=:99 TEST_IN_CONTAINER=true node ${envFileArgs(repoRoot)} "\$S" ${argsStr}`,
+      ],
+      env: { DISPLAY: ':99', TEST_IN_CONTAINER: 'true' },
+    });
+
+    const childAny = child as unknown as {
+      readStdout?: () => Promise<Buffer>;
+      readStderr?: () => Promise<Buffer>;
+      wait?: () => Promise<{ exitCode: number }>;
+    };
+    const streamGuest = async (
+      reader: (() => Promise<Buffer>) | undefined,
+      out: NodeJS.WriteStream,
+    ): Promise<void> => {
+      if (!reader) return;
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const chunk = await reader().catch(() => null);
+        if (!chunk || chunk.length === 0) return;
+        out.write(chunk);
+      }
+    };
+    void streamGuest(childAny.readStdout, process.stdout);
+    void streamGuest(childAny.readStderr, process.stderr);
+
+    const result = await (childAny.wait?.() ?? Promise.resolve({ exitCode: 0 }));
+    await cleanup();
+    if (result.exitCode === 0) {
+      console.error(`[runVmScript] ✓ ${scriptName} completed.`);
+    } else {
+      console.error(`[runVmScript] ${scriptName} exited with code ${result.exitCode}`);
+    }
+    process.exit(result.exitCode);
+  } catch (err) {
+    console.error('[runVmScript] fatal:', (err as Error).message);
+    await cleanup();
+    process.exit(1);
+  }
+}
+
+main().catch(async (err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/scripts/setupTestDb.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * One-time / on-demand local Postgres prep for tests.
+ *
+ * - Smoke-tests that local Postgres is reachable
+ * - Runs `prisma migrate deploy` against an ephemeral DB and drops it
+ *
+ * The actual test runner (runTests.ts) creates a fresh UUID-named DB
+ * per run and applies migrations there. This script is just for
+ * diagnostics — confirms the toolchain works before you try to run
+ * tests.
+ */
+import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadEnv, printEnvSummary } from '@essential-apps/shopify-test-core';
+
+const PG_HOST = 'localhost';
+const PG_PORT = '5432';
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(process.cwd(), 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      `No package.json at ${pkgPath}. Run this from the consuming app's repo root.`,
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+  if (!pkg.name) throw new Error(`package.json at ${pkgPath} has no \`name\` field.`);
+  return pkg.name.replace(/^@[^/]+\//, '');
+}
+
+async function main(): Promise<void> {
+  const env = loadEnv();
+  printEnvSummary(env);
+
+  console.log('[setup-db] checking local Postgres reachability…');
+  execSync(`pg_isready -h ${PG_HOST} -p ${PG_PORT}`, { stdio: 'inherit' });
+
+  const appName = readAppName();
+  const dbPrefix = (process.env['TEST_ONLINE_DB_NAME_PREFIX'] ?? `${appName}_online`)
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_');
+  const dbName = `${dbPrefix}_smoke_${randomUUID().replace(/-/g, '_')}`;
+  const url = `postgresql://${PG_HOST}:${PG_PORT}/${dbName}`;
+  console.log(`[setup-db] creating throwaway DB: ${dbName}`);
+  execSync(`createdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`, { stdio: 'inherit' });
+
+  try {
+    console.log('[setup-db] running prisma migrate deploy…');
+    execSync('npx prisma migrate deploy', {
+      stdio: 'inherit',
+      env: { ...process.env, DATABASE_URL: url, DIRECT_URL: url, NODE_ENV: 'test' },
+    });
+    console.log('');
+    console.log('✓ Local Postgres + migrations work. You can now run: npm run test:online');
+  } finally {
+    console.log(`[setup-db] dropping throwaway DB: ${dbName}`);
+    execSync(`dropdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`, { stdio: 'inherit' });
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/scripts/verifyContracts.ts

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * verifyContracts — the offline-side conformance check.
+ *
+ * Reads every vendored contract under `tests/test-offline/contracts/<api>/`,
+ * re-runs its operation against an in-process offline mock with the
+ * vendored `variables`, and asserts the response equals the
+ * vendored `response`. Any drift fails the check.
+ *
+ * See `docs/CONTRACTS.md` for the full architecture. This is one
+ * of three checks that together ensure the offline test suite
+ * cannot drift from real Shopify undetected:
+ *
+ *   1. check-operation-coverage  — static: every prod root field has a resolver
+ *   2. verify-contracts          — this script: mock matches vendored contracts
+ *   3. verify-contracts-from-live — (conformance suite) live matches vendored contracts
+ *
+ * Drift modes this catches:
+ *   - A resolver was removed or its return shape changed.
+ *   - A new field was added to a contract without the matching mock.
+ *   - The mock's seeded ShopState shape diverged from the contract's
+ *     expectation.
+ *
+ * What it doesn't catch (by design — owned by other checks):
+ *   - The contract itself is wrong vs live Shopify. That's
+ *     `verify-contracts-from-live`'s job.
+ *   - Production code calls a field with no contract. That's
+ *     `check-operation-coverage`.
+ *
+ * Run: `npm run test:online:verify-contracts`.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import {
+  createAdminApi,
+  createStorefrontApi,
+} from '@essential-apps/shopify-test-shopify-api';
+import { ShopState } from '@essential-apps/shopify-test-storefront';
+import { normaliseResponse } from '../contracts/normalize.js';
+
+type ApiType = 'admin' | 'storefront';
+
+interface Args {
+  api: ApiType;
+  contractsDir: string;
+  cwd: string;
+}
+
+function parseArgs(): Args {
+  const argv = process.argv.slice(2);
+  const out: Args = {
+    api: 'admin',
+    contractsDir: '',
+    cwd: process.cwd(),
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? '';
+    if (a === '--api' && i + 1 < argv.length) {
+      const next = argv[++i] ?? '';
+      if (next !== 'admin' && next !== 'storefront') {
+        console.error(`--api must be "admin" or "storefront"`);
+        process.exit(2);
+      }
+      out.api = next;
+    } else if (a === '--dir' && i + 1 < argv.length) {
+      out.contractsDir = argv[++i] ?? '';
+    }
+  }
+  if (!out.contractsDir) {
+    out.contractsDir = resolve(out.cwd, 'tests/test-offline/contracts', out.api);
+  } else {
+    out.contractsDir = resolve(out.cwd, out.contractsDir);
+  }
+  return out;
+}
+
+/**
+ * Offline-only executor — POSTs the operation to an in-process
+ * Hono mock for the consuming app's API surface (admin or
+ * storefront GraphQL). No live target by design: contract
+ * verification at the consuming-app layer answers "does the mock
+ * satisfy my operations?". The separate question — "does the mock
+ * match real Shopify?" — is owned by `@essential-apps/shopify-test-conformance`
+ * and runs against canonical platform primitives, not per-app
+ * operation sets. Mixing the two layers (the original `--target live`
+ * here) conflated app-level coverage with platform parity. Kept
+ * the layering clean by removing it.
+ */
+type Executor = (
+  source: string,
+  variables: Record<string, unknown>,
+) => Promise<unknown>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono types are loose
+function buildOfflineExecutor(api: ApiType, state: ShopState): Executor {
+  const app =
+    api === 'admin' ? createAdminApi({ state }) : createStorefrontApi({ state });
+  const endpoint =
+    api === 'admin'
+      ? '/admin/api/2025-07/graphql.json'
+      : '/api/2025-07/graphql.json';
+  return async (source, variables) => {
+    const resp = await app.request(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Shopify-Access-Token': 'mock-access-token',
+      },
+      body: JSON.stringify({ query: source, variables }),
+    });
+    return resp.json();
+  };
+}
+
+interface Contract {
+  operationName: string;
+  source: string;
+  variables: Record<string, unknown>;
+  response: unknown;
+  capturedFrom: 'offline' | 'live';
+  capturedAt: string;
+  warning?: string;
+}
+
+/**
+ * Same deterministic ShopState seed `captureContracts` uses. The
+ * contracts were captured against this state; verification must
+ * replay against the identical state for results to match.
+ *
+ * Keep this in lockstep with `captureContracts.ts`'s
+ * `buildSeededState`. If you change one, change the other.
+ */
+function buildSeededState(): ShopState {
+  const state = new ShopState({
+    shop: {
+      domain: 'test-shop.myshopify.com',
+      permanent_domain: 'test-shop.myshopify.com',
+    },
+  });
+  state.addProduct({
+    id: 900_000_001,
+    handle: 'sample-product',
+    title: 'Sample Product',
+    description: 'Used by contract capture as a deterministic fixture.',
+    price: 1000,
+    vendor: 'Sample Vendor',
+    type: 'Sample',
+    variants: [
+      {
+        id: 900_010_001,
+        title: 'Default Title',
+        price: 1000,
+        available: true,
+        sku: 'SAMPLE-1',
+        inventory_quantity: 100,
+        selected_options: ['Default Title'],
+      },
+    ],
+    tags: [],
+  });
+  state.addCollection({
+    id: 900_020_001,
+    handle: 'sample-collection',
+    title: 'Sample Collection',
+    productHandles: ['sample-product'],
+  });
+  return state;
+}
+
+/**
+ * Deep-equal that returns a human-readable diff path on the first
+ * mismatch. Not a perfect serialiser — sufficient for asserting
+ * captured JSON equals re-run JSON.
+ */
+function diff(
+  expected: unknown,
+  actual: unknown,
+  path = '$',
+): string | null {
+  if (expected === actual) return null;
+  if (
+    typeof expected !== typeof actual ||
+    expected === null ||
+    actual === null
+  ) {
+    return `${path}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+  }
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) return `${path}: expected array, got object`;
+    if (expected.length !== actual.length) {
+      return `${path}: expected length ${expected.length}, got ${actual.length}`;
+    }
+    for (let i = 0; i < expected.length; i++) {
+      const d = diff(expected[i], actual[i], `${path}[${i}]`);
+      if (d) return d;
+    }
+    return null;
+  }
+  if (typeof expected === 'object') {
+    const e = expected as Record<string, unknown>;
+    const a = actual as Record<string, unknown>;
+    const allKeys = new Set([...Object.keys(e), ...Object.keys(a)]);
+    for (const k of allKeys) {
+      if (!(k in e)) return `${path}.${k}: unexpected key`;
+      if (!(k in a)) return `${path}.${k}: missing key`;
+      const d = diff(e[k], a[k], `${path}.${k}`);
+      if (d) return d;
+    }
+    return null;
+  }
+  return `${path}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs();
+
+  let entries: string[];
+  try {
+    entries = readdirSync(args.contractsDir);
+  } catch {
+    console.error(
+      `[verify-contracts] no contracts directory at ${args.contractsDir}. ` +
+        `Run \`npm run test:online:capture-contracts\` first.`,
+    );
+    process.exit(2);
+  }
+  const contractFiles = entries.filter((f) => f.endsWith('.json'));
+  if (contractFiles.length === 0) {
+    console.error(`[verify-contracts] no contracts found in ${args.contractsDir}`);
+    process.exit(2);
+  }
+
+  const state = buildSeededState();
+  const executor: Executor =
+    buildOfflineExecutor(args.api, state);
+
+  let pass = 0;
+  let drift = 0;
+  let skipped = 0;
+  const failures: { contract: string; diff: string }[] = [];
+
+  for (const f of contractFiles) {
+    const path = resolve(args.contractsDir, f);
+    let st;
+    try {
+      st = statSync(path);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    const contract = JSON.parse(readFileSync(path, 'utf8')) as Contract;
+    // Contracts captured with a warning never executed cleanly;
+    // skip them in verify (they need fixtures.json before they can
+    // be verified).
+    if (contract.warning) {
+      skipped++;
+      continue;
+    }
+    let actual: unknown;
+    try {
+      actual = await executor(contract.source, contract.variables);
+    } catch (err) {
+      drift++;
+      failures.push({
+        contract: f,
+        diff: `executor threw: ${(err as Error).message}`,
+      });
+      continue;
+    }
+    // Normalise both sides before diffing. Volatile values
+    // (Shopify GIDs, timestamps, CDN URLs, cursors) reduce to
+    // stable tokens so live verification doesn't drown in
+    // expected-vs-real-ID noise. Offline verification is also
+    // safe — deterministic values still normalise to the same
+    // tokens on both sides. Genuine structural drift survives.
+    const expectedNorm = normaliseResponse(contract.response);
+    const actualNorm = normaliseResponse(actual);
+    const d = diff(expectedNorm, actualNorm);
+    if (d === null) {
+      pass++;
+    } else {
+      drift++;
+      failures.push({ contract: f, diff: d });
+    }
+  }
+
+  console.log(
+    `[verify-contracts] api=${args.api}: ${pass} pass, ${drift} drift, ${skipped} skipped (fixtures needed)`,
+  );
+  if (failures.length > 0) {
+    console.log('');
+    console.log('[verify-contracts] drift:');
+    for (const f of failures) {
+      console.log(
+        `  ${relative(args.cwd, resolve(args.contractsDir, f.contract))}`,
+      );
+      console.log(`    ${f.diff}`);
+    }
+    console.log('');
+    console.log(
+      'If the mock is correct and the contract is stale, regenerate with `npm run test:online:capture-contracts`.',
+    );
+  }
+  process.exit(drift === 0 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(2);
+});