@deeeed/metamask-harness 0.58.0 → 0.60.0

package/dist/adapters/mobile/feature-flags.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { runnerDir } from "../../paths.js";
+const DEFAULT_TIMEOUT_MS = 1e4;
+function bridgeScriptPath() {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+}
+const CONTROLLER_PREAMBLE = `
+  var ctx = globalThis.Engine && globalThis.Engine.context;
+  var c = ctx && ctx.RemoteFeatureFlagController;
+  if (!c) return JSON.stringify({ ok: false, error: 'Engine.context.RemoteFeatureFlagController is not available on the running app.' });
+  var snap = function () {
+    var st = c.state || {};
+    return { effective: st.remoteFeatureFlags || {}, overrides: st.localOverrides || {} };
+  };
+`;
+function evalExpression(body) {
+  return `(function(){ try {${CONTROLLER_PREAMBLE}${body} } catch (e) { return JSON.stringify({ ok: false, error: e && (e.message || String(e)) }); } })()`;
+}
+function runBridgeEval(target, expression, timeoutMs) {
+  const script = bridgeScriptPath();
+  if (!fs.existsSync(script)) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = "";
+    const child = spawn(process.execPath, [script, "eval", expression], {
+      cwd: target,
+      env: { ...process.env, APP_ROOT: target, CDP_TIMEOUT: String(timeoutMs) },
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      const killTimer = setTimeout(() => child.kill("SIGKILL"), 500);
+      child.once("close", () => clearTimeout(killTimer));
+      finish(null);
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("close", (code) => {
+      if (code !== 0) return finish(null);
+      const trimmed = stdout.trim();
+      if (!trimmed) return finish(null);
+      try {
+        const first = JSON.parse(trimmed);
+        const parsed = typeof first === "string" ? JSON.parse(first) : first;
+        return finish(parsed);
+      } catch {
+        return finish(null);
+      }
+    });
+    child.on("error", () => finish(null));
+  });
+}
+async function readMobileFeatureFlags(target, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const result = await runBridgeEval(
+    target,
+    evalExpression("var s = snap(); return JSON.stringify({ ok: true, effective: s.effective, overrides: s.overrides });"),
+    timeoutMs
+  );
+  if (!result || result.ok !== true) return null;
+  return { effective: result.effective ?? {}, overrides: result.overrides ?? {} };
+}
+async function pinMobileFeatureFlags(target, flags, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const payload = JSON.stringify(JSON.stringify(flags));
+  const result = await runBridgeEval(
+    target,
+    evalExpression(`
+      if (typeof c.setFlagOverride !== 'function') {
+        return JSON.stringify({ ok: false, error: 'RemoteFeatureFlagController.setFlagOverride is unavailable in this build.' });
+      }
+      var requested = JSON.parse(${payload});
+      if (typeof c.clearAllFlagOverrides === 'function') c.clearAllFlagOverrides();
+      var applied = [];
+      for (var k in requested) {
+        if (Object.prototype.hasOwnProperty.call(requested, k)) { c.setFlagOverride(k, requested[k]); applied.push(k); }
+      }
+      var s = snap();
+      return JSON.stringify({ ok: true, applied: applied, effective: s.effective, overrides: s.overrides });
+    `),
+    timeoutMs
+  );
+  if (!result) {
+    return {
+      ok: false,
+      error: "the mobile bridge did not answer, so no remote feature flag was applied.",
+      applied: [],
+      effective: {},
+      overrides: {},
+      mismatched: Object.keys(flags)
+    };
+  }
+  if (result.ok !== true) {
+    return {
+      ok: false,
+      error: result.error ?? "the mobile runtime refused the remote feature-flag override.",
+      applied: [],
+      effective: {},
+      overrides: {},
+      mismatched: Object.keys(flags)
+    };
+  }
+  const effective = result.effective ?? {};
+  const overrides = result.overrides ?? {};
+  const mismatched = [
+    ...Object.keys(flags).filter((key) => JSON.stringify(effective[key]) !== JSON.stringify(flags[key])),
+    ...Object.keys(overrides).filter((key) => !(key in flags))
+  ];
+  return {
+    ok: mismatched.length === 0,
+    applied: result.applied ?? [],
+    effective,
+    overrides,
+    mismatched
+  };
+}
+export {
+  pinMobileFeatureFlags,
+  readMobileFeatureFlags
+};

package/dist/adapters/resolve-slot-ports.js

@@ -3,6 +3,7 @@ import {
   formatExtensionIdentityPorts,
   formatExtensionSlotPorts,
   inferSlotSuffix,
+  poolFilesForHost,
   realRepoPath,
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimeContext,
@@ -17,6 +18,7 @@ export {
   formatExtensionSlotPorts,
   formatKvLines,
   inferSlotSuffix,
+  poolFilesForHost,
   realRepoPath,
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimeContext,

package/dist/adapters.js

@@ -105,6 +105,11 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state"
 ]);
+const LIVE_ONLY_FEATURE_FLAG_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.feature_flags.set",
+  "metamask.feature_flags.read",
+  "metamask.feature_flags.clear"
+]);
 const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
   "ui.navigate",
   "app.network_capture",
@@ -113,7 +118,7 @@ const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
   "app.performance_assert"
 ]);
 function requiresLiveAdapter(platform, action) {
-  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
+  return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_FEATURE_FLAG_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
 function liveRuntimeConfigured(platform, node) {
   if (platform === "mobile" || platform === "core") return true;

package/dist/cli.js

@@ -103,7 +103,7 @@ async function main(argv) {
   if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));
   if (command === "provision") return handleProvision(parseArgs(argv.slice(1), command));
   if (OVERLAY_COMMANDS.includes(command)) {
-    if (command === "verify") {
+    if (command === "verify" && process.env.MM_HARNESS_SKIP_OVERLAY_ENSURE !== "1") {
       try {
         const { options } = parseArgs(argv.slice(1), command);
         const target = targetPath(options);

package/dist/command-contract.js

@@ -154,7 +154,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--platform": value(["mobile", "extension", "core"]),
       "--mobile-platform": value(["ios", "android"]),
       "--clear-metro": bool(),
-      "--artifacts-dir": value()
+      "--artifacts-dir": value(),
+      "--remote-flag": value()
     })
   },
   task: {
@@ -329,7 +330,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--sidepanel": bool(),
       "--fullscreen": bool(),
       "--url": value(),
-      "--heal": value(["off", "infra-only", "auto"])
+      "--heal": value(["off", "infra-only", "auto"]),
+      "--remote-flag": value()
     }),
     positionals: [{ label: "platform", choices: ["ios", "android"] }]
   },
@@ -383,7 +385,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--cdp-port": value(),
       "--extension-dir": value(),
       "--extension-id-file": value(),
-      "--action-manifest": value()
+      "--action-manifest": value(),
+      "--remote-flag": value()
     }),
     positionals: [{ label: "action", choices: ["init", "sync", "set", "reset", "generate", "finalize"] }],
     minimumPositionals: 0

package/dist/commands/doctor.js

@@ -2,6 +2,8 @@ import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { readExtensionPinnedFlags } from "../adapters/extension/feature-flags.js";
+import { featureFlagReport } from "../feature-flags.js";
 import { color } from "../cli-color.js";
 import { collectCheckoutView, renderCheckoutView } from "../checkout-view.js";
 import { createDoctorReport, fixtureSummary, requiredDoctorCheckSummary } from "../doctor.js";
@@ -209,12 +211,14 @@ async function handleDoctor({ options }) {
   }
   const skills = skillsView(target);
   const update = updateStatus();
+  const extensionFlags = adapter === "extension" ? readExtensionPinnedFlags(target) : null;
+  const featureFlags = extensionFlags ? featureFlagReport(extensionFlags.overrides, extensionFlags) : featureFlagReport(liveView?.featureFlagOverrides ?? null);
   const doctorUserAction = doctorResult.checks.find(
     (check) => check.required && check.status === "fail" && check.userAction
   )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
   const next = doctorError?.userAction ?? discovery.deviceDiscoveryErrors?.[0]?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, view, orphanMetros, capture, skills, update, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, view, orphanMetros, capture, skills, update, featureFlags, devices, additionalReachableDevices, ...discovery, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -236,6 +240,10 @@ async function handleDoctor({ options }) {
       console.log(`${out("err", "runtime probe failed:")} ${out("dim", runtimeProbeError)}`);
     }
     console.log(renderCheckoutView(view));
+    console.log(`${out("label", "feature flags:")} ${out(
+      featureFlags.error || (featureFlags.overrideCount ?? 0) > 0 ? "warn" : "dim",
+      featureFlags.summary.replace(/^feature flags: /u, "")
+    )}`);
     if (adapter === "mobile") {
       const perps = mobilePerpsEnvironment(target);
       console.log(

package/dist/commands/fixtures.js

@@ -8,6 +8,8 @@ import { acquireCheckoutLock } from "../checkout-lock.js";
 import { colorHumanMessage } from "../cli-color.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import { ADAPTER_DETECT_NEXT, checkoutBusyOut, EXIT, flag, parseFlags, resolveAdapter, scriptOverride, spawnScript, spawnScriptStreaming, str, targetOf, usageOut } from "./shared.js";
+import { FeatureFlagSpecError, fixtureFeatureFlags, parseRemoteFlagSpec, sameFeatureFlags } from "../feature-flags.js";
+import { readExtensionPinnedFlags } from "../adapters/extension/feature-flags.js";
 const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["dev", "force", "json"]);
 const FIXTURE_STREAM_TIMEOUT_MS = 12e4;
 const MOBILE_SETUP_WALLET_TIMEOUT_MS = 36e4;
@@ -177,8 +179,20 @@ async function handleFixturesLocked(argv) {
       );
     }
   }
+  const remoteFlagSpec = str(options, "remoteFlag");
+  let fixtureFlags;
+  try {
+    fixtureFlags = {
+      ...fixtureFeatureFlags(fixturePath),
+      ...remoteFlagSpec === void 0 ? {} : parseRemoteFlagSpec(remoteFlagSpec)
+    };
+  } catch (error) {
+    if (!(error instanceof FeatureFlagSpecError)) throw error;
+    return usageOut(json, "fixtures", error.message, error.userAction);
+  }
+  const fixtureFlagsJson = JSON.stringify(fixtureFlags);
   if (adapter === "extension") {
-    return applyExtensionFixture(target, fixturePath, canonicalFixture, json, sub);
+    return applyExtensionFixture(target, fixturePath, canonicalFixture, json, sub, fixtureFlags);
   }
   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
@@ -252,7 +266,7 @@ async function handleFixturesLocked(argv) {
       if (!resetError) {
         mobileSetupResult = await spawnScriptStreaming(
           setupWalletSh,
-          ["--fixture", fixturePath],
+          ["--fixture", fixturePath, "--remote-flags-json", fixtureFlagsJson],
           target,
           {
             env: {
@@ -303,7 +317,7 @@ async function handleFixturesLocked(argv) {
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;
 }
-async function applyExtensionFixture(target, fixturePath, canonicalFixture, json, action) {
+async function applyExtensionFixture(target, fixturePath, canonicalFixture, json, action, fixtureFlags) {
   const distManifest = path.join(target, "dist/chrome/manifest.json");
   const userAction = `mm-harness launch --build --verify --target ${JSON.stringify(target)}`;
   if (!fs.existsSync(distManifest)) {
@@ -330,11 +344,39 @@ async function applyExtensionFixture(target, fixturePath, canonicalFixture, json
 `);
   const liveScript = path.join(runnerDir, "adapters/extension/live.sh");
   const args = ["--target", target, "--launch-existing-dist", "--launch-only", "--reset-profile"];
+  const flagKeys = Object.keys(fixtureFlags);
+  if (flagKeys.length > 0) args.push("--remote-flags-json", JSON.stringify(fixtureFlags));
   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 },
     timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
   });
+  const pinned = readExtensionPinnedFlags(target);
+  const pinnedFlags = pinned.pinned ?? {};
+  const flagMismatch = result.status === 0 && !pinned.error && (pinned.pinned === null || !sameFeatureFlags(pinnedFlags, fixtureFlags)) ? [.../* @__PURE__ */ new Set([...flagKeys, ...Object.keys(pinnedFlags)])].filter(
+    (key) => JSON.stringify(pinnedFlags[key]) !== JSON.stringify(fixtureFlags[key])
+  ) : [];
+  if (result.status === 0 && (pinned.error || flagMismatch.length > 0)) {
+    const detail = pinned.error ? `the launched snapshot manifest could not be read (${pinned.sourcePath ?? "unknown path"}): ${pinned.error}` : `snapshot pin disagrees with the fixture for: ${flagMismatch.join(", ")}`;
+    const flagNext = `mm-harness launch --adapter extension --build --target ${JSON.stringify(target)}`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "fixtures",
+        action,
+        adapter: "extension",
+        fixture: fixturePath,
+        canonicalFixture,
+        status: "fail",
+        exitCode: EXIT.runtime,
+        error: { code: "EXTENSION_FIXTURE_FLAGS_NOT_APPLIED", message: detail, userAction: flagNext }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness fixtures ${action}: ${detail}
+  Next: ${flagNext}`);
+    }
+    return EXIT.runtime;
+  }
   const status = result.status === 0 ? "pass" : "fail";
   const exitCode = status === "pass" ? EXIT.ok : EXIT.runtime;
   const message = status === "pass" ? `Wallet fixture applied and validated. Want different accounts? Edit: ${canonicalFixture}` : "Extension wallet fixture could not be applied and validated.";

package/dist/commands/launch/extension.js

@@ -30,6 +30,8 @@ import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { isExtensionWatcherLive, stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { EXIT, spawnScriptStreaming } from "../shared.js";
+import { readExtensionPinnedFlags } from "../../adapters/extension/feature-flags.js";
+import { sameFeatureFlags } from "../../feature-flags.js";
 const { CdpSession } = await importRecipeHarnessRuntimeCdp();
 const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
   path.join(runnerDir, "adapters/extension/lib/chrome-args.cjs")
@@ -55,7 +57,7 @@ async function installExtensionDeps(target) {
   if (result.status === 0) recordDepsBaseline(target);
   return result;
 }
-async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen", remoteFlags) {
   const requestedCdpPort = process.env.CDP_PORT;
   const requestedRecipeCdpPort = process.env.RECIPE_CDP_PORT;
   const restoreRequestedPorts = () => {
@@ -68,8 +70,19 @@ async function launchExtension(target, tier, wantWatch, displayMode = "fullscree
   const artifact = releaseArtifactState(target);
   const artifactSnapshot = runtimeDistCheck(target, artifact);
   const artifactLaunchable = !wantWatch && tier !== "build" && artifact.status === "valid" && artifactSnapshot.status === "fresh";
-  const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target, artifact);
+  const livePin = readExtensionPinnedFlags(target);
+  const requestedPin = remoteFlags?.flags ?? {};
+  const pinCurrent = !livePin.error && (livePin.overrides === null ? Object.keys(requestedPin).length === 0 : livePin.pinned !== null) && sameFeatureFlags(livePin.pinned ?? {}, requestedPin);
+  const reusable = !wantWatch && tier !== "build" && pinCurrent && await extensionRuntimeReusable(target, artifact);
   restoreRequestedPorts();
+  if (!pinCurrent && !wantWatch) {
+    const have = Object.keys(livePin.pinned ?? {});
+    const want = Object.keys(requestedPin);
+    const dropping = have.filter((key) => !want.includes(key));
+    console.error(colorHumanMessage(
+      `\u2192 extension launch \u2014 re-creating the dist snapshot to pin remote feature flags` + (want.length ? ` (${want.join(", ")})` : "") + (dropping.length ? `, dropping the previous run's ${dropping.join(", ")}` : "")
+    ));
+  }
   if (artifact.status !== "none" && !reusable && !artifactLaunchable) {
     const detail = artifact.status === "invalid" ? `identity is invalid: ${artifact.reason ?? "unknown reason"}` : "runtime is not healthy and reusable";
     return {
@@ -98,7 +111,7 @@ Next: ${block.userAction}`
     return spawnScriptStreaming(startWatchSh, watchArgs, target);
   }
   if (tier === "build") {
-    return extensionRebuild(target);
+    return extensionRebuild(target, remoteFlags);
   }
   if (reusable) {
     if (artifact.status === "valid") {
@@ -110,9 +123,16 @@ Next: ${block.userAction}`
     return extensionReattach(target, displayMode);
   }
   if (artifactLaunchable) {
+    if (remoteFlags) {
+      return {
+        status: EXIT.infra,
+        output: `REMOTE_FLAG_NOT_PINNABLE: the remote feature-flag pin '${remoteFlags.spec}' (from --remote-flag and the wallet fixture's remoteFeatureFlags) cannot be applied to a verified release artifact; the artifact's manifest is signed evidence and is never rewritten.
+Next: drop --remote-flag and remove remoteFeatureFlags from the wallet fixture to validate the artifact as shipped, or validate the variant on a source checkout launched without the artifact.`
+      };
+    }
     return extensionLaunchReleaseArtifact(target, artifact);
   }
-  return extensionLaunchDevelopment(target);
+  return extensionLaunchDevelopment(target, remoteFlags);
 }
 async function extensionRuntimeReusable(target, artifact = releaseArtifactState(target)) {
   const cdpPort = process.env.CDP_PORT;
@@ -370,11 +390,12 @@ 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) {
+async function extensionLaunchDevelopment(target, remoteFlags) {
   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 (remoteFlags) liveArgs.push("--remote-flags-json", remoteFlags.json);
   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(
@@ -425,7 +446,7 @@ function harnessWatcherMatchesProductConfig(target) {
     return false;
   }
 }
-async function extensionRebuild(target) {
+async function extensionRebuild(target, remoteFlags) {
   const runtimeDirRel = recipeRuntimeDir();
   const runtimeAbs = path.join(target, runtimeDirRel);
   const rebuildLog = path.join(runtimeAbs, "rebuild.log");
@@ -434,6 +455,7 @@ async function extensionRebuild(target) {
   fs.writeFileSync(rebuildLog, "");
   const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
   const liveArgs = ["--target", target, "--build-lavamoat"];
+  if (remoteFlags) liveArgs.push("--remote-flags-json", remoteFlags.json);
   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(`\u2192 extension quick relaunch \u2014 production-like LavaMoat build \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`));