@deeeed/metamask-harness 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.6.3
+
+### Fixed
+- **Extension `launch` reuses a healthy live runtime instead of always clean-building** — quick `launch` / `launch --sidepanel` on an extension slot now probes for a reusable runtime (webpack watcher LISTENing on `WATCHER_PORT` + CDP `/json/version` reachable on `CDP_PORT` + dist not stale). When all hold it REATTACHES: re-snapshots `dist/chrome` into the loaded runtime-dist and reloads the extension in place over CDP (service worker + pages), re-asserts the side panel, and applies `--url` — against the existing slot Chrome profile, with no watcher stop, webpack cache clear, or Chrome kill/relaunch. Reuse is best-effort: a failed probe (watcher down, CDP unreachable, stale dist) falls through to the clean path, and `--build` is the explicit escape that always clean-builds + relaunches a fresh runtime (no probe) to force-recover a broken slot.
+
 ## 0.6.2 - 2026-07-06
 
 ### Added

package/adapters/extension/inject.mjs

@@ -101,6 +101,7 @@ copyFile(path.join(runnerDir, 'adapters/extension/snapshot-dist.sh'), path.join(
 copyFile(path.join(runnerDir, 'adapters/extension/pin-remote-flags.cjs'), path.join(harnessDir, 'scripts/pin-remote-flags.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/seed-fixture.sh'), path.join(harnessDir, 'scripts/seed-fixture.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/sidepanel-toggle.sh'), path.join(harnessDir, 'scripts/sidepanel-toggle.sh'));
+copyFile(path.join(runnerDir, 'adapters/extension/reattach.sh'), path.join(harnessDir, 'scripts/reattach.sh'));
 copyFile(path.join(runnerDir, 'adapters/extension/readiness.mjs'), path.join(harnessDir, 'scripts/readiness.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/wallet-fixture-state.cjs'), path.join(harnessDir, 'scripts/wallet-fixture-state.cjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/verify.sh'), path.join(harnessDir, 'scripts/verify.sh'));
@@ -138,6 +139,7 @@ const manifest = {
     refreshBuild: `${harnessRel}/scripts/refresh-build.sh`,
     reopenBrowser: `${harnessRel}/scripts/reopen-browser.sh`,
     sidepanelToggle: `${harnessRel}/scripts/sidepanel-toggle.sh`,
+    reattach: `${harnessRel}/scripts/reattach.sh`,
   },
   patchedFiles: [],
   backupDir: null,

package/adapters/extension/reattach.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# reattach.sh — reload a live extension slot in place (no rebuild, no relaunch)
+#
+# Purpose:
+#   Quick-reuse leaf for `mm-harness launch` on an already-healthy extension slot:
+#   re-snapshots dist/chrome into the loaded runtime-dist so the running Chrome
+#   picks up watched code changes, then reloads the extension over CDP (service
+#   worker + extension pages) and re-opens the wallet. Optionally navigates a
+#   main tab to --start-url. Runs entirely against the EXISTING slot Chrome
+#   profile — it never stops the watcher, kills Chrome, or clears the webpack
+#   cache (that is the clean path in live.sh).
+#
+# Inputs (flags / env):
+#   --target <metamask-extension> (default $PWD; becomes the working dir)
+#   --cdp-port <port> (required, numeric) — the slot's CDP endpoint
+#   --watcher-port <port> (optional; informational only)
+#   --start-url <url> (optional; opened as a main tab beside the wallet)
+#   --ext-id <id> (optional; else resolved from the extension.id file or CDP)
+#   --dist-dir <rel> (default dist/chrome), --settle-ms <ms> (default 8000)
+#
+# Outputs:
+#   Progress on stderr. Exit 0 — reloaded; 1 — repo/reload failed; 2 — bad args
+#   / non-numeric port / CDP unreachable.
+#
+# Never touches: product source files; the webpack watcher; the Chrome process;
+# other slots' browsers (single CDP port scope).
+set -euo pipefail
+
+TARGET="$PWD"
+CDP_PORT="${CDP_PORT:-}"
+WATCHER_PORT="${WATCHER_PORT:-}"
+START_URL="${EXTENSION_START_URL:-}"
+EXT_ID="${EXT_ID:-}"
+DIST_DIR="dist/chrome"
+SETTLE_MS="8000"
+
+require_value() { [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; }
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target) require_value "$@"; TARGET="$2"; shift 2 ;;
+    --cdp-port) require_value "$@"; CDP_PORT="$2"; shift 2 ;;
+    --watcher-port) require_value "$@"; WATCHER_PORT="$2"; shift 2 ;;
+    --start-url) require_value "$@"; START_URL="$2"; shift 2 ;;
+    --ext-id) require_value "$@"; EXT_ID="$2"; shift 2 ;;
+    --dist-dir) require_value "$@"; DIST_DIR="$2"; shift 2 ;;
+    --settle-ms) require_value "$@"; SETTLE_MS="$2"; shift 2 ;;
+    -h|--help)
+      echo "Usage: reattach.sh --target <metamask-extension> --cdp-port <port> [--watcher-port <port>] [--start-url <url>] [--ext-id <id>] [--dist-dir <rel>] [--settle-ms <ms>]"
+      exit 0
+      ;;
+    *) echo "reattach: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -z "$CDP_PORT" ]; then
+  echo "reattach: --cdp-port is required" >&2
+  echo "  Next: mm-harness launch --build   (clean build + relaunch a fresh slot)" >&2
+  exit 2
+fi
+case "$CDP_PORT" in
+  *[!0-9]*) echo "reattach: --cdp-port must be numeric (got: $CDP_PORT)" >&2; exit 2 ;;
+esac
+
+if [ ! -f "$TARGET/package.json" ]; then
+  echo "reattach: --target is not a checkout (no package.json): $TARGET" >&2
+  echo "  Next: mm-harness launch --target /path/to/metamask-extension --build" >&2
+  exit 1
+fi
+TARGET="$(cd "$TARGET" && pwd)"
+
+if ! curl -s -m 3 "http://127.0.0.1:${CDP_PORT}/json/version" >/dev/null 2>&1; then
+  echo "reattach: CDP not reachable on port ${CDP_PORT}; the slot browser is not live." >&2
+  echo "  Next: mm-harness launch --build   (clean build + relaunch)" >&2
+  exit 2
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DIST_ABS="$TARGET/$DIST_DIR"
+# The running Chrome loads the runtime-dist snapshot (frozen at launch), not the
+# live dist. Re-snapshot so the in-place reload serves the latest watched build.
+RUNTIME_DIST_ABS="$TARGET/temp/recipe/runtime/runtime-dist"
+
+if [ -f "$SCRIPT_DIR/snapshot-dist.sh" ] && [ -d "$RUNTIME_DIST_ABS" ]; then
+  echo "[reattach] re-snapshotting dist -> runtime-dist for in-place reload" >&2
+  bash "$SCRIPT_DIR/snapshot-dist.sh" --dist "$DIST_ABS" --runtime-dist "$RUNTIME_DIST_ABS" >&2 || {
+    echo "reattach: dist re-snapshot failed; the loaded extension may be mid-rebuild." >&2
+    echo "  Next: mm-harness launch --build   (clean build + relaunch)" >&2
+    exit 1
+  }
+fi
+
+# Resolve the extension id: explicit flag, then the recorded id file, else CDP.
+if [ -z "$EXT_ID" ]; then
+  for idf in "$TARGET/temp/recipe/runtime/extension.id" "$SCRIPT_DIR/extension.id"; do
+    if [ -f "$idf" ]; then
+      EXT_ID="$(tr -d '[:space:]' < "$idf")"
+      [ -n "$EXT_ID" ] && break
+    fi
+  done
+fi
+
+cd "$TARGET"
+echo "[reattach] reloading extension in place over CDP :${CDP_PORT}" >&2
+
+CDP_PORT="$CDP_PORT" EXT_ID="$EXT_ID" START_URL="$START_URL" SETTLE_MS="$SETTLE_MS" node <<'NODE'
+let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
+
+const port = process.env.CDP_PORT;
+const startUrl = process.env.START_URL || '';
+const settleMs = Number(process.env.SETTLE_MS || '8000') || 8000;
+
+function extensionIdFrom(context, provided) {
+  if (provided) return provided;
+  const urls = [];
+  for (const page of context.pages()) urls.push(page.url());
+  for (const worker of context.serviceWorkers()) urls.push(worker.url());
+  for (const url of urls) {
+    const match = /^chrome-extension:\/\/([^/]+)\//u.exec(url);
+    if (match) return match[1];
+  }
+  return '';
+}
+
+async function connect() {
+  const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
+  const context = browser.contexts()[0];
+  return { browser, context };
+}
+
+(async () => {
+  // Phase 1: trigger a full extension reload (service worker + all pages) from an
+  // extension page so Chrome re-reads the freshly snapshotted runtime-dist.
+  let { browser, context } = await connect();
+  const extId = extensionIdFrom(context, process.env.EXT_ID);
+  if (!extId) {
+    await browser.close();
+    console.error('reattach: could not resolve the extension id from the live CDP targets.');
+    console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
+    process.exit(1);
+  }
+
+  let page = context
+    .pages()
+    .find((candidate) => candidate.url().startsWith(`chrome-extension://${extId}/`));
+  if (!page) {
+    page = await context.newPage();
+    await page.goto(`chrome-extension://${extId}/home.html`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 15000,
+    });
+  }
+  await page.evaluate(() => chrome.runtime.reload()).catch(() => {
+    // The reload tears the page context down; a rejected evaluate is expected.
+  });
+  await browser.close();
+
+  // Phase 2: wait for the extension to come back, then re-open the wallet and,
+  // when requested, a dapp tab. Chrome itself never restarted, so CDP stays up.
+  const deadline = Date.now() + settleMs;
+  let back = false;
+  while (Date.now() < deadline) {
+    try {
+      const probe = await connect();
+      const id = extensionIdFrom(probe.context, extId);
+      await probe.browser.close();
+      if (id) { back = true; break; }
+    } catch {
+      // CDP momentarily unavailable during reload; retry until the deadline.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  if (!back) {
+    console.error(`reattach: extension did not come back within ${settleMs}ms after reload.`);
+    console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
+    process.exit(1);
+  }
+
+  ({ browser, context } = await connect());
+  let home = context
+    .pages()
+    .find(
+      (candidate) =>
+        candidate.url().startsWith(`chrome-extension://${extId}/`) &&
+        !candidate.url().includes('/sidepanel.html'),
+    );
+  if (!home) {
+    home = await context.newPage();
+    await home
+      .goto(`chrome-extension://${extId}/home.html`, { waitUntil: 'domcontentloaded', timeout: 15000 })
+      .catch(() => { /* wallet home is best-effort; the reload already applied */ });
+  }
+  if (startUrl) {
+    const dapp = context
+      .pages()
+      .find((candidate) => candidate.url().startsWith('http://') || candidate.url().startsWith('https://'));
+    const tab = dapp || (await context.newPage());
+    await tab
+      .goto(startUrl, { waitUntil: 'domcontentloaded', timeout: 20000 })
+      .catch(() => { /* dapp navigation is best-effort */ });
+  }
+  await browser.close();
+})().catch((error) => {
+  console.error(`reattach: ${error && error.message ? error.message : error}`);
+  console.error('  Next: mm-harness launch --build   (clean build + relaunch)');
+  process.exit(1);
+});
+NODE
+
+echo "[reattach] extension reloaded in place — no rebuild, no relaunch" >&2
+echo "  Next: mm-harness verify   (confirm the reloaded runtime)" >&2

package/adapters/manifest.json

@@ -178,6 +178,14 @@
       "inputs": "<status|open|close|toggle|cycle> --cdp-port --ext-id --agent-dir --settle-ms; env REPO, CDP_PORT, EXT_ID, SETTLE_MS, AGENT_DIR",
       "outputs": "status/progress on stdout; exit 0/1/2"
     },
+    {
+      "id": "extension/reattach",
+      "entry": "adapters/extension/reattach.sh",
+      "kind": "bash",
+      "purpose": "Reload a live extension slot in place: re-snapshot dist into the loaded runtime-dist, then reload the extension (service worker + pages) over CDP — no watcher stop, no Chrome kill.",
+      "inputs": "--target --cdp-port --watcher-port --start-url --ext-id --dist-dir --settle-ms; env CDP_PORT, WATCHER_PORT, EXTENSION_START_URL, EXT_ID",
+      "outputs": "progress on stderr; exit 0/1/2"
+    },
     {
       "id": "extension/pin-remote-flags",
       "entry": "adapters/extension/pin-remote-flags.cjs",

package/dist/adapters/extension/runtime-decision.js

@@ -181,6 +181,9 @@ function distCheck(target) {
   }
   return { status: "fresh", distGitId: distShort, head: headShort };
 }
+function isExtensionDistStale(target) {
+  return distCheck(path.resolve(target)).status === "stale";
+}
 async function cdpCheck(target, cdpPort) {
   if (!cdpPort) return { status: "skipped" };
   try {
@@ -301,5 +304,6 @@ function buildAction(target, clean) {
 }
 export {
   decideExtensionReadiness,
+  isExtensionDistStale,
   recordReadinessBaseline
 };

package/dist/commands/launch/extension.js

@@ -1,17 +1,72 @@
+import { execFileSync } from "node:child_process";
+import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
+import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { spawnScriptStreaming } from "../shared.js";
 async function launchExtension(target, tier, wantWatch) {
-  if (!wantWatch && tier === "quick") {
+  if (wantWatch) {
+    const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
+    const watchArgs = ["--target", target];
+    if (process.env.WATCHER_PORT) watchArgs.push("--watcher-port", process.env.WATCHER_PORT);
+    console.error(`\u2192 extension watch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`);
+    return spawnScriptStreaming(startWatchSh, watchArgs, target);
+  }
+  if (tier === "build") {
     return extensionRebuild(target);
   }
-  const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
-  const watchArgs = ["--target", target];
-  if (process.env.WATCHER_PORT) watchArgs.push("--watcher-port", process.env.WATCHER_PORT);
-  console.error(`\u2192 extension ${wantWatch ? "watch" : "build"} \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`);
-  return spawnScriptStreaming(startWatchSh, watchArgs, target);
+  if (await extensionRuntimeReusable(target)) {
+    return extensionReattach(target);
+  }
+  return extensionRebuild(target);
+}
+async function extensionRuntimeReusable(target) {
+  const watcherPort = process.env.WATCHER_PORT;
+  const cdpPort = process.env.CDP_PORT;
+  if (!watcherPort || !cdpPort) return false;
+  if (!portHasListener(watcherPort)) return false;
+  if (!await cdpVersionReachable(cdpPort)) return false;
+  if (isExtensionDistStale(target)) return false;
+  return true;
+}
+function portHasListener(port) {
+  try {
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.split(/\s+/u).some((value) => /^\d+$/u.test(value));
+  } catch {
+    return false;
+  }
+}
+function cdpVersionReachable(port) {
+  return new Promise((resolve) => {
+    const request = http.get(
+      { host: "127.0.0.1", port: Number(port), path: "/json/version", timeout: 2e3 },
+      (response) => {
+        response.resume();
+        const code = response.statusCode ?? 0;
+        resolve(code >= 200 && code < 300);
+      }
+    );
+    request.on("timeout", () => {
+      request.destroy();
+      resolve(false);
+    });
+    request.on("error", () => resolve(false));
+  });
+}
+async function extensionReattach(target) {
+  const reattachScript = recipeHarnessPath(target, "extension", "scripts", "reattach.sh");
+  const reattachArgs = ["--target", target];
+  if (process.env.CDP_PORT) reattachArgs.push("--cdp-port", process.env.CDP_PORT);
+  if (process.env.WATCHER_PORT) reattachArgs.push("--watcher-port", process.env.WATCHER_PORT);
+  if (process.env.EXTENSION_START_URL) reattachArgs.push("--start-url", process.env.EXTENSION_START_URL);
+  console.error(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`);
+  return spawnScriptStreaming(reattachScript, reattachArgs, target);
 }
 async function extensionRebuild(target) {
   const runtimeDirRel = recipeRuntimeDir();
@@ -35,6 +90,7 @@ async function extensionRebuild(target) {
   return result;
 }
 export {
+  extensionReattach,
   extensionRebuild,
   launchExtension
 };

package/dist/mm-harness-cli.js

@@ -230,8 +230,10 @@ Example:
   Launch the app \u2014 quick relaunch by default; --build for a full native/webpack build.
   Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
   --sidepanel to override). core is headless (teaching error \u2014 use verify/run).
+  Extension quick launch REUSES a healthy live runtime (reload in place, no rebuild);
+  --build is the escape hatch that always clean-builds + relaunches a fresh runtime.
 
-  --build                            Full native/webpack build tier (default = quick relaunch)
+  --build                            Full clean build + relaunch (escape hatch; skips extension reuse)
   --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
   --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
   --watch                            Persistent webpack watcher then relaunch (extension only)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"