@deeeed/metamask-harness 0.72.0 → 0.74.0

package/dist/commands/launch/extension.js

@@ -12,7 +12,8 @@ import {
   importRecipeHarnessRuntimeCdp,
   recipeHarnessPath,
   recipeRuntimeDir,
-  runnerDir
+  runnerDir,
+  walletFixturePath
 } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
 import {
@@ -29,9 +30,16 @@ import {
 import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { isExtensionWatcherLive, stopExtensionWatcher } from "../../adapters/slot-ports.js";
-import { EXIT, spawnScriptStreaming } from "../shared.js";
+import { EXIT, spawnScript, spawnScriptStreaming } from "../shared.js";
 import { readExtensionPinnedFlags } from "../../adapters/extension/feature-flags.js";
-import { sameFeatureFlags } from "../../feature-flags.js";
+import { ensureExtensionConsoleCapture } from "../../adapters/extension/console-capture.js";
+import {
+  fixtureFeatureFlags,
+  sameFeatureFlags,
+  toRemoteFlagSpec
+} from "../../feature-flags.js";
+import { RECOVERY_CODE } from "../../heal-bounds.js";
+import { shellQuote } from "./device.js";
 const { CdpSession } = await importRecipeHarnessRuntimeCdp();
 const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
   path.join(runnerDir, "adapters/extension/lib/chrome-args.cjs")
@@ -479,9 +487,301 @@ async function extensionRebuild(target, remoteFlags) {
   }
   return result;
 }
+const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
+function verifyExtensionPin(target, requested) {
+  const pinned = readExtensionPinnedFlags(target);
+  if (pinned.error) {
+    return {
+      ok: false,
+      flags: {},
+      code: "RUNTIME_MANIFEST_UNREADABLE",
+      message: `the launched dist snapshot manifest could not be read (${pinned.sourcePath ?? "unknown path"}): ${pinned.error}`
+    };
+  }
+  if (pinned.overrides !== null && pinned.pinned === null) {
+    return {
+      ok: false,
+      flags: {},
+      code: "REMOTE_FLAG_NOT_APPLIED",
+      message: `the launched dist snapshot manifest (${pinned.sourcePath ?? "unknown path"}) carries no harness pin record; it was not written by this launch.`
+    };
+  }
+  const actual = pinned.pinned ?? {};
+  if (!sameFeatureFlags(actual, requested)) {
+    const mismatched = [.../* @__PURE__ */ new Set([...Object.keys(requested), ...Object.keys(actual)])].filter(
+      (key) => JSON.stringify(actual[key]) !== JSON.stringify(requested[key])
+    );
+    return {
+      ok: false,
+      flags: {},
+      code: "REMOTE_FLAG_NOT_APPLIED",
+      message: `the remote feature-flag pin ${toRemoteFlagSpec(requested) || "(none)"} does not match the launched snapshot manifest: ` + mismatched.map((key) => `${key} expected ${JSON.stringify(requested[key])}, got ${JSON.stringify(actual[key])}`).join("; ")
+    };
+  }
+  return { ok: true, flags: actual, message: "" };
+}
+function extensionQuickReattachFailed(output) {
+  return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
+}
+function extensionRuntimeBlocked(output) {
+  return /ERR_BLOCKED_BY_CLIENT|has been blocked by Chromium/u.test(output);
+}
+function extensionBrowserMissing(output) {
+  return /Playwright Chromium is not installed|No compatible Chromium binary selected/u.test(output);
+}
+function extensionProductConfigMissing(output) {
+  return /EXTENSION_PRODUCT_CONFIG_REQUIRED:/u.test(output);
+}
+function extensionEvmRpcUnreachable(output) {
+  return /EVM_RPC_UNREACHABLE|EVM RPC readiness probe failed|Infura configured ≠ RPC reachable/u.test(output);
+}
+const extensionLaunchProfile = {
+  refuseFlags({ target }, { watch, runway, clearMetro, remoteFlagSpec }) {
+    if (runway) return { message: "runway is mobile-only.", userAction: "drop --runway for the extension" };
+    if (clearMetro) return { message: "--clear-metro is mobile-only.", userAction: "drop --clear-metro for the extension" };
+    if (remoteFlagSpec !== void 0 && watch) {
+      return {
+        message: "--remote-flag cannot be applied with --watch: the watcher never re-creates the dist snapshot that carries the pin.",
+        userAction: `mm-harness launch --adapter extension --remote-flag ${remoteFlagSpec} --target ${shellQuote(target)}`
+      };
+    }
+    return void 0;
+  },
+  // --url: initial main-tab page for extension launches (dapp beside the
+  // sidepanel); travels to live.sh/launch-browser via env. Sidepanel mode has a
+  // useful default so `mm-harness launch --sidepanel` opens a working dapp, not
+  // just a wallet panel with no page to connect from.
+  start({ options, displayMode, machine, wantWatch, tier }) {
+    const requestedUrl = typeof options["url"] === "string" && options["url"] ? options["url"] : "";
+    if (requestedUrl || displayMode === "sidepanel") {
+      process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
+    }
+    if (machine) return;
+    const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
+    const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
+    console.error(colorHumanMessage(
+      `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
+    ));
+  },
+  nativeInputs: ["package.json", "yarn.lock", "webpack.config.js"],
+  rebuildCommand: () => "mm-harness launch --build",
+  // Source-development launch paths require checkout tooling. A verified local
+  // release artifact can reuse its healthy browser without building or watching.
+  async healthcheck(launch, state) {
+    const { target, tier, wantWatch, heal, stream } = launch;
+    const artifact = releaseArtifactState(target);
+    const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+    const verifiedReleaseReuse = artifact.status === "valid" && reusable;
+    const verifiedReleaseLaunch = !wantWatch && tier !== "build" && artifact.status === "valid" && runtimeDistCheck(target, artifact).status === "fresh";
+    const willBuild = !reusable;
+    if (willBuild) {
+      const productConfigBlock = extensionProductConfigBlock(target);
+      if (productConfigBlock) {
+        return launch.fail(state, {
+          code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+          message: productConfigBlock.message,
+          recoverable: false,
+          userAction: productConfigBlock.userAction,
+          exitCode: EXIT.infra
+        });
+      }
+    }
+    const depsBlock = verifiedReleaseReuse || verifiedReleaseLaunch ? null : extensionDepsBlock(target);
+    if (depsBlock) {
+      if (heal === "off") return launch.usage(depsBlock.message, depsBlock.userAction);
+      const recoveryCode = "deps.installed";
+      state.attemptedRecoveries.push(recoveryCode);
+      stream.phase("recover");
+      const repaired = await installExtensionDeps(target);
+      if (repaired.status !== 0 || extensionDepsBlock(target)) {
+        return launch.fail(state, {
+          code: "DEPENDENCY_INSTALL_FAILED",
+          message: depsBlock.message,
+          recoverable: false,
+          userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
+          originalError: repaired.output,
+          exitCode: EXIT.infra
+        });
+      }
+      state.recovered.push(recoveryCode);
+      state.mutations.push({ type: "dependencies", action: "installed", path: target });
+    }
+    return void 0;
+  },
+  compose: ({ target, wantWatch, displayMode, remoteFlagRequest }, tier) => launchExtension(target, tier, wantWatch, displayMode, remoteFlagRequest),
+  classify({ target, remoteFlagRequest }, output) {
+    if (output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
+      return {
+        code: "REMOTE_FLAG_NOT_PINNABLE",
+        message: `a verified release artifact cannot carry a remote feature-flag pin (${remoteFlagRequest?.spec ?? ""}); its manifest is signed evidence and is never rewritten. Validate the artifact as shipped (drop --remote-flag and the fixture's remoteFeatureFlags) or validate the variant on a source build.`,
+        recoverable: false,
+        // The next step must leave the artifact alone: a --build here would replace
+        // the artifact under validation with a source build.
+        userAction: Object.keys(fixtureFeatureFlags(walletFixturePath(target))).length > 0 ? `remove remoteFeatureFlags from ${shellQuote(walletFixturePath(target))}, then: mm-harness launch --adapter extension --target ${shellQuote(target)}` : `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+        exitCode: EXIT.infra,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (extensionProductConfigMissing(output)) {
+      const block = extensionProductConfigBlock(target);
+      return {
+        code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+        message: block?.message ?? "Extension product configuration was not ready when the build started.",
+        recoverable: false,
+        userAction: block?.userAction ?? `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+        exitCode: EXIT.infra
+      };
+    }
+    if (extensionBrowserMissing(output)) {
+      return {
+        code: "EXTENSION_BROWSER_REQUIRED",
+        message: "the checkout Playwright browser is not installed; system Chrome is not a compatible unpacked-extension fallback. Installing the browser cache requires user approval.",
+        recoverable: false,
+        userAction: `ask the user for approval, then run: cd ${shellQuote(target)} && yarn playwright install chromium`,
+        exitCode: EXIT.infra
+      };
+    }
+    if (output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") || output.includes("EXTENSION_STARTUP_UNVERIFIED:")) {
+      return {
+        code: output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") ? "EXTENSION_BACKGROUND_UNRESPONSIVE" : "EXTENSION_STARTUP_UNVERIFIED",
+        message: "Extension startup is not healthy; inspect the background error before restarting or resetting wallet state.",
+        recoverable: false,
+        userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (output.includes("EVM_RPC_EXECUTION_FAILED:")) {
+      return {
+        code: "EVM_RPC_EXECUTION_FAILED",
+        message: "Background RPC fetch failed during JavaScript execution; this does not establish an Infura authentication or connectivity failure.",
+        recoverable: false,
+        userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    if (extensionEvmRpcUnreachable(output)) {
+      return {
+        code: "EVM_RPC_UNREACHABLE",
+        message: "EVM RPC readiness failed; Infura configured does not mean RPC reachable.",
+        recoverable: false,
+        userAction: `Check the effective INFURA_PROJECT_ID from the environment, .metamaskprodrc, or ${shellQuote(path.join(target, ".metamaskrc"))}, then rerun: mm-harness launch --verify --target ${shellQuote(target)}`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      };
+    }
+    return void 0;
+  },
+  async beforeHeal(launch, attempt, state) {
+    if (launch.tier !== "quick" || !extensionQuickReattachFailed(attempt.output)) return void 0;
+    const recoveryCode = "chrome.relaunched";
+    state.attemptedRecoveries.push(recoveryCode);
+    launch.stream.phase("recover");
+    const rebuildAttempt = await launch.compose("build");
+    if (rebuildAttempt.status === 0) {
+      state.recovered.push(recoveryCode);
+      return await launch.settle(state, rebuildAttempt.remoteFeatureFlags);
+    }
+    return launch.fail(state, {
+      code: "EXTENSION_RELAUNCH_FAILED",
+      message: "quick reattach failed, and clean relaunch failed too.",
+      recoverable: false,
+      exitCode: EXIT.infra,
+      originalError: rebuildAttempt.output.trim() || void 0
+    });
+  },
+  recovery: () => ({ code: RECOVERY_CODE.extension, restartApp: false }),
+  // --watch only restarts the webpack watcher; the snapshot, and its pin, are
+  // untouched, so the live record is reported rather than verified against a
+  // request the watcher could never apply (--remote-flag is refused with it;
+  // the fixture baseline stays whatever the last launch pinned).
+  provenFlags({ target, wantWatch, remoteFlagRequest }, requested) {
+    if (wantWatch) return { flags: readExtensionPinnedFlags(target).pinned };
+    const pinned = verifyExtensionPin(target, requested);
+    if (pinned.ok) return { flags: pinned.flags };
+    const spec = remoteFlagRequest?.spec;
+    return {
+      code: pinned.code ?? "REMOTE_FLAG_NOT_APPLIED",
+      message: pinned.message,
+      recoverable: false,
+      // A rebuild re-creates the snapshot; the flag is repeated only when one was asked for.
+      userAction: `mm-harness launch --adapter extension --build${spec ? ` --remote-flag ${spec}` : ""} --target ${shellQuote(target)}`,
+      exitCode: EXIT.runtime
+    };
+  },
+  async finish(launch, state, sidepanelRecoveryAllowed) {
+    const { target, machine, displayMode, tier, stream } = launch;
+    const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
+    if (displayMode === "fullscreen") {
+      const sidepanelArgs = ["close"];
+      if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+      const fullscreen = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
+      if (fullscreen.status !== 0) {
+        return launch.fail(state, {
+          code: "FULLSCREEN_OPEN_FAILED",
+          message: "app launched but restoring the fullscreen Extension surface failed.",
+          recoverable: false,
+          userAction: `bash adapters/extension/sidepanel-toggle.sh close --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+          exitCode: EXIT.runtime,
+          originalError: fullscreen.output.trim() || void 0
+        });
+      }
+    }
+    if (displayMode === "sidepanel") {
+      const sidepanelArgs = ["open"];
+      if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+      if (!machine) {
+        console.error(
+          `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
+        );
+      }
+      const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
+      if (sidepanel.status !== 0) {
+        const recoveryCode = "chrome.relaunched";
+        if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
+          state.attemptedRecoveries.push(recoveryCode);
+          stream.phase("recover");
+          const rebuildAttempt = await launch.compose("build");
+          if (rebuildAttempt.status === 0) {
+            state.recovered.push(recoveryCode);
+            return await launch.settle(state, void 0, false);
+          }
+          return launch.fail(state, {
+            code: "EXTENSION_RELAUNCH_FAILED",
+            message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
+            recoverable: false,
+            exitCode: EXIT.infra,
+            originalError: rebuildAttempt.output.trim() || void 0
+          });
+        }
+        return launch.fail(state, {
+          code: "SIDEPANEL_OPEN_FAILED",
+          message: "app launched but opening the side panel failed.",
+          recoverable: false,
+          userAction: `bash adapters/extension/sidepanel-toggle.sh open --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+          exitCode: EXIT.runtime,
+          originalError: sidepanel.output.trim() || void 0
+        });
+      }
+    }
+    try {
+      await ensureExtensionConsoleCapture(target);
+    } catch (error) {
+      if (!machine) {
+        console.error(`WARN: Extension console capture unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return void 0;
+  },
+  verifyArgs: () => process.env.CDP_PORT ? ["--cdp-port", process.env.CDP_PORT] : [],
+  platformLabel: ({ mobileTarget, displayMode }) => mobileTarget ?? displayMode,
+  deviceLabel: ({ displayMode }) => displayMode
+};
 export {
   extensionDepsBlock,
   extensionLaunchDevelopment,
+  extensionLaunchProfile,
   extensionReattach,
   extensionRebuild,
   extensionRuntimeReusable,