@deeeed/metamask-harness 0.34.4 → 0.36.0

package/dist/commands/fixtures.js

@@ -48,7 +48,7 @@ function fixturesStatus(options) {
   const fixture = { ...summary, path: canonical };
   const ready = summary.status === "ready";
   const nextCommand = ready ? "mm-harness fixtures set" : "mm-harness fixtures init --from <path>   # or: mm-harness fixtures init --dev";
-  const operations = adapter === "extension" ? ["init", "sync", "set", "generate", "finalize"] : ["init", "sync", "set"];
+  const operations = adapter === "extension" ? ["init", "sync", "set", "reset", "generate", "finalize"] : adapter === "mobile" ? ["init", "sync", "set", "reset"] : ["init", "sync", "set"];
   if (json) {
     console.log(JSON.stringify({
       schemaVersion: 1,
@@ -103,8 +103,8 @@ async function handleFixturesLocked(argv) {
   const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
   const json = flag(options, "json");
   const sub = positional[0];
-  if (sub !== "init" && sub !== "sync" && sub !== "set" && sub !== "generate" && sub !== "finalize") {
-    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <init|sync|set|generate|finalize>", "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
+  if (sub !== "init" && sub !== "sync" && sub !== "set" && sub !== "reset" && sub !== "generate" && sub !== "finalize") {
+    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <init|sync|set|reset|generate|finalize>", "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
   }
   if (sub !== "init" && (flag(options, "dev") || flag(options, "force") || str(options, "from"))) {
     return usageOut(
@@ -121,7 +121,7 @@ async function handleFixturesLocked(argv) {
   }
   const surface = getAdapterSurface(adapter);
   surface.resolveSlotPorts(target);
-  const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
+  const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: sub === "reset", rerun: "" });
   if ("code" in dtResult) {
     return usageOut(json, "fixtures", dtResult.message, dtResult.userAction);
   }
@@ -129,6 +129,9 @@ async function handleFixturesLocked(argv) {
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
   const canonicalFixture = walletFixturePath(target);
   if (sub === "init") return fixturesInit(adapter, target, options, json);
+  if (sub === "reset" && surface.headless) {
+    return usageOut(json, "fixtures", "fixtures reset requires a Mobile or Extension client.", "use fixtures set for the core adapter");
+  }
   if (surface.headless && sub === "set") {
     const fixture = fixtureSummary(target, adapter);
     if (fixture.status !== "ready") {
@@ -139,7 +142,7 @@ async function handleFixturesLocked(argv) {
     else console.error(message);
     return EXIT.ok;
   }
-  const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures set`;
+  const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures ${sub}`;
   if (sub === "sync") {
     const exitCode = fixturesSync(adapter, target, json);
     if (json) {
@@ -162,34 +165,105 @@ async function handleFixturesLocked(argv) {
       "mm-harness fixtures init --dev && mm-harness fixtures set"
     );
   }
+  if (sub === "reset") {
+    const selectedFixture = fixtureFileSummary(fixturePath, adapter, fixturePath);
+    if (selectedFixture.status !== "ready") {
+      return usageOut(
+        json,
+        "fixtures",
+        `wallet fixture is ${String(selectedFixture.status)} at ${fixturePath}; reset was not started.`,
+        `mm-harness fixtures init --from <path> --target ${target}`
+      );
+    }
+  }
   if (adapter === "extension") {
-    return applyExtensionFixture(target, fixturePath, canonicalFixture, json);
+    return applyExtensionFixture(target, fixturePath, canonicalFixture, json, sub);
   }
-  process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
+  const reset = sub === "reset";
+  process.stderr.write(`\u2192 fixtures ${sub} ${adapter} \u2014 ${reset ? "resetting selected app data, relaunching, then applying" : "connecting bridge + applying"} wallet fixture (can take ~30s)\u2026
 `);
   let status;
   let mobileSetupResult;
+  let resetError;
   if (adapter === "mobile") {
     const setupWalletSh = path.join(runnerDir, "adapters/mobile/bridge-runtime/setup-wallet.sh");
     const previousAppRoot = process.env.APP_ROOT;
     process.env.APP_ROOT = target;
     try {
+      if (reset) {
+        const platform = process.env.PLATFORM === "android" || process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+        const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "8081";
+        const resetAppData = path.join(runnerDir, "adapters/mobile/reset-app-data.sh");
+        const resetArgs = ["--platform", platform, "--target", target];
+        if (platform === "ios") {
+          resetArgs.push("--simulator", process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted");
+        } else if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+          resetArgs.push("--adb-serial", process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || "");
+        }
+        const resetResult = await spawnScriptStreaming(resetAppData, resetArgs, target, {
+          timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+        });
+        if (resetResult.status !== 0) {
+          resetError = new Error("Mobile app data reset failed.");
+        } else {
+          const prewarmBundle = path.join(runnerDir, "adapters/mobile/prewarm-bundle.sh");
+          const prewarmResult = await spawnScriptStreaming(
+            prewarmBundle,
+            ["--platform", platform, "--target", target, "--port", port],
+            target,
+            {
+              timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+            }
+          );
+          if (prewarmResult.status !== 0) {
+            resetError = new Error("Mobile bundle prewarm failed after app data reset.");
+          }
+        }
+        if (!resetError) {
+          const openDevice = path.join(runnerDir, "adapters/mobile/open-device.sh");
+          const openArgs = ["--platform", platform, "--target", target, "--port", port, "--preflight-mode", "fast", "--restart"];
+          if (platform === "ios") {
+            openArgs.push("--simulator", process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted");
+          } else if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+            openArgs.push("--adb-serial", process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || "");
+          }
+          const openResult = await spawnScriptStreaming(openDevice, openArgs, target, {
+            timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+          });
+          if (openResult.status !== 0) {
+            resetError = new Error("Mobile app relaunch after data reset failed.");
+          } else {
+            const waitForBridge = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
+            const waitResult = await spawnScriptStreaming(
+              waitForBridge,
+              ["--target", target, "--port", port, "--platform", platform],
+              target,
+              { timeoutMs: FIXTURE_STREAM_TIMEOUT_MS }
+            );
+            if (waitResult.status !== 0) {
+              resetError = new Error("Mobile bridge did not return after app data reset.");
+            }
+          }
+        }
+      }
       const configuredTimeout = Number(process.env.MM_HARNESS_FIXTURES_SET_TIMEOUT_MS ?? FIXTURE_STREAM_TIMEOUT_MS);
       const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : FIXTURE_STREAM_TIMEOUT_MS;
-      mobileSetupResult = await spawnScriptStreaming(
-        setupWalletSh,
-        ["--fixture", fixturePath],
-        target,
-        {
-          env: {
-            APP_ROOT: target,
-            WATCHER_PORT: process.env.WATCHER_PORT ?? "8081",
-            METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? "8081"
-          },
-          timeoutMs
-        }
-      );
-      status = mobileSetupResult.status === 0 ? "pass" : "fail";
+      if (!resetError) {
+        mobileSetupResult = await spawnScriptStreaming(
+          setupWalletSh,
+          ["--fixture", fixturePath],
+          target,
+          {
+            env: {
+              APP_ROOT: target,
+              WATCHER_PORT: process.env.WATCHER_PORT ?? "8081",
+              METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? "8081"
+            },
+            timeoutMs
+          }
+        );
+      }
+      status = !resetError && mobileSetupResult?.status === 0 ? "pass" : "fail";
     } finally {
       if (previousAppRoot === void 0) delete process.env.APP_ROOT;
       else process.env.APP_ROOT = previousAppRoot;
@@ -205,16 +279,17 @@ async function handleFixturesLocked(argv) {
         {
           schemaVersion: 1,
           command: "fixtures",
-          action: "set",
+          action: sub,
           adapter,
           fixture: fixturePath,
           canonicalFixture,
           status,
           exitCode: status === "pass" ? EXIT.ok : EXIT.runtime,
+          walletReset: reset && status === "pass",
           message: teaching,
           error: status === "fail" ? {
-            code: mobileSetupResult?.timedOut ? "SETUP_WALLET_TIMEOUT" : "SETUP_WALLET_FAILED",
-            message: mobileSetupResult?.timedOut ? `wallet fixture setup exceeded its ${String(mobileSetupResult.timeoutMs)}ms bound on Metro port ${process.env.WATCHER_PORT ?? "8081"}` : `wallet fixture setup failed on ${process.env.WATCHER_PORT ?? "8081"}`,
+            code: resetError ? "MOBILE_WALLET_RESET_FAILED" : mobileSetupResult?.timedOut ? "SETUP_WALLET_TIMEOUT" : "SETUP_WALLET_FAILED",
+            message: resetError ? `wallet reset failed: ${resetError instanceof Error ? resetError.message : String(resetError)}` : mobileSetupResult?.timedOut ? `wallet fixture setup exceeded its ${String(mobileSetupResult.timeoutMs)}ms bound on Metro port ${process.env.WATCHER_PORT ?? "8081"}` : `wallet fixture setup failed on ${process.env.WATCHER_PORT ?? "8081"}`,
             userAction: retryHint
           } : null
         },
@@ -227,7 +302,7 @@ async function handleFixturesLocked(argv) {
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
-async function applyExtensionFixture(target, fixturePath, canonicalFixture, json) {
+async function applyExtensionFixture(target, fixturePath, canonicalFixture, json, action) {
   const distManifest = path.join(target, "dist/chrome/manifest.json");
   const userAction = `mm-harness launch --build --verify --target ${JSON.stringify(target)}`;
   if (!fs.existsSync(distManifest)) {
@@ -236,7 +311,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
       console.log(JSON.stringify({
         schemaVersion: 1,
         command: "fixtures",
-        action: "set",
+        action,
         adapter: "extension",
         fixture: fixturePath,
         canonicalFixture,
@@ -245,15 +320,15 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
         error: { code: "EXTENSION_FIXTURE_BUILD_REQUIRED", message: message2, userAction }
       }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness fixtures set: ${message2}
+      console.error(`\u2717 mm-harness fixtures ${action}: ${message2}
   Next: ${userAction}`);
     }
     return EXIT.runtime;
   }
-  process.stderr.write(`${colorHumanMessage("\u2192 fixtures set extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026")}
+  process.stderr.write(`${colorHumanMessage(`\u2192 fixtures ${action} extension \u2014 resetting and seeding the slot-owned profile from the existing build\u2026`)}
 `);
   const liveScript = path.join(runnerDir, "adapters/extension/live.sh");
-  const args = ["--target", target, "--launch-existing-dist"];
+  const args = ["--target", target, "--launch-existing-dist", "--launch-only"];
   if (process.env.CDP_PORT) args.push("--cdp-port", process.env.CDP_PORT);
   const result = await spawnScriptStreaming(liveScript, args, target, {
     env: { RECIPE_WALLET_FIXTURE: fixturePath },
@@ -266,7 +341,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
     console.log(JSON.stringify({
       schemaVersion: 1,
       command: "fixtures",
-      action: "set",
+      action,
       adapter: "extension",
       fixture: fixturePath,
       canonicalFixture,
@@ -279,7 +354,7 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
   } else if (status === "pass") {
     console.error(message);
   } else {
-    console.error(`\u2717 mm-harness fixtures set: ${message}
+    console.error(`\u2717 mm-harness fixtures ${action}: ${message}
   Next: ${userAction}`);
   }
   return exitCode;

package/dist/commands/launch/extension.js

@@ -15,11 +15,16 @@ import {
   runnerDir
 } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
-import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
+import {
+  EXTENSION_PRODUCT_CONFIG_FINGERPRINT_FILENAME,
+  extensionCompiledScriptsMatchProductConfig,
+  extensionProductConfigBlock,
+  extensionProductConfigFingerprint
+} from "../../adapters/extension/product-config.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
-import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
+import { isExtensionWatcherLive, stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { EXIT, spawnScriptStreaming } from "../shared.js";
 const { CdpSession } = await importRecipeHarnessRuntimeCdp();
 const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
@@ -75,12 +80,14 @@ Next: ${block.userAction}`
   if (reusable) {
     return extensionReattach(target, displayMode);
   }
-  return extensionRebuild(target);
+  return extensionLaunchDevelopment(target);
 }
 async function extensionRuntimeReusable(target) {
   const cdpPort = process.env.CDP_PORT;
   if (!cdpPort) return false;
   if (isExtensionDistStale(target)) return false;
+  if (isExtensionWatcherLive(target) && !harnessWatcherMatchesProductConfig(target)) return false;
+  if (!extensionCompiledScriptsMatchProductConfig(target, expectedRuntimeDist(target))) return false;
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const reachable = await cdpVersionReachable(cdpPort);
     const nonceOwned = reachable && await cdpOwnedByRuntimeNonce(cdpPort, target);
@@ -325,6 +332,34 @@ async function extensionReattach(target, displayMode = "fullscreen") {
   console.error(colorHumanMessage(`\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 extensionLaunchDevelopment(target) {
+  const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
+  const liveArgs = ["--target", target];
+  const existingBuild = isExtensionWatcherLive(target) && harnessWatcherMatchesProductConfig(target) && extensionCompiledScriptsMatchProductConfig(target, path.join(target, "dist/chrome")) && fs.existsSync(path.join(target, "dist/chrome/manifest.json")) && !isExtensionDistStale(target);
+  liveArgs.push(existingBuild ? "--launch-existing-dist" : "--start-watch");
+  if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
+  if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);
+  console.error(colorHumanMessage(
+    existingBuild ? `\u2192 extension quick launch \u2014 existing yarn start build \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)` : `\u2192 extension quick launch \u2014 yarn start development build \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`
+  ));
+  return spawnScriptStreaming(liveScript, liveArgs, target);
+}
+function harnessWatcherMatchesProductConfig(target) {
+  const runtimeDir = path.join(target, recipeRuntimeDir());
+  const harnessPidFile = path.join(runtimeDir, "recipe-harness-webpack.pid");
+  if (!fs.existsSync(harnessPidFile)) return true;
+  const expected = extensionProductConfigFingerprint(target);
+  if (!expected) return true;
+  try {
+    const actual = fs.readFileSync(
+      path.join(runtimeDir, EXTENSION_PRODUCT_CONFIG_FINGERPRINT_FILENAME),
+      "utf8"
+    ).trim();
+    return actual === expected;
+  } catch {
+    return false;
+  }
+}
 async function extensionRebuild(target) {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
@@ -348,6 +383,7 @@ async function extensionRebuild(target) {
 }
 export {
   extensionDepsBlock,
+  extensionLaunchDevelopment,
   extensionReattach,
   extensionRebuild,
   extensionRuntimeReusable,

package/dist/commands/launch/index.js

@@ -259,6 +259,16 @@ async function handleLaunchLocked(argv, stream) {
       exitCode: EXIT.infra
     });
   }
+  if (adapter === "extension" && extensionEvmRpcUnreachable(attempt.output)) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      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: attempt.output.trim() || void 0
+    });
+  }
   if (heal === "off") {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "LAUNCH_FAILED",
@@ -374,6 +384,9 @@ function extensionBrowserMissing(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);
+}
 function mobileProvisioningBlocked(output) {
   return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
 }

package/dist/doctor.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { color } from "./cli-color.js";
 import {
@@ -148,7 +149,8 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
     },
-    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : []
+    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : [],
+    ...adapter === "extension" ? [extensionBrowserDoctorCheck(target)] : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -169,6 +171,32 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     manifestValidation: manifestValidation.summary
   };
 }
+function extensionBrowserDoctorCheck(target) {
+  const requireFromTarget = createRequire(path.join(path.resolve(target), "package.json"));
+  for (const packageName of ["@playwright/test", "playwright"]) {
+    try {
+      const playwright = requireFromTarget(packageName);
+      const executable = playwright.chromium?.executablePath?.();
+      if (executable && fs.existsSync(executable)) {
+        return {
+          id: "playwright-chromium",
+          status: "pass",
+          required: true,
+          message: "Checkout-pinned Playwright Chromium is installed.",
+          detail: executable
+        };
+      }
+    } catch {
+    }
+  }
+  return {
+    id: "playwright-chromium",
+    status: "fail",
+    required: true,
+    message: "Checkout-pinned Playwright Chromium is not installed.",
+    userAction: "yarn playwright install chromium"
+  };
+}
 function mobileToolDoctorChecks(platform) {
   const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
     { tool: "adb", platform: "Android" },
@@ -250,6 +278,7 @@ function readJsonObject(file) {
 export {
   compatibilityMode,
   createDoctorReport,
+  extensionBrowserDoctorCheck,
   fixtureFileSummary,
   fixtureSummary,
   mobileToolDoctorChecks,

package/dist/mm-harness-cli.js

@@ -452,7 +452,7 @@ Example:
   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 clean build + relaunch (escape hatch; skips extension reuse)
+  --build                            Full production-like build + relaunch (escape hatch; skips extension reuse)
   --clear-metro                      Mobile only: clear Metro's transform cache before launch
   --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
   --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
@@ -539,9 +539,9 @@ Example:
   },
   {
     name: "fixtures",
-    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / generate / finalize.",
+    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / reset / generate / finalize.",
     example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures [<init|sync|set|generate|finalize>] [flags]
+    helpText: `mm-harness fixtures [<init|sync|set|reset|generate|finalize>] [flags]
 
   Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
   With no action, show the current fixture status and safe next command.
@@ -550,6 +550,8 @@ Example:
   sync       Refresh the wallet fixture files on the target.
   set        Apply the canonical fixture (SRP/password/accounts); the password is
              read FROM the fixture, never typed.
+  reset      Delete the current Mobile/Extension wallet, then apply and validate
+             the canonical fixture from a clean state.
   generate   Render the extension fixture-state.json from a wallet fixture, for
              pre-launch profile prefill (extension-only). Requires --fixture and --out.
   finalize   Seed account labels/selection into the LIVE extension over CDP and
@@ -578,6 +580,7 @@ Example:
   mm-harness fixtures init --dev
   mm-harness fixtures sync
   mm-harness fixtures set
+  mm-harness fixtures reset
   mm-harness fixtures generate --fixture wallet-fixture.json --out fixture-state.json
   mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
   }

package/dist/recipe-security.js

@@ -4,6 +4,7 @@ import path from "node:path";
 const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "ui.locators",
   "metamask.wallet.fixture_status",
+  "metamask.wallet.validate_import",
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state",
   "metamask.perps.read_positions",
@@ -19,6 +20,8 @@ const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
 ]);
 const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
+  "metamask.wallet.import",
+  "metamask.wallet.reset",
   "metamask.wallet.ensure_unlocked",
   "metamask.wallet.select_account",
   "metamask.deeplink.open",

package/docs/RECIPES.md

@@ -58,6 +58,35 @@ mm-harness run recipe.json account="Account 2" --plan
 mm-harness run recipe.json account="Account 2"
 ```
 
+Use the shared wallet setup recipe on either Mobile or Extension. `auto`
+reuses a ready fixture-backed profile and otherwise completes visible
+onboarding; `ui` requires a fresh onboarding state.
+
+```bash
+mm-harness run wallet.import method=auto
+mm-harness run wallet.import method=ui credential_source=environment
+mm-harness run wallet.import method=ui metametrics=true 'interests=["trade_perpetuals"]'
+```
+
+The UI path reads the primary mnemonic from `MM_HARNESS_WALLET_SRP` and the
+password from `MM_HARNESS_WALLET_PASSWORD`, or from the canonical wallet
+fixture. Secret values are redacted from commands and evidence. Visible imports
+default to MetaMetrics off and skip Mobile's optional interests; password terms
+are required and always accepted by the action.
+
+To prove the full real-user recovery journey, delete the current wallet through
+visible client UI and import it again:
+
+```bash
+mm-harness run wallet.reset-import credential_source=fixture
+```
+
+For fixture-backed development clients, `mm-harness fixtures reset` performs a
+clean reset and reapplies the canonical fixture. Extension resets its owned
+Chrome profile; Mobile clears only the selected app's data, preserves the
+installed build, relaunches it, and then applies the fixture. Use
+`wallet.reset-import` when the reset itself must be exercised through visible UI.
+
 ### Mobile device targeting
 
 Always pass `--device <name|udid|serial>` when more than one simulator/device may