@essential-apps/shopify-test-runner 1.0.0

package/docker/Dockerfile.vm

@@ -0,0 +1,137 @@
+# Self-contained test image targeting an HVF arm64 microVM
+# (via supermachine HVF) — sibling of `Dockerfile` (which targets libkrun-via-
+# Rosetta amd64). The two are deliberately separate files rather
+# than a single multi-arch Dockerfile because the diff between them
+# is meaningful, not just an ARCH var:
+#
+#   - libkrun (`Dockerfile`):     amd64, bind-mounted workspace,
+#                                 Google Chrome stable amd64 for
+#                                 Cloudflare Turnstile.
+#   - vm (this file):             arm64 native (Apple HVF), workspace
+#                                 mounted via virtio-fs DAX once that
+#                                 lands (until then, baked-in or
+#                                 vm.writeFile'd), arm64 Chromium
+#                                 bundled with Playwright — passes
+#                                 Turnstile too (verified against
+#                                 nowsecure.nl, the public canary).
+#
+# Built via either `container build --arch arm64 -t essential-apps/
+# shopify-test-vm:latest -f Dockerfile.vm .` (Apple
+# `container`) or `docker buildx build --platform linux/arm64 ...`
+# once the VM runtime adds local-OCI-archive `Image.build` support.
+# Then consumed by the VM-side runner as:
+#
+#   const image = await Image.build({
+#     ref: 'essential-apps/shopify-test-vm:latest',
+#     source: 'local-oci-archive',  // future API
+#     memoryMib: 4096,              // for safeFetch's patchright
+#                                   // pre-warm; 2 GiB OOM-killed it.
+#     vcpus: 2,
+#   });
+#
+# Until local-OCI-archive lands, push to ghcr.io as a workaround.
+#
+# Workspace shape inside the guest (matches the libkrun side so
+# probe code is identical):
+#   /workspace                     ← virtio-fs mount from host (or
+#                                    baked snapshot if mount missing)
+#   /var/lib/postgresql/data       ← per-VM Postgres data dir (NOT
+#                                    persisted; VMs are
+#                                    ephemeral, fresh per acquire)
+FROM mcr.microsoft.com/playwright:v1.59.1-jammy
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Base toolchain. Same set as the amd64 image MINUS:
+#   - Google Chrome stable (no arm64 build; not needed because
+#     Playwright's bundled arm64 Chromium passes Turnstile)
+#
+# Kept:
+#   - postgresql-14 + client (mock backend for offline-full tests)
+#   - openssh-client (localhost.run SSH tunnel fallback when
+#     cloudflared 429s — verified working in VMs)
+#   - cloudflared (primary webhook tunnel; arm64 .deb below)
+#   - net-tools, procps (debugging + process inspection)
+#   - libnss3-tools (Playwright's NSS for client cert handling)
+#   - x11vnc — auth-capture flow (runVmAuth.ts) starts it
+#     post-acquire to expose Xvfb :99 to host via vm.exposeTcp,
+#     so a human can interactively log in to Shopify Partners.
+#
+# Xvfb ships in the Playwright base image (it's how MS expects you
+# to run headful flows under their image); no extra install needed.
+#
+# build-essential (make + g++): consuming apps declare native deps (e.g.
+# bufferutil + utf-8-validate — DIRECT deps, not optional) that have no
+# prebuilt for the guest's Node on arm64, so the warmup `npm install`
+# compiles them via node-gyp, which needs make + a C++ toolchain. Without
+# it the warmup fails ("not found: make") and a fresh bake never boots.
+# (The compile is serialized via MAKEFLAGS=-j1 in the warmup to avoid OOM.)
+RUN apt-get update -qq \
+ && apt-get install -y -qq \
+      build-essential \
+      postgresql-14 \
+      postgresql-client-14 \
+      openssh-client \
+      sudo \
+      procps \
+      net-tools \
+      wget \
+      gnupg \
+      ca-certificates \
+      libnss3-tools \
+      x11vnc \
+ && rm -rf /var/lib/apt/lists/*
+
+# cloudflared — arm64 .deb (vs amd64 in the sibling Dockerfile).
+# Used by webhook-envelope probes to expose the in-VM Hono receiver
+# on a public *.trycloudflare.com URL so real Shopify can POST
+# webhooks during conformance live capture.
+#
+# Note: when running INSIDE the VM, cloudflared still spawns
+# fine because it's an outbound connection (to Cloudflare's edge)
+# — the VM runtime's vsock-based TSI doesn't block outbound
+# AF_INET on real interfaces. The in-VM 127.0.0.1 loopback for
+# guest-local listeners is the bit that has the accept-queue
+# split (known limitation, deferred); cloudflared's connect to the
+# receiver via 127.0.0.1 WOULD hit that, so we either:
+#   (a) run cloudflared on host + use vm.exposeTcp(N, receiverPort)
+#       so cloudflared sees `host:N` and forwards from there, OR
+#   (b) bake cloudflared into the VM and accept that it'll work
+#       once the TSI accept-queue split is fixed upstream.
+# We bake it here (option b) so the image is self-sufficient; the
+# host-side runner (`vmProbe.ts`, TBD) picks the topology.
+RUN wget -q -O /tmp/cloudflared.deb \
+      https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb \
+ && apt-get update -qq \
+ && apt-get install -y -qq /tmp/cloudflared.deb \
+ && rm -f /tmp/cloudflared.deb \
+ && rm -rf /var/lib/apt/lists/*
+
+# Native-addon build toolchain. Consuming apps may pull npm deps with
+# native bindings that lack a linux-arm64 / current-Node prebuild (e.g.
+# utf-8-validate, bufferutil — WebSocket accelerators). The in-VM
+# `npm install` (offline warmup) then falls back to compiling them with
+# node-gyp, which needs make + a C/C++ compiler + python3. Without these
+# the build fails and aborts the whole bake. Added as a dedicated late
+# layer so rebuilds stay cache-friendly (the base/Chrome/cloudflared
+# layers above don't re-run).
+RUN apt-get update -qq \
+ && apt-get install -y -qq \
+      build-essential \
+      python3 \
+ && rm -rf /var/lib/apt/lists/*
+
+ENV PGDATA=/var/lib/postgresql/data
+ENV PG_BIN=/usr/lib/postgresql/14/bin
+
+RUN mkdir -p "$PGDATA" \
+ && chown -R postgres:postgres "$PGDATA" \
+ && chmod 700 "$PGDATA"
+
+# VM quirk: `cmd` is set by the host-side runner at
+# Image.build time, not by Dockerfile CMD/ENTRYPOINT. Whatever we
+# put here is overridden. Leaving CMD as `bash` so the image is
+# still useful for ad-hoc `docker run` / `container run` debugging.
+WORKDIR /workspace
+
+CMD ["bash"]

package/docker/README.md

@@ -0,0 +1,50 @@
+# `essential-apps/shopify-test` container image
+
+Canonical Linux Chrome + Postgres + VNC image used by every layer of
+the test stack. The tag mirrors the npm scope (`@essential-apps/shopify-test`)
+so anyone inspecting `container images` sees the same name they
+`npm install`.
+
+Consumers (current):
+
+- **Conformance Partner-session capture** — `conformance:auth` boots
+  this image and exposes VNC so an operator can log in once. Bootstrap
+  (`conformance:bootstrap`) reuses it headlessly to mint per-store
+  admin tokens.
+- **Online-test fallback** — `dev:online` / online specs were historically
+  run from inside this image so real Google Chrome amd64 could clear
+  Cloudflare Turnstile on `admin.shopify.com`. The `runDocker*.ts`
+  drivers were removed in the May 2026 rename; the image lingers as
+  a fallback only — the vm is the default, but the vm runtime
+  ships only arm64 chromium and patchright doesn't clear Turnstile
+  (see `packages/conformance/docs/AUTH.md` — escalation pending).
+
+## Build
+
+From the shopify-test workspace root:
+
+```bash
+npm run image:build
+```
+
+Tags the image as `essential-apps/shopify-test:latest`. Override
+with `SHOPIFY_TEST_IMAGE_TAG=...` env var. Build is amd64
+(Rosetta-emulated on Apple Silicon) because Google only ships
+Chrome stable for Linux amd64.
+
+## Why amd64, not arm64
+
+Bundled Playwright chromium hits Cloudflare's Turnstile challenge
+on Linux even with patchright stealth patches. Real Google Chrome
+(stable) renders Turnstile the same way it does on macOS host
+Chrome, where the challenge auto-clicks cleanly. Google doesn't
+ship an arm64 Linux Chrome, so the image is amd64-only.
+
+## Migrating existing consumers
+
+Apps that built their own per-app image (e.g. `essential-upsell-online:latest`)
+can either:
+
+1. **Retag** — `container image tag essential-apps/shopify-test:latest essential-upsell-online:latest` — zero changes to their scripts.
+2. **Point at the shared image** — update `TEST_IMAGE` (or equivalent env var)
+   in their `.env.test` to `essential-apps/shopify-test:latest`.

package/docker/entrypoint.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+# Container entrypoint: initialize/start Postgres, then exec the user's
+# command. Postgres data lives at $PGDATA (bind-mounted from the host
+# at runtime, so it survives container restarts).
+set -euo pipefail
+
+# Initialize cluster on first run
+if [ ! -s "$PGDATA/PG_VERSION" ]; then
+  echo "[entrypoint] Initializing fresh Postgres cluster at $PGDATA"
+  chown -R postgres:postgres "$PGDATA"
+  sudo -u postgres "$PG_BIN/initdb" \
+    -D "$PGDATA" \
+    --auth-local=trust \
+    --auth-host=trust \
+    --no-locale \
+    --encoding=UTF8 \
+    >/dev/null
+  # Allow connections from any IP within the container's loopback range.
+  echo "host all all 127.0.0.1/32 trust" >> "$PGDATA/pg_hba.conf"
+  echo "host all all ::1/128       trust" >> "$PGDATA/pg_hba.conf"
+fi
+
+echo "[entrypoint] Starting Postgres on 127.0.0.1:5432"
+sudo -u postgres "$PG_BIN/pg_ctl" \
+  -D "$PGDATA" \
+  -l "$PGDATA/postgres.log" \
+  -o "-h 127.0.0.1 -p 5432 -k /tmp" \
+  start
+
+# Wait for pg ready
+for _ in $(seq 1 30); do
+  if "$PG_BIN/pg_isready" -h 127.0.0.1 -p 5432 -q; then break; fi
+  sleep 0.5
+done
+
+# Create a superuser role matching the container's running user (root by
+# default) so createdb/psql work without explicit -U postgres flags. The
+# OR-true tolerates the role already existing on warm starts.
+# Using -h /tmp because pg started with -k /tmp (custom socket dir).
+CURRENT_USER=$(id -un)
+sudo -u postgres "$PG_BIN/psql" -h /tmp -d postgres -c \
+  "CREATE ROLE \"$CURRENT_USER\" SUPERUSER LOGIN" 2>&1 | grep -v "already exists" || true
+
+# Stop pg cleanly when the container exits
+trap 'sudo -u postgres "$PG_BIN/pg_ctl" -D "$PGDATA" stop -m fast >/dev/null 2>&1 || true' EXIT
+
+# Mark to test runner that we're running inside the container so the
+# storePool fixture uses vanilla @playwright/test (matches the bundled
+# chromium in this image) instead of patchright (which wants a newer
+# Playwright image version).
+export TEST_IN_CONTAINER=true
+
+# ── Offline-mode wiring: /etc/hosts + system CA trust ───────────────
+#
+# When the OFFLINE runner is invoked inside this container, it boots a
+# tiny HTTPS reverse-proxy ("edge") on :443 that fronts the per-process
+# mock Storefront / Admin / Storefront-API / Admin-Shell servers. We
+# need:
+#
+#   1. DNS: Shopify hostnames must resolve to 127.0.0.1 so the browser
+#      AND Node both reach the edge instead of real Shopify on the
+#      internet. /etc/hosts works for both — it's read by glibc's
+#      getaddrinfo, which is what `dns.lookup` (and therefore Node's
+#      HTTP stack) calls, and Chrome reads it on Linux via its host
+#      resolver.
+#
+#   2. TLS: the edge presents a self-signed cert with broad SANs
+#      (*.myshopify.com, *.shopify.com, etc.) shipped at
+#      `node_modules/@essential-apps/shopify-test-runner/src/edge/cert.pem`.
+#      We install it as a system CA so Chrome AND Node trust it
+#      natively — no --ignore-certificate-errors, no
+#      NODE_TLS_REJECT_UNAUTHORIZED=0.
+#
+# We do this in the entrypoint (rather than at image-build time)
+# because (a) /etc/hosts is mounted by the container runtime at
+# start, not baked into the image; and (b) the cert lives in the
+# bind-mounted node_modules, not in the image. Both restrictions push
+# this work to runtime.
+#
+# Idempotent: re-running the entrypoint (warm container restart) is
+# safe — the hosts entries dedupe, and update-ca-certificates is
+# a no-op if the cert is already trusted.
+# Conformance (and any future "talk to real Shopify" mode) skips
+# offline wiring entirely — it needs real DNS for *.shopify.com and
+# the real Shopify TLS cert chain. Set SKIP_OFFLINE_HOST_HIJACK=1 in
+# `container run --env ...` from such callers; the rest of the
+# entrypoint (Postgres, x11vnc) still runs.
+EDGE_CERT_SRC="/workspace/node_modules/@essential-apps/shopify-test-runner/src/edge/ca.crt"
+if [ "${SKIP_OFFLINE_HOST_HIJACK:-0}" = "1" ]; then
+  echo "[entrypoint] SKIP_OFFLINE_HOST_HIJACK=1 — leaving /etc/hosts and CA store untouched."
+elif [ -f "$EDGE_CERT_SRC" ]; then
+  # /etc/hosts entries — preserve any existing content (e.g. container
+  # runtime's auto-injected hostname line). Need BOTH IPv4 (127.0.0.1)
+  # and IPv6 (::1) entries: glibc's getaddrinfo consults /etc/hosts for
+  # both address families, but if only an IPv4 entry exists for a host
+  # that ALSO has IPv6 DNS records (real test-shop.myshopify.com has
+  # AAAA records), the IPv6 lookup falls through to DNS and resolves
+  # to real Shopify. Chrome prefers IPv6 when available and would
+  # connect there, bypassing our /etc/hosts redirect entirely.
+  for HOST in test-shop.myshopify.com admin.shopify.com cdn.shopify.com fonts.shopifycdn.com; do
+    if ! grep -q "^127\.0\.0\.1[[:space:]]\+$HOST\$" /etc/hosts 2>/dev/null; then
+      echo "127.0.0.1 $HOST" >> /etc/hosts
+    fi
+    if ! grep -q "^::1[[:space:]]\+$HOST\$" /etc/hosts 2>/dev/null; then
+      echo "::1 $HOST" >> /etc/hosts
+    fi
+  done
+  # Trust the edge's CA cert. /usr/local/share/ca-certificates/*.crt
+  # is the canonical location; update-ca-certificates appends to
+  # /etc/ssl/certs/ca-certificates.crt (which Node + glibc OpenSSL +
+  # Chrome's bundled NSS all read).
+  cp -f "$EDGE_CERT_SRC" /usr/local/share/ca-certificates/edge-ca.crt
+  update-ca-certificates >/dev/null 2>&1 || true
+  # Tell Node explicitly too — NODE_EXTRA_CA_CERTS is the
+  # supported way to extend Node's TLS trust without touching
+  # built-in defaults.
+  export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/edge-ca.crt
+  echo "[entrypoint] Offline mode: /etc/hosts + system CA configured for *.myshopify.com / *.shopify.com → 127.0.0.1"
+fi
+
+# Prepend the consuming app's node_modules/.bin so locally-installed
+# CLIs (e.g. `shopify`, used by the storefront mock to run discount
+# function WASM via `@shopify/cli`) resolve from PATH without
+# requiring an `npx` wrapper. npm scripts already do this; child
+# processes spawned from in-process mocks don't go through npm and
+# inherit only PATH.
+if [ -d /workspace/node_modules/.bin ]; then
+  export PATH="/workspace/node_modules/.bin:$PATH"
+fi
+
+# Newer Shopify CLI versions (3.90+) refuse to run `shopify app
+# function run` if no `shopify.app.toml` exists in the app root.
+# Consuming apps typically check in variant configs only
+# (`shopify.app.dev.toml`, `shopify.app.production.toml`, etc.) and
+# select one via `shopify app config use` — that picks one and
+# symlinks it as `shopify.app.toml`. Container starts can't run
+# interactive `config use`, so do the symlink here: pick a sensible
+# default (prefer an online-named variant if present, else any
+# variant). The actual config CONTENT doesn't matter for `function
+# run` — it just needs to find the file to satisfy its preflight.
+if [ -d /workspace ] && [ ! -e /workspace/shopify.app.toml ]; then
+  cd /workspace
+  CANDIDATE=""
+  for pattern in shopify.app.online*.toml shopify.app.dev*.toml shopify.app.*.toml; do
+    for f in $pattern; do
+      if [ -f "$f" ]; then CANDIDATE="$f"; break; fi
+    done
+    [ -n "$CANDIDATE" ] && break
+  done
+  if [ -n "$CANDIDATE" ]; then
+    ln -s "$CANDIDATE" shopify.app.toml
+    echo "[entrypoint] Symlinked $CANDIDATE → shopify.app.toml (for Shopify CLI compatibility)"
+  fi
+  cd /
+fi
+
+# Start Xvfb as a background daemon so headed Chromium has a virtual
+# display. This avoids xvfb-run's process-wrapping behavior (which has
+# been observed to hang under Apple `container`). We just need DISPLAY
+# to point at a live X server.
+if [ -z "${DISPLAY:-}" ] && command -v Xvfb >/dev/null 2>&1; then
+  # 1600x1000 matches modern laptop screens better than 1400x900 and
+  # gives explore-mode Chrome enough room for DevTools-open layout
+  # without clipping. Tests use Playwright's own viewport setting
+  # (1400x900) so this only affects what's visible via VNC.
+  Xvfb :99 -screen 0 1600x1000x24 -nolisten tcp &
+  export DISPLAY=:99
+  # Tiny wait for the X server to be ready before any X client connects.
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    [ -S /tmp/.X11-unix/X99 ] && break
+    sleep 0.1
+  done
+fi
+
+# Optional: expose the Xvfb display via VNC for the one-time interactive
+# auth-capture flow. The wrapper (scripts/test/runDockerAuth.ts) starts
+# the container with TEST_ONLINE_VNC=1 and --publish 5900:5900, then opens
+# macOS Screen Sharing pointing at vnc://localhost:5900. After auth is
+# captured, normal test runs don't set this and the VNC server doesn't
+# start — Xvfb stays purely virtual.
+if [ "${TEST_ONLINE_VNC:-}" = "1" ] && command -v x11vnc >/dev/null 2>&1; then
+  # macOS Screen Sharing.app prompts for a password even against a
+  # -nopw VNC server, so set a static token. Port is only published
+  # on host loopback (--publish 127.0.0.1:5900:5900), so this is just
+  # to satisfy Screen Sharing's UI, not real security.
+  VNC_PASSWORD="${TEST_ONLINE_VNC_PASSWORD:-test}"
+  mkdir -p /root/.vnc
+  x11vnc -storepasswd "$VNC_PASSWORD" /root/.vnc/passwd >/dev/null 2>&1
+  echo "[entrypoint] Starting x11vnc on :5900 (display :99); password: $VNC_PASSWORD"
+  # x11vnc must bind 0.0.0.0 inside the container or the host-side
+  # port forward can't reach it. -shared/-forever: allow disconnect &
+  # reconnect.
+  x11vnc -display :99 -forever -shared -rfbauth /root/.vnc/passwd \
+    -rfbport 5900 -bg -quiet \
+    >/var/log/x11vnc.log 2>&1
+fi
+
+exec "$@"

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@essential-apps/shopify-test-runner",
+  "version": "1.0.0",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "import": "./dist/playwright/index.js"
+    },
+    "./contracts/normalize": {
+      "types": "./dist/contracts/normalize.d.ts",
+      "import": "./dist/contracts/normalize.js"
+    },
+    "./contracts/normalize-html": {
+      "types": "./dist/contracts/normalizeHtml.d.ts",
+      "import": "./dist/contracts/normalizeHtml.js"
+    }
+  },
+  "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",
+    "shopify-test-add-store": "./dist/scripts/addStore.js",
+    "shopify-test-list-stores": "./dist/scripts/listStores.js",
+    "shopify-test-create-stores": "./dist/scripts/createStores.js",
+    "shopify-test-cleanup-stores": "./dist/scripts/cleanupStores.js",
+    "shopify-test-setup-db": "./dist/scripts/setupTestDb.js",
+    "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-check-operation-coverage": "./dist/scripts/checkOperationCoverage.js",
+    "shopify-test-capture-contracts": "./dist/scripts/captureContracts.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"
+  },
+  "files": [
+    "dist",
+    "docker",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@essential-apps/shopify-test-core": "^1.0.0",
+    "@essential-apps/shopify-test-mock-admin": "^1.0.0",
+    "@essential-apps/shopify-test-shopify-api": "^1.0.0",
+    "@essential-apps/shopify-test-storefront": "^1.0.0",
+    "@essential-apps/shopify-test-themes": "^1.0.0",
+    "@playwright/test": "^1.49.0",
+    "@types/node": "^20.19.40",
+    "@types/tar-stream": "^3.1.4",
+    "esbuild": "^0.25.0",
+    "graphql": "^16.8.1",
+    "jszip": "^3.10.1",
+    "patchright": "^1.59.4",
+    "tar-stream": "^3.2.0",
+    "undici": "^7.0.0",
+    "ws": "^8.18.0",
+    "@supermachine/core": "^0.7.67"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "vite": "^5.4.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/contracts/normalize.ts

@@ -0,0 +1,96 @@
+/**
+ * Response normalisation for operation contracts.
+ *
+ * The contract-conformance system (see docs/CONTRACTS.md) compares
+ * GraphQL responses captured from two different sources — the
+ * offline mock and live Shopify — and asserts they're "the same".
+ * But "the same" can mean two different things:
+ *
+ *   - **Shape-equal**: same keys, same value types, same array
+ *     lengths. Ignores actual values that Shopify generates per
+ *     request (IDs, timestamps, CDN-cache-busted image URLs).
+ *   - **Value-equal**: byte-for-byte JSON equality.
+ *
+ * Live verification REQUIRES shape-equal — real Shopify hands out
+ * different numeric IDs and cache-bust hashes on every store. If
+ * we compare raw values, every live diff is noise.
+ *
+ * This module implements shape-equal by walking a response tree
+ * and replacing volatile substrings with stable tokens. Two
+ * responses that differ ONLY in IDs/timestamps/CDN-URLs become
+ * byte-equal after normalisation; real structural drift survives.
+ *
+ * Replacement rules (each preserves the surrounding context so the
+ * normalised value remains parseable):
+ *
+ *   gid://shopify/<Type>/<digits>             → gid://shopify/<Type>/<ID>
+ *   gid://shopify/<Type>/<digits>?<rest>      → gid://shopify/<Type>/<ID>?<rest>
+ *   2026-05-14T12:34:56Z                      → <DATETIME>
+ *   2026-05-14T12:34:56.789Z                  → <DATETIME>
+ *   2026-05-14                                → <DATE>
+ *   https://cdn.shopify.com/...               → <CDN_URL>
+ *   https://<shop>.myshopify.com/cdn/...      → <CDN_URL>
+ *   base64-ish cursor (eyJ... starting)       → <CURSOR>
+ *
+ * The replacement is INTENTIONALLY GENEROUS. We'd rather over-
+ * normalise (treat two distinct values as equal) than under (treat
+ * two equivalent values as different and produce noisy diffs).
+ * Genuine drift (a field that's now missing, a type that changed)
+ * survives because we only rewrite well-formed volatile patterns.
+ *
+ * For offline-only verification (Layer 3), normalisation is a
+ * no-op — the offline mock returns deterministic values, so raw
+ * equality already works. For live verification (Layer 4),
+ * normalisation is essential.
+ */
+
+const ID_GID_RE = /^(gid:\/\/shopify\/[A-Za-z]+)\/(\d+)(\?.*)?$/;
+const ISO_DATE_TIME_RE =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const CDN_URL_RE =
+  /^https?:\/\/(?:cdn\.shopify\.com|[^./]+\.myshopify\.com\/cdn\/)/;
+// Base64-ish cursors are tough to detect without false-positives. A
+// loose heuristic: starts with `eyJ` (the base64 prefix of `{"...`)
+// and is at least 40 chars. Real Shopify cursors are JWT-ish.
+const CURSOR_RE = /^eyJ[A-Za-z0-9_+/=-]{37,}$/;
+
+export function normaliseString(s: string): string {
+  const gid = s.match(ID_GID_RE);
+  if (gid) {
+    const [, typePrefix, , suffix] = gid;
+    return `${typePrefix}/<ID>${suffix ?? ''}`;
+  }
+  if (ISO_DATE_TIME_RE.test(s)) return '<DATETIME>';
+  if (ISO_DATE_RE.test(s)) return '<DATE>';
+  if (CDN_URL_RE.test(s)) return '<CDN_URL>';
+  if (CURSOR_RE.test(s)) return '<CURSOR>';
+  return s;
+}
+
+/**
+ * Walk a JSON-able value and replace volatile substrings with
+ * stable tokens. Returns a deep-cloned tree — never mutates the
+ * input. Objects and arrays recurse; scalars (string / number /
+ * boolean / null) get inspected directly.
+ *
+ * Number IDs (e.g. `legacyResourceId: 12345`) — we DON'T normalise
+ * these. They're explicit values the consuming app may compare on.
+ * If a contract relies on a specific numeric ID, the live and
+ * offline values won't match and the diff fires (correctly — it's
+ * a fixture-mismatch issue, fix via fixtures.json or by re-
+ * capturing against a known seeded live store).
+ */
+export function normaliseResponse(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return normaliseString(value);
+  if (Array.isArray(value)) return value.map(normaliseResponse);
+  if (typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = normaliseResponse(v);
+    }
+    return out;
+  }
+  return value;
+}

package/src/contracts/normalizeHtml.ts

@@ -0,0 +1,98 @@
+/**
+ * HTML normalisation for Liquid output contracts.
+ *
+ * Liquid renders produce HTML with three kinds of volatile content
+ * that would otherwise diff-spam every capture against live:
+ *
+ *   1. Generated identifiers — UUIDs in data-* attributes,
+ *      auto-incremented `id="..."` values, cursor-y opaque tokens.
+ *   2. Asset URLs with cache-busters — `?v=1234567890` on every
+ *      CDN-served image / CSS.
+ *   3. Whitespace + attribute order — both sides may render the
+ *      same logical HTML with different formatting.
+ *
+ * The normaliser collapses these to stable tokens, preserving the
+ * structural skeleton that conformance actually cares about. Two
+ * outputs that differ ONLY in these volatile dimensions become
+ * byte-equal after normalisation; genuine structural drift
+ * (a missing element, a renamed attribute) survives.
+ *
+ * Implementation: regex passes on the raw HTML string. We could
+ * use a real HTML parser (parse5 / node-html-parser) for attribute
+ * sorting, but that's a substantial dep for marginal gain — both
+ * the offline mock and live Shopify emit attributes in source-
+ * declaration order, so post-render orders match anyway. Switch
+ * to a parser later if a real ordering mismatch shows up.
+ *
+ * Keep the patterns in `normaliseHtmlString` aligned with whatever
+ * volatile values surface during live captures — drift caught here
+ * (false positive) means add a rule; drift missed (false negative)
+ * means tighten an existing one.
+ */
+
+/** UUID v4-ish — case-insensitive, hyphenated. Used for funnel / variant / extension IDs. */
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+
+/** Long base-N numeric IDs — Shopify uses these everywhere (product IDs, variant IDs). */
+const NUMERIC_ID_8PLUS_RE = /\b\d{8,}\b/g;
+
+/** Asset cache-buster `?v=12345` (with surrounding URL chars preserved). */
+const CACHE_BUSTER_RE = /\?v=\d+/g;
+
+/** Token used by Shopify analytics — `__st.*` payloads in inline script tags. */
+const ANALYTICS_TOKEN_RE = /"(s|t|a|p|c|e)t":\s*\d+/g;
+
+/** Long base64-ish blob (40+ chars) — cursors, signed URLs, etc. */
+const LONG_BASE64_RE = /\b[A-Za-z0-9+/]{40,}={0,2}\b/g;
+
+/**
+ * Replace the value of any `data-…="…"` attribute whose key looks
+ * "id-like" with a token. Catches `data-funnel-id="abc-..."`,
+ * `data-product-id="123"`, etc. without us having to enumerate every
+ * possible attribute name. Conservative — only matches keys ending
+ * in `-id` to avoid stomping on legitimate data attributes like
+ * `data-trigger-type`.
+ */
+const DATA_ID_ATTR_RE = /(data-[\w-]*-id)="[^"]+"/gi;
+
+/** `id="..."` value — any HTML id attribute. */
+const ID_ATTR_RE = /\bid="([^"]+)"/g;
+
+/**
+ * Collapse runs of whitespace BETWEEN HTML tags. Preserves
+ * whitespace WITHIN text content (which can be semantically
+ * meaningful, e.g. between words in a sentence).
+ */
+function collapseInterTagWhitespace(html: string): string {
+  return html.replace(/>\s+</g, '><');
+}
+
+/**
+ * Trim leading/trailing whitespace and collapse all-whitespace
+ * runs to single spaces inside text nodes that span attribute
+ * boundaries. Safe: applied after the inter-tag pass.
+ */
+function collapseTextWhitespace(html: string): string {
+  return html.replace(/\s{2,}/g, ' ').trim();
+}
+
+/**
+ * Single entry point. Apply each normalisation in a deterministic
+ * order — later passes assume earlier ones already ran.
+ */
+export function normaliseHtmlString(html: string): string {
+  let out = html;
+  // Order matters — narrower patterns first, so they consume the
+  // input before generic ones (`NUMERIC_ID_8PLUS_RE`) eat the
+  // numeric tail of a cache-buster or UUID.
+  out = out.replace(CACHE_BUSTER_RE, '?v=<CACHE_BUSTER>');
+  out = out.replace(UUID_RE, '<UUID>');
+  out = out.replace(DATA_ID_ATTR_RE, '$1="<ID>"');
+  out = out.replace(ID_ATTR_RE, 'id="<ID>"');
+  out = out.replace(LONG_BASE64_RE, '<BASE64>');
+  out = out.replace(ANALYTICS_TOKEN_RE, (_m, k) => `"${k}t":<TS>`);
+  out = out.replace(NUMERIC_ID_8PLUS_RE, '<NUMERIC_ID>');
+  out = collapseInterTagWhitespace(out);
+  out = collapseTextWhitespace(out);
+  return out;
+}