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

package/dist/lib/guestVnc.d.ts

@@ -0,0 +1,31 @@
+/** 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 declare 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 declare function exposeGuestVnc(vm: VncCapableVm, opts?: ExposeGuestVncOptions): Promise<unknown>;
+//# sourceMappingURL=guestVnc.d.ts.map

package/dist/lib/guestVnc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guestVnc.d.ts","sourceRoot":"","sources":["../../src/lib/guestVnc.ts"],"names":[],"mappings":"AAuBA,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,IAAI,EAAE;QACT,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClE,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,YAAY,EAChB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,OAAO,CAAC,CA4FlB"}

package/dist/lib/guestVnc.js

@@ -0,0 +1,111 @@
+/**
+ * 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';
+export const DEFAULT_VNC_PORT = 5900;
+/**
+ * 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, opts = {}) {
+    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;
+}
+//# sourceMappingURL=guestVnc.js.map

package/dist/lib/guestVnc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guestVnc.js","sourceRoot":"","sources":["../../src/lib/guestVnc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAW3D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAarC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAgB,EAChB,OAA8B,EAAE;IAEhC,MAAM,WAAW,GACf,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,IAAI,MAAM,CAAC;IACxE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,cAAc,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,YAAY,CAAC;IAE3C,mEAAmE;IACnE,kEAAkE;IAClE,iEAAiE;IACjE,kEAAkE;IAClE,uCAAuC;IACvC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,8BAA8B,IAAI,GAAG,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC;QAC7B,IAAI,EAAE;YACJ,MAAM;YACN,IAAI;YACJ;;;;yCAImC,MAAM;;;;iCAId,MAAM;;;;;;;;;;;;;;6BAcV,WAAW;oCACJ,IAAI;;8CAEM,IAAI;;;;;;kDAMA,IAAI;;;;;kCAKpB,IAAI;;;;KAIjC;SACA;QACD,SAAS,EAAE,MAAM;KAClB,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CACX,GAAG,GAAG,iBAAiB,EACvB,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,EAC1B,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,CAC3B,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IAED,+CAA+C;IAC/C,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,8BAA8B,IAAI,aAAa,IAAI,EAAE,CAAC,CAAC;IAE3E,+DAA+D;IAC/D,IAAI,UAAU,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC9B,iEAAiE;QACjE,iEAAiE;QACjE,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACjB,MAAM,MAAM,GAAG,UAAU,kBAAkB,CAAC,WAAW,CAAC,cAAc,IAAI,EAAE,CAAC;QAC7E,OAAO,CAAC,KAAK,CACX,GAAG,GAAG,mDAAmD,IAAI,uBAAuB,CACrF,CAAC;QACF,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,6BAA6B,MAAM,IAAI,CAAC,CAAC;QAC7D,SAAS,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IAC3E,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CACX,GAAG,GAAG,wCAAwC,IAAI,eAAe,WAAW,IAAI,CACjF,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/scripts/buildImage.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=buildImage.d.ts.map

package/dist/scripts/buildImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildImage.d.ts","sourceRoot":"","sources":["../../src/scripts/buildImage.ts"],"names":[],"mappings":""}

package/dist/scripts/{buildDockerImage.js → buildImage.js}

@@ -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.
@@ -20,7 +22,7 @@ import { fileURLToPath } from 'node:url';
 // Mirrors the npm scope (`@essential-apps/shopify-test`) so anyone
 // inspecting `container images` sees the same name they `npm install`.
 const DEFAULT_TAG = 'essential-apps/shopify-test:latest';
-function dockerContextDir() {
+function imageContextDir() {
     // 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));
@@ -38,9 +40,9 @@ function dockerContextDir() {
 }
 async function main() {
     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}`);
@@ -57,4 +59,4 @@ main().catch((err) => {
     console.error(err);
     process.exit(1);
 });
-//# sourceMappingURL=buildDockerImage.js.map
+//# sourceMappingURL=buildImage.js.map

package/dist/scripts/buildImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildImage.js","sourceRoot":"","sources":["../../src/scripts/buildImage.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,mEAAmE;AACnE,uEAAuE;AACvE,MAAM,WAAW,GAAG,oCAAoC,CAAC;AAEzD,SAAS,eAAe;IACtB,oEAAoE;IACpE,+CAA+C;IAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,gDAAgD;IAChD,MAAM,UAAU,GAAG;QACjB,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC;QAC7B,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC;KAC3B,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,IAAI,KAAK,CACb,iEAAiE;QAC/D,UAAU,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,WAAW,CAAC;IACjE,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;IAElC,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;IACtE,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACjE,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IAChD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;AACjD,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"}

package/dist/scripts/captureSharedContracts.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=captureSharedContracts.d.ts.map

package/dist/scripts/captureSharedContracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureSharedContracts.d.ts","sourceRoot":"","sources":["../../src/scripts/captureSharedContracts.ts"],"names":[],"mappings":""}

package/dist/scripts/captureSharedContracts.js

@@ -0,0 +1,209 @@
+#!/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, } 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, b) {
+    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() {
+    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() {
+    return new ShopState({
+        shop: {
+            domain: 'test-shop.myshopify.com',
+            permanent_domain: 'test-shop.myshopify.com',
+        },
+    });
+}
+function fillPath(template, params) {
+    return template.replace(/\{([^}]+)\}/g, (_, key) => {
+        if (!(key in params)) {
+            throw new Error(`path template references {${key}} but no value provided`);
+        }
+        return encodeURIComponent(params[key] ?? '');
+    });
+}
+function appendQuery(path, query) {
+    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) {
+    let entries;
+    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) {
+    const dir = resolve(fixturesDir(), api);
+    const state = buildGraphqlState();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono types are loose
+    const app = 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'));
+        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() {
+    const dir = resolve(fixturesDir(), 'admin-rest');
+    const state = buildRestState();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono types are loose
+    const app = createAdminApi({ state });
+    let changed = 0;
+    for (const f of flatGoldens(dir)) {
+        const p = resolve(dir, f);
+        const c = JSON.parse(readFileSync(p, 'utf8'));
+        if (c.warning)
+            continue;
+        const finalPath = appendQuery(fillPath(c.path, { version: ADMIN_API_VERSION, ...(c.pathParams ?? {}) }), c.query);
+        const init = {
+            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 = await app.request(finalPath, init);
+        let body = 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() {
+    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);
+});
+//# sourceMappingURL=captureSharedContracts.js.map

package/dist/scripts/captureSharedContracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureSharedContracts.js","sourceRoot":"","sources":["../../src/scripts/captureSharedContracts.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,cAAc,EACd,mBAAmB,GACpB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EACL,WAAW,GAGZ,MAAM,2DAA2D,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAEpC;;;;;GAKG;AACH,SAAS,SAAS,CAAC,CAAU,EAAE,CAAU;IACvC,OAAO,CACL,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAC9E,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB;IACxB,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC;QAC1B,IAAI,EAAE;YACJ,MAAM,EAAE,yBAAyB;YACjC,gBAAgB,EAAE,yBAAyB;SAC5C;KACF,CAAC,CAAC;IACH,KAAK,CAAC,UAAU,CAAC;QACf,EAAE,EAAE,WAAW;QACf,MAAM,EAAE,gBAAgB;QACxB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,sDAAsD;QACnE,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,eAAe;QACvB,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE;YACR;gBACE,EAAE,EAAE,WAAW;gBACf,KAAK,EAAE,eAAe;gBACtB,KAAK,EAAE,IAAI;gBACX,SAAS,EAAE,IAAI;gBACf,GAAG,EAAE,UAAU;gBACf,kBAAkB,EAAE,GAAG;gBACvB,gBAAgB,EAAE,CAAC,eAAe,CAAC;aACpC;SACF;QACD,IAAI,EAAE,EAAE;KACT,CAAC,CAAC;IACH,KAAK,CAAC,aAAa,CAAC;QAClB,EAAE,EAAE,WAAW;QACf,MAAM,EAAE,mBAAmB;QAC3B,KAAK,EAAE,mBAAmB;QAC1B,cAAc,EAAE,CAAC,gBAAgB,CAAC;KACnC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uEAAuE;AACvE,SAAS,cAAc;IACrB,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE;YACJ,MAAM,EAAE,yBAAyB;YACjC,gBAAgB,EAAE,yBAAyB;SAC5C;KACF,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,QAAgB,EAAE,MAA8B;IAChE,OAAO,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,GAAW,EAAE,EAAE;QACzD,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;AACD,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,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;AACxE,CAAC;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CACnB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;QACnB,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAC7B,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,GAA2B;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC;IAClC,sFAAsF;IACtF,MAAM,GAAG,GACP,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,MAAM,QAAQ,GACZ,GAAG,KAAK,OAAO;QACb,CAAC,CAAC,iCAAiC;QACnC,CAAC,CAAC,2BAA2B,CAAC;IAClC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAsB,CAAC;QACnE,IAAI,CAAC,CAAC,OAAO;YAAE,SAAS;QACxB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE;YACvC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,wBAAwB,EAAE,mBAAmB;aAC9C;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;SAClE,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;YACnC,CAAC,CAAC,QAAQ,GAAG,MAAM,CAAC;YACpB,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpD,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;YACrC,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,SAAS;IACtB,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAC/B,sFAAsF;IACtF,MAAM,GAAG,GAAQ,cAAc,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAiB,CAAC;QAC9D,IAAI,CAAC,CAAC,OAAO;YAAE,SAAS;QACxB,MAAM,SAAS,GAAG,WAAW,CAC3B,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC,EACzE,CAAC,CAAC,KAAK,CACR,CAAC;QACF,MAAM,IAAI,GAAgB;YACxB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,wBAAwB,EAAE,mBAAmB;aAC9C;SACF,CAAC;QACF,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAa,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC1D,IAAI,IAAI,GAAY,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;QACD,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;QAC3C,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChF,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC;YAClB,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpD,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC;YACzC,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,OAAO,CAAC,GAAG,CAAC,+EAA+E,CAAC,CAAC;IAC7F,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,KAAK,IAAI,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,KAAK,IAAI,MAAM,SAAS,EAAE,CAAC;IAC3B,OAAO,CAAC,GAAG,CAAC,qCAAqC,KAAK,uBAAuB,CAAC,CAAC;AACjF,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"}

package/dist/scripts/runOffline.js

@@ -56,6 +56,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { pickApp, prepareOciArchive, envFileArgs, computeBuildHash } from '@essential-apps/shopify-test-core';
 import { buildExtensions } from '../lib/buildExtensions.js';
+import { exposeGuestVnc } from '../lib/guestVnc.js';
 const repoRoot = process.cwd();
 function readAppName() {
     const pkgPath = resolve(repoRoot, 'package.json');
@@ -293,6 +294,25 @@ async function main() {
         }
     })();
     const runtimeTag = `sm${runtimeVersion.replace(/[^0-9a-z]+/gi, '')}`;
+    // Fold THIS runner package's own version into the snapshot key. The
+    // warm snapshot bakes the in-VM `npm install` (which installs the
+    // orchestrator + fixtures this same shopify-test version ships). Those
+    // run INSIDE the VM, so a version bump that changes orchestrator/
+    // fixture behaviour (e.g. screen-video support) would otherwise
+    // warm-restore a STALE in-VM install — the consumer updates the
+    // package but keeps running the old in-VM code until they manually
+    // `rm -rf ~/.cache/<app>-test`. Keying on the runner version makes a
+    // bump auto-rebake (cold install of the new version) — same
+    // no-manual-bust philosophy as manifestHash + runtimeTag.
+    const runnerVersion = (() => {
+        try {
+            return createRequire(import.meta.url)('../../package.json').version;
+        }
+        catch {
+            return 'unknown';
+        }
+    })();
+    const runnerTag = `r${runnerVersion.replace(/[^0-9a-z]+/gi, '')}`;
     // Scope the snapshot to the consuming app. supermachine keys WARM
     // snapshots by (image + warmupTag), but the image is shared across
     // apps and the rest of the tag is identical for any two apps vendoring
@@ -302,7 +322,7 @@ async function main() {
     // identity (observed: essential-upsell booting with essential-seo's
     // DB). The cache paths are already appName-namespaced; this aligns the
     // snapshot key with them.
-    const warmupTag = `offline-v13-${appName}-${runtimeTag}-${manifestHash}`;
+    const warmupTag = `offline-v13-${appName}-${runtimeTag}-${runnerTag}-${manifestHash}`;
     // Dynamic import — @supermachine/core is heavy and only needed
     // when actually running tests, not for `--help` etc.
     const { Image } = await import('@supermachine/core');
@@ -455,6 +475,15 @@ async function main() {
             // orchestrator's Xvfb startup + the offlineFullStack screen-video
             // fixture).
             'TEST_OFFLINE_VIDEO',
+            // Offline runs headed-under-Xvfb by default; opt out to headless.
+            'TEST_OFFLINE_HEADLESS',
+            // Interactive explore mode: orchestrator skips Playwright and
+            // instead opens a headed Chromium (admin + storefront tabs) on
+            // the guest Xvfb display, which we surface over VNC (see the
+            // explore branch below).
+            'TEST_OFFLINE_EXPLORE',
+            'TEST_OFFLINE_EXPLORE_URL',
+            'TEST_OFFLINE_EXPLORE_NO_DEVTOOLS',
             'CI',
             'DEBUG',
         ]) {
@@ -524,6 +553,54 @@ async function main() {
         // mismatch unless we tell it exactly which .so.node to dlopen.
         forwardEnv['PRISMA_QUERY_ENGINE_LIBRARY'] =
             '/workspace/node_modules/.prisma/client/libquery_engine-linux-arm64-openssl-3.0.x.so.node';
+        // ── Explore mode (interactive, VNC) ───────────────────────────
+        // `TEST_OFFLINE_EXPLORE=true` boots the full offline mock stack
+        // and hands the developer a real browser inside the VM instead of
+        // running Playwright. We surface the guest's Xvfb display over VNC
+        // (supermachine `vm.exposeTcp`, NOT docker --publish) so they can
+        // click through the admin app + storefront against the mock stack.
+        // The orchestrator opens both tabs (see runOfflineFullTests explore
+        // branch) and holds until the browser window is closed / Ctrl-C.
+        if (process.env['TEST_OFFLINE_EXPLORE'] === 'true') {
+            let forwarder;
+            try {
+                forwarder = (await exposeGuestVnc(vm, {
+                    logPrefix: '[runOffline]',
+                }));
+                console.error('[runOffline] launching explore session…');
+                const exploreProc = await vm.spawn({
+                    argv: ['sh', '-c', `
+            cd /workspace
+            export PATH=/workspace/node_modules/.bin:$PATH
+            export DISPLAY=:99
+            node ${envFileArgs(repoRoot)} node_modules/@essential-apps/shopify-test-runner/dist/scripts/runOfflineFullTests.js
+          `],
+                    env: forwardEnv,
+                });
+                // Stream guest output verbatim with NO stall/hard timeout — an
+                // explore session legitimately sits idle for as long as the
+                // developer is poking around. It ends when they close the
+                // browser (orchestrator exits) or Ctrl-C here.
+                const pump = (async () => {
+                    while (true) {
+                        const out = await exploreProc.readStdout(64 * 1024);
+                        if (out.length === 0) {
+                            await new Promise((r) => setTimeout(r, 200));
+                            continue;
+                        }
+                        process.stdout.write(out);
+                    }
+                })();
+                pump.catch(() => { });
+                const wait = await exploreProc.wait();
+                process.exitCode = wait.exitCode ?? 0;
+                return;
+            }
+            finally {
+                if (forwarder?.stop)
+                    await Promise.resolve(forwarder.stop()).catch(() => { });
+            }
+        }
         // Optional --grep forwarding for fast iteration on a single
         // scenario or spec without writing a one-off bench script.
         const grep = process.env['PLAYWRIGHT_GREP'];