@deeeed/metamask-harness 0.80.0 → 0.82.0

package/dist/adapters/{terminal → web-dapp}/stop.js

@@ -1,8 +1,9 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { runnerDir } from "../../paths.js";
-function stopTerminalBrowserSync(target) {
-  const args = [path.join(runnerDir, "adapters", "terminal", "stop.mjs"), "--target", path.resolve(target)];
+import { webDappAdapterId } from "../../../adapters/web-dapp/lib/policy.mjs";
+function stopWebDappBrowserSync(target) {
+  const args = [path.join(runnerDir, "adapters", "web-dapp", "stop.mjs"), "--target", path.resolve(target)];
   const cdpPort = process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
   if (cdpPort) args.push("--cdp-port", cdpPort);
   const result = spawnSync(process.execPath, args, { encoding: "utf8" });
@@ -10,10 +11,10 @@ function stopTerminalBrowserSync(target) {
   const status = result.status ?? 1;
   return {
     status,
-    summary: status === 0 ? "terminal browser and wallet host stopped" : "terminal browser stop failed",
+    summary: status === 0 ? `${webDappAdapterId()} browser and wallet host stopped` : `${webDappAdapterId()} browser stop failed`,
     output
   };
 }
 export {
-  stopTerminalBrowserSync
+  stopWebDappBrowserSync
 };

package/dist/adapters/web-dapp/surface.js

@@ -0,0 +1,149 @@
+import { shellQuote } from "@farmslot/recipe-cli/harness";
+import path from "node:path";
+import { defineAdapter } from "@farmslot/adapter-sdk";
+import fs from "node:fs";
+import { POLICY_ENV, webDappAdapterId, webDappPolicy } from "../../../adapters/web-dapp/lib/policy.mjs";
+import { WEB_DAPP_CONSOLE_FILES, webDappRuntimeFile } from "./console-capture.js";
+import { stopWebDappBrowserSync } from "./stop.js";
+import { adapterRegistry } from "../registry.js";
+import { webDappActions } from "./actions.js";
+import { webDappHarness, webDappRuntimeContext } from "./overlay.js";
+import { webDappReadiness } from "./readiness.js";
+import { webDappDiagnostics, webDappObservation } from "./run.js";
+function portFromEnv(...names) {
+  for (const name of names) {
+    const raw = process.env[name];
+    if (raw && /^\d+$/u.test(raw)) return Number(raw);
+  }
+  return void 0;
+}
+function webDappAppPort() {
+  return portFromEnv("TERMINAL_APP_PORT", "RECIPE_WATCHER_PORT", "WATCHER_PORT");
+}
+function webDappCdpPort() {
+  return portFromEnv("RECIPE_CDP_PORT", "CDP_PORT");
+}
+function webDappSignerFor(target) {
+  try {
+    const state = JSON.parse(fs.readFileSync(webDappRuntimeFile(target, "browser.json"), "utf8"));
+    if (typeof state.signer === "string") return state.signer;
+  } catch {
+  }
+  return process.env.TERMINAL_SIGNER || "extension";
+}
+function bindWebDappPolicy(adapter) {
+  if (adapter.extends === "web-dapp" && typeof adapter.policy?.module === "string") {
+    process.env[POLICY_ENV] = adapter.policy.module;
+  }
+  return adapter;
+}
+const webDappSurface = defineAdapter({
+  id: "web-dapp",
+  sdkVersion: 1,
+  headless: false,
+  resolveSlotPorts() {
+  },
+  async runtimeStatus(target) {
+    if (!process.env[POLICY_ENV]) {
+      return {
+        decision: "blocked",
+        reasonCode: "web-dapp-venue-policy",
+        reasons: ["web-dapp needs a venue policy: select an adapter that extends it"],
+        nextAction: "pass --adapter <the adapter that extends web-dapp>, e.g. --adapter terminal, with its recipe library on RECIPE_LIBRARY_PATH",
+        deps: "missing",
+        devServer: { label: "next", status: "down" }
+      };
+    }
+    const policy = webDappPolicy();
+    const { webDappReadiness: webDappReadiness2 } = await import("../../../adapters/web-dapp/lib/readiness.mjs");
+    const report = await webDappReadiness2({
+      policy,
+      target: path.resolve(target),
+      appPort: webDappAppPort(),
+      cdpPort: webDappCdpPort(),
+      signer: process.env.TERMINAL_SIGNER || "extension"
+    });
+    const blocking = report.checks.filter((check) => check.required && check.status === "fail");
+    const devServer = report.checks.find((check) => check.id === "app-dev-server");
+    return {
+      decision: blocking.length === 0 ? "ready" : "blocked",
+      reasonCode: blocking[0]?.id,
+      reasons: (blocking.length ? blocking : report.checks).map((check) => `${check.id}: ${check.detail}`),
+      nextAction: blocking.length === 0 ? void 0 : blocking[0].id === "app-dev-server" || blocking[0].id === "testnet-forced" ? "start the slot dev server with testnet forced (Farmslot preflight), then retry" : `mm-harness doctor --adapter ${policy.adapterId} --target ${shellQuote(path.resolve(target))} --json`,
+      deps: report.checks.find((check) => check.id === "dependencies")?.status === "pass" ? "current" : "missing",
+      devServer: {
+        label: "next",
+        status: devServer?.status === "pass" ? "up" : "down"
+      }
+    };
+  },
+  runwayProvision: {
+    async run(target, options) {
+      return {
+        schemaVersion: 1,
+        command: "provision",
+        adapter: webDappAdapterId(),
+        target: path.resolve(target),
+        status: "fail",
+        exitCode: 2,
+        error: {
+          code: "UNSUPPORTED_ADAPTER",
+          message: `the ${process.env[POLICY_ENV] ? webDappPolicy().checkout.name : "web dapp"} is a website; there is no simulator or build to provision.`,
+          userAction: options.rerunCommand || `mm-harness launch --adapter ${webDappAdapterId()}`
+        }
+      };
+    }
+  },
+  devServer: {
+    label: "browser",
+    describe: () => `${webDappAdapterId()} slot browser and wallet host (the Next.js dev server belongs to the slot)`,
+    stop(target) {
+      const result = stopWebDappBrowserSync(target);
+      return { kind: "stopped", status: result.status, summary: result.summary, output: result.output };
+    }
+  },
+  logSources(target) {
+    return [
+      { label: "app-console", path: webDappRuntimeFile(target, WEB_DAPP_CONSOLE_FILES.app) },
+      ...webDappSignerFor(target) === "extension" ? [{ label: "extension-console", path: webDappRuntimeFile(target, WEB_DAPP_CONSOLE_FILES.extension) }] : [],
+      { label: "wallet-requests", path: webDappRuntimeFile(target, "wallet-requests.jsonl") },
+      { label: "wallet-host", path: webDappRuntimeFile(target, "wallet-host.log") },
+      { label: "browser", path: webDappRuntimeFile(target, "browser.log") },
+      { label: "next", path: path.join(target, "temp/farmslot/next-dev.log") }
+    ];
+  },
+  // The app page's console and uncaught exceptions, as the Extension's
+  // diagnostics read the extension console: errors make a run REVIEW.
+  appLogSource(target) {
+    return { label: "app-console", path: webDappRuntimeFile(target, WEB_DAPP_CONSOLE_FILES.app) };
+  },
+  flags: { launch: ["freshProfile", "headless", "headful"] },
+  hints: {
+    // Bare web-dapp has no venue: every hint names the adapter that extends it.
+    launch: "pass --adapter <the adapter that extends web-dapp>, e.g. --adapter terminal, with its recipe library on RECIPE_LIBRARY_PATH",
+    relaunch: "pass --adapter <the adapter that extends web-dapp>, e.g. --adapter terminal, with --fresh-profile",
+    runtimeProbeRecovery: () => "pass --adapter <the adapter that extends web-dapp>, e.g. --adapter terminal, with its recipe library on RECIPE_LIBRARY_PATH"
+  },
+  launch: async (context) => (await import("./launch.js")).launchWebDapp(context),
+  actions: webDappActions,
+  harness: webDappHarness,
+  runtimeContext: webDappRuntimeContext,
+  readiness: webDappReadiness,
+  fixtures: { operations: ["init", "sync", "set"] },
+  debug: {
+    args: ({ devMenu }) => [
+      ...process.env.WATCHER_PORT ? ["--port", process.env.WATCHER_PORT] : [],
+      "--action",
+      devMenu ? "dev-menu" : "debug"
+    ]
+  },
+  diagnostics: webDappDiagnostics,
+  observation: webDappObservation
+});
+adapterRegistry.register(webDappSurface);
+export {
+  bindWebDappPolicy,
+  webDappAppPort,
+  webDappCdpPort,
+  webDappSurface
+};

package/dist/adapters.js

@@ -1,14 +1,13 @@
 import http from "node:http";
 import { createHash } from "node:crypto";
 import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
-import { runLiveAdapterScript } from "@farmslot/recipe-cli/harness";
+import { liveAdapterProcessTimeoutMs, runLiveAdapterScript, runNetworkCaptureAction } from "@farmslot/recipe-cli/harness";
 import { trustedMutationContextExtras } from "./funding-execution-context.js";
 import { LIBRARY_ACTION_NAMESPACE } from "./paths.js";
 import { liveTsxCandidates } from "./live-tsx.js";
 import { resolveWalletImportCredentials, validateWalletImportOptions } from "../library/actions/shared/wallet/import-source.mjs";
 import { isRecord, traceText } from "./action-values.js";
 import { getAdapterSurface } from "./adapters/surface.js";
-import { handleRunNetworkAction } from "./network-observation.js";
 import { handleRunPerformanceAction } from "./performance-observation.js";
 function simpleAdapter(action, executor) {
   return {
@@ -100,6 +99,12 @@ function liveRuntimeConfigured(platform, node) {
   if (!getAdapterSurface(platform).actions.liveNeedsCdpPort) return true;
   return Boolean(node.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT);
 }
+const IMMEDIATE_CLOSE_ALLOWANCE_MS = 18e4;
+function withImmediateCloseBudget(action, node) {
+  if (action !== `${LIBRARY_ACTION_NAMESPACE}.perps.place_order`) return node;
+  if (node.close_immediately !== true && node.closeImmediately !== true) return node;
+  return { ...node, live_adapter_timeout_ms: liveAdapterProcessTimeoutMs(node) + IMMEDIATE_CLOSE_ALLOWANCE_MS };
+}
 async function runLiveFirst(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
   if (node.allow_static_placeholder === true) {
     throw new Error(
@@ -111,7 +116,7 @@ async function runLiveFirst(platform, action, node, context, forceLive = false,
     platform,
     action,
     namespace: LIBRARY_ACTION_NAMESPACE,
-    node,
+    node: withImmediateCloseBudget(action, node),
     context,
     prepared: preparedLiveAdapters?.get(action),
     contextExtras: trustedMutationContextExtras(context),
@@ -131,6 +136,15 @@ function liveAdapterPathHint(platform, action) {
   }
   return `library/actions/${platform}/${action.replaceAll(".", "/")}.mjs`;
 }
+async function handleRunNetworkAction(platform, action, node, context) {
+  if (!getAdapterSurface(platform).observation?.network?.actions) return null;
+  if (action === "app.network_assert") {
+    const assertion = await import("../library/actions/shared/app/network-assert.mjs");
+    return { output: await assertion.assertNetwork({ action, node, context }) };
+  }
+  if (action !== "app.network_capture") return null;
+  return runNetworkCaptureAction(platform, node, context);
+}
 async function semanticResult(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
   const performanceAction = await handleRunPerformanceAction(
     platform,
@@ -368,7 +382,9 @@ function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiv
   return adapters;
 }
 export {
+  IMMEDIATE_CLOSE_ALLOWANCE_MS,
   createMetaMaskAdapters,
   createMetaMaskUiTransport,
-  normalizeUiWaitNode
+  normalizeUiWaitNode,
+  withImmediateCloseBudget
 };

package/dist/cli.js

@@ -1,18 +1,25 @@
 import "./host.js";
 import "./adapters/surface.js";
+import fs from "node:fs";
 import {
   detectAdapter,
+  handleActions,
+  handleCall,
   handleHarness,
   handleLast,
   handleLaunch,
   handleReload,
+  handleRun,
   handleStop,
   parseArgs,
   targetPath
 } from "@farmslot/recipe-cli/harness";
 import { stopProjectCollector } from "../library/actions/shared/analytics/collector.mjs";
+import { loadSelectedAdapter } from "./adapters/plugin-surface.js";
 import { adapterRegistry } from "./adapters/registry.js";
-import { handleActions } from "./commands/manifest.js";
+import { applyDeviceTargeting } from "./commands/device-target.js";
+import { metaMaskEngine } from "./engine.js";
+import { walletFixturePath } from "./paths.js";
 import { handleDoctor } from "./commands/doctor.js";
 import { handleProvision } from "./commands/provision.js";
 import { handleRuntimeHealth } from "./commands/runtime-health.js";
@@ -20,9 +27,7 @@ import { handleRuntimeLaunch } from "./commands/runtime-launch.js";
 import { handleRuntimeDecision } from "./commands/runtime-decision.js";
 import { handleResolveExtension } from "./commands/resolve-extension.js";
 import { handleEnsureReady } from "./commands/ensure-ready.js";
-import { handleRun } from "./commands/run.js";
 import { handleSelfTest } from "./commands/self-test.js";
-import { handleCall } from "./commands/call.js";
 import { handleCompletionCandidates, invalidateCompletionCache } from "./commands/completion-candidates.js";
 import { handleLogs } from "./commands/logs.js";
 import { handleDebug } from "./commands/debug.js";
@@ -45,15 +50,35 @@ const stopOptions = {
     return collector.stopped && collector.pid !== null ? [{ label: "analytics collector", pid: collector.pid }] : [];
   }
 };
+const targetDevice = (command, adapter, options) => applyDeviceTargeting(command, adapter, options, { gate: true, rerun: "" });
+const runOptions = {
+  engine: metaMaskEngine,
+  targetDevice,
+  plan: {
+    // The wallet fixture `fixtures set` seeds.
+    steps: (target) => [{
+      step: "fixture.file",
+      confidence: "static",
+      status: "ok",
+      detail: fs.existsSync(walletFixturePath(target)) ? `present: ${walletFixturePath(target)}` : `absent: ${walletFixturePath(target)} (fixtures set to seed)`
+    }],
+    launchDetail: "would launch/attach the app + heal transport (Metro/Chrome/CDP) before executing"
+  }
+};
+const callOptions = {
+  engine: metaMaskEngine,
+  targetDevice,
+  // A wallet action makes the most useful first example.
+  exampleAction: (names) => names.find((name) => /wallet|unlock/u.test(name))
+};
 const COMMANDS = {
-  actions: handleActions,
+  actions: (parsed) => handleActions(parsed, { catalog: metaMaskEngine }),
   doctor: handleDoctor,
   "runtime-health": handleRuntimeHealth,
   "runtime-decision": handleRuntimeDecision,
   "runtime-launch": handleRuntimeLaunch,
   "resolve-extension": handleResolveExtension,
   "ensure-ready": handleEnsureReady,
-  run: handleRun,
   "self-test": handleSelfTest
 };
 const OVERLAY_COMMANDS = ["install", "verify", "cleanup"];
@@ -111,10 +136,13 @@ async function main(argv) {
     usage();
     return command ? 0 : 2;
   }
+  const refused = await loadSelectedAdapter(command, argv.slice(1));
+  if (refused !== void 0) return refused;
   if (command === "status" || command === "health" || command === "home") {
     return handleStatus(parseArgs(argv.slice(1)));
   }
-  if (command === "call") return handleCall(argv.slice(1));
+  if (command === "run") return handleRun(argv.slice(1), runOptions);
+  if (command === "call") return handleCall(argv.slice(1), callOptions);
   if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));
   if (command === "provision") return handleProvision(parseArgs(argv.slice(1)));
   if (OVERLAY_COMMANDS.includes(command)) {

package/dist/command-contract.js

@@ -1,4 +1,5 @@
-import { closest } from "@farmslot/recipe-cli/harness";
+import { adapterChoices, closest } from "@farmslot/recipe-cli/harness";
+import { configuredLibrarySources, operatorLibraryEnv } from "./adapters/plugin-surface.js";
 const bool = () => ({ kind: "boolean" });
 const value = (choices) => ({ kind: "value", ...choices ? { choices } : {} });
 const optionalValue = (choices) => ({ kind: "optional-value", ...choices ? { choices } : {} });
@@ -8,9 +9,18 @@ const JSON = { "--json": bool() };
 const NO_OPEN = { "--no-open": bool() };
 const JSON_STREAM = { "--json-stream": bool() };
 const TARGET = { "--target": value() };
-const ADAPTER = { "--adapter": value(["mobile", "extension", "core", "terminal"]) };
+const adapterIds = (tokens) => adapterChoices(optionValues(tokens, "--library"), {
+  configured: configuredLibrarySources(),
+  env: operatorLibraryEnv()
+});
+const ADAPTER = { "--adapter": { kind: "value", choices: adapterIds } };
 const MOBILE_PLATFORM = { "--platform": value(["ios", "android"]) };
-const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value(["mobile", "extension", "core", "terminal", "ios", "android"]) };
+const ADAPTER_OR_MOBILE_PLATFORM = {
+  "--platform": {
+    kind: "value",
+    choices: (tokens) => [...adapterIds(tokens), "ios", "android"]
+  }
+};
 const DEVICE = { "--device": value() };
 const RUNTIME_PORTS = {
   "--cdp-port": value(),
@@ -152,7 +162,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
   prepare: {
     usage: "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--clear-metro] [--artifacts-dir <dir>] [--json]",
     options: options(HELP, JSON, TARGET, {
-      "--platform": value(["mobile", "extension", "core", "terminal"]),
+      "--platform": { kind: "value", choices: adapterIds },
       "--mobile-platform": value(["ios", "android"]),
       "--clear-metro": bool(),
       "--artifacts-dir": value(),
@@ -420,6 +430,16 @@ const PUBLIC_COMMAND_CONTRACTS = {
     minimumPositionals: 0
   }
 };
+function optionValues(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--") break;
+    if (arg === name && args[index + 1] !== void 0) values.push(args[index += 1]);
+    else if (arg.startsWith(`${name}=`)) values.push(arg.slice(name.length + 1));
+  }
+  return values;
+}
 function validatePublicInvocation(argv, examples = {}) {
   const token = argv[0];
   if (!token || token === "--help" || token === "-h" || token === "--version" || token === "-v") return null;
@@ -487,12 +507,13 @@ function validatePublicInvocation(argv, examples = {}) {
       return usageFailure("CLI_MISSING_OPTION_VALUE", name, `${optionName} requires a value.`, contract, examples);
     }
     if (inlineValue === void 0) index += 1;
-    if (spec.choices && !spec.choices.includes(optionValue)) {
-      const suggestion = closest(optionValue, spec.choices);
+    const choices = typeof spec.choices === "function" ? spec.choices(tokens) : spec.choices;
+    if (choices && !choices.includes(optionValue)) {
+      const suggestion = closest(optionValue, choices);
       return {
         code: "CLI_INVALID_OPTION_VALUE",
         command: name,
-        message: `${optionName} must be ${formatChoiceList(spec.choices)}; received '${optionValue}'.`,
+        message: `${optionName} must be ${formatChoiceList(choices)}; received '${optionValue}'.`,
         userAction: actionFor(optionValue, suggestion, exampleFor(name, examples))
       };
     }
@@ -701,6 +722,7 @@ function exampleFor(command, examples) {
 }
 export {
   PUBLIC_COMMAND_CONTRACTS,
+  optionValues,
   publicCommandNames,
   publicCommandTokens,
   validatePublicInvocation

package/dist/commands/check.js

@@ -3,11 +3,12 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import "../adapters/surface.js";
-const USAGE = "mm-harness check diff [--fix] [--target <repo>] [--adapter mobile|extension|core] [--base <ref>] [--profile fast|full] [--artifacts-dir <dir>] [--json]";
+const USAGE = "mm-harness check diff [--fix] [--target <repo>] [--adapter <adapter>] [--base <ref>] [--profile fast|full] [--artifacts-dir <dir>] [--json]";
 const JS_TS_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$/u;
 const FORMAT_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$|\.json$|\.md$|\.css$|\.scss$|\.ya?ml$/u;
 const TEST_FILE_RE = /(?:^|[./_-])(?:test|spec)\.(?:c|m)?jsx?$|(?:^|[./_-])(?:test|spec)\.tsx?$/u;
 const ESLINT_SUPPRESSION_RE = /^\s*eslint-disable(?:-line|-next-line)?\b/u;
+const EXTENSION_LOCALE_RE = /^app\/_locales\//u;
 async function handleCheck(argv) {
   const { positional, options } = parseArgs(argv);
   const action = positional[0];
@@ -20,7 +21,7 @@ async function handleCheck(argv) {
   const target = path.resolve(optionString(options, "target") ?? process.cwd());
   const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
   const detected = explicitAdapter ?? detectAdapter(target);
-  if (detected && !["mobile", "extension", "core", "terminal"].includes(detected)) {
+  if (detected === "ios" || detected === "android") {
     return usageOut(json, "check", `unsupported adapter '${detected}'`, USAGE);
   }
   const adapter = detected;
@@ -52,10 +53,12 @@ async function handleCheck(argv) {
   const mergeBase = resolveMergeBase(target, baseRef);
   const changedFiles = listChangedFiles(target, mergeBase, artifactsDir);
   const existingChangedFiles = changedFiles.filter((file) => fs.existsSync(path.join(target, file)));
+  const untracked = untrackedFiles(target);
   const suppressionCheck = checkNewEslintSuppressions({
     target,
     artifactsDir,
     mergeBase,
+    untracked,
     files: existingChangedFiles.filter((file) => JS_TS_EXT_RE.test(file))
   });
   const policyFailed = suppressionCheck.status === "fail";
@@ -97,6 +100,9 @@ async function handleCheck(argv) {
         files: existingChangedFiles.filter((file) => TEST_FILE_RE.test(file))
       })
     );
+    if (adapter === "extension") {
+      checks.push(...runExtensionDiffChecks({ target, artifactsDir, packageJson, files: changedFiles }));
+    }
     if (profile === "full") {
       checks.push(runTypecheck({ target, artifactsDir, packageJson }));
     } else {
@@ -187,10 +193,10 @@ function listChangedFiles(target, mergeBase, artifactsDir) {
     }
   };
   if (mergeBase) {
-    addLines(runCommand("git", ["diff", "--name-only", "--diff-filter=ACMR", `${mergeBase}...HEAD`], target).stdout);
+    addLines(runCommand("git", ["diff", "--name-only", "--no-renames", "--diff-filter=ACMRD", `${mergeBase}...HEAD`], target).stdout);
   }
-  addLines(runCommand("git", ["diff", "--name-only", "--diff-filter=ACMR", "HEAD"], target).stdout);
-  addLines(runCommand("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR"], target).stdout);
+  addLines(runCommand("git", ["diff", "--name-only", "--no-renames", "--diff-filter=ACMRD", "HEAD"], target).stdout);
+  addLines(runCommand("git", ["diff", "--cached", "--name-only", "--no-renames", "--diff-filter=ACMRD"], target).stdout);
   addLines(runCommand("git", ["ls-files", "--others", "--exclude-standard"], target).stdout);
   return [...files].filter((file) => !isUnderArtifactsDir(target, artifactsDir, file)).sort();
 }
@@ -209,9 +215,7 @@ function checkNewEslintSuppressions(input) {
   if (input.files.length === 0) {
     return { id, label, status: "skip", reason: "no changed JS/TS files" };
   }
-  const untracked = new Set(
-    runCommand("git", ["ls-files", "--others", "--exclude-standard"], input.target).stdout.split("\n").map((file) => normalizeRelativePath(file.trim())).filter(Boolean)
-  );
+  const { untracked } = input;
   const findings = [];
   const trackedFiles = input.files.filter((file) => !untracked.has(normalizeRelativePath(file)));
   if (trackedFiles.length > 0) {
@@ -240,6 +244,26 @@ function checkNewEslintSuppressions(input) {
     reason: `${findings.length} newly added eslint-disable directive(s)`
   } : { id, label, status: "pass", logPath };
 }
+function untrackedFiles(target) {
+  return new Set(
+    runCommand("git", ["ls-files", "--others", "--exclude-standard"], target).stdout.split("\n").map((file) => normalizeRelativePath(file.trim())).filter(Boolean)
+  );
+}
+function runExtensionDiffChecks(input) {
+  const scripts = input.packageJson?.scripts && typeof input.packageJson.scripts === "object" ? input.packageJson.scripts : {};
+  const results = [];
+  if (typeof scripts["verify-locales"] === "string") {
+    results.push(
+      input.files.some((file) => EXTENSION_LOCALE_RE.test(normalizeRelativePath(file))) ? runCheckCommand("verify-locales", "Locale strings", input.target, input.artifactsDir, "yarn", ["verify-locales", "--quiet"]) : { id: "verify-locales", label: "Locale strings", status: "skip", reason: "no app/_locales changes" }
+    );
+  }
+  if (typeof scripts["circular-deps:check"] === "string") {
+    results.push(
+      input.files.some((file) => JS_TS_EXT_RE.test(file)) ? runCheckCommand("circular-deps", "Circular dependencies", input.target, input.artifactsDir, "yarn", ["circular-deps:check"]) : { id: "circular-deps", label: "Circular dependencies", status: "skip", reason: "no JS/TS changes" }
+    );
+  }
+  return results;
+}
 function findAddedSuppressions(diff) {
   const findings = [];
   let file = "";

package/dist/commands/completion-candidates.js

@@ -1,4 +1,4 @@
-import { EXIT, parseArgs, optionFlag, optionString, optionStrings, resolveAdapter, targetPath } from "@farmslot/recipe-cli/harness";
+import { EXIT, listRunnableRecipes, parseArgs, optionFlag, optionString, optionStrings, resolveAdapter, resolveLibrarySources, targetPath } from "@farmslot/recipe-cli/harness";
 import { resolveActionManifest } from "../manifest.js";
 import {
   invalidateCompletionCache,
@@ -6,7 +6,7 @@ import {
   writeCompletionCandidates
 } from "../completions-cache.js";
 import { importRecipeProtocol } from "../paths.js";
-import { listRunnableRecipes, resolveMetaMaskLibrarySources } from "./run-engine.js";
+import { metaMaskEngine } from "../engine.js";
 async function handleCompletionCandidates(argv) {
   const kind = argv[0];
   const { options } = parseArgs(argv.slice(1));
@@ -20,7 +20,7 @@ async function handleCompletionCandidates(argv) {
   let candidates;
   if (kind === "actions") {
     adapter = resolveAdapter(options).adapter;
-    const sources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+    const sources = await resolveLibrarySources(metaMaskEngine, optionStrings(options, "library"));
     const { manifest } = await resolveActionManifest(adapter, optionString(options, "actionManifest"), sources);
     const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
     candidates = getRecipeActionManifestActionNames(manifest);
@@ -30,8 +30,8 @@ async function handleCompletionCandidates(argv) {
     const cacheKey = `recipes:${adapter}`;
     candidates = readFreshCandidates(target, cacheKey);
     if (!candidates) {
-      const sources = await resolveMetaMaskLibrarySources(optionStrings(options, "library")).catch(() => void 0);
-      candidates = sources ? (await listRunnableRecipes(adapter, sources)).map((recipe) => recipe.name) : [];
+      const sources = await resolveLibrarySources(metaMaskEngine, optionStrings(options, "library")).catch(() => void 0);
+      candidates = sources ? (await listRunnableRecipes(metaMaskEngine, adapter, sources)).map((recipe) => recipe.name) : [];
       writeCompletionCandidates(target, cacheKey, candidates);
     }
   }

package/dist/commands/doctor.js

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { featureFlagReport } from "../feature-flags.js";
-import { color, acquireCheckoutLock, detectAdapter, resolveRuntimeContextPath, ensureOverlay, newHealState, recipeRunning, adapterDetectNext, checkoutBusyOut, EXIT, usageOut, actionManifestPathOption, applyRuntimeDirOption, optionFlag, optionString, shellQuote, targetPath } from "@farmslot/recipe-cli/harness";
+import { adapterPluginChecks, color, acquireCheckoutLock, detectAdapter, resolveRuntimeContextPath, ensureOverlay, newHealState, recipeRunning, adapterDetectNext, checkoutBusyOut, EXIT, usageOut, actionManifestPathOption, applyRuntimeDirOption, optionFlag, optionString, shellQuote, targetPath } from "@farmslot/recipe-cli/harness";
 import { collectCheckoutView, renderCheckoutView } from "../checkout-view.js";
 import { createDoctorReport, fixtureSummary, requiredDoctorCheckSummary } from "../doctor.js";
 import { assertAdapter, runnerDir } from "../paths.js";
@@ -158,7 +158,10 @@ async function handleDoctor({ options }) {
   const checks = [
     ...result.checks,
     runtimeCheck,
-    ...await readiness.liveChecks?.(target) ?? []
+    ...await readiness.liveChecks?.(target) ?? [],
+    ...await platformDoctorChecks(adapter, target),
+    // Which library plugin code this process loaded: library, module and digest.
+    ...adapterPluginChecks()
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   const doctorResult = {
@@ -244,6 +247,20 @@ async function handleDoctor({ options }) {
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
+async function platformDoctorChecks(adapter, target) {
+  try {
+    return await getAdapterSurface(adapter).doctor?.(target) ?? [];
+  } catch (error) {
+    return [{
+      id: `adapter-plugin:${adapter}:doctor`,
+      status: "fail",
+      required: true,
+      message: `${adapter}'s doctor checks failed to run.`,
+      detail: error instanceof Error ? error.message : String(error),
+      userAction: `fix the doctor() of the ${adapter} adapter, then rerun mm-harness doctor --adapter ${adapter}`
+    }];
+  }
+}
 function doctorRuntimeCheck(runtime, error, expectLive) {
   if (error) {
     return {

package/dist/commands/farmslot-ready.js

@@ -11,6 +11,7 @@ function farmslotReadyIndicator(adapter, devices) {
       return "OK";
     case "core":
       return "ready";
+    case "web-dapp":
     case "terminal":
       return "OK";
     case "mobile": {

package/dist/commands/help.js

@@ -5,7 +5,7 @@ import { handleHelpReview } from "./review.js";
 import "../adapters/surface.js";
 const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core|terminal>";
 function validHelpLine(value) {
-  return typeof value === "string" || Boolean(value && typeof value.text === "string" && Array.isArray(value.adapters) && value.adapters.length > 0 && value.adapters.every((adapter) => ["mobile", "extension", "core", "terminal"].includes(adapter)));
+  return typeof value === "string" || Boolean(value && typeof value.text === "string" && Array.isArray(value.adapters) && value.adapters.length > 0 && value.adapters.every((adapter) => ["mobile", "extension", "core", "web-dapp"].includes(adapter)));
 }
 function scopedSections(topic, adapter) {
   const select = (lines) => lines.flatMap((line) => typeof line === "string" ? [line] : line.adapters.includes(adapter) ? [line.text] : []);

package/dist/commands/launch/device.js

@@ -9,15 +9,15 @@ import {
   parseRemoteFlagSpec,
   remoteFlagRequestFor
 } from "../../feature-flags.js";
-import { terminalOnlyLaunchFlags } from "../../adapters/terminal/launch.js";
+import { webDappOnlyLaunchFlags } from "../../adapters/web-dapp/launch.js";
 import { shellQuote } from "./quote.js";
 async function runDeviceLaunch(context, profile) {
   const { adapter, options, target, heal, jsonOutput, machine, stream, usage } = context;
-  const terminalOnly = terminalOnlyLaunchFlags(options);
-  if (terminalOnly.length > 0) {
+  const webDappOnly = webDappOnlyLaunchFlags(options);
+  if (webDappOnly.length > 0) {
     return usage(
-      `${terminalOnly.join(", ")} apply only to --adapter terminal; ${adapter} does not read them.`,
-      "drop the terminal flags, or pass --adapter terminal"
+      `${webDappOnly.join(", ")} apply only to adapters that extend web-dapp (e.g. --adapter terminal); ${adapter} does not read them.`,
+      "drop those flags, or pass --adapter terminal"
     );
   }
   const wantBuild = flag(options, "build");

package/dist/commands/self-test.js

@@ -1,10 +1,10 @@
-import { optionFlag, optionString, requiredOption } from "@farmslot/recipe-cli/harness";
+import { activateRecipeRuntimeEnvironment, optionFlag, optionString, requiredOption, runRecipe } from "@farmslot/recipe-cli/harness";
 import { mkdtemp } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { recipePath, runnerDir } from "../paths.js";
-import { runRecipe } from "./run-engine.js";
+import { metaMaskEngine } from "../engine.js";
 async function handleSelfTest({ options }) {
   const result = await runSelfTest(options);
   if (optionFlag(options, "json")) console.log(JSON.stringify(result, null, 2));
@@ -23,9 +23,14 @@ async function runSelfTest(options) {
       const manifestValidation = await validateManifest(manifest);
       const smokeRecipe = recipePath(`${adapter}/runner/smoke.recipe.json`);
       const artifactsDir = path.join(root, adapter);
-      const result = await runRecipe(adapter, smokeRecipe, artifactsDir, runnerDir, void 0, {
-        platform: { skipExtensionRuntimePrepare: true }
-      });
+      const runtimeOptions = { platform: { skipExtensionRuntimePrepare: true } };
+      const restoreRuntimeEnvironment = activateRecipeRuntimeEnvironment(adapter, runnerDir, runtimeOptions);
+      let result;
+      try {
+        result = await runRecipe(metaMaskEngine, adapter, smokeRecipe, artifactsDir, runnerDir, void 0, runtimeOptions);
+      } finally {
+        restoreRuntimeEnvironment();
+      }
       runs.push({ adapter, manifestValidation: manifestValidation.summary, artifactsDir, result });
     }
   } finally {