@deeeed/metamask-harness 0.58.0 → 0.60.0

package/dist/feature-flags.js

@@ -0,0 +1,193 @@
+import { readFileSync } from "node:fs";
+const REMOTE_FLAG_USAGE = 'pass --remote-flag KEY=VALUE[,KEY=VALUE] \u2014 VALUE is a variant name (treatment), true/false, or JSON ({"enabled":true})';
+class FeatureFlagSpecError extends Error {
+  userAction;
+  constructor(message, userAction = REMOTE_FLAG_USAGE) {
+    super(message);
+    this.name = "FeatureFlagSpecError";
+    this.userAction = userAction;
+  }
+}
+const KEY_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$.-]*$/u;
+function assertKey(key, where) {
+  if (!key) {
+    throw new FeatureFlagSpecError(`${where} has an empty feature-flag key.`);
+  }
+  if (!KEY_PATTERN.test(key)) {
+    throw new FeatureFlagSpecError(
+      `${where} feature-flag key ${JSON.stringify(key)} is not a flag name; expected a remote feature-flag key such as perpsTAT3938AbtestScreenVsBottomSheet.`
+    );
+  }
+}
+function normalizeFeatureFlagValue(raw, where) {
+  if (typeof raw !== "string") {
+    if (raw === null) return null;
+    if (typeof raw === "boolean" || typeof raw === "number") return raw;
+    if (typeof raw === "object") return raw;
+    throw new FeatureFlagSpecError(
+      `${where} feature-flag value has unsupported type ${typeof raw}; use a variant name, true/false, or JSON.`
+    );
+  }
+  const value = raw.trim();
+  if (!value) {
+    throw new FeatureFlagSpecError(
+      `${where} has an empty feature-flag value; a flag needs a variant name, true/false, or JSON.`
+    );
+  }
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value.startsWith("{") || value.startsWith("[")) {
+    try {
+      return JSON.parse(value);
+    } catch (error) {
+      throw new FeatureFlagSpecError(
+        `${where} feature-flag value is not valid JSON: ${value} (${error instanceof Error ? error.message : String(error)}).`
+      );
+    }
+  }
+  return { name: value };
+}
+function splitPairs(spec) {
+  const pairs = [];
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let current = "";
+  for (const char of spec) {
+    if (inString) {
+      current += char;
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      current += char;
+      continue;
+    }
+    if (char === "{" || char === "[") depth += 1;
+    if (char === "}" || char === "]") depth -= 1;
+    if (char === "," && depth <= 0) {
+      pairs.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  pairs.push(current);
+  return pairs.map((pair) => pair.trim()).filter((pair) => pair.length > 0);
+}
+function parseRemoteFlagSpec(spec, where = "--remote-flag") {
+  const pairs = splitPairs(spec);
+  if (pairs.length === 0) {
+    throw new FeatureFlagSpecError(`${where} had no KEY=VALUE pairs: ${JSON.stringify(spec)}.`);
+  }
+  const flags = {};
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    if (separator < 0) {
+      throw new FeatureFlagSpecError(`${where} expects KEY=VALUE, got: ${pair}.`);
+    }
+    const key = pair.slice(0, separator).trim();
+    assertKey(key, where);
+    if (Object.prototype.hasOwnProperty.call(flags, key)) {
+      throw new FeatureFlagSpecError(`${where} sets ${key} more than once; give each key one value.`);
+    }
+    flags[key] = normalizeFeatureFlagValue(pair.slice(separator + 1), where);
+  }
+  return flags;
+}
+function normalizeFeatureFlagRecord(raw, where) {
+  if (raw === void 0 || raw === null) return {};
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new FeatureFlagSpecError(
+      `${where} remoteFeatureFlags must be an object of key \u2192 variant name, true/false, or JSON.`,
+      'edit the wallet fixture so remoteFeatureFlags is an object, e.g. { "perpsTAT3938AbtestScreenVsBottomSheet": "treatment" }'
+    );
+  }
+  const flags = {};
+  for (const [key, value] of Object.entries(raw)) {
+    assertKey(key, `${where} remoteFeatureFlags`);
+    flags[key] = normalizeFeatureFlagValue(value, `${where} remoteFeatureFlags.${key}`);
+  }
+  return flags;
+}
+function describeFeatureFlagValue(value) {
+  if (typeof value === "boolean" || typeof value === "number") return String(value);
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const named = value["name"];
+    if (typeof named === "string") return named;
+  }
+  return JSON.stringify(value);
+}
+function featureFlagReport(overrides, detail = {}) {
+  return {
+    summary: formatFeatureFlagLine(overrides, detail),
+    overrides,
+    overrideCount: overrides ? Object.keys(overrides).length : null,
+    ...detail.error ? { error: detail.error } : {},
+    ...detail.sourcePath ? { sourcePath: detail.sourcePath } : {}
+  };
+}
+function formatFeatureFlagLine(overrides, detail = {}) {
+  if (detail.error) {
+    return `feature flags: (unreadable${detail.sourcePath ? ` \u2014 ${detail.sourcePath}` : ""}: ${detail.error})`;
+  }
+  if (!overrides) return "feature flags: (no runtime)";
+  const entries = Object.entries(overrides);
+  if (entries.length === 0) return "feature flags: 0 override(s)";
+  const described = entries.map(([key, value]) => `${key}=${describeFeatureFlagValue(value)}`).join(", ");
+  return `feature flags: ${entries.length} override(s) ${described}`;
+}
+function sameFeatureFlags(a, b) {
+  const keys = [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])];
+  return keys.every((key) => JSON.stringify(a[key]) === JSON.stringify(b[key]));
+}
+function fixtureFeatureFlags(fixturePath) {
+  let raw;
+  try {
+    raw = readFileSync(fixturePath, "utf8");
+  } catch {
+    return {};
+  }
+  let body;
+  try {
+    body = JSON.parse(raw);
+  } catch (error) {
+    throw new FeatureFlagSpecError(
+      `${fixturePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+      "fix the wallet fixture, or run mm-harness fixtures init to regenerate it"
+    );
+  }
+  return normalizeFeatureFlagRecord(body?.["remoteFeatureFlags"], fixturePath);
+}
+function remoteFlagRequestFor(flags) {
+  if (Object.keys(flags).length === 0) return void 0;
+  return { flags, json: JSON.stringify(flags), spec: toRemoteFlagSpec(flags) };
+}
+function toRemoteFlagSpec(flags) {
+  return Object.entries(flags).map(([key, value]) => {
+    if (typeof value === "boolean") return `${key}=${String(value)}`;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const named = value["name"];
+      if (typeof named === "string" && Object.keys(value).length === 1) return `${key}=${named}`;
+    }
+    return `${key}=${JSON.stringify(value)}`;
+  }).join(",");
+}
+export {
+  FeatureFlagSpecError,
+  REMOTE_FLAG_USAGE,
+  describeFeatureFlagValue,
+  featureFlagReport,
+  fixtureFeatureFlags,
+  formatFeatureFlagLine,
+  normalizeFeatureFlagRecord,
+  normalizeFeatureFlagValue,
+  parseRemoteFlagSpec,
+  remoteFlagRequestFor,
+  sameFeatureFlags,
+  toRemoteFlagSpec
+};

package/dist/harness.js

@@ -259,19 +259,7 @@ Next: mm-harness install --platform core --target ${target}`
     }
     return { command: delegate, prefixArgs: ["doctor", "--adapter", "core"] };
   }
-  if (adapter === "mobile" && action === "verify") {
-    return { inProcess: "mobile-verify" };
-  }
-  const installedScript = path.join(recipeHarnessPath(target, adapter), "scripts", `${action}.sh`);
-  if (fs.existsSync(installedScript)) {
-    return { command: installedScript, prefixArgs: [] };
-  }
-  const command = resolveEntry(
-    runnerDir,
-    [`adapters/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
-    "file"
-  );
-  return { command, prefixArgs: [] };
+  return { inProcess: adapter === "mobile" ? "mobile-verify" : "extension-verify" };
 }
 async function handleHarness(argv) {
   const action = argv[0];
@@ -340,10 +328,10 @@ async function handleHarness(argv) {
   }
   const start = Date.now();
   if ("inProcess" in dispatch) {
-    const { runMobileVerify } = await import("./adapters/mobile/verify.js");
+    const runVerify = dispatch.inProcess === "mobile-verify" ? (await import("./adapters/mobile/verify.js")).runMobileVerify : (await import("./adapters/extension/verify.js")).runExtensionVerify;
     let exitCode;
     try {
-      exitCode = await runMobileVerify(forwardArgs, {
+      exitCode = await runVerify(forwardArgs, {
         out: quiet ? () => {
         } : (line) => {
           (json ? process.stderr : process.stdout).write(`${line}

package/dist/mm-harness-cli.js

@@ -435,7 +435,13 @@ Example:
 Example (real actions; run mm-harness actions for this checkout's full set):
   mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
   mm-harness call navigate page=perps --adapter mobile
-  mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)`
+  mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)
+
+Remote feature flags (mobile applies at runtime; extension pins at launch):
+  mm-harness call metamask.feature_flags.read --adapter mobile
+  mm-harness call metamask.feature_flags.set --adapter mobile \\
+    --arg 'flags={"perpsTAT3938AbtestScreenVsBottomSheet":"treatment"}'
+  mm-harness call metamask.feature_flags.clear --adapter mobile`
   },
   {
     name: "run",
@@ -691,6 +697,11 @@ Example:
   --surface <fullscreen|sidepanel>   Extension display mode (default: fullscreen)
   --sidepanel | --fullscreen         Legacy aliases for --surface
   --url <dapp-url>                    Open a dapp beside the sidepanel (default: MetaMask test dapp)
+  --remote-flag <KEY=VALUE[,...]>    Pin remote feature flags. VALUE is a variant name (treatment),
+                                     true/false, or JSON. Mobile applies it through
+                                     RemoteFeatureFlagController once the bridge is ready and fails the
+                                     launch if it does not read back; Extension pins it into the per-run
+                                     dist snapshot manifest (so it skips the reuse fast path).
   --heal <off|infra-only|auto>       Healing policy (default auto); bounds always enforced
   --device <udid|name>               Target simulator/device (env: IOS_SIMULATOR / ADB_SERIAL)
   --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
@@ -704,7 +715,8 @@ Example:
   mm-harness launch ios
   mm-harness launch android --clear-metro --verify
   mm-harness launch ios --build
-  mm-harness launch --verify --json`
+  mm-harness launch --verify --json
+  mm-harness launch --remote-flag perpsTAT3938AbtestScreenVsBottomSheet=treatment`
   },
   {
     name: "logs",
@@ -849,6 +861,7 @@ Example:
   --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
   --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
   --action-manifest <path>           Extension set: override the wallet action manifest
+  --remote-flag <KEY=VALUE[,...]>    set/reset: one-run override layered over the fixture's remoteFeatureFlags
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --device <udid|serial|name>        Mobile only: target this device for sync/set

package/library/actions/core/feature_flags/_unsupported.mjs

@@ -0,0 +1,29 @@
+// Core is the headless adapter: it drives controllers over HTTP and runs no app
+// runtime, so there is no RemoteFeatureFlagController and no manifest to pin.
+// Reads answer `{ supported: false }` with exit 0 (an honest empty observation);
+// mutations exit non-zero so nobody records a variant that was never applied.
+import { readFile, writeFile } from 'node:fs/promises';
+
+export const CORE_UNSUPPORTED_REASON =
+  'core is headless: it has no app runtime, so it holds no RemoteFeatureFlagController and no extension manifest to pin. Run this action against the mobile or extension adapter.';
+
+export async function runCoreFeatureFlagStub({ mutation }) {
+  const inputPath = process.argv[2] || process.env.METAMASK_RECIPE_ADAPTER_INPUT;
+  if (!inputPath) throw new Error('Adapter input path is required.');
+  const input = JSON.parse(await readFile(inputPath, 'utf8'));
+  const output = {
+    action: input.action,
+    source: 'core-headless',
+    supported: false,
+    reason: CORE_UNSUPPORTED_REASON,
+    effective: {},
+    overrides: {},
+    next: `mm-harness call ${input.action} --adapter mobile --target <metamask-mobile-checkout>`,
+    proofPath: 'core-feature-flags-unsupported',
+  };
+  if (input.outputPath) await writeFile(input.outputPath, `${JSON.stringify(output, null, 2)}\n`);
+  else process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (mutation) {
+    throw new Error(`${input.action} is not supported on core. ${CORE_UNSUPPORTED_REASON}\n  Next: ${output.next}`);
+  }
+}

package/library/actions/core/feature_flags/clear.mjs

@@ -0,0 +1,8 @@
+// core has no runtime feature flags — answer honestly instead of fabricating one.
+import { pathToFileURL } from 'node:url';
+
+import { runCoreFeatureFlagStub } from './_unsupported.mjs';
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await runCoreFeatureFlagStub({ mutation: true });
+}

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

@@ -0,0 +1,8 @@
+// core has no runtime feature flags — answer honestly instead of fabricating one.
+import { pathToFileURL } from 'node:url';
+
+import { runCoreFeatureFlagStub } from './_unsupported.mjs';
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await runCoreFeatureFlagStub({ mutation: false });
+}

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

@@ -0,0 +1,8 @@
+// core has no runtime feature flags — answer honestly instead of fabricating one.
+import { pathToFileURL } from 'node:url';
+
+import { runCoreFeatureFlagStub } from './_unsupported.mjs';
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await runCoreFeatureFlagStub({ mutation: true });
+}

package/library/actions/extension/feature_flags/clear.mjs

@@ -0,0 +1,48 @@
+// Clear overrides when there are none; otherwise name the relaunch that drops the pin.
+//
+// The extension's overrides live in the per-run dist snapshot manifest, which is
+// re-created at launch. A slot with no pin is already clear (exit 0); a pinned
+// slot needs a relaunch without --remote-flag, so this refuses rather than
+// reporting a clear it did not perform.
+import { runAdapter, withExtensionPage, writeOutput } from '../platform/cdp.mjs';
+import { EXTENSION_SET_UNSUPPORTED_REASON, readFeatureFlagsExpression, resolveOverrides } from './state.mjs';
+
+runAdapter(async (input) => {
+  const state = await withExtensionPage(input, (page) =>
+    page.evaluate(readFeatureFlagsExpression(), { awaitPromise: true }));
+  const resolved = resolveOverrides(state, input.context?.projectRoot);
+  const effective = { ...state.stateFlags, ...resolved.overrides };
+  const pinned = Object.keys(resolved.overrides);
+  const target = String(input.context?.projectRoot ?? '<extension-checkout>');
+  const quoted = /[^A-Za-z0-9_@%+=:,./-]/u.test(target) ? `'${target.replaceAll("'", "'\\''")}'` : target;
+  const next = `mm-harness launch --adapter extension --target ${quoted}`;
+  if (pinned.length === 0) {
+    return {
+      action: input.action,
+      source: 'extension-manifest-pin',
+      supported: true,
+      cleared: [],
+      overrides: {},
+      effective,
+      overrideSource: resolved.overrideSource,
+      needsRelaunch: false,
+      proofPath: 'extension-remote-feature-flags',
+    };
+  }
+  await writeOutput(input, {
+    action: input.action,
+    source: 'extension-manifest-pin',
+    supported: false,
+    reason: EXTENSION_SET_UNSUPPORTED_REASON,
+    cleared: [],
+    overrides: resolved.overrides,
+    effective,
+    overrideSource: resolved.overrideSource,
+    needsRelaunch: true,
+    next,
+    proofPath: 'extension-remote-feature-flags',
+  });
+  throw new Error(
+    `metamask.feature_flags.clear cannot drop the extension manifest pin at runtime (${pinned.join(', ')}). ${EXTENSION_SET_UNSUPPORTED_REASON}\n  Next: ${next}`,
+  );
+});

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

@@ -0,0 +1,27 @@
+// Read the effective remote feature flags and the manifest pin from the running extension.
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import { readFeatureFlagsExpression, resolveOverrides, selectKeys } from './state.mjs';
+
+runAdapter((input) => withExtensionPage(input, async (page) => {
+  const keys = Array.isArray(input.node?.keys) ? input.node.keys.map(String) : [];
+  const state = await page.evaluate(readFeatureFlagsExpression(), { awaitPromise: true });
+  const resolved = resolveOverrides(state, input.context?.projectRoot);
+  // The extension merges the manifest pin over the fetched flags, manifest wins.
+  const effective = { ...state.stateFlags, ...resolved.overrides };
+  return {
+    action: input.action,
+    source: 'extension-manifest-pin-and-controller-state',
+    overrideSource: resolved.overrideSource,
+    ...(resolved.overrideSourcePath ? { overrideSourcePath: resolved.overrideSourcePath } : {}),
+    ...(resolved.manifestUnreadableReason
+      ? { manifestUnreadableReason: resolved.manifestUnreadableReason }
+      : {}),
+    effective: selectKeys(effective, keys),
+    overrides: selectKeys(resolved.overrides, keys),
+    overrideCount: Object.keys(resolved.overrides).length,
+    fetched: selectKeys(state.stateFlags, keys),
+    thresholdGroups: state.thresholdGroups,
+    supported: true,
+    proofPath: 'extension-remote-feature-flags',
+  };
+}));

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

@@ -0,0 +1,36 @@
+// Refuse a runtime override honestly and name the relaunch that pins the flag.
+//
+// The extension's only override channel is the per-run dist snapshot manifest
+// (`_flags.remoteFeatureFlags`), written at launch. Nothing in the background
+// exposes setFlagOverride, so there is no code path that could make this action
+// take effect — see EXTENSION_SET_UNSUPPORTED_REASON in ./state.mjs. The
+// structured refusal is written to the output file before throwing so callers
+// keep the record and still see a non-zero exit.
+import { normalizeFeatureFlagRecord, toRemoteFlagSpec } from '../../harness-exports.mjs';
+import { runAdapter, writeOutput } from '../platform/cdp.mjs';
+import { EXTENSION_SET_UNSUPPORTED_REASON, relaunchHint } from './state.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 next = relaunchHint(
+    String(input.context?.projectRoot ?? '<extension-checkout>'),
+    toRemoteFlagSpec(requested),
+  );
+  await writeOutput(input, {
+    action: input.action,
+    source: 'extension-manifest-pin',
+    supported: false,
+    reason: EXTENSION_SET_UNSUPPORTED_REASON,
+    applied: [],
+    requested,
+    needsRelaunch: true,
+    next,
+    proofPath: 'extension-remote-feature-flags',
+  });
+  throw new Error(
+    `metamask.feature_flags.set is not supported on the extension at runtime. ${EXTENSION_SET_UNSUPPORTED_REASON}\n  Next: ${next}`,
+  );
+});

package/library/actions/extension/feature_flags/state.mjs

@@ -0,0 +1,129 @@
+// Extension remote feature-flag transport: the manifest `_flags` pin plus controller state.
+//
+// The extension resolves flags as
+//   getRemoteFeatureFlags = merge({}, state.metamask.remoteFeatureFlags, manifest._flags.remoteFeatureFlags)
+// (shared/lib/selectors/remote-feature-flags.ts), with the manifest winning. The
+// manifest pin is therefore the extension's override channel, and it is written
+// into the per-run dist snapshot at launch by adapters/extension/pin-remote-flags.cjs.
+//
+// There is no runtime override RPC: metamask-controller.js never wires
+// RemoteFeatureFlagController.setFlagOverride into getApi(), and
+// `grep -rn 'setFlagOverride' app/ shared/ ui/` finds nothing in the checkout,
+// so stateHooks.submitRequestToBackground cannot reach it. `set` and `clear`
+// therefore refuse honestly and name the relaunch that does work.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { recipeRuntimeDir } from '../../harness-exports.mjs';
+
+export const EXTENSION_SET_UNSUPPORTED_REASON =
+  'The extension exposes no runtime remote feature-flag override RPC: RemoteFeatureFlagController.setFlagOverride is never registered in metamask-controller.js getApi(), so stateHooks.submitRequestToBackground cannot reach it. Overrides are pinned into the per-run dist snapshot manifest at launch.';
+
+/**
+ * Page expression reading the controller's fetched flags, plus the running
+ * manifest's pin when the page realm can still reach `chrome`.
+ *
+ * A LavaMoat build scuttles `chrome` in the page realm, so the manifest read is
+ * best-effort here and the caller falls back to the snapshot file on disk. The
+ * failure is reported, never swallowed: `manifestReadable` says which source the
+ * override record can come from.
+ */
+export function readFeatureFlagsExpression() {
+  return `(async () => {
+    const hooks = globalThis.stateHooks || {};
+    let root = null;
+    if (typeof hooks.getCleanAppState === 'function') {
+      root = await hooks.getCleanAppState();
+    }
+    if ((!root || typeof root !== 'object') && typeof hooks.store?.getState === 'function') {
+      root = hooks.store.getState();
+    }
+    if (!root || typeof root !== 'object') {
+      throw new Error('stateHooks.getCleanAppState and stateHooks.store.getState are unavailable.');
+    }
+    const metamask = root.metamask || root;
+    let manifestFlags = null;
+    let manifestUnreadableReason = null;
+    try {
+      // Gate on the accessor itself: optional chaining alone would yield
+      // undefined on a page without chrome and report an empty pin as if the
+      // running manifest had answered.
+      if (typeof globalThis.chrome?.runtime?.getManifest !== 'function') {
+        throw new Error('chrome.runtime.getManifest is not a function on this page.');
+      }
+      const manifest = globalThis.chrome.runtime.getManifest();
+      manifestFlags = manifest?._flags?.remoteFeatureFlags || {};
+    } catch (error) {
+      // Not swallowed: a LavaMoat build scuttles chrome in the page realm, and
+      // the caller answers from the snapshot manifest on disk instead. The
+      // reason travels with the result so the source is never ambiguous.
+      manifestUnreadableReason = String(error?.message || error);
+    }
+    return {
+      manifestReadable: manifestFlags !== null,
+      manifestUnreadableReason,
+      stateFlags: metamask.remoteFeatureFlags || {},
+      manifestFlags: manifestFlags || {},
+      thresholdGroups: metamask.featureFlagThresholdGroups || {},
+    };
+  })()`;
+}
+
+/**
+ * The per-run dist snapshot manifest, which is what pin-remote-flags.cjs writes
+ * and what the browser was launched from. `null` means no snapshot exists.
+ */
+export function readSnapshotManifestFlags(projectRoot) {
+  const manifestPath = path.join(
+    String(projectRoot ?? ''),
+    recipeRuntimeDir(),
+    process.env.RECIPE_RUNTIME_DIST_DIR || 'runtime-dist',
+    'manifest.json',
+  );
+  if (!fs.existsSync(manifestPath)) return null;
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  return { flags: manifest?._flags?.remoteFeatureFlags || {}, path: manifestPath };
+}
+
+/**
+ * Resolve the override record from the running manifest when the page can read
+ * it, and from the launched snapshot on disk when LavaMoat scuttles `chrome`.
+ * Always reports which source answered.
+ */
+export function resolveOverrides(pageState, projectRoot) {
+  if (pageState.manifestReadable) {
+    return {
+      overrides: pageState.manifestFlags,
+      overrideSource: 'running-extension-manifest',
+    };
+  }
+  const snapshot = readSnapshotManifestFlags(projectRoot);
+  if (!snapshot) {
+    throw new Error(
+      `The page realm cannot read chrome.runtime.getManifest() (${pageState.manifestUnreadableReason}) and no dist snapshot manifest exists under ${String(projectRoot)}, so the pinned remote feature flags are unknown.`,
+    );
+  }
+  return {
+    overrides: snapshot.flags,
+    overrideSource: 'launched-dist-snapshot-manifest',
+    overrideSourcePath: snapshot.path,
+    manifestUnreadableReason: pageState.manifestUnreadableReason,
+  };
+}
+
+/** Restrict a flag 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;
+}
+
+/** The relaunch that does pin a flag, quoted so it can be run as printed. */
+export function relaunchHint(target, spec) {
+  const quoted = /[^A-Za-z0-9_@%+=:,./-]/u.test(target) ? `'${target.replaceAll("'", "'\\''")}'` : target;
+  return `mm-harness launch --adapter extension --remote-flag ${spec} --target ${quoted}`;
+}

package/library/actions/harness-exports.mjs

@@ -15,13 +15,27 @@ async function load(distRelative, srcRelative) {
 
 const paths = await load('dist/paths.js', 'src/paths.ts');
 const recording = await load('dist/run-recording.js', 'src/run-recording.ts');
+const featureFlags = await load('dist/feature-flags.js', 'src/feature-flags.ts');
 
 export const {
   importRecipeHarnessRuntimeBrowserExtension,
   importRecipeHarnessRuntimeCdp,
   extensionIdPath,
   recipeHarnessPath,
+  recipeRuntimeDir,
   walletFixturePath,
 } = paths;
 
 export const { captureActiveRecipeRecordingSnapshot } = recording;
+
+// One normalisation for --remote-flag specs, fixture objects, and the
+// doctor/status summary line. See src/feature-flags.ts.
+export const {
+  FeatureFlagSpecError,
+  describeFeatureFlagValue,
+  formatFeatureFlagLine,
+  normalizeFeatureFlagRecord,
+  normalizeFeatureFlagValue,
+  parseRemoteFlagSpec,
+  toRemoteFlagSpec,
+} = featureFlags;

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

@@ -0,0 +1,20 @@
+// Drop every local remote feature-flag override so the slot leaks no variant.
+import { runAdapter } from '../platform/bridge.mjs';
+import { clearMobileFlags } from './controller.mjs';
+
+runAdapter(async (input) => {
+  const { cleared, effective, overrides } = await clearMobileFlags(input);
+  const remaining = Object.keys(overrides);
+  if (remaining.length > 0) {
+    throw new Error(`metamask.feature_flags.clear left ${remaining.length} override(s): ${remaining.join(', ')}.`);
+  }
+  return {
+    action: input.action,
+    source: 'mobile-remote-feature-flag-controller',
+    cleared,
+    overrides,
+    effective,
+    supported: true,
+    proofPath: 'mobile-remote-feature-flags',
+  };
+});