@essential-apps/shopify-test-runner 1.0.12 → 1.0.13

package/dist/scripts/verifyRestContracts.js

@@ -20,8 +20,8 @@
  * GraphQL verifier uses. Offline-offline matches byte-for-byte
  * anyway; the normaliser only matters for live-vs-contract.
  */
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { resolve, relative } from 'node:path';
+import { resolve } from 'node:path';
+import { resolveRestContracts, } from '@essential-apps/shopify-test-contracts/operation-contract';
 import { createAdminApi, } from '@essential-apps/shopify-test-shopify-api';
 import { ShopState } from '@essential-apps/shopify-test-storefront';
 import { normaliseResponse } from '../contracts/normalize.js';
@@ -142,38 +142,25 @@ function diff(expected, actual, path = '$') {
 }
 async function main() {
     const args = parseArgs();
-    let entries;
-    try {
-        entries = readdirSync(args.contractsDir);
-    }
-    catch {
-        console.error(`[verify-rest] no contracts directory at ${args.contractsDir}. ` +
-            `Run \`npm run test:online:capture-rest-contracts\` first.`);
-        process.exit(2);
-    }
-    const contractFiles = entries.filter((f) => f.endsWith('.json'));
-    if (contractFiles.length === 0) {
-        console.error(`[verify-rest] no contracts found in ${args.contractsDir}`);
+    // Merged view: shared package REST goldens overlaid by the app's
+    // local admin-rest dir (app wins by operation name).
+    const resolved = resolveRestContracts({ appDir: args.contractsDir });
+    if (resolved.length === 0) {
+        console.error(`[verify-rest] no REST contracts (shared package + ${args.contractsDir}).`);
         process.exit(2);
     }
+    const sharedCount = resolved.filter((r) => r.origin === 'shared').length;
+    console.log(`[verify-rest] ${resolved.length} operations ` +
+        `(${sharedCount} shared, ${resolved.length - sharedCount} app-local override)`);
     const state = buildSeededState();
     const executor = buildOfflineExecutor(state);
     let pass = 0;
     let drift = 0;
     let skipped = 0;
     const failures = [];
-    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'));
+    for (const entry of resolved) {
+        const contract = entry.contract;
+        const label = `${entry.operationName} [${entry.origin}]`;
         if (contract.warning) {
             skipped++;
             continue;
@@ -184,14 +171,14 @@ async function main() {
         }
         catch (err) {
             drift++;
-            failures.push({ contract: f, diff: `executor threw: ${err.message}` });
+            failures.push({ contract: label, diff: `executor threw: ${err.message}` });
             continue;
         }
         // Status-code mismatch is a hard diff — surface it directly.
         if (actual.status !== contract.response.status) {
             drift++;
             failures.push({
-                contract: f,
+                contract: label,
                 diff: `$.status: expected ${contract.response.status}, got ${actual.status}`,
             });
             continue;
@@ -206,7 +193,7 @@ async function main() {
         }
         else {
             drift++;
-            failures.push({ contract: f, diff: d });
+            failures.push({ contract: label, diff: d });
         }
     }
     console.log(`[verify-rest]: ${pass} pass, ${drift} drift, ${skipped} skipped`);
@@ -214,7 +201,7 @@ async function main() {
         console.log('');
         console.log('[verify-rest] drift:');
         for (const f of failures) {
-            console.log(`  ${relative(args.cwd, resolve(args.contractsDir, f.contract))}`);
+            console.log(`  ${f.contract}`);
             console.log(`    ${f.diff}`);
         }
         console.log('');

package/dist/scripts/verifyRestContracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"verifyRestContracts.js","sourceRoot":"","sources":["../../src/scripts/verifyRestContracts.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EACL,cAAc,GACf,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAuB9D,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAEpC,SAAS,SAAS;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,GAAG,GAAS;QAChB,YAAY,EAAE,EAAE;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;KACnB,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACzC,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QACtB,GAAG,CAAC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,yCAAyC,CAAC,CAAC;IACjF,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,QAAgB,EAAE,MAA8B;IAChE,OAAO,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,yBAAyB,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,KAA8B;IAC/D,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9C,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AAChD,CAAC;AAMD,uFAAuF;AACvF,SAAS,oBAAoB,CAAC,KAAgB;IAC5C,MAAM,GAAG,GAAG,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;YACrC,OAAO,EAAE,iBAAiB;YAC1B,GAAG,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC;SAC/B,CAAC,CAAC;QACH,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtD,MAAM,IAAI,GAAgB;YACxB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,wBAAwB,EAAE,mBAAmB;aAC9C;SACF,CAAC;QACF,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,IAAI,GAAa,MAAO,GAAG,CAAC,OAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACnE,IAAI,IAAI,GAAY,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,mBAAmB;QACrB,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,uCAAuC;AACvC,4DAA4D;AAC5D,4DAA4D;AAE5D;;;;GAIG;AACH,SAAS,IAAI,CACX,QAAiB,EACjB,MAAe,EACf,IAAI,GAAG,GAAG;IAEV,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrC,IACE,OAAO,QAAQ,KAAK,OAAO,MAAM;QACjC,QAAQ,KAAK,IAAI;QACjB,MAAM,KAAK,IAAI,EACf,CAAC;QACD,OAAO,GAAG,IAAI,cAAc,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;IACxF,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,GAAG,IAAI,8BAA8B,CAAC;QACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YACtC,OAAO,GAAG,IAAI,qBAAqB,QAAQ,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7E,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;YACxD,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,QAAmC,CAAC;QAC9C,MAAM,CAAC,GAAG,MAAiC,CAAC;QAC5C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAAE,OAAO,GAAG,IAAI,IAAI,CAAC,kBAAkB,CAAC;YACrD,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAAE,OAAO,GAAG,IAAI,IAAI,CAAC,eAAe,CAAC;YAClD,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3C,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,IAAI,cAAc,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;IACzB,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CACX,2CAA2C,IAAI,CAAC,YAAY,IAAI;YAC9D,2DAA2D,CAC9D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,uCAAuC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,QAAQ,GACZ,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAE9B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,QAAQ,GAAyC,EAAE,CAAC;IAE1D,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QAC3C,IAAI,EAAE,CAAC;QACP,IAAI,CAAC;YACH,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;YAAE,SAAS;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAa,CAAC;QACpE,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,OAAO,EAAE,CAAC;YACV,SAAS;QACX,CAAC;QACD,IAAI,MAAyC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,KAAK,EAAE,CAAC;YACR,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAoB,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAClF,SAAS;QACX,CAAC;QACD,6DAA6D;QAC7D,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC/C,KAAK,EAAE,CAAC;YACR,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,CAAC;gBACX,IAAI,EAAE,sBAAsB,QAAQ,CAAC,QAAQ,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE;aAC7E,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,4DAA4D;QAC5D,+CAA+C;QAC/C,MAAM,YAAY,GAAG,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACf,IAAI,EAAE,CAAC;QACT,CAAC;aAAM,CAAC;YACN,KAAK,EAAE,CAAC;YACR,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CACT,kBAAkB,IAAI,UAAU,KAAK,WAAW,OAAO,UAAU,CAClE,CAAC;IACF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;QACpC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,OAAO,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;YAC/E,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CACT,iHAAiH,CAClH,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE;YACJ,MAAM,EAAE,yBAAyB;YACjC,gBAAgB,EAAE,yBAAyB;SAC5C;KACF,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"verifyRestContracts.js","sourceRoot":"","sources":["../../src/scripts/verifyRestContracts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@essential-apps/shopify-test-runner",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Orchestration scripts (container, auth capture, install) and Playwright config preset for Essential Apps' Shopify test suites. Internal use only.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,14 +21,14 @@
     "./contracts/normalize-html": {
       "types": "./dist/contracts/normalizeHtml.d.ts",
       "import": "./dist/contracts/normalizeHtml.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "shopify-test-run-online": "./dist/scripts/runVm.js",
     "shopify-test-run-offline": "./dist/scripts/runOffline.js",
     "shopify-test-run-tests": "./dist/scripts/runTests.js",
     "shopify-test-capture-online-auth": "./dist/scripts/runVmAuth.js",
-    "shopify-test-capture-online-auth-libkrun": "./dist/scripts/runDockerAuth.js",
     "shopify-test-capture-auth": "./dist/scripts/captureAuth.js",
     "shopify-test-deploy-app-version": "./dist/scripts/deployAppVersion.js",
     "shopify-test-install-app": "./dist/scripts/installApp.js",
@@ -40,9 +40,10 @@
     "shopify-test-dev-backend": "./dist/scripts/devOnlineBackend.js",
     "shopify-test-run-offline-full-tests": "./dist/scripts/runOfflineFullTests.js",
     "shopify-test-probe": "./dist/probes/runProbe.js",
-    "shopify-test-build-image": "./dist/scripts/buildDockerImage.js",
+    "shopify-test-build-image": "./dist/scripts/buildImage.js",
     "shopify-test-check-operation-coverage": "./dist/scripts/checkOperationCoverage.js",
     "shopify-test-capture-contracts": "./dist/scripts/captureContracts.js",
+    "shopify-test-capture-shared-contracts": "./dist/scripts/captureSharedContracts.js",
     "shopify-test-verify-contracts": "./dist/scripts/verifyContracts.js",
     "shopify-test-capture-rest-contracts": "./dist/scripts/captureRestContracts.js",
     "shopify-test-verify-rest-contracts": "./dist/scripts/verifyRestContracts.js"
@@ -57,11 +58,12 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@essential-apps/shopify-test-core": "^1.0.12",
-    "@essential-apps/shopify-test-mock-admin": "^1.0.12",
-    "@essential-apps/shopify-test-shopify-api": "^1.0.12",
-    "@essential-apps/shopify-test-storefront": "^1.0.12",
-    "@essential-apps/shopify-test-themes": "^1.0.12",
+    "@essential-apps/shopify-test-core": "^1.0.13",
+    "@essential-apps/shopify-test-contracts": "^1.0.13",
+    "@essential-apps/shopify-test-mock-admin": "^1.0.13",
+    "@essential-apps/shopify-test-shopify-api": "^1.0.13",
+    "@essential-apps/shopify-test-storefront": "^1.0.13",
+    "@essential-apps/shopify-test-themes": "^1.0.13",
     "@playwright/test": "^1.49.0",
     "@types/node": "^20.19.40",
     "@types/tar-stream": "^3.1.4",

package/src/lib/guestVnc.ts

@@ -0,0 +1,147 @@
+/**
+ * Expose a guest VM's Xvfb display over VNC to the host.
+ *
+ * Shared by the interactive VM flows that need a developer to *see*
+ * what a headed Chromium is doing inside the microVM:
+ *   - `runVmAuth.ts`         — one-time Shopify login capture.
+ *   - `runOffline.ts` (explore mode) — click through the offline mock
+ *     stack (admin app + storefront) by hand.
+ *
+ * The sequence (extracted so both flows share one implementation):
+ *   1. (Re)start Xvfb :99 with access control off, then x11vnc bound
+ *      to 0.0.0.0:5900 inside the guest.
+ *   2. Forward host 127.0.0.1:5900 → guest :5900 via `vm.exposeTcp`.
+ *   3. On macOS, open Screen Sharing at vnc://localhost:5900 with the
+ *      password prefilled. Elsewhere, print connect instructions.
+ *
+ * Returns the TCP forwarder handle so the caller can keep it alive
+ * for the session and close it on teardown.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { platform as osPlatform } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+/** Minimal structural view of the VM handle this helper needs. */
+export interface VncCapableVm {
+  exec(opts: {
+    argv: string[];
+    timeoutMs?: number;
+  }): Promise<{ exitCode: number; stdout: Buffer; stderr: Buffer }>;
+  exposeTcp(hostPort: number, guestPort: number): Promise<unknown>;
+}
+
+export const DEFAULT_VNC_PORT = 5900;
+
+export interface ExposeGuestVncOptions {
+  /** VNC auth password. Default: TEST_ONLINE_VNC_PASSWORD ?? 'test'. */
+  vncPassword?: string;
+  /** Host+guest VNC port. Default: 5900. */
+  port?: number;
+  /** Xvfb virtual screen geometry. Default: '1600x1000x24'. */
+  screen?: string;
+  /** Log prefix, e.g. '[runOffline]'. Default: '[guestVnc]'. */
+  logPrefix?: string;
+}
+
+/**
+ * Start x11vnc in the guest, bridge it to the host, and (on macOS)
+ * open Screen Sharing. Throws if Xvfb or x11vnc fail to come up.
+ *
+ * @returns the forwarder handle (keep it referenced; close on exit).
+ */
+export async function exposeGuestVnc(
+  vm: VncCapableVm,
+  opts: ExposeGuestVncOptions = {},
+): Promise<unknown> {
+  const vncPassword =
+    opts.vncPassword ?? process.env['TEST_ONLINE_VNC_PASSWORD'] ?? 'test';
+  const port = opts.port ?? DEFAULT_VNC_PORT;
+  const screen = opts.screen ?? '1600x1000x24';
+  const log = opts.logPrefix ?? '[guestVnc]';
+
+  // 1) (Re)start Xvfb :99 + x11vnc inside the guest. We restart Xvfb
+  //    with -ac (access control off) so x11vnc — launched from this
+  //    fresh exec shell, without the entrypoint's Xauthority — can
+  //    attach without a cookie. Background via shell `&` + nohup so
+  //    both survive this exec returning.
+  console.error(`${log} starting x11vnc on guest :${port}…`);
+  const vncStart = await vm.exec({
+    argv: [
+      'bash',
+      '-c',
+      `
+      # No set -e: pkill/rm of absent things exit nonzero legitimately.
+      # Match Xvfb by exact name (-x), NOT -f: -f matches this script's
+      # own argv (the heredoc contains "Xvfb") and would kill our shell.
+      echo "[xvfb] restarting Xvfb :99 ${screen} -ac …"
+      pkill -x Xvfb 2>/dev/null || true
+      rm -f /tmp/.X11-unix/X99 /tmp/.X99-lock
+      sleep 0.3
+      nohup Xvfb :99 -screen 0 ${screen} -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
+      if [ ! -e /tmp/.X11-unix/X99 ]; then
+        echo "[xvfb] FAILED to bind /tmp/.X11-unix/X99 within 5s"
+        cat /var/log/xvfb.log
+        exit 1
+      fi
+      echo "[xvfb] up."
+
+      mkdir -p /root/.vnc
+      x11vnc -storepasswd "${vncPassword}" /root/.vnc/passwd >/dev/null 2>&1
+      echo "[x11vnc] starting on :${port}…"
+      nohup x11vnc -display :99 -forever -shared \
+        -rfbauth /root/.vnc/passwd -rfbport ${port} -quiet \
+        >/var/log/x11vnc.log 2>&1 &
+      echo "[x11vnc] pid $!"
+      # Confirm the listener bound. netstat (net-tools) is in the image;
+      # bash /dev/tcp is unreliable on jammy (device sometimes disabled).
+      for _ in $(seq 1 30); do
+        if netstat -ltn 2>/dev/null | grep -q ":${port} "; then
+          exit 0
+        fi
+        sleep 0.1
+      done
+      echo "x11vnc didn't bind :${port} within 3s"
+      netstat -ltn 2>&1 || echo "(netstat unavailable)"
+      cat /var/log/x11vnc.log
+      exit 1
+    `,
+    ],
+    timeoutMs: 15_000,
+  });
+  if (vncStart.exitCode !== 0) {
+    console.error(
+      `${log} x11vnc failed:`,
+      vncStart.stdout.toString(),
+      vncStart.stderr.toString(),
+    );
+    throw new Error('x11vnc startup failed');
+  }
+
+  // 2) Bridge host 127.0.0.1:port → guest :port.
+  const forwarder = await vm.exposeTcp(port, port);
+  console.error(`${log} forwarding host 127.0.0.1:${port} → guest :${port}`);
+
+  // 3) Open a viewer (macOS Screen Sharing), password prefilled.
+  if (osPlatform() === 'darwin') {
+    // Tiny delay so the accept loop is warm before the client dials,
+    // else Screen Sharing intermittently shows "connection refused".
+    await sleep(500);
+    const vncUrl = `vnc://:${encodeURIComponent(vncPassword)}@localhost:${port}`;
+    console.error(
+      `${log} opening macOS Screen Sharing → vnc://localhost:${port} (password prefilled)`,
+    );
+    console.error(`${log} (if nothing opens: open '${vncUrl}')`);
+    nodeSpawn('open', [vncUrl], { stdio: 'ignore', detached: true }).unref();
+  } else {
+    console.error(
+      `${log} connect any VNC viewer to localhost:${port} (password: ${vncPassword}).`,
+    );
+  }
+
+  return forwarder;
+}

package/src/scripts/{buildDockerImage.ts → buildImage.ts}

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 /**
- * Build the canonical `shopify-test` image from the Dockerfile
- * bundled in this package. Run from the shopify-test workspace
- * root:
+ * Build the canonical `shopify-test` VM image via Apple's `container
+ * build` (NOT docker — we don't use docker for any test path). The
+ * image spec is the bundled `docker/Dockerfile`; Dockerfile syntax is
+ * what `container build` consumes, and the directory name is
+ * historical. supermachine restores microVMs from the built image.
  *
- *   npm run docker:build
+ * Run directly:
  *
- * Or directly:
+ *   node --import tsx packages/runner/src/scripts/buildImage.ts
  *
- *   node --import tsx packages/runner/src/scripts/buildDockerImage.ts
+ * or via the exposed bin `shopify-test-build-image`.
  *
  * The image is amd64-only (Rosetta on Apple Silicon) — see
  * docker/README.md for why.
@@ -22,7 +24,7 @@ import { fileURLToPath } from 'node:url';
 // inspecting `container images` sees the same name they `npm install`.
 const DEFAULT_TAG = 'essential-apps/shopify-test:latest';
 
-function dockerContextDir(): string {
+function imageContextDir(): string {
   // This file lives at packages/runner/src/scripts/ (or dist/scripts/
   // after build). Walk up + sideways to docker/.
   const here = dirname(fileURLToPath(import.meta.url));
@@ -42,10 +44,10 @@ function dockerContextDir(): string {
 
 async function main(): Promise<void> {
   const tag = process.env['SHOPIFY_TEST_IMAGE_TAG'] ?? DEFAULT_TAG;
-  const context = dockerContextDir();
+  const context = imageContextDir();
 
   console.log('────────────────────────────────────────────────────────────');
-  console.log(' shopify-test docker image build');
+  console.log(' shopify-test VM image build (Apple `container build`)');
   console.log('────────────────────────────────────────────────────────────');
   console.log(`  Tag      : ${tag}`);
   console.log(`  Context  : ${context}`);

package/src/scripts/captureSharedContracts.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * Regenerate the SHARED contract goldens in
+ * `@essential-apps/shopify-test-contracts/fixtures` from the in-process
+ * offline mock — the "replayable-variable capture" generator.
+ *
+ * Why this exists (the design the centralization landed on):
+ *   A verify golden must be *mock-replayable* — `verify-contracts`
+ *   replays its `source` + `variables` against the offline mock and
+ *   asserts the response matches. A conformance capture (scrubbed LIVE
+ *   variables like `ownerId: <NUMERIC_ID>`, a richer field selection)
+ *   is NOT replayable: the mock can't resolve the placeholders. So the
+ *   two are different artifacts.
+ *
+ *   The clean split:
+ *     - The verify golden is captured FROM THE MOCK with deterministic
+ *       seed variables — replayable by construction. That's this script.
+ *     - `@essential-apps/shopify-test-conformance` separately CERTIFIES
+ *       the mock matches live Shopify (schema SDL + shape diffs). A
+ *       golden that's mock-replayable AND mock-certified-vs-live is
+ *       trustworthy end to end.
+ *
+ * This script keeps each golden's `operationName` / `source` /
+ * `variables` (so the *request* contract is stable) and refreshes only
+ * the `response` to the current mock output. Idempotent: unchanged
+ * responses aren't rewritten.
+ *
+ *   node --import tsx packages/runner/src/scripts/captureSharedContracts.ts
+ *   # or the bin: shopify-test-capture-shared-contracts
+ */
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  createAdminApi,
+  createStorefrontApi,
+} from '@essential-apps/shopify-test-shopify-api';
+import { ShopState } from '@essential-apps/shopify-test-storefront';
+import {
+  fixturesDir,
+  type OperationContract,
+  type RestContract,
+} from '@essential-apps/shopify-test-contracts/operation-contract';
+import { normaliseResponse } from '../contracts/normalize.js';
+
+const ADMIN_API_VERSION = '2025-07';
+
+/**
+ * Structural equality under the same normalisation `verify` applies
+ * (gids → `<ID>`, timestamps → `<DATETIME>`, …). We rewrite a golden
+ * only on genuine structural drift — not when a volatile-but-equivalent
+ * value (a fresh timestamp/id) changed — so the generator is idempotent.
+ */
+function sameShape(a: unknown, b: unknown): boolean {
+  return (
+    JSON.stringify(normaliseResponse(a)) === JSON.stringify(normaliseResponse(b))
+  );
+}
+
+/**
+ * Deterministic GraphQL seed. MUST stay in lockstep with
+ * `verifyContracts.ts` / `captureContracts.ts` `buildSeededState` — the
+ * goldens are replayed against this exact state at verify time.
+ */
+function buildGraphqlState(): 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;
+}
+
+/** REST seed — matches `verifyRestContracts.ts` `buildSeededState`. */
+function buildRestState(): ShopState {
+  return new ShopState({
+    shop: {
+      domain: 'test-shop.myshopify.com',
+      permanent_domain: 'test-shop.myshopify.com',
+    },
+  });
+}
+
+function fillPath(template: string, params: Record<string, string>): string {
+  return template.replace(/\{([^}]+)\}/g, (_, key: string) => {
+    if (!(key in params)) {
+      throw new Error(`path template references {${key}} but no value provided`);
+    }
+    return encodeURIComponent(params[key] ?? '');
+  });
+}
+function appendQuery(path: string, query?: Record<string, string>): string {
+  if (!query || Object.keys(query).length === 0) return path;
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) params.set(k, v);
+  return `${path}${path.includes('?') ? '&' : '?'}${params.toString()}`;
+}
+
+/** Flat `<op>.json` goldens only (skip manifests + store-keyed captures). */
+function flatGoldens(dir: string): string[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter(
+    (f) =>
+      f.endsWith('.json') &&
+      !f.endsWith('.manifest.json') &&
+      !f.slice(0, -'.json'.length).includes('.'),
+  );
+}
+
+async function regenGraphql(api: 'admin' | 'storefront'): Promise<number> {
+  const dir = resolve(fixturesDir(), api);
+  const state = buildGraphqlState();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono types are loose
+  const app: any =
+    api === 'admin' ? createAdminApi({ state }) : createStorefrontApi({ state });
+  const endpoint =
+    api === 'admin'
+      ? '/admin/api/2025-07/graphql.json'
+      : '/api/2025-07/graphql.json';
+  let changed = 0;
+  for (const f of flatGoldens(dir)) {
+    const p = resolve(dir, f);
+    const g = JSON.parse(readFileSync(p, 'utf8')) as OperationContract;
+    if (g.warning) continue;
+    const resp = await app.request(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Shopify-Access-Token': 'mock-access-token',
+      },
+      body: JSON.stringify({ query: g.source, variables: g.variables }),
+    });
+    const actual = await resp.json();
+    if (!sameShape(g.response, actual)) {
+      g.response = actual;
+      writeFileSync(p, JSON.stringify(g, null, 2) + '\n');
+      console.log(`  updated ${api}/${f}`);
+      changed++;
+    }
+  }
+  return changed;
+}
+
+async function regenRest(): Promise<number> {
+  const dir = resolve(fixturesDir(), 'admin-rest');
+  const state = buildRestState();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono types are loose
+  const app: any = createAdminApi({ state });
+  let changed = 0;
+  for (const f of flatGoldens(dir)) {
+    const p = resolve(dir, f);
+    const c = JSON.parse(readFileSync(p, 'utf8')) as RestContract;
+    if (c.warning) continue;
+    const finalPath = appendQuery(
+      fillPath(c.path, { version: ADMIN_API_VERSION, ...(c.pathParams ?? {}) }),
+      c.query,
+    );
+    const init: RequestInit = {
+      method: c.method,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Shopify-Access-Token': 'mock-access-token',
+      },
+    };
+    if (c.body !== undefined) init.body = JSON.stringify(c.body);
+    const resp: Response = await app.request(finalPath, init);
+    let body: unknown = null;
+    try {
+      body = await resp.json();
+    } catch {
+      /* empty / non-JSON */
+    }
+    const next = { status: resp.status, body };
+    if (c.response.status !== next.status || !sameShape(c.response.body, next.body)) {
+      c.response = next;
+      writeFileSync(p, JSON.stringify(c, null, 2) + '\n');
+      console.log(`  updated admin-rest/${f}`);
+      changed++;
+    }
+  }
+  return changed;
+}
+
+async function main(): Promise<void> {
+  console.log('[capture-shared-contracts] regenerating shared goldens from the offline mock…');
+  let total = 0;
+  total += await regenGraphql('admin');
+  total += await regenGraphql('storefront');
+  total += await regenRest();
+  console.log(`[capture-shared-contracts] done — ${total} golden(s) refreshed.`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});