@deeeed/metamask-harness 0.69.0 → 0.70.0

package/adapters/shared/open-debug.mjs

@@ -475,8 +475,13 @@ async function openBrokeredMobileDebugger(port, shouldOpen) {
 function pickExtensionTarget(targets, targetKind) {
   const extensionTargets = targets.filter((target) => String(target.url || '').startsWith('chrome-extension://'));
   if (targetKind === 'worker') {
+    // Branded Chrome runs component extensions with their own service workers;
+    // prefer the worker of the extension whose wallet page is open.
+    const walletPage = extensionTargets.find((target) => /\/(home|sidepanel)\.html/u.test(String(target.url || '')));
+    const walletId = process.env.RECIPE_HARNESS_EXTENSION_ID || (walletPage ? String(walletPage.url).split('/')[2] : '');
     return (
-      extensionTargets.find((target) => target.type === 'service_worker')
+      (walletId && extensionTargets.find((target) => target.type === 'service_worker' && String(target.url).startsWith(`chrome-extension://${walletId}/`)))
+      || extensionTargets.find((target) => target.type === 'service_worker')
       || targets.find((target) => target.type === 'service_worker' && String(target.url || '').startsWith('chrome-extension://'))
       || null
     );

package/dist/commands/run-engine.js

@@ -44,6 +44,7 @@ import {
   beginRunDiagnostics,
   finishRunDiagnostics
 } from "../run-diagnostics.js";
+import { executedBrowser, recipeCdpPorts } from "./run-report.js";
 import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
@@ -155,7 +156,13 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
       finalized.artifactManifestPath,
       effectsState
     );
-    return finalized;
+    const browser = executedBrowser(
+      adapter,
+      projectRoot,
+      finalized.artifactManifestPath,
+      recipeCdpPorts(runRequest)
+    );
+    return browser ? { ...finalized, browser } : finalized;
   } finally {
     restoreRuntimeEnvironment();
   }

package/dist/commands/run-report.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { recipeRuntimeDir } from "../paths.js";
 import { isRecord } from "./parse-args.js";
 function writeRunReport(result) {
   const summaryPath = String(result.summaryPath);
@@ -20,7 +22,7 @@ function writeRunReport(result) {
     preview: lines.filter((line) => line.startsWith("- ")).slice(0, 6).map((line) => line.slice(2))
   };
 }
-function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
+function indexProductProvenanceArtifact(artifactManifestPath, target, adapter, browser = null) {
   const artifactsDir = path.dirname(artifactManifestPath);
   let gitRef = "unknown";
   let branch = "unknown";
@@ -53,7 +55,8 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
     repository: path.basename(path.resolve(target)),
     git_ref: gitRef,
     branch,
-    dirty
+    dirty,
+    ...browser ? { browser } : {}
   };
   fs.writeFileSync(
     path.join(artifactsDir, "product-provenance.json"),
@@ -77,7 +80,13 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
       type: "json",
       label: "Product checkout provenance",
       category: "system",
-      metadata: { adapter, git_ref: gitRef, branch, dirty }
+      metadata: {
+        adapter,
+        git_ref: gitRef,
+        branch,
+        dirty,
+        ...browser?.boundTo && browser.boundTo !== "none" ? { browser: browser.browser, browser_version: browser.version, browser_source: browser.source, extension_loading: browser.extensionLoading } : {}
+      }
     }
   ];
   fs.writeFileSync(
@@ -86,6 +95,87 @@ function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
 `
   );
 }
+function readRecord(file) {
+  try {
+    const recorded = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isRecord(recorded) ? recorded : null;
+  } catch {
+    return null;
+  }
+}
+const browserCdp = createRequire(import.meta.url)("../../adapters/shared/browser-cdp.cjs");
+function verifyLaunch(record, cdpPort) {
+  const launch = isRecord(record.launch) ? record.launch : {};
+  const pid = Number(launch.pid);
+  const port = Number(launch.cdpPort);
+  if (!Number.isInteger(pid) || !Number.isInteger(port) || typeof launch.profile !== "string" || typeof launch.processStartedAt !== "string") {
+    return "the browser record has no process identity (pid, start time, profile, CDP port)";
+  }
+  if (cdpPort && port !== Number(cdpPort)) return `the browser record is for CDP port ${port}, not ${cdpPort}`;
+  try {
+    const owner = browserCdp.cdpOwner(port, launch.profile);
+    if (owner.pid !== pid || owner.startedAt !== launch.processStartedAt) {
+      return `CDP port ${port} is now held by another browser process than the recorded pid ${pid}`;
+    }
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  return null;
+}
+function resolveTemplatedPort(value, params, recipe) {
+  let resolved = value;
+  const template = /^\{\{\s*params\.([\w-]+)\s*\}\}$/u.exec(String(value).trim());
+  if (template) {
+    const name = template[1];
+    const schema = isRecord(recipe) && isRecord(recipe.paramsSchema) && isRecord(recipe.paramsSchema.properties) ? recipe.paramsSchema.properties[name] : void 0;
+    resolved = isRecord(params) && params[name] !== void 0 ? params[name] : isRecord(schema) ? schema.default : void 0;
+  }
+  const text = String(resolved ?? "").trim();
+  return /^\d+$/u.test(text) ? text : null;
+}
+function recipeCdpPorts(request) {
+  const ports = /* @__PURE__ */ new Set();
+  const envPort = request.env?.CDP_PORT || request.env?.RECIPE_CDP_PORT;
+  if (envPort) ports.add(String(envPort));
+  let recipe = request.recipeDocument;
+  if (recipe === void 0 && request.recipePath) {
+    try {
+      recipe = JSON.parse(fs.readFileSync(request.recipePath, "utf8"));
+    } catch {
+      recipe = void 0;
+    }
+  }
+  const workflow = isRecord(recipe) && isRecord(recipe.workflow) ? recipe.workflow : null;
+  const nodes = workflow && isRecord(workflow.nodes) ? Object.values(workflow.nodes) : [];
+  for (const node of nodes) {
+    if (!isRecord(node) || node.cdp_port === void 0 || node.cdp_port === null) continue;
+    const port = resolveTemplatedPort(node.cdp_port, request.params, recipe);
+    ports.add(port ?? `unresolved ${String(node.cdp_port)}`);
+  }
+  return [...ports];
+}
+function executedBrowser(adapter, target, artifactManifestPath, ports) {
+  if (adapter !== "extension") return null;
+  if (ports.length === 0) return { boundTo: "none", reason: "the run had no known CDP port" };
+  if (ports.length > 1) return { boundTo: "none", reason: `the run drove several CDP ports (${ports.join(", ")})` };
+  return launchedBrowser(target, path.dirname(artifactManifestPath), ports[0]);
+}
+function launchedBrowser(target, artifactsDir, cdpPort) {
+  const runtime = readRecord(path.join(artifactsDir, "extension-runtime", "runtime.json"));
+  const autolaunched = runtime && isRecord(runtime.browser) ? runtime.browser : null;
+  const candidates = [];
+  if (autolaunched) candidates.push([autolaunched, "run-autolaunch"]);
+  const slot = readRecord(path.join(path.resolve(target), recipeRuntimeDir(), "browser-resolution.json"));
+  if (slot) candidates.push([slot, "slot-runtime"]);
+  if (candidates.length === 0) return null;
+  const reasons = [];
+  for (const [record, boundTo] of candidates) {
+    const problem = verifyLaunch(record, cdpPort);
+    if (problem === null) return { ...record, boundTo };
+    reasons.push(`${boundTo}: ${problem}`);
+  }
+  return { boundTo: "none", reason: reasons.join("; ") };
+}
 function renderRunReport(summary, entries) {
   const lines = [
     "# MetaMask Recipe Run",
@@ -187,6 +277,9 @@ function indexRunReportArtifact(artifactManifestPath) {
 `);
 }
 export {
+  executedBrowser,
   indexProductProvenanceArtifact,
+  launchedBrowser,
+  recipeCdpPorts,
   writeRunReport
 };

package/dist/commands/run.js

@@ -376,7 +376,8 @@ async function handleRunInner({ positional, options }, stream) {
     indexProductProvenanceArtifact(
       result.artifactManifestPath,
       target,
-      adapter
+      adapter,
+      result.browser ?? null
     );
     if (violation !== null) {
       const userAction = violation.userAction ?? `inspect ${shellQuote(result.summaryPath)} and ${shellQuote(result.tracePath)}; fix the application or recipe failure before retrying`;

package/dist/doctor.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -167,7 +168,7 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
     },
     ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : [],
-    ...adapter === "extension" ? [extensionBrowserDoctorCheck(target)] : []
+    ...adapter === "extension" ? [extensionBrowserDoctorCheck(target), extensionBrowserResolutionDoctorCheck(target)] : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -214,6 +215,51 @@ function extensionBrowserDoctorCheck(target) {
     userAction: "yarn playwright install chromium"
   };
 }
+function extensionBrowserResolutionDoctorCheck(target) {
+  const resolver = path.join(runnerDir, "adapters/shared/browser-resolver.cjs");
+  const runtime = path.join(path.resolve(target), recipeRuntimeDir());
+  const record = path.join(runtime, "browser-resolution.json");
+  let profile = process.env.CHROME_USER_DATA_DIR || path.join(runtime, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile");
+  while (profile.length > 1 && profile.endsWith("/")) profile = profile.slice(0, -1);
+  const profileExists = fs.existsSync(path.join(profile, "Local State"));
+  const result = spawnSync(process.execPath, [
+    resolver,
+    "resolve",
+    "--target",
+    path.resolve(target),
+    "--launch-method",
+    "launch-services",
+    "--display",
+    "headful",
+    ...profileExists && fs.existsSync(record) ? ["--recorded", record] : [],
+    "--json"
+  ], {
+    cwd: path.resolve(target),
+    encoding: "utf8",
+    timeout: 135e3
+  });
+  if (result.status === 0) {
+    const resolution = JSON.parse(result.stdout);
+    const managed = resolution.managedChrome;
+    const managedNote = managed && !resolution.warning ? ` Google Chrome is managed by policy (${managed.forcedExtensions.length} forced extension${managed.forcedExtensions.length === 1 ? "" : "s"}: ${managed.forcedExtensions.map(({ id, name }) => name ? `${id} (${name})` : id).join(", ")}${managed.signinForced ? "; browser sign-in forced" : ""}); slots use Chrome for Testing.` : "";
+    const probe = resolution.probe ? `; Chrome for Testing probe (${resolution.probe.launchMethod}, ${resolution.probe.display}${resolution.probe.cached ? ", cached" : ""}${resolution.probe.transient ? `, retried after ${resolution.probe.expiresAt}` : ""}): ${resolution.probe.reason}` : resolution.recordedFrom ? `; kept from the slot profile record ${resolution.recordedFrom}` : "";
+    return {
+      id: "extension-browser",
+      status: "pass",
+      required: false,
+      message: `Launch browser: ${resolution.browser} ${resolution.version ?? "(unknown version)"} via ${resolution.source} (${resolution.mode}); extension loading: ${resolution.extensionLoading}${probe}.${managedNote}${resolution.warning ? ` Warning: ${resolution.warning}` : ""}`,
+      detail: resolution.bin
+    };
+  }
+  const message = (result.stderr || result.error?.message || "browser resolution failed").trim();
+  return {
+    id: "extension-browser",
+    status: "fail",
+    required: message.includes("BROWSER_UNLAUNCHABLE:"),
+    message,
+    userAction: "install Google Chrome, or set RECIPE_HARNESS_BROWSER / RECIPE_HARNESS_CHROME_BIN to a browser that starts"
+  };
+}
 function mobileToolDoctorChecks(platform) {
   const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
     { tool: "adb", platform: "Android" },
@@ -294,6 +340,7 @@ export {
   compatibilityMode,
   createDoctorReport,
   extensionBrowserDoctorCheck,
+  extensionBrowserResolutionDoctorCheck,
   fixtureFileSummary,
   fixtureSummary,
   mobileToolDoctorChecks,

package/docs/QA.md

@@ -94,6 +94,9 @@ mm-harness debug
   `EXTENSION_PRODUCT_CONFIG_REQUIRED` before build or browser startup.
 - [ ] Missing Chromium returns `EXTENSION_BROWSER_REQUIRED` without using system
   Chrome.
+- [ ] `doctor --adapter extension` names the launch browser, its version, why
+  it was chosen and how the extension loads; `RECIPE_HARNESS_BROWSER=cft`
+  restores Chrome for Testing, `=chrome` loads into Google Chrome over CDP.
 - [ ] Launch uses the checkout-owned profile, opens one MetaMask surface, avoids
   keychain prompts, and preserves keyboard focus by default.
 - [ ] A second launch reuses the watcher/profile without duplicate tabs.

package/library/actions/extension/platform/cdp.mjs

@@ -19,6 +19,7 @@ import { closeSync, openSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   importRecipeHarnessRuntimeBrowserExtension,
@@ -368,24 +369,26 @@ function autolaunchEnabled(input) {
     process.env.METAMASK_RECIPE_EXTENSION_LAUNCH_EXISTING_DIST === '1';
 }
 
-function projectRequire(projectRoot) {
-  return createRequire(path.join(projectRoot, 'package.json'));
-}
+const runnerRequire = createRequire(import.meta.url);
+const runnerRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const browserResolver = runnerRequire(path.join(runnerRoot, 'adapters/shared/browser-resolver.cjs'));
+const { stopProfileProcessesSync } = runnerRequire(path.join(runnerRoot, 'adapters/extension/lib/validation-process-ownership.cjs'));
 
-function resolveChromeBinary(projectRoot) {
-  if (process.env.RECIPE_HARNESS_CHROME_BIN) return process.env.RECIPE_HARNESS_CHROME_BIN;
-  const requireFromProject = projectRequire(projectRoot);
-  for (const packageName of ['@playwright/test', 'playwright']) {
-    try {
-      const { chromium } = requireFromProject(packageName);
-      const executable = chromium.executablePath();
-      if (executable) return executable;
-    } catch (error) {
-      if (error?.code === 'MODULE_NOT_FOUND') continue;
-      throw error;
-    }
+// Same browser choice as the live launcher (RECIPE_HARNESS_BROWSER /
+// RECIPE_HARNESS_CHROME_BIN); branded Chrome loads the dist over CDP. This
+// launcher spawns a headful browser directly, so the probe does too, and a
+// reused profile keeps its recorded browser.
+async function resolveChromeBinary(projectRoot, recorded) {
+  try {
+    return await browserResolver.resolveBrowser({
+      cft: () => browserResolver.playwrightChromiumExecutable(projectRoot),
+      launchMethod: browserResolver.SPAWN,
+      display: browserResolver.HEADFUL,
+      recorded,
+    });
+  } catch (error) {
+    throw new Error(`Extension autolaunch could not select a browser: ${error.message}`);
   }
-  throw new Error('Extension autolaunch requires RECIPE_HARNESS_CHROME_BIN or Playwright installed in the target checkout.');
 }
 
 async function execNodeScript(script, args, options) {
@@ -446,7 +449,7 @@ async function findWalletFixture(projectRoot) {
   return null;
 }
 
-async function launchExistingDistRuntime(input, port) {
+export async function launchExistingDistRuntime(input, port) {
   const projectRoot = input.context.projectRoot;
   const artifactsDir = input.context.artifactsDir;
   const distDir = path.resolve(projectRoot, input.node?.dist_dir || process.env.METAMASK_RECIPE_EXTENSION_DIST_DIR || 'dist/chrome');
@@ -476,12 +479,23 @@ async function launchExistingDistRuntime(input, port) {
     fixtureSeeded = true;
   }
 
-  const chrome = resolveChromeBinary(projectRoot);
+  // Never start a second browser on a port something else holds: whatever
+  // answers there afterwards would not be ours to load or seed.
+  const holders = browserResolver.cdpListenerPids(port);
+  if (holders.length > 0) {
+    throw new Error(`Extension autolaunch refused: CDP port ${port} is already held by pid ${holders.join(', ')}. Next: stop that browser or choose a free --cdp-port.`);
+  }
+  // Next to the profile, so a reused profile (METAMASK_RECIPE_EXTENSION_PROFILE_DIR)
+  // finds the browser it was created with.
+  const browserRecord = `${profileDir}.browser.json`;
+  const profileExisted = await canAccess(path.join(profileDir, 'Local State'));
+  const browser = await resolveChromeBinary(projectRoot, profileExisted ? browserRecord : null);
+  const loadsOverCdp = browser.extensionLoading === browserResolver.CDP_LOAD_UNPACKED;
   const stdoutFd = openSync(path.join(logsDir, 'chrome.log'), 'a');
   const stderrFd = openSync(path.join(logsDir, 'chrome.log'), 'a');
   let child;
   try {
-    child = spawn(chrome, [
+    child = spawn(browser.bin, [
       `--user-data-dir=${profileDir}`,
       ...(process.platform === 'darwin' ? ['--use-mock-keychain'] : []),
       '--remote-debugging-address=127.0.0.1',
@@ -493,8 +507,7 @@ async function launchExistingDistRuntime(input, port) {
       '--disable-extensions-file-access-check',
       '--disable-extensions-content-verification',
       '--disable-features=ExtensionContentVerification,DisableLoadExtensionCommandLineSwitch',
-      `--disable-extensions-except=${runtimeDist}`,
-      `--load-extension=${runtimeDist}`,
+      ...browserResolver.extensionLaunchArgs(runtimeDist, browser.extensionLoading),
       'chrome://extensions/',
     ], {
       cwd: projectRoot,
@@ -516,32 +529,58 @@ async function launchExistingDistRuntime(input, port) {
   }
   child.unref();
   await writeFile(path.join(logsDir, 'chrome.pid'), `${child.pid}\n`);
-  await retryJsonGet(`http://127.0.0.1:${port}/json/version`, 45000);
-
   let fixtureValidation = null;
-  if (fixtureSeeded) {
-    fixtureValidation = path.join(logsDir, 'fixture-account-parity.json');
-    await execNodeScript(
-      fixtureScript,
-      [
-        'seed-cdp',
-        '--target',
-        projectRoot,
-        '--fixture',
-        fixture,
-        '--state',
-        fixtureState,
-        '--cdp-port',
-        String(port),
-        '--extension-dir',
-        runtimeDist,
-        '--extension-id-file',
-        extensionIdFile,
-        '--out',
-        fixtureValidation,
-      ],
-      { cwd: projectRoot },
-    );
+  let launchedBrowser = null;
+  try {
+    await retryJsonGet(`http://127.0.0.1:${port}/json/version`, 45000);
+    const owner = browserResolver.waitForCdpOwner(port, profileDir);
+    const cdpLoad = loadsOverCdp ? await browserResolver.loadUnpackedOverPort(port, runtimeDist, { profile: profileDir }) : null;
+    launchedBrowser = {
+      ...browser,
+      launch: {
+        pid: owner.pid,
+        cdpPort: port,
+        startedAt: new Date().toISOString(),
+        profile: owner.profile,
+        processStartedAt: owner.startedAt,
+        ...(cdpLoad ? { extensionId: cdpLoad.id, otherExtensions: cdpLoad.otherExtensions } : {}),
+      },
+    };
+    await writeFile(browserRecord, `${JSON.stringify(launchedBrowser, null, 2)}\n`);
+    if (fixtureSeeded) {
+      fixtureValidation = path.join(logsDir, 'fixture-account-parity.json');
+      await execNodeScript(
+        fixtureScript,
+        [
+          'seed-cdp',
+          '--target',
+          projectRoot,
+          '--fixture',
+          fixture,
+          '--state',
+          fixtureState,
+          '--cdp-port',
+          String(port),
+          '--extension-dir',
+          runtimeDist,
+          '--extension-id-file',
+          extensionIdFile,
+          '--out',
+          fixtureValidation,
+        ],
+        { cwd: projectRoot },
+      );
+    }
+  } catch (error) {
+    // The launch failed after the browser started: stop it before reporting,
+    // so no detached browser outlives this action. A failed stop is reported
+    // with the original failure, never swallowed.
+    try {
+      stopProfileProcessesSync(profileDir, { extraPids: [child.pid] });
+    } catch (stopError) {
+      throw new Error(`${error.message}\nStopping the autolaunched browser (pid ${child.pid}, profile ${profileDir}) also failed: ${stopError.message}`, { cause: error });
+    }
+    throw error;
   }
 
   await writeFile(path.join(runtimeRoot, 'runtime.json'), `${JSON.stringify({
@@ -553,6 +592,8 @@ async function launchExistingDistRuntime(input, port) {
     profileDir,
     fixtureSeeded,
     fixtureValidation,
+    browser: launchedBrowser,
+    browserRecord,
     launchedAt: new Date().toISOString(),
   }, null, 2)}\n`);
   return { launched: true, pid: child.pid, runtimeRoot, fixtureSeeded };

package/package.json

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

package/scripts/site-contrast.mjs

@@ -449,8 +449,12 @@ async function checkBehavior(browserEndpoint, port, pages) {
         return checked;
       })()
     `);
-    if (!previews.includes('review-pr/static-perps.mobile') || !previews.includes('qa/default')) {
-      throw new Error('Static review and QA previews must both be available');
+    if (!['fix-bug/extension', 'fix-bug/mobile', 'qa/default'].every(id => previews.includes(id))) {
+      throw new Error('Runtime workflow previews must be available');
+    }
+    const reviewSource = await page.evaluate("document.querySelector('[data-static-review-source]')?.href");
+    if (!reviewSource?.endsWith('/domains/perps/skills/perps-review-pr/skill.md')) {
+      throw new Error('Static review must link to its owning skill');
     }
     const progress = await page.evaluate(String.raw`
       (() => {
@@ -514,7 +518,16 @@ async function checkBehavior(browserEndpoint, port, pages) {
                 await new Promise((resolve) => setTimeout(resolve, 100));
               }
             }
-            if (!response?.ok) failures.push(url.pathname + ' (' + (response?.status ?? 'network') + ')');
+            if (!response?.ok) {
+              failures.push(url.pathname + ' (' + (response?.status ?? 'network') + ')');
+            } else if (url.hash) {
+              const target = url.pathname === location.pathname
+                ? document
+                : new DOMParser().parseFromString(await response.text(), 'text/html');
+              if (!target.getElementById(decodeURIComponent(url.hash.slice(1)))) {
+                failures.push(url.pathname + url.hash + ' (missing anchor)');
+              }
+            }
           }
           return failures;
         })()