@deeeed/metamask-harness 0.58.0 → 0.60.0

package/library/actions/mobile/feature_flags/controller.mjs

@@ -0,0 +1,120 @@
+// Mobile remote feature-flag transport: RemoteFeatureFlagController over the CDP bridge.
+//
+// `setFlagOverride` writes `state.localOverrides` and recomputes
+// `state.remoteFeatureFlags` as merge(processed remote flags, localOverrides) —
+// overrides persist and win over every later refetch, so a pinned variant
+// survives a ClientConfigApi response. Verified against
+// @metamask/remote-feature-flag-controller
+// dist/remote-feature-flag-controller.cjs (setFlagOverride / removeFlagOverride /
+// clearAllFlagOverrides) and the global Engine in app/core/Engine/Engine.ts.
+import { evalAsync } from '../platform/bridge.mjs';
+
+const CONTROLLER_PREAMBLE = `
+  var engine = globalThis.Engine;
+  var context = engine && engine.context;
+  var controller = context && context.RemoteFeatureFlagController;
+  if (!controller) {
+    return JSON.stringify({
+      ok: false,
+      error: 'Engine.context.RemoteFeatureFlagController is not available on the running app.',
+    });
+  }
+  var snapshot = function () {
+    var state = controller.state || {};
+    return {
+      effective: state.remoteFeatureFlags || {},
+      overrides: state.localOverrides || {},
+    };
+  };
+`;
+
+function evaluate(input, body) {
+  return evalAsync(input, `Promise.resolve().then(function () {${CONTROLLER_PREAMBLE}${body}})`);
+}
+
+function unwrap(result, action) {
+  if (!result || typeof result !== 'object') {
+    throw new Error(`${action} did not return a controller result from the mobile bridge.`);
+  }
+  if (result.ok !== true) {
+    throw new Error(String(result.error || `${action} failed on the mobile runtime.`));
+  }
+  return result;
+}
+
+/** Read `{ effective, overrides }` straight from controller state. */
+export async function readMobileFlags(input) {
+  const result = await evaluate(input, `
+    var current = snapshot();
+    return JSON.stringify({ ok: true, effective: current.effective, overrides: current.overrides });
+  `);
+  return unwrap(result, 'metamask.feature_flags.read');
+}
+
+/** Apply every normalised flag, then read the controller back in the same eval. */
+export async function setMobileFlags(input, flags) {
+  const payload = JSON.stringify(JSON.stringify(flags));
+  const result = await evaluate(input, `
+    if (typeof controller.setFlagOverride !== 'function') {
+      return JSON.stringify({
+        ok: false,
+        error: 'RemoteFeatureFlagController.setFlagOverride is unavailable in this build; update @metamask/remote-feature-flag-controller in the checkout.',
+      });
+    }
+    var requested = JSON.parse(${payload});
+    var applied = [];
+    for (var key in requested) {
+      if (Object.prototype.hasOwnProperty.call(requested, key)) {
+        controller.setFlagOverride(key, requested[key]);
+        applied.push(key);
+      }
+    }
+    var current = snapshot();
+    return JSON.stringify({ ok: true, applied: applied, effective: current.effective, overrides: current.overrides });
+  `);
+  return unwrap(result, 'metamask.feature_flags.set');
+}
+
+/** Drop every override so the slot never leaks a variant into the next run. */
+export async function clearMobileFlags(input) {
+  const result = await evaluate(input, `
+    if (typeof controller.clearAllFlagOverrides !== 'function') {
+      return JSON.stringify({
+        ok: false,
+        error: 'RemoteFeatureFlagController.clearAllFlagOverrides is unavailable in this build; update @metamask/remote-feature-flag-controller in the checkout.',
+      });
+    }
+    var before = Object.keys((controller.state || {}).localOverrides || {});
+    controller.clearAllFlagOverrides();
+    var current = snapshot();
+    return JSON.stringify({ ok: true, cleared: before, effective: current.effective, overrides: current.overrides });
+  `);
+  return unwrap(result, 'metamask.feature_flags.clear');
+}
+
+/** Restrict an effective/override map to the requested keys, when `keys` is given. */
+export function selectKeys(map, keys) {
+  if (!Array.isArray(keys) || keys.length === 0) return map;
+  const selected = {};
+  // An absent key reads as null rather than disappearing: a caller that asked
+  // about a key deserves an answer about it, and JSON drops undefined.
+  for (const key of keys) selected[key] = map[key] === undefined ? null : map[key];
+  return selected;
+}
+
+/**
+ * Read the requested keys back and fail loudly when the runtime disagrees with
+ * what was asked for. Applying a flag nobody can observe is not proof.
+ */
+export function assertFlagsReadBack(requested, effective, action) {
+  const mismatched = Object.keys(requested).filter(
+    (key) => JSON.stringify(effective[key]) !== JSON.stringify(requested[key]),
+  );
+  if (mismatched.length > 0) {
+    throw new Error(
+      `${action} did not read back: ${mismatched
+        .map((key) => `${key} expected ${JSON.stringify(requested[key])}, got ${JSON.stringify(effective[key])}`)
+        .join('; ')}.`,
+    );
+  }
+}

package/library/actions/mobile/feature_flags/read.mjs

@@ -0,0 +1,20 @@
+// Read the effective remote feature flags and the local overrides from the running app.
+import { runAdapter } from '../platform/bridge.mjs';
+import { readMobileFlags, selectKeys } from './controller.mjs';
+
+runAdapter(async (input) => {
+  const keys = Array.isArray(input.node?.keys) ? input.node.keys.map(String) : [];
+  // Read only. The keys here are the app's, not the harness's, so they are
+  // reported as the controller holds them: validating app-owned key names on a
+  // read would fail the read over a flag the harness never authored.
+  const { effective, overrides } = await readMobileFlags(input);
+  return {
+    action: input.action,
+    source: 'mobile-remote-feature-flag-controller',
+    effective: selectKeys(effective, keys),
+    overrides: selectKeys(overrides, keys),
+    overrideCount: Object.keys(overrides).length,
+    supported: true,
+    proofPath: 'mobile-remote-feature-flags',
+  };
+});

package/library/actions/mobile/feature_flags/set.mjs

@@ -0,0 +1,25 @@
+// Pin remote feature-flag overrides on the running app, then read them back.
+import { normalizeFeatureFlagRecord } from '../../harness-exports.mjs';
+import { runAdapter } from '../platform/bridge.mjs';
+import { assertFlagsReadBack, setMobileFlags } from './controller.mjs';
+
+runAdapter(async (input) => {
+  const requested = normalizeFeatureFlagRecord(
+    input.node?.flags,
+    'metamask.feature_flags.set',
+  );
+  if (Object.keys(requested).length === 0) {
+    throw new Error('metamask.feature_flags.set requires a non-empty flags object, e.g. flags={"perpsTAT3938AbtestScreenVsBottomSheet":"treatment"}.');
+  }
+  const { applied, effective, overrides } = await setMobileFlags(input, requested);
+  assertFlagsReadBack(requested, effective, 'metamask.feature_flags.set');
+  return {
+    action: input.action,
+    source: 'mobile-remote-feature-flag-controller',
+    applied,
+    overrides,
+    effective,
+    supported: true,
+    proofPath: 'mobile-remote-feature-flags',
+  };
+});

package/library/actions/mobile/wallet/reset.mjs

@@ -1,21 +1,42 @@
 // Reset the wallet through visible UI and verify fresh onboarding using the bridge or native accessibility.
 import { runAdapter } from '../platform/bridge.mjs';
+import { clearMobileFlags } from '../feature_flags/controller.mjs';
 import { resetMobileWalletThroughUi } from './reset-helper.mjs';
 import { isOpaqueMobileRuntime, resetWalletThroughNativeUi } from './native-ui.mjs';
 
+// A reset that leaves a pinned A/B variant behind would silently carry one run's
+// variant into the next. Overrides live in the controller, not the vault, so the
+// visible reset flow does not drop them on its own.
+//
+// The opaque-runtime path drives native accessibility precisely because the JS
+// bridge is unavailable there, so the controller cannot be reached and the
+// override state is reported as unattempted rather than failing the reset or
+// claiming a clear that never happened.
+async function clearFeatureFlagOverrides(input) {
+  const { cleared } = await clearMobileFlags(input);
+  return { attempted: true, cleared };
+}
+
 runAdapter(async (input) => {
   if (isOpaqueMobileRuntime(input)) {
     const result = await resetWalletThroughNativeUi(input);
     return {
       action: input.action,
       ...result,
+      featureFlagOverrides: {
+        attempted: false,
+        reason: 'The opaque mobile runtime has no JS bridge, so RemoteFeatureFlagController is unreachable from this reset path.',
+        cleared: [],
+      },
       route: 'Onboarding',
       redacted: true,
       proofPath: 'mobile-visible-wallet-reset-native',
     };
   }
+  const reset = await resetMobileWalletThroughUi(input);
   return {
     action: input.action,
-    ...(await resetMobileWalletThroughUi(input)),
+    ...reset,
+    featureFlagOverrides: await clearFeatureFlagOverrides(input),
   };
 });

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

@@ -1,6 +1,96 @@
 {
   "$schema": "https://farmslot.io/schemas/action-manifest-v1.schema.json",
   "actions": {
+    "metamask.feature_flags.set": {
+      "description": "Report that core, the headless adapter, holds no remote feature flags to override.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "flags": {
+            "type": "object",
+            "description": "Flag key to value. A bare word is a named A/B variant (\"treatment\" becomes { \"name\": \"treatment\" }); true/false is a boolean; an object or array is used as authored."
+          },
+          "controller_ready_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the app runtime to accept the override."
+          }
+        },
+        "required": [
+          "flags"
+        ],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.set",
+          "flags": {
+            "perpsTAT3938AbtestScreenVsBottomSheet": "treatment"
+          },
+          "intent": "Pin the A/B variant the proof runs under",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
+    "metamask.feature_flags.read": {
+      "description": "Report that core, the headless adapter, holds no remote feature flags to read.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict the reported flags to these keys. Omit to report every flag."
+          },
+          "controller_ready_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the app runtime to answer."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.read",
+          "keys": [
+            "perpsTAT3938AbtestScreenVsBottomSheet"
+          ],
+          "intent": "Record the A/B variant the proof ran under",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.feature_flags.clear": {
+      "description": "Report that core, the headless adapter, holds no remote feature-flag overrides to clear.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "controller_ready_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the app runtime to answer."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.clear",
+          "intent": "Drop the pinned variant before the next run",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
     "command": {
       "description": "Run a shell command from the project root.",
       "examples": [

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

@@ -1,6 +1,76 @@
 {
   "$schema": "https://farmslot.io/schemas/action-manifest-v1.schema.json",
   "actions": {
+    "metamask.feature_flags.set": {
+      "description": "Report that the extension cannot pin remote feature flags at runtime and name the relaunch that can. The extension pins flags into the per-run dist snapshot manifest at launch.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "flags": {
+            "type": "object",
+            "description": "Flag key to value. A bare word is a named A/B variant (\"treatment\" becomes { \"name\": \"treatment\" }); true/false is a boolean; an object or array is used as authored."
+          }
+        },
+        "required": [
+          "flags"
+        ],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.set",
+          "flags": {
+            "perpsTAT3938AbtestScreenVsBottomSheet": "treatment"
+          },
+          "intent": "Pin the A/B variant the proof runs under",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.feature_flags.read": {
+      "description": "Read the effective remote feature flags, the manifest pin, and the fetched flags from the running extension.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict the reported flags to these keys. Omit to report every flag."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.read",
+          "keys": [
+            "perpsTAT3938AbtestScreenVsBottomSheet"
+          ],
+          "intent": "Record the A/B variant the proof ran under",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.feature_flags.clear": {
+      "description": "Confirm no manifest flag pin is active, or name the relaunch that drops it.",
+      "schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.clear",
+          "intent": "Drop the pinned variant before the next run",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
     "command": {
       "description": "Run a shell command from the project root.",
       "examples": [

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

@@ -1,6 +1,96 @@
 {
   "$schema": "https://farmslot.io/schemas/action-manifest-v1.schema.json",
   "actions": {
+    "metamask.feature_flags.set": {
+      "description": "Pin remote feature-flag overrides on the running app and read them back. Overrides persist and win over every later remote refetch.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "flags": {
+            "type": "object",
+            "description": "Flag key to value. A bare word is a named A/B variant (\"treatment\" becomes { \"name\": \"treatment\" }); true/false is a boolean; an object or array is used as authored."
+          },
+          "controller_ready_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the app runtime to accept the override."
+          }
+        },
+        "required": [
+          "flags"
+        ],
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.set",
+          "flags": {
+            "perpsTAT3938AbtestScreenVsBottomSheet": "treatment"
+          },
+          "intent": "Pin the A/B variant the proof runs under",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
+    "metamask.feature_flags.read": {
+      "description": "Read the effective remote feature flags and the local overrides from the running app.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict the reported flags to these keys. Omit to report every flag."
+          },
+          "controller_ready_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the app runtime to answer."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.read",
+          "keys": [
+            "perpsTAT3938AbtestScreenVsBottomSheet"
+          ],
+          "intent": "Record the A/B variant the proof ran under",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
+    "metamask.feature_flags.clear": {
+      "description": "Drop every local remote feature-flag override so the slot leaks no variant into the next run.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "controller_ready_timeout_ms": {
+            "type": "number",
+            "minimum": 1,
+            "description": "Maximum time in milliseconds to wait for the app runtime to answer."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.feature_flags.clear",
+          "intent": "Drop the pinned variant before the next run",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": [
+        "app-mutation"
+      ]
+    },
     "command": {
       "description": "Run a shell command from the project root.",
       "examples": [

package/package.json

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