@deeeed/metamask-harness 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.32.0 - 2026-08-02
+
+### Changed
+
+- Organize bundled platform recipe variants under `library/recipes/<adapter>/` while retaining temporary compatibility with legacy filename suffixes.
+
+## 0.31.0 - 2026-08-02
+
+### Added
+
+- Add one cross-platform `metamask.deeplink.open` capability that exercises real Chrome or device URL ingress for external deeplink proofs.
+
 ## 0.30.0 - 2026-08-02
 
 ### Changed

package/adapters/extension/verify.sh

@@ -88,7 +88,7 @@ RUNNER_BIN="$HARNESS_DIR/runner/bin/mm-harness"
 # --out (optional): a task-local recipes dir. Resolve it safely within the target
 # (resolve_harness_out rejects absolute/.. escapes) and prefer its smoke recipe so
 # `live --out <dir>` does not silently fall back to the installed default.
-SMOKE_RECIPE="$HARNESS_DIR/runner/recipes/runner/smoke.extension.recipe.json"
+SMOKE_RECIPE="$HARNESS_DIR/runner/recipes/extension/runner/smoke.recipe.json"
 if [ -n "$OUT" ]; then
   # Fail fast on a task-local --out that does not contain the requested recipe.
   # Silently falling back to the installed default would validate a different
@@ -98,11 +98,23 @@ if [ -n "$OUT" ]; then
     echo "extension verify: --out '$OUT' did not resolve to a safe path under the target." >&2
     exit 2
   fi
-  if [ ! -f "$OUT_ABS/runner/smoke.extension.recipe.json" ]; then
-    echo "extension verify: --out '$OUT' (resolved: $OUT_ABS) has no runner/smoke.extension.recipe.json. Refusing to fall back to the installed default recipe; place the recipe under --out or omit --out." >&2
+  CANONICAL_SMOKE_RECIPE="$OUT_ABS/extension/runner/smoke.recipe.json"
+  LEGACY_SMOKE_RECIPE="$OUT_ABS/runner/smoke.extension.recipe.json"
+  if [ -f "$CANONICAL_SMOKE_RECIPE" ] && [ -f "$LEGACY_SMOKE_RECIPE" ]; then
+    echo "extension verify: --out '$OUT' declares runner.smoke for extension in both canonical and legacy paths." >&2
+    echo "Next: Remove $LEGACY_SMOKE_RECIPE and rerun verification." >&2
     exit 2
   fi
-  SMOKE_RECIPE="$OUT_ABS/runner/smoke.extension.recipe.json"
+  if [ -f "$CANONICAL_SMOKE_RECIPE" ]; then
+    SMOKE_RECIPE="$CANONICAL_SMOKE_RECIPE"
+  elif [ -f "$LEGACY_SMOKE_RECIPE" ]; then
+    SMOKE_RECIPE="$LEGACY_SMOKE_RECIPE"
+  else
+    echo "extension verify: --out '$OUT' has no extension runner.smoke recipe." >&2
+    echo "Next: Add extension/runner/smoke.recipe.json under $OUT_ABS or omit --out." >&2
+    exit 2
+  fi
+  unset CANONICAL_SMOKE_RECIPE LEGACY_SMOKE_RECIPE
 fi
 ARTIFACTS="${ARTIFACTS:-$HARNESS_DIR/verify/$(date -u +%Y%m%dT%H%M%SZ)}"
 mkdir -p "$ARTIFACTS/logs"

package/dist/commands/self-test.js

@@ -26,7 +26,7 @@ async function runSelfTest(options) {
       const manifest = loadActionManifest(adapter);
       const manifestValidation = await validateManifest(manifest);
       const smokeRecipe = recipePath(
-        adapter === "mobile" ? "runner/smoke.mobile.recipe.json" : "runner/smoke.extension.recipe.json"
+        adapter === "mobile" ? "mobile/runner/smoke.recipe.json" : "extension/runner/smoke.recipe.json"
       );
       const artifactsDir = path.join(root, adapter);
       const result = await runRecipe(adapter, smokeRecipe, artifactsDir, runnerDir, void 0, {

package/dist/recipe-security.js

@@ -20,6 +20,7 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
   "metamask.wallet.ensure_unlocked",
   "metamask.wallet.select_account",
+  "metamask.deeplink.open",
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",

package/docs/RECIPES.md

@@ -116,7 +116,7 @@ The protocol is authoritative:
 team-recipes/
   manifests/extension.action-manifest.json
   actions/extension/wallet/ensure_ready.mjs
-  recipes/onboarding/smoke.extension.recipe.json
+  recipes/extension/onboarding/smoke.recipe.json
 ```
 
 ```bash
@@ -129,7 +129,10 @@ mm-harness run onboarding.smoke --plan
 Use `--library wallet=/path/to/library` for one command. The alias is the
 source name; without one, the directory name is used. Resolution follows the
 explicit library order, then bundled MetaMask. Adapter-specific variants are
-selected deterministically. Every run records the root recipe, exact resolved
+selected deterministically from `recipes/<adapter>/<domain>/`. Legacy
+`*.<adapter>.recipe.json` paths remain readable during migration, but new and
+migrated libraries use the adapter-first layout. A file cannot declare its
+adapter through both forms. Every run records the root recipe, exact resolved
 dependency documents, their digests, call edges, selected sources, and shadows.
 
 ## Direct product access

package/library/actions/extension/deeplink/open.mjs

@@ -0,0 +1,26 @@
+import { pathToFileURL } from 'node:url';
+
+import {
+  externalDeeplinkTimeout,
+  externalDeeplinkUrl,
+} from '../../shared/deeplink/url.mjs';
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+export async function openExtensionDeeplink(input) {
+  return withExtensionPage(input, (page) => navigateExtensionDeeplink(page, input));
+}
+
+export async function navigateExtensionDeeplink(page, input) {
+  const url = externalDeeplinkUrl(input.node);
+  const timeoutMs = externalDeeplinkTimeout(input.node);
+  return {
+    action: input.action,
+    url,
+    navigation: await page.navigate(url, timeoutMs),
+    proofPath: 'external-deeplink',
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter(openExtensionDeeplink);
+}

package/library/actions/mobile/deeplink/open.mjs

@@ -0,0 +1,16 @@
+import {
+  externalDeeplinkTimeout,
+  externalDeeplinkUrl,
+} from '../../shared/deeplink/url.mjs';
+import { openExternalDeeplink, runAdapter } from '../platform/bridge.mjs';
+
+runAdapter(async (input) => {
+  const url = externalDeeplinkUrl(input.node);
+  const timeoutMs = externalDeeplinkTimeout(input.node);
+  return {
+    action: input.action,
+    url,
+    ...(await openExternalDeeplink(input, url, timeoutMs)),
+    proofPath: 'external-deeplink',
+  };
+});

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

@@ -160,6 +160,86 @@ function resolveMobileTarget(input) {
   return { watcherPort, iosSimulator, androidDevice, androidTargetDeviceName, adbSerial };
 }
 
+export async function openExternalDeeplink(input, url, timeout = 15000) {
+  const target = resolveMobileTarget(input);
+  const requestedPlatform = String(
+    input.context?.env?.PLATFORM ?? process.env.PLATFORM ?? '',
+  ).toLowerCase();
+  const serial = String(
+    input.context?.env?.ADB_SERIAL ??
+      input.context?.env?.ANDROID_SERIAL ??
+      process.env.ADB_SERIAL ??
+      process.env.ANDROID_SERIAL ??
+      '',
+  ).trim();
+  const android =
+    requestedPlatform === 'android' || (requestedPlatform !== 'ios' && Boolean(serial));
+  if (android) {
+    if (!serial) {
+      throw new Error(
+        'Android deeplink ingress requires an adb serial.\n' +
+          '  Next: mm-harness devices --adapter mobile --json',
+      );
+    }
+    const adb = resolveMobileToolPath('adb', { required: true });
+    const { stdout } = await runDeeplinkCommand(
+      adb,
+      [
+        '-s',
+        serial,
+        'shell',
+        'am',
+        'start',
+        '-W',
+        '-a',
+        'android.intent.action.VIEW',
+        '-d',
+        quoteRemoteShellArgument(url),
+      ],
+      timeout,
+      `Android device ${serial}`,
+    );
+    if (!/^Status:\s*ok\s*$/imu.test(stdout)) {
+      throw new Error(
+        `Android device ${serial} did not report a successful deeplink launch.\n` +
+          '  Next: mm-harness doctor --adapter mobile --json',
+      );
+    }
+    return { platform: 'android', selectedDevice: serial, method: 'adb-am-start-view' };
+  }
+
+  const simulator = String(target.iosSimulator ?? '').trim();
+  if (!simulator) {
+    throw new Error(
+      'iOS deeplink ingress requires an iOS simulator.\n' +
+        '  Next: mm-harness devices --adapter mobile --json',
+    );
+  }
+  await runDeeplinkCommand(
+    'xcrun',
+    ['simctl', 'openurl', simulator, url],
+    timeout,
+    `iOS simulator ${simulator}`,
+  );
+  return { platform: 'ios', selectedDevice: simulator, method: 'simctl-openurl' };
+}
+
+function quoteRemoteShellArgument(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+async function runDeeplinkCommand(command, args, timeout, target) {
+  try {
+    return await execFileAsync(command, args, { timeout, encoding: 'utf8' });
+  } catch (error) {
+    const detail = String(error?.stderr ?? error?.message ?? error).trim();
+    throw new Error(
+      `Could not open the deeplink on ${target}${detail ? `: ${detail}` : '.'}\n` +
+        '  Next: mm-harness doctor --adapter mobile --json',
+    );
+  }
+}
+
 function androidDeviceNameMatches(deviceName, targetName) {
   if (!targetName) return false;
   return deviceName === targetName || deviceName.startsWith(`${targetName} -`);

package/library/actions/shared/deeplink/url.mjs

@@ -0,0 +1,37 @@
+export function externalDeeplinkUrl(node) {
+  const raw = node?.url;
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new Error(
+      'metamask.deeplink.open requires url.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home',
+    );
+  }
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(
+      'metamask.deeplink.open requires an absolute HTTPS url.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home',
+    );
+  }
+  if (url.protocol !== 'https:') {
+    throw new Error(
+      'metamask.deeplink.open accepts only HTTPS urls.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home',
+    );
+  }
+  return url.toString();
+}
+
+export function externalDeeplinkTimeout(node) {
+  const timeout = Number(node?.timeout_ms ?? 15000);
+  if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 120000) {
+    throw new Error(
+      'metamask.deeplink.open timeout_ms must be between 1 and 120000.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home timeout_ms=15000',
+    );
+  }
+  return timeout;
+}

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

@@ -2779,6 +2779,37 @@
         "external-mutation"
       ]
     },
+    "metamask.deeplink.open": {
+      "description": "Open an HTTPS deeplink through real browser ingress so the Extension owns parsing, verification, and destination navigation.",
+      "execution_capabilities": [
+        "app-mutation"
+      ],
+      "examples": [
+        {
+          "action": "metamask.deeplink.open",
+          "url": "https://link.metamask.io/home",
+          "intent": "Open the deeplink through external browser navigation",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Absolute HTTPS deeplink URL."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "description": "Maximum time for the external navigation. Default 15000."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "additionalProperties": false
+      }
+    },
     "metamask.analytics.start_capture": {
       "description": "extension Start capturing MetaMetrics events at the Segment transport and return a cursor to bracket later reads.",
       "execution_capabilities": [
@@ -2945,6 +2976,7 @@
     {
       "ref": "ui.screen",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.key_press",
@@ -2957,6 +2989,7 @@
     {
       "ref": "ui.visible",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.key_press",

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

@@ -2901,6 +2901,37 @@
         "external-mutation"
       ]
     },
+    "metamask.deeplink.open": {
+      "description": "Open an HTTPS deeplink through the selected Android device or iOS simulator so Mobile owns parsing and destination navigation.",
+      "execution_capabilities": [
+        "app-mutation"
+      ],
+      "examples": [
+        {
+          "action": "metamask.deeplink.open",
+          "url": "https://link.metamask.io/home",
+          "intent": "Open the deeplink through external device navigation",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Absolute HTTPS deeplink URL."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "description": "Maximum time for the external navigation. Default 15000."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "additionalProperties": false
+      }
+    },
     "metamask.analytics.start_capture": {
       "description": "mobile Start capturing MetaMetrics events at the Segment transport and return a cursor to bracket later reads.",
       "execution_capabilities": [
@@ -3067,6 +3098,7 @@
     {
       "ref": "ui.screen",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.screenshot",
@@ -3078,6 +3110,7 @@
     {
       "ref": "ui.visible",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.screenshot",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -23,7 +23,7 @@
     "@farmslot/agent-runtime": "0.5.1",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "0.16.0",
-    "@farmslot/recipe-harness": "0.12.0",
+    "@farmslot/recipe-harness": "0.13.0",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",
     "esbuild": "0.28.1",