@deeeed/metamask-harness 0.47.0 → 0.47.2

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 0.47.2 - 2026-09-05
+
+### Changed
+
+- Teach recipe and action discovery, bounded setup probes, source-based diagnosis, and honest blocked-proof reporting through version-matched CLI help.
+
+### Fixed
+
+- Flush machine-readable command output before exit so large JSON documents remain complete when piped to another process.
+- Keep `metamask.perps.set_market_favorite` in the current mode while waiting for a temporarily absent favorite control.
+- Preserve the current Mobile Perps mode when `ui.navigate` omits `mode`, including opaque Android navigation.
+- Prefer an exact visible Mobile Perps market row or recently-viewed tile before falling back to search.
+- Preserve Mobile Perps teardown navigation when embedded and fallback bridges use different wording for a missing scrollable target.
+
+## 0.47.1 - 2026-09-04
+
+### Fixed
+
+- Open the tutorial on the protected MetaMask GitHub Pages site instead of the public unpkg CDN.
+- Stop shipping the static HTML site in the public npm package; retain only the recipe-help JSON required by the CLI.
+
 ## 0.47.0 - 2026-09-04
 
 ### Added

package/adapters/mobile/bridge-runtime/lib/bridge-errors.cjs

@@ -18,6 +18,10 @@ const BRIDGE_ERROR_CODES = {
   METRO_UNREACHABLE: 'METRO_UNREACHABLE',
 };
 
+const BRIDGE_RESULT_ERROR_CODES = {
+  SCROLLABLE_NOT_FOUND: 'SCROLLABLE_NOT_FOUND',
+};
+
 // Process exit code the bridge returns per failure code so a caller that only
 // sees the child's exit status (no stderr) can still recover the code. Kept
 // clear of exit 1 (unknown/uncoded) and 2 (usage).
@@ -78,6 +82,15 @@ function classifyBridgeErrorMessage(message) {
   return null;
 }
 
+function classifyBridgeResultError(command, result) {
+  if (command !== 'scroll-view' || result?.ok !== false) return null;
+  return /^No scrollable(?: found)? near testID=/u.test(
+    String(result.error ?? ''),
+  )
+    ? BRIDGE_RESULT_ERROR_CODES.SCROLLABLE_NOT_FOUND
+    : null;
+}
+
 // Attach a code to an error at its throw site (source classification).
 function coded(error, code) {
   if (error && typeof error === 'object') error.code = code;
@@ -99,10 +112,12 @@ function parseErrorMarker(text) {
 
 module.exports = {
   BRIDGE_ERROR_CODES,
+  BRIDGE_RESULT_ERROR_CODES,
   EXIT_CODE_BY_ERROR_CODE,
   ERROR_CODE_BY_EXIT_CODE,
   TEACHING_BY_ERROR_CODE,
   classifyBridgeErrorMessage,
+  classifyBridgeResultError,
   coded,
   formatErrorMarker,
   parseErrorMarker,

package/dist/commands/tutorial.js

@@ -1,11 +1,11 @@
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "./parse-args.js";
-const PACKAGE_NAME = "@deeeed/metamask-harness";
-function recipeTutorialUrl(harnessVersion, runMode = process.env.MM_HARNESS_RUN_MODE) {
+const PROTECTED_TUTORIAL_URL = "https://glowing-chainsaw-gwzrn8k.pages.github.io/recipes.html#agent-method";
+function recipeTutorialUrl(runMode = process.env.MM_HARNESS_RUN_MODE) {
   if (runMode === "src") {
     return "http://127.0.0.1:8765/site/recipes.html#agent-method";
   }
-  return `https://unpkg.com/${PACKAGE_NAME}@${harnessVersion}/site/recipes.html#agent-method`;
+  return PROTECTED_TUTORIAL_URL;
 }
 function openUrl(url) {
   const command = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
@@ -14,7 +14,7 @@ function openUrl(url) {
 }
 function handleTutorial(argv, context) {
   const parsed = parseArgs(argv, "tutorial");
-  const url = recipeTutorialUrl(context.harnessVersion);
+  const url = recipeTutorialUrl();
   const noOpen = parsed.options.noOpen === true;
   const opened = noOpen ? false : (context.open ?? openUrl)(url);
   const payload = {

package/dist/mm-harness-cli.js

@@ -41,12 +41,12 @@ Example:
   },
   {
     name: "tutorial",
-    summary: "Open the visual recipe tutorial for this harness version.",
+    summary: "Open the protected visual recipe tutorial.",
     example: "mm-harness tutorial",
     helpText: `mm-harness tutorial [flags]
 
   Source checkouts open the local tutorial on port 8765. Installed releases
-  open the tutorial published with that exact harness version.
+  open the protected MetaMask GitHub Pages site.
 
   --no-open                          Print the tutorial URL without opening it
   --json                             Print version, URL, and open status as JSON
@@ -830,7 +830,7 @@ for (const command of REAL) {
     if (command.name === "tutorial") {
       process.exit(handleTutorial(rawArgv.slice(1), { harnessVersion: pkgVersion }));
     }
-    process.exit(await withCommandJournal(command.name, rawArgv, () => delegate(rawArgv)));
+    process.exitCode = await withCommandJournal(command.name, rawArgv, () => delegate(rawArgv));
   });
 }
 const HIDDEN = [

package/library/actions/mobile/perps/perps.mjs

@@ -1,5 +1,6 @@
 import { pathToFileURL } from 'node:url';
 import {
+  MOBILE_BRIDGE_RESULT_ERROR_CODES,
   bridgeCommand,
   evalAsync,
   isTargetTransition,
@@ -915,29 +916,50 @@ async function readVisiblePerpsTestIds(input, deadline) {
   return new Set(visible.items.map((item) => String(item.test_id ?? '')));
 }
 
-async function waitForPerpsUiTarget(input, testId, deadline) {
+async function waitForPerpsUiTargets(input, testIds, deadline) {
   let lastTestIds = [];
   while (Date.now() < deadline) {
-    const testIds = await readVisiblePerpsTestIds(input, deadline);
-    if (testIds.has(testId)) return testIds;
-    lastTestIds = [...testIds].filter(Boolean).slice(0, 20);
+    const visibleTestIds = await readVisiblePerpsTestIds(input, deadline);
+    const matchedTestId = testIds.find((testId) =>
+      visibleTestIds.has(testId),
+    );
+    if (matchedTestId) return { matchedTestId, visibleTestIds };
+    lastTestIds = [...visibleTestIds].filter(Boolean).slice(0, 20);
     await sleepBeforeDeadline(deadline, 250);
   }
+  const targetDescription =
+    testIds.length === 1
+      ? `control ${testIds[0]}`
+      : `controls ${testIds.join(' or ')}`;
   throw new Error(
-    `Perps control ${testId} did not become visible before timeout. Observed: ${lastTestIds.join(', ') || 'none'}.`,
+    `Perps ${targetDescription} did not become visible before timeout. Observed: ${lastTestIds.join(', ') || 'none'}.`,
   );
 }
 
+async function waitForPerpsUiTarget(input, testId, deadline) {
+  const { visibleTestIds } = await waitForPerpsUiTargets(
+    input,
+    [testId],
+    deadline,
+  );
+  return visibleTestIds;
+}
+
 async function selectPerpsMarketFromHome(input, symbol, previousRoute) {
   const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15_000);
   const deadline = deadlineFromTimeout(input, timeoutMs);
   const params = { market: { symbol } };
   const rowTestId = `perps-market-row-item-${symbol}`;
+  const recentlyViewedTestId = `perps-recently-viewed-tile-${symbol}`;
+  const marketTestIds = [rowTestId, recentlyViewedTestId];
   const searchTestId = 'perps-market-list-search-bar';
   let visibleTestIds = await readVisiblePerpsTestIds(input, deadline);
+  let marketTestId = marketTestIds.find((testId) =>
+    visibleTestIds.has(testId),
+  );
   let usedSearch = false;
 
-  if (!visibleTestIds.has(rowTestId)) {
+  if (!marketTestId) {
     if (!visibleTestIds.has(searchTestId)) {
       if (!visibleTestIds.has('perps-home-search-toggle')) {
         throw new Error(
@@ -959,17 +981,19 @@ async function selectPerpsMarketFromHome(input, symbol, previousRoute) {
       searchTestId,
       symbol,
     ]);
-    visibleTestIds = await waitForPerpsUiTarget(
+    const visibleMarketTarget = await waitForPerpsUiTargets(
       input,
-      rowTestId,
+      marketTestIds,
       deadline,
     );
+    visibleTestIds = visibleMarketTarget.visibleTestIds;
+    marketTestId = visibleMarketTarget.matchedTestId;
     usedSearch = true;
   }
 
   await bridgeCommand(withRemainingDeadline(input, deadline), [
     'press-test-id',
-    rowTestId,
+    marketTestId,
   ]);
   const currentRoute = await waitForRoute(
     withRemainingDeadline(input, deadline),
@@ -983,7 +1007,7 @@ async function selectPerpsMarketFromHome(input, symbol, previousRoute) {
     previousRoute,
     currentRoute,
     verifiedRoute: 'PerpsMarketDetails',
-    visibleMarketSelection: { usedSearch },
+    visibleMarketSelection: { usedSearch, testId: marketTestId },
   };
 }
 
@@ -1033,7 +1057,12 @@ async function navigateFromMarketDetailsToHome(input, previousRoute) {
         backTestId = expectedBackTestId;
         break;
       } catch (error) {
-        if (!/No scrollable near testID=/u.test(String(error))) throw error;
+        if (
+          error?.code !==
+          MOBILE_BRIDGE_RESULT_ERROR_CODES.SCROLLABLE_NOT_FOUND
+        ) {
+          throw error;
+        }
       }
     }
   }
@@ -1079,7 +1108,7 @@ async function navigateFromMarketDetailsToHome(input, previousRoute) {
   };
 }
 
-async function navigatePerps(input) {
+export async function navigatePerps(input) {
   const selected = String(
     input.node?.target ?? input.node?.destination ?? defaultNavigationTarget(input.node),
   ).toLowerCase();

package/library/actions/mobile/perps/set_market_favorite.mjs

@@ -51,17 +51,6 @@ runAdapter(async (input) => {
       throw new Error(`Visible Perps market ${JSON.stringify(subtitle)} does not match ${market}.`);
     }
     let control = favoriteControl(snapshot);
-    if (!control && nativeNode(snapshot, 'perps-mode-toggle-lite')?.enabled !== false) {
-      try {
-        await session.execute('ui.press', {
-          test_id: 'perps-mode-toggle-lite',
-          timeout_ms: timeoutMs,
-          settle: false,
-        });
-      } catch (error) {
-        if (!/Selector did not match/iu.test(String(error?.message ?? error))) throw error;
-      }
-    }
     const controlDeadline = Date.now() + timeoutMs;
     let lastControls = [];
     while (Date.now() <= controlDeadline && !control) {

package/library/actions/mobile/platform/bridge.mjs

@@ -13,8 +13,10 @@ import { resolveMobileToolPath } from './tool-paths.mjs';
 
 const {
   BRIDGE_ERROR_CODES,
+  BRIDGE_RESULT_ERROR_CODES,
   ERROR_CODE_BY_EXIT_CODE,
   classifyBridgeErrorMessage,
+  classifyBridgeResultError,
   coded,
   parseErrorMarker,
 } = bridgeErrors;
@@ -24,6 +26,7 @@ const { resolvePort } = configModule;
 // Re-exported so the TS adapter classifies on the same code constants without a
 // second import path into the cjs bridge-runtime.
 export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
+export const MOBILE_BRIDGE_RESULT_ERROR_CODES = BRIDGE_RESULT_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
 const ACTION_DEADLINE_FIELD = '_action_deadline_epoch_ms';
@@ -536,9 +539,11 @@ export async function bridgeCommand(input, args) {
   try {
     const parsed = JSON.parse(result.stdout);
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.ok === false) {
-      throw new Error(
+      const error = new Error(
         `Mobile CDP bridge command reported failure for ${redactBridgeArgs(args).join(' ')}: ${redactBridgeOutput(JSON.stringify(parsed), sensitiveBridgeArgs(args))}`,
       );
+      const code = classifyBridgeResultError(command, parsed);
+      throw code ? coded(error, code) : error;
     }
     return parsed;
   } catch (error) {

package/library/actions/mobile/ui/native-navigation.mjs

@@ -73,7 +73,9 @@ export async function navigateOpaqueMobile(input, destination) {
     artifactsDir: input.context.artifactsDir,
     env,
   };
-  const perpsMode = destination.params?.mode === 'pro' ? 'pro' : 'lite';
+  const perpsMode = ['lite', 'pro'].includes(destination.params?.mode)
+    ? destination.params.mode
+    : undefined;
   const press = (testId) => transport.execute('ui.press', {
     test_id: testId,
     timeout_ms: Number(input.node?.timeout_ms ?? 30_000),
@@ -542,11 +544,16 @@ async function navigatePerpsMarketList({ identifiers, press, wait, back, timeout
   throw new Error(`Opaque Mobile navigation reached ${observed}, but no visible market-list control was available.`);
 }
 
-async function waitForPerpsDestination(identifiers, timeoutMs, press, perpsMode = 'lite') {
+async function waitForPerpsDestination(identifiers, timeoutMs, press, perpsMode) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() <= deadline) {
     const ids = await identifiers();
     if (ids.has(IDS.modeLite) || ids.has(IDS.modePro)) {
+      if (!perpsMode) {
+        throw new Error(
+          'Opaque Mobile navigation requires mode=lite or mode=pro when the product requests a Perps mode choice.',
+        );
+      }
       await press(perpsMode === 'pro' ? IDS.modePro : IDS.modeLite);
       continue;
     }

package/library/actions/mobile/ui/navigate.mjs

@@ -23,8 +23,8 @@ function text(value) {
 function pageRoute(node) {
   const page = text(node?.page);
   if (!page) return undefined;
-  const mode = text(node?.mode)?.toLowerCase() ?? 'lite';
-  if (!['lite', 'pro'].includes(mode)) {
+  const mode = text(node?.mode)?.toLowerCase();
+  if (mode && !['lite', 'pro'].includes(mode)) {
     throw new Error('mobile ui.navigate mode must be lite or pro.');
   }
   if (PAGE_ROUTES[page]) {
@@ -32,13 +32,22 @@ function pageRoute(node) {
     return {
       page,
       ...route,
-      params: page.startsWith('perps') ? { ...route.params, mode } : route.params,
+      params: page.startsWith('perps') && mode
+        ? { ...route.params, mode }
+        : route.params,
     };
   }
   if (page === 'perps-market') {
     const market = text(node.market) ?? text(node.symbol) ?? text(node.params?.market?.symbol);
     if (!market) throw new Error('mobile ui.navigate page=perps-market requires market or symbol.');
-    return { page, route: 'PerpsMarketDetails', params: { market: { symbol: market }, mode } };
+    return {
+      page,
+      route: 'PerpsMarketDetails',
+      params: {
+        market: { symbol: market },
+        ...(mode ? { mode } : {}),
+      },
+    };
   }
   throw new Error('mobile ui.navigate supported page intents: home, perps, perps-market-list, perps-market, swap.');
 }

package/library/manifests/mobile.action-manifest.json

@@ -412,8 +412,7 @@
             "enum": [
               "lite",
               "pro"
-            ],
-            "default": "lite"
+            ]
           },
           "url": {
             "type": "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.47.0",
+  "version": "0.47.2",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -64,7 +64,7 @@
     "dist",
     "adapters",
     "library",
-    "site",
+    "site/assets/help-recipes.json",
     "scripts/completions.sh",
     "scripts/install-completions.sh",
     "scripts/site-contrast.mjs",

package/site/assets/help-recipes.json

@@ -26,7 +26,8 @@
       "instruction": "Search the installed recipe and action catalogs, inspect exact schemas, and select the closest recipe before writing anything new.",
       "details": [
         "A bundled recipe, including a Core recipe, is strong composable vocabulary, not authority for every future product version.",
-        "Prefer an existing recipe, then existing actions, then read-only CDP or controller inspection. Add shared vocabulary only after repeated need is proven."
+        "Prefer an existing recipe, then existing actions, then read-only CDP or controller inspection. Add shared vocabulary only after repeated need is proven.",
+        "Before declaring a capability unsupported, inspect both catalogs and the closest recipe's composition. A missing dedicated action may already be composed from UI actions. Read the returned schema before filtering fields; do not treat guessed field names as empty capabilities."
       ],
       "commands": [
         "mm-harness actions --json",
@@ -61,6 +62,7 @@
       "instruction": "Probe each unfamiliar action with call or a tiny action-to-end recipe. Use read-only CDP inspection only when declared actions cannot reveal the needed authoring detail, then consolidate the final proof from manifest-declared actions.",
       "details": [
         "Plan after every structural change and preserve the first failing trace.",
+        "A plan validates structure only. Probe a reused setup boundary against the current build with a short explicit timeout before a full journey; a bundled journey timeout is not a discovery budget.",
         "A CDP observation can help find the current route or selector; it is not final evidence unless the recipe records an allowed action and assertion for that signal."
       ],
       "commands": [
@@ -84,6 +86,7 @@
       "instruction": "Run the complete graph once into an explicit artifact directory, then apply the built-in quality bar before assigning coverage or a verdict.",
       "details": [
         "Coverage: every criterion needs an executable path and assertion; manual, untestable, and environment-dependent gaps stay explicit.",
+        "A blocked required runtime claim is incomplete proof. Passing static checks or closing a checklist cannot make that claim validated or fixed.",
         "Graph: no unconditional pass, generic intent, hidden start state, or opaque node that collapses preparation, action, assertion, evidence, and teardown.",
         "Evidence: inspect the recipe resolution, summary, trace, manifest, logs, and actual visual evidence. A filename or passing node is not visual proof.",
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",
@@ -101,6 +104,8 @@
       "instruction": "When a shared recipe fails, reproduce once and classify product regression, recipe drift, fixture/runtime drift, harness defect, or live dependency before changing anything.",
       "details": [
         "The graph and evidence contract can be deterministic while the product, provider, account, or network outcome is not. Honest external rejection remains a valid result, not a reason to seek a green retry.",
+        "Trace the first failure through the exact action source and test the smallest causal explanation before filing or fixing a harness issue. A selector name does not establish its cause. If a proposed fix outgrows the confirmed cause, preserve it separately and return to the minimal fix.",
+        "For blocked runtime proof, retain the target identity, build/app state, and first failing command and error. Reconcile later status snapshots with that evidence; they cannot establish that an earlier device was absent.",
         "For product-version drift, preserve the failed trace, copy the composed recipe into the task, keep working nodes, and repair the smallest owning node against the tested build.",
         "Prove the changed node in isolation, re-plan, then rerun the full task-local recipe and affected callers. Never weaken an assertion or change product code merely to turn stale proof green.",
         "Record the source recipe digest, tested product identity, repair, and fresh evidence. If the defect belongs to reusable harness code or bundled vocabulary, prepare a focused experimental-metamask-harness issue and open it when authorized.",