@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/runOffline.ts

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+/**
+ * Run the OFFLINE-FULL suite inside a microVM.
+ *
+ * Sibling of `runVm.ts` (which runs the ONLINE Shopify suite).
+ * Both use the same arm64 microVM image; this one drives the offline
+ * orchestrator (`runOfflineFullTests.js`) instead of the online one
+ * (`runTests.js`). The runOfflineFullTests script bootstraps the full
+ * mock stack (Remix backend + MSW Admin + storefront + mock admin
+ * shell + per-run Postgres DB) entirely inside the VM — no Shopify
+ * round-trips, no Cloudflare, no auth.
+ *
+ * Architecture (matches the online runner where the shape overlaps):
+ *
+ *   - Same image (`essential-apps/shopify-test-vm:latest`)
+ *     as the online runner — one image to bake, both runners restore
+ *     from the same snapshot family.
+ *   - Bind mounts (virtio-fs DAX):
+ *       - consuming app repo      → /workspace
+ *       - linux node_modules cache → /workspace/node_modules
+ *   - Postgres autostart + /etc/hosts patch + npm install folded
+ *     into the warmup callback. Warm restores skip all of that.
+ *   - `runOfflineFullTests.js` spawned inside; its in-VM Vite +
+ *     Playwright + mocks all dial localhost.
+ *
+ * Why a host build of `build/server/index.js` is required:
+ * the in-VM Vite build is markedly slower than the host one (~5 min
+ * vs ~6 s) and hits a virtio-fs perf cliff during the Rollup small-
+ * file emission phase. Building on the host + skipping the in-VM
+ * build with TEST_OFFLINE_SKIP_BUILD=true is the supported path.
+ * runOfflineFullTests.js still spins up Vite for non-build needs.
+ *
+ * Override env vars (mirrors runVm where applicable; same
+ * TEST_ONLINE_VM_* knobs):
+ *   TEST_ONLINE_VM_IMAGE / TEST_ONLINE_VM_IMAGE_SOURCE
+ *   TEST_ONLINE_VM_IMAGE_LAYOUT_PATH
+ *   TEST_ONLINE_VM_MEMORY_MIB     Default: 8192.
+ *   TEST_ONLINE_VM_VCPUS          Default: 4.
+ *   TEST_LINUX_NODE_MODULES          Default: ~/.cache/${appName}-test/node_modules
+ *   TEST_ONLINE_VM_TIMEOUT_MS     Default: 10 min.
+ *   TEST_OFFLINE_EXTENSIONS_JSON     forwarded to runOfflineFullTests.
+ *   TEST_OFFLINE_POST_PURCHASE_EXT   forwarded.
+ *   LIQUID_CONTRACTS_CAPTURE        set to 'true' to regenerate
+ *                                   tests/test-offline/contracts/liquid/*.html
+ *                                   in full-suite context. See
+ *                                   tests/README.md.
+ *   PLAYWRIGHT_GREP                 forwarded as Playwright --grep,
+ *                                   e.g. PLAYWRIGHT_GREP='cart flow'
+ */
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pickApp, prepareOciArchive, envFileArgs, computeBuildHash } from '@essential-apps/shopify-test-core';
+
+const repoRoot = process.cwd();
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(repoRoot, 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      `No package.json at ${pkgPath}. Run this from the consuming app's repo root.`,
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+  if (!pkg.name) {
+    throw new Error(`package.json at ${pkgPath} has no \`name\` field.`);
+  }
+  return pkg.name.replace(/^@[^/]+\//, '');
+}
+
+/**
+ * Ensure the VM base image exists in the local container store, building
+ * it once from the vendored Dockerfile if not. No external registry: the
+ * runner package ships docker/Dockerfile.vm (via its package.json
+ * "files"), so a fresh clone builds the image on first run with the same
+ * `container build` the conformance:image:build script uses. Slow (~mins:
+ * apt + browser base) but one-time — the image then persists in the
+ * store. Only the oci-archive source mode calls this (registry /
+ * oci-layout source the image elsewhere).
+ */
+function ensureVmImageBuilt(ref: string): void {
+  try {
+    execSync(`container image inspect ${JSON.stringify(ref)}`, { stdio: 'ignore' });
+    return; // already present
+  } catch {
+    // not found → build below
+  }
+  const dockerCtx = resolve(dirname(fileURLToPath(import.meta.url)), '../../docker');
+  const dockerfile = resolve(dockerCtx, 'Dockerfile.vm');
+  if (!existsSync(dockerfile)) {
+    throw new Error(
+      `[runOffline] VM image "${ref}" is not in the local container store, ` +
+        `and the vendored Dockerfile is missing at ${dockerfile} (expected ` +
+        `under the @essential-apps/shopify-test-runner package's docker/).`,
+    );
+  }
+  console.error(
+    `[runOffline] VM image "${ref}" not found — building it once from ` +
+      `${dockerfile}. This takes a few minutes (apt + browser base); it is ` +
+      `cached in the container store afterward, so later runs skip to bake.`,
+  );
+  const t = performance.now();
+  execSync(
+    `container build --arch arm64 -t ${JSON.stringify(ref)} ` +
+      `-f ${JSON.stringify(dockerfile)} ${JSON.stringify(dockerCtx)}`,
+    { stdio: 'inherit' },
+  );
+  console.error(
+    `[runOffline] VM image built in ${((performance.now() - t) / 1000).toFixed(1)} s.`,
+  );
+}
+
+/**
+ * Resolve the VM image source the same way the conformance
+ * runner does. Duplicated here intentionally — extracting into a
+ * shared helper would create a runner→conformance dep cycle (runner
+ * is allowed to depend on conformance, but in practice this is the
+ * single use-site and the indirection isn't worth a new dep).
+ */
+async function imageSourceOptions(): Promise<Record<string, unknown>> {
+  const mode = process.env['TEST_ONLINE_VM_IMAGE_SOURCE'] ?? 'oci-archive';
+  if (mode === 'registry') return {};
+  const ref =
+    process.env['TEST_ONLINE_VM_IMAGE'] ??
+    'essential-apps/shopify-test-vm:latest';
+  if (mode === 'oci-archive') {
+    ensureVmImageBuilt(ref);
+    const prep = await prepareOciArchive(ref);
+    if (prep.freshlySaved) {
+      console.error(
+        `[runOffline] saved ${ref} → ${prep.archivePath} (${(prep.sizeBytes / 1024 / 1024).toFixed(1)} MB)`,
+      );
+    }
+    return { source: 'oci-archive', sourcePath: prep.archivePath };
+  }
+  if (mode === 'oci-layout') {
+    const sourcePath = process.env['TEST_ONLINE_VM_IMAGE_LAYOUT_PATH'];
+    if (!sourcePath) {
+      throw new Error(
+        `TEST_ONLINE_VM_IMAGE_SOURCE=oci-layout requires TEST_ONLINE_VM_IMAGE_LAYOUT_PATH`,
+      );
+    }
+    return { source: 'oci-layout', sourcePath };
+  }
+  throw new Error(
+    `TEST_ONLINE_VM_IMAGE_SOURCE=${mode} not recognised. Valid: oci-archive | oci-layout | registry`,
+  );
+}
+
+async function main(): Promise<void> {
+  const appName = readAppName();
+  const linuxModules =
+    process.env['TEST_LINUX_NODE_MODULES'] ??
+    resolve(homedir(), `.cache/${appName}-test/node_modules`);
+  mkdirSync(linuxModules, { recursive: true });
+
+  // ── Host build (gated by app-source hash) ───────────────────
+  // The in-VM runner skips building (TEST_OFFLINE_SKIP_BUILD, set below)
+  // and serves build/server/index.js from the bind-mounted workspace — so
+  // we build it HERE on the host (much faster than in-VM), but only when
+  // the app's sources actually changed. computeBuildHash hashes app/ plus
+  // the package/config files; we cache it next to the output. Net: editing
+  // app code transparently rebuilds, and a fresh clone (no build/) builds
+  // on first run — no manual `npm run build`. Force with
+  // TEST_OFFLINE_FORCE_BUILD=true.
+  const buildCachePath = resolve(repoRoot, 'build/.test-build-cache');
+  const serverBundlePath = resolve(repoRoot, 'build/server/index.js');
+  const currentBuildHash = await computeBuildHash(repoRoot);
+  const forceBuild = process.env['TEST_OFFLINE_FORCE_BUILD'] === 'true';
+  const cachedBuildHash =
+    !forceBuild && existsSync(buildCachePath) && existsSync(serverBundlePath)
+      ? readFileSync(buildCachePath, 'utf8').trim()
+      : null;
+  if (cachedBuildHash === currentBuildHash) {
+    console.error(
+      `[runOffline] build cache HIT (${currentBuildHash.slice(0, 12)}) — skipping host build.`,
+    );
+  } else {
+    console.error(
+      `[runOffline] build cache MISS — host-building app (TEST_OFFLINE=true)… ` +
+        `(${cachedBuildHash ? `was ${cachedBuildHash.slice(0, 12)}` : 'no cache'} → ${currentBuildHash.slice(0, 12)})`,
+    );
+    const tBuild = performance.now();
+    // TEST_OFFLINE gates off vercelPreset (→ a remix-serve-compatible
+    // build); the app reads runtime secrets at request time, so no
+    // build-time env is required. NODE_ENV=production for a prod bundle.
+    execSync('npm run build', {
+      stdio: 'inherit',
+      env: { ...process.env, TEST_OFFLINE: 'true', NODE_ENV: 'production' },
+    });
+    writeFileSync(buildCachePath, currentBuildHash);
+    console.error(
+      `[runOffline] host build: ${((performance.now() - tBuild) / 1000).toFixed(1)} s`,
+    );
+  }
+
+  // Tarball-manifest written by `scripts/pack-into.sh` — a hash list
+  // of the vendored @essential-apps/* tarballs. Passed as an
+  // `extraFile` so its bytes fold into the snapshot's bake input-hash:
+  // any tarball change (= someone ran pack-into.sh) changes the
+  // manifest, which invalidates the snapshot, which re-runs warmup,
+  // which reinstalls. This is what makes a tarball refresh "just work"
+  // WITHOUT a manual warmupTag bump or a `rm -rf ~/.cache/<app>-test`.
+  //
+  // Before this, the only snapshot key was the static `warmupTag`
+  // string, so a tarball refresh left a stale snapshot + a stale
+  // bind-mounted node_modules cache serving old code — the classic
+  // "I repacked but the test still runs the old build" footgun.
+  // (Mirrors the online runner runVm.ts, which already does this.)
+  const tarballManifest = resolve(
+    repoRoot,
+    'vendor/essential-apps-shopify-test/.tarball-manifest',
+  );
+  const tarballManifestExists = existsSync(tarballManifest);
+
+  // Fold a hash of the manifest into the warmupTag. The `extraFiles`
+  // approach alone (below) does NOT reliably invalidate the snapshot
+  // in this VM-runtime version — observed: manifest changed but bake
+  // was still a 0.0s warm restore. The warmupTag, by contrast,
+  // DEFINITIVELY keys the snapshot (a tag bump always rebakes). So we
+  // hash the manifest (itself a sha256 list of the vendored tarballs)
+  // into the tag: any tarball change → manifest change → tag change →
+  // rebake → warmup reinstalls. The leading `v12` is the WARMUP-SCRIPT
+  // version — bump it only when changing the warmup steps below
+  // (perms/hosts/install), not for tarball refreshes.
+  const manifestHash = tarballManifestExists
+    ? createHash('sha256').update(readFileSync(tarballManifest)).digest('hex').slice(0, 12)
+    : 'no-manifest';
+
+  // Fold the @supermachine/core (VM runtime) version into the snapshot
+  // key as well. A snapshot is produced by a specific VMM version, and
+  // restoring one baked by a different runtime is unsound — but the bake
+  // hash keys only on GUEST inputs (image + tarballs), not the host VMM,
+  // so a runtime bump would otherwise warm-restore a stale snapshot. Key
+  // on the installed version so a bump auto-rebakes — same philosophy as
+  // the manifest hash (no manual tag bump, no `rm -rf ~/.cache/<app>`).
+  // Resolved from the consumer root; degrades to a stable bucket (never
+  // crashes) if the version can't be read.
+  const runtimeVersion = ((): string => {
+    try {
+      const requirePkg = createRequire(resolve(repoRoot, 'package.json'));
+      return (
+        requirePkg('@supermachine/core/package.json') as { version: string }
+      ).version;
+    } catch {
+      return 'unknown';
+    }
+  })();
+  const runtimeTag = `sm${runtimeVersion.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
+  // the SAME shopify-test build (same manifestHash + runtime). The warm
+  // snapshot captures THIS app's `npm install`, so without appName, app
+  // B would restore app A's warm snapshot — wrong node_modules + app
+  // 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}`;
+
+  // Dynamic import — @supermachine/core is heavy and only needed
+  // when actually running tests, not for `--help` etc.
+  const { Image } = await import('@supermachine/core');
+
+  const imageOpts = await imageSourceOptions();
+  console.error(`[runOffline] baking image… (warmupTag=${warmupTag})`);
+  const tBake = performance.now();
+  const image = await Image.build({
+    ref:
+      process.env['TEST_ONLINE_VM_IMAGE'] ??
+      'essential-apps/shopify-test-vm:latest',
+    memoryMib: Number(process.env['TEST_ONLINE_VM_MEMORY_MIB'] ?? 8192),
+    vcpus: Number(process.env['TEST_ONLINE_VM_VCPUS'] ?? 4),
+    cmd: ['sleep', 'infinity'],
+    mounts: [
+      // VM runtime 0.7.28+ requires explicit guestPath and
+      // auto-mounts at boot before warmup fires.
+      { hostPath: repoRoot, guestTag: 'workspace', guestPath: '/workspace' },
+      { hostPath: linuxModules, guestTag: 'lmod', guestPath: '/workspace/node_modules' },
+    ],
+    extraFiles: tarballManifestExists
+      ? [
+          // Belt-and-suspenders alongside the manifest-hashed
+          // warmupTag (the tag is what actually drives invalidation;
+          // see warmupTag note above). Harmless if the runtime ignores
+          // it; matches the online runner runVm.ts.
+          { hostPath: tarballManifest, guestPath: '/etc/.shopify-test-tarball-manifest' },
+        ]
+      : [],
+    // Snapshot key. `warmupTag` is computed from the tarball-manifest
+    // hash (see above), so a tarball refresh auto-rebakes WITHOUT a
+    // manual bump or a `rm -rf ~/.cache/<app>-test`. Warmup runs ONCE
+    // per bake; warm acquires skip it.
+    warmupTag,
+    // @ts-expect-error — @supermachine/core's BuildOptions type
+    // doesn't declare `warmup`, but the runtime accepts it. Tracked
+    // upstream; fix-or-augment when the types catch up.
+    warmup: async (vm: {
+      exec: (opts: { argv: string[]; timeoutMs?: number }) => Promise<{
+        exitCode: number;
+        stdout: Buffer;
+        stderr: Buffer;
+      }>;
+    }) => {
+      const r = await vm.exec({
+        argv: ['sh', '-c', `
+          set -e
+          # VM runtime 0.7.28+ auto-mounts declared mounts/volumes
+          # at boot before warmup fires — no manual mount needed.
+          echo "--- repair perms for postgres ---"
+          chown -R postgres:postgres /var/lib/postgresql/data
+          chmod 700 /var/lib/postgresql/data
+          mkdir -p /var/run/postgresql
+          chown postgres:postgres /var/run/postgresql
+          chmod 775 /var/run/postgresql
+
+          echo "--- npm install (fresh per rebake) ---"
+          # Warmup runs EXACTLY when the snapshot rebakes — which now
+          # happens only when the tarball-manifest extraFile changes
+          # (pack-into.sh) or the warmupTag bumps. Either way we want a
+          # clean install, so wipe the bind-mounted cache first; npm
+          # can't reuse a stale tarball that way.
+          #
+          # NB: this is a DEDICATED cache dir (~/.cache/<app>-test/
+          # node_modules), NOT the repo's node_modules, so the rm-rf is
+          # safe. Replaces the old "skip if .package-lock.json exists"
+          # check, which left stale code in the cache across tarball
+          # refreshes (the bind mount served old bytes because warmup
+          # never re-ran the install).
+          cd /workspace
+          rm -rf node_modules/* node_modules/.[!.]* 2>/dev/null || true
+          # Don't pipe npm to "tail" — the pipeline status is tail's,
+          # masking npm failures under "set -e", so a transient install
+          # error would bake a half-installed node_modules cache that
+          # warm restores then reuse. Check npm's own status so a failed
+          # install aborts the bake (no cache poisoned, next run rebakes).
+          # Low-memory install. The 8 GiB guest intermittently
+          # OOM-killed npm (exit 137) once build-essential let native
+          # deps (utf-8-validate / bufferutil) compile — parallel g++
+          # spiked peak memory. Serialize node-gyp (jobs=1, make -j1)
+          # and skip audit/fund work to keep the install under the cap.
+          if ! npm_config_jobs=1 MAKEFLAGS=-j1 npm install --legacy-peer-deps --engine-strict=false --no-audit --no-fund > /tmp/npm-install.log 2>&1; then
+            echo "--- npm install FAILED - last 40 lines ---"
+            tail -40 /tmp/npm-install.log
+            exit 1
+          fi
+          tail -10 /tmp/npm-install.log
+
+          echo "--- patch /etc/hosts for localhost ---"
+          if ! grep -q "^127.0.0.1.*localhost" /etc/hosts; then
+            echo "127.0.0.1 localhost" >> /etc/hosts
+            echo "::1 localhost" >> /etc/hosts
+          fi
+
+          echo "--- warmup done ---"
+        `],
+        timeoutMs: 15 * 60 * 1000,
+      });
+      if (r.exitCode !== 0) {
+        throw new Error(
+          `warmup failed (exit ${r.exitCode}): ${r.stderr.toString().slice(-2000)}\n${r.stdout.toString().slice(-2000)}`,
+        );
+      }
+    },
+    ...imageOpts,
+  });
+  console.error(`[runOffline] bake: ${((performance.now() - tBake) / 1000).toFixed(1)} s`);
+
+  const pool = await image.pool({ min: 1, max: 1, restoreOnRelease: false });
+  const vm = await pool.acquire();
+  try {
+    // Postgres startup — fast because warmup already chowned the data dir.
+    const tPg = performance.now();
+    const pgR = await vm.exec({
+      argv: ['sh', '-c', `
+        export PGDATA=/var/lib/postgresql/data
+        export PG_BIN=/usr/lib/postgresql/14/bin
+        if su postgres -c "\${PG_BIN}/pg_ctl -D \${PGDATA} status" >/dev/null 2>&1; then echo running; exit 0; fi
+        if [ -z "$(ls -A \${PGDATA} 2>/dev/null)" ]; then su postgres -c "\${PG_BIN}/initdb -D \${PGDATA} -A trust" >/dev/null; fi
+        su postgres -c "\${PG_BIN}/pg_ctl -D \${PGDATA} -l /tmp/pg.log -o '-h 127.0.0.1 -p 5432' start" >/dev/null
+        for _ in $(seq 1 50); do
+          if su postgres -c "\${PG_BIN}/pg_isready -h 127.0.0.1 -p 5432" >/dev/null 2>&1; then
+            # Create 'root' superuser to match the libkrun image entrypoint
+            # — runTests.js connects as 'root'.
+            su postgres -c "\${PG_BIN}/createuser -h 127.0.0.1 -p 5432 -s root" 2>&1 | grep -v 'already exists' || true
+            exit 0
+          fi
+          sleep 0.1
+        done
+        cat /tmp/pg.log
+        exit 1
+      `],
+      timeoutMs: 30_000,
+    });
+    if (pgR.exitCode !== 0) {
+      console.error('[runOffline] postgres start failed:', pgR.stderr.toString());
+      process.exit(1);
+    }
+    console.error(`[runOffline] postgres: ${((performance.now() - tPg) / 1000).toFixed(2)} s`);
+
+    // Forward a curated env subset. Mostly the same as the online
+    // runner, plus the offline-specific extension list + post-
+    // purchase host + the SKIP_BUILD escape hatch the host-build
+    // path requires + LIQUID_CONTRACTS_CAPTURE for regenerating
+    // the stored Liquid snapshots.
+    const forwardEnv: Record<string, string> = {};
+    for (const k of [
+      'TEST_VISIBLE',
+      'TEST_WORKERS',
+      'TEST_PRESERVE_DB',
+      'TEST_OFFLINE_STRICT_GRAPHQL',
+      'TEST_OFFLINE_EXTENSIONS_JSON',
+      'TEST_OFFLINE_POST_PURCHASE_EXT',
+      'LIQUID_CONTRACTS_CAPTURE',
+      // Playwright reads this natively to update visual-regression
+      // PNG baselines (`all` | `missing` | `none`). Forward so
+      // teammates can run `PLAYWRIGHT_UPDATE_SNAPSHOTS=all npm run
+      // test:offline` after intentional UI changes.
+      'PLAYWRIGHT_UPDATE_SNAPSHOTS',
+      'CI',
+      'DEBUG',
+    ]) {
+      const v = process.env[k];
+      if (v !== undefined) forwardEnv[k] = v;
+    }
+    forwardEnv['TEST_IN_CONTAINER'] = 'true';
+
+    // Auto-wire the consuming app's theme app extensions into the
+    // storefront mock. Without this, the orchestrator's `loadExtensions`
+    // returns [] and no app-embed Liquid gets injected into rendered
+    // pages — symptoms: widget tests time out waiting for
+    // `<essential-upsell-app-embed>` to attach or
+    // `[data-essential-upsell-funnel-id]` to portal.
+    //
+    // Source of truth is `tests/test-online/.apps.json` — same file the
+    // online tier reads (one app registry, shared across tiers). Each
+    // extension entry needs a host-side `rootDir`; we translate it to
+    // the VM-side `/workspace/<rel>` path so the orchestrator sees the
+    // extension at the same logical location it lives in the repo.
+    //
+    // Honour a pre-set `TEST_OFFLINE_EXTENSIONS_JSON` (e.g. the user
+    // wants a custom mix) — only auto-populate when the env var is
+    // missing. Same pattern for `TEST_OFFLINE_POST_PURCHASE_EXT`.
+    if (!forwardEnv['TEST_OFFLINE_EXTENSIONS_JSON']) {
+      try {
+        const app = pickApp();
+        if (app.extensions && app.extensions.length > 0) {
+          const vmExtensions = app.extensions
+            .filter((e) => e.rootDir)
+            .map((e) => ({
+              name: e.name,
+              // rootDir in .apps.json is relative to the consumer repo
+              // (e.g. `app_extensions/upsells`). Inside the VM, the
+              // repo is bind-mounted at `/workspace`.
+              rootDir: `/workspace/${e.rootDir!.replace(/^\.?\//, '')}`,
+            }));
+          if (vmExtensions.length > 0) {
+            forwardEnv['TEST_OFFLINE_EXTENSIONS_JSON'] = JSON.stringify(vmExtensions);
+          }
+          // Post-purchase bundle (separate env — orchestrator loads it
+          // via a different code path from theme app extensions).
+          if (!forwardEnv['TEST_OFFLINE_POST_PURCHASE_EXT']) {
+            const postPurchase = app.extensions.find((e) => e.postPurchaseBundle);
+            if (postPurchase?.postPurchaseBundle) {
+              forwardEnv['TEST_OFFLINE_POST_PURCHASE_EXT'] = `/workspace/${postPurchase.postPurchaseBundle.replace(/^\.?\//, '')}`;
+            }
+          }
+        }
+      } catch (err) {
+        // .apps.json missing or malformed — skip auto-wiring rather than
+        // crash. Tests that don't depend on extensions still run.
+        console.error(
+          `[runOffline] couldn't auto-load extensions from .apps.json: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    // The host-built bundle in build/server/index.js was generated
+    // with the host's Prisma client. Skip the in-VM rebuild — see
+    // the runOfflineFullTests source for the full picture. The
+    // host build must exist and be fresh; `npm run build` in the
+    // consuming app with TEST_OFFLINE=true NODE_ENV=production
+    // before invoking this script.
+    forwardEnv['TEST_OFFLINE_SKIP_BUILD'] = 'true';
+    // Pin Prisma to the linux-arm64 query engine that lives in
+    // LMOD's node_modules/.prisma/client/. The bundled client's
+    // built-in resolver gets confused by the host-vs-guest engine
+    // 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';
+
+    // 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'];
+    const grepArg = grep ? `--grep ${JSON.stringify(grep)}` : '';
+
+    // Spawn the test runner. Streaming stdout/stderr via spawn so
+    // the user sees Playwright output as it lands rather than at end.
+    console.error('[runOffline] launching runOfflineFullTests.js…');
+    const tTests = performance.now();
+    const testProc = await vm.spawn({
+      argv: ['sh', '-c', `
+        cd /workspace
+        # node_modules/.bin on PATH so test code can shell out to
+        # local CLIs (shopify, prisma, playwright).
+        export PATH=/workspace/node_modules/.bin:$PATH
+        node ${envFileArgs(repoRoot)} node_modules/@essential-apps/shopify-test-runner/dist/scripts/runOfflineFullTests.js ${grepArg}
+      `],
+      env: forwardEnv,
+    });
+
+    // Stream + collect output. Hard 10-min cap by default, with a
+    // no-output stall guard for hung processes.
+    //
+    // The stall guard has to outlast legitimate cold-start silence:
+    //   - edge proxy bind (instant)
+    //   - prisma migrate deploy (~5-15 s cold)
+    //   - Remix backend boot via remix-serve (~10-30 s cold)
+    //   - Playwright spawning chromium (~10-30 s cold first time)
+    //   - testDir discovery + worker boot
+    // Cumulative cold-start silence can reach ~60-90 s before any test
+    // produces stdout. Default 180 s lives comfortably outside that
+    // window. Override via env if a test legitimately needs more.
+    const maxMs = Number(process.env['TEST_ONLINE_VM_TIMEOUT_MS'] ?? 10 * 60 * 1000);
+    const stallMs = Number(process.env['TEST_OFFLINE_STALL_MS'] ?? 180_000);
+    const start = Date.now();
+    let lastByteAt = Date.now();
+    while (true) {
+      const out = await testProc.readStdout(64 * 1024);
+      const now = Date.now();
+      if (out.length === 0) {
+        if (now - start > maxMs) {
+          console.error(`\n[runOffline] HARD TIMEOUT ${maxMs / 1000}s — killing`);
+          await testProc.signal(15).catch(() => {});
+          break;
+        }
+        if (now - lastByteAt > stallMs) {
+          console.error(`\n[runOffline] no output for ${stallMs / 1000}s — killing`);
+          await testProc.signal(15).catch(() => {});
+          break;
+        }
+        await new Promise((r) => setTimeout(r, 200));
+        continue;
+      }
+      lastByteAt = now;
+      process.stdout.write(out);
+      // Playwright summary lines look like "  17 passed (45.6s)" or
+      // "  3 failed". Once we see one, drain the tail and break.
+      if (/\b\d+ (passed|failed)\b/.test(out.toString())) {
+        await new Promise((r) => setTimeout(r, 500));
+        const tail = await testProc.readStdout(64 * 1024);
+        if (tail.length > 0) process.stdout.write(tail);
+        break;
+      }
+    }
+    const wait = await testProc.wait();
+    console.error(`[runOffline] tests: ${((performance.now() - tTests) / 1000).toFixed(1)} s`);
+    console.error(`[runOffline] grand: ${((performance.now() - tBake) / 1000).toFixed(1)} s`);
+    process.exit(wait.exitCode ?? 0);
+  } finally {
+    await vm.release().catch(() => {});
+    await pool.shutdown().catch(() => {});
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});