@deeeed/metamask-harness 0.3.9 → 0.5.0

package/dist/heal-bounds.js

@@ -0,0 +1,120 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { handleHarness } from "./harness.js";
+import { recipeHarnessPath, recipeRuntimePath } from "./paths.js";
+import { EXIT } from "./commands/shared.js";
+function newHealState() {
+  return { recovered: [], mutations: [], attemptedRecoveries: [] };
+}
+function parseHeal(options, fallback) {
+  const value = options.heal;
+  if (value === void 0) return fallback;
+  if (value === "off" || value === "infra-only" || value === "auto") return value;
+  return { error: `--heal must be off, infra-only, or auto (got "${String(value)}").` };
+}
+function overlayDir(target, adapter) {
+  return recipeHarnessPath(target, adapter);
+}
+function overlayPresent(target, adapter) {
+  try {
+    return fs.statSync(overlayDir(target, adapter)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function overlayDelegateValid(target, adapter) {
+  if (adapter === "core") return true;
+  const pointer = path.join(recipeHarnessPath(target, adapter), "runner", ".runner-source");
+  if (!fs.existsSync(pointer)) return true;
+  const runnerPath = fs.readFileSync(pointer, "utf8").trim();
+  if (!Boolean(runnerPath) || !fs.existsSync(runnerPath)) return false;
+  return fs.existsSync(path.join(runnerPath, "bin", "mm-harness"));
+}
+async function ensureOverlay(adapter, target, heal, state, json) {
+  if (adapter === "core") return { ok: true };
+  if (overlayPresent(target, adapter) && overlayDelegateValid(target, adapter)) return { ok: true };
+  if (heal === "off") return { ok: true };
+  const installBin = process.env.MM_HARNESS_INSTALL_BIN;
+  let code;
+  if (installBin) {
+    const result = spawnSync(installBin, ["install", "--platform", adapter, "--target", target], {
+      cwd: target,
+      stdio: ["ignore", 2, "inherit"],
+      env: process.env
+    });
+    code = result.status ?? 1;
+  } else {
+    code = await handleHarness(["install", "--platform", adapter, "--target", target, ...json ? ["--json"] : []]);
+  }
+  if (code !== 0 || !overlayPresent(target, adapter)) {
+    return { ok: false, error: `runtime overlay install failed (exit ${code})` };
+  }
+  const dir = overlayDir(target, adapter);
+  state.mutations.push({ type: "file", action: "created", path: dir });
+  if (!json) process.stderr.write(`installed mm-harness overlay \u2192 ${dir}
+`);
+  return { ok: true };
+}
+function classifyFailure(output) {
+  if (/wallet|fixture|keyring|not seeded|\bsrp\b|password|onboard/iu.test(output)) return "wallet";
+  if (/metro|cdp|chrome|bundle|packager|port\b|econnrefused|not reachable|watcher|dev client|websocket/iu.test(output)) {
+    return "infra";
+  }
+  return "app";
+}
+function recipeRunning(target) {
+  if (process.env.MM_HARNESS_RECIPE_RUNNING === "1") return true;
+  return fs.existsSync(recipeRuntimePath(target, "recipe.lock"));
+}
+const RECOVERY_CODE = {
+  mobile: "metro.restarted",
+  extension: "chrome.reopened"
+};
+function checkHealBounds(target, output, state) {
+  const originalError = output.trim() || void 0;
+  if (recipeRunning(target)) {
+    return {
+      code: "RECIPE_RUNNING",
+      exitCode: EXIT.bounded,
+      message: "a recipe is currently running \u2014 refusing recovery to avoid corrupting mid-run state.",
+      originalError
+    };
+  }
+  const failureClass = classifyFailure(output);
+  if (failureClass === "wallet") {
+    return {
+      code: "WALLET_STATE_REQUIRED",
+      exitCode: EXIT.bounded,
+      message: "recovery would require a seeded wallet \u2014 healing never touches fixtures.",
+      userAction: "run mm-harness fixtures set",
+      originalError
+    };
+  }
+  if (failureClass === "app") {
+    return {
+      code: "APP_LOGIC_FAILURE",
+      exitCode: EXIT.runtime,
+      message: "failure looks like app-logic \u2014 healing cannot help; surface verbatim.",
+      originalError
+    };
+  }
+  if (state.attemptedRecoveries.length > 0) {
+    return {
+      code: "SAME_RECOVERY_TWICE",
+      exitCode: EXIT.bounded,
+      message: "same recovery already failed once this invocation \u2014 refusing to loop.",
+      originalError
+    };
+  }
+  return null;
+}
+export {
+  RECOVERY_CODE,
+  checkHealBounds,
+  classifyFailure,
+  ensureOverlay,
+  newHealState,
+  parseHeal,
+  recipeRunning
+};

package/dist/index.js

@@ -0,0 +1,25 @@
+import { createDoctorReport } from "./doctor.js";
+import { loadActionManifest, validateManifest } from "./manifest.js";
+import { createMetaMaskExtensionRunner, createMetaMaskMobileRunner, createMetaMaskRunner } from "./runner.js";
+import {
+  extensionIdPath,
+  importRecipeHarnessRuntimeBrowserExtension,
+  importRecipeHarnessRuntimeCdp,
+  recipeHarnessPath,
+  walletFixturePath
+} from "./paths.js";
+import { captureActiveRecipeRecordingSnapshot } from "./run-recording.js";
+export {
+  captureActiveRecipeRecordingSnapshot,
+  createDoctorReport,
+  createMetaMaskExtensionRunner,
+  createMetaMaskMobileRunner,
+  createMetaMaskRunner,
+  extensionIdPath,
+  importRecipeHarnessRuntimeBrowserExtension,
+  importRecipeHarnessRuntimeCdp,
+  loadActionManifest,
+  recipeHarnessPath,
+  validateManifest,
+  walletFixturePath
+};

package/dist/leaf-invoke.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import path from "node:path";
+function resolveLeafInvoke(command, args) {
+  if (command.endsWith(".sh")) return { bin: "bash", args: [command, ...args] };
+  return { bin: command, args };
+}
+function missingShellLeafMessage(leafPath) {
+  const leaf = path.basename(leafPath);
+  return `leaf could not start: ${leaf} (ENOENT)
+  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the shell leaf is missing or not executable`;
+}
+function shellLeafMissing(leafPath) {
+  return leafPath.endsWith(".sh") && !fs.existsSync(leafPath);
+}
+export {
+  missingShellLeafMessage,
+  resolveLeafInvoke,
+  shellLeafMissing
+};

package/dist/live-adapter-contract.js

@@ -0,0 +1,240 @@
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { resolveRequiredLocalProtocolRoot, runnerDir } from "./paths.js";
+function actionFileStem(action) {
+  return String(action).replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function actionParts(action) {
+  const parts = String(action).split(".").filter(Boolean);
+  if (parts.length >= 3 && parts[0] === "metamask") {
+    return { family: parts[1], localName: parts.slice(2).join(".") };
+  }
+  if (parts.length >= 2) {
+    return { family: parts[0], localName: parts.slice(1).join(".") };
+  }
+  return { family: "actions", localName: String(action) };
+}
+function candidateStems(action) {
+  const stem = actionFileStem(action);
+  const { localName } = actionParts(action);
+  const localStem = actionFileStem(localName);
+  const stems = [stem];
+  if (localStem && localStem !== stem) stems.push(localStem);
+  return stems;
+}
+function candidateFamilies(action) {
+  const { family } = actionParts(action);
+  const families = [family];
+  return [...new Set(families)];
+}
+function candidatePaths(platform, action) {
+  const stems = candidateStems(action);
+  const families = candidateFamilies(action);
+  const roots = [
+    process.env.METAMASK_RECIPE_LIVE_ADAPTER_DIR,
+    path.join(runnerDir, "library/actions")
+  ].filter(Boolean);
+  const files = [];
+  for (const root of roots) {
+    for (const family of families) {
+      for (const candidateStem of stems) {
+        pushCandidateFiles(files, root, platform, family, candidateStem);
+      }
+      pushDomainDispatcherFiles(files, root, platform, family);
+    }
+    for (const candidateStem of stems) {
+      pushFlatCandidateFiles(files, root, platform, candidateStem);
+    }
+  }
+  return files;
+}
+function pushCandidateFiles(files, root, platform, family, stem) {
+  for (const extension of ["mjs", "js", "sh"]) {
+    files.push(path.join(root, platform, family, `${stem}.${extension}`));
+    files.push(path.join(root, "shared", family, `${stem}.${extension}`));
+  }
+}
+function pushDomainDispatcherFiles(files, root, platform, family) {
+  for (const extension of ["mjs", "js", "sh"]) {
+    files.push(path.join(root, platform, family, `${family}.${extension}`));
+    files.push(path.join(root, "shared", family, `${family}.${extension}`));
+  }
+}
+function pushFlatCandidateFiles(files, root, platform, stem) {
+  for (const extension of ["mjs", "js", "sh"]) {
+    files.push(path.join(root, platform, `${stem}.${extension}`));
+    files.push(path.join(root, "shared", `${stem}.${extension}`));
+  }
+}
+async function firstExecutablePath(paths) {
+  for (const file of paths) {
+    try {
+      await access(file);
+      return file;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return null;
+}
+function runProcess(command, args, options) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const timeout = options.timeoutMs ? setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (!child.killed) child.kill("SIGKILL");
+      }, 1e3);
+      resolve({ exitCode: null, stdout, stderr, timedOut: true });
+    }, options.timeoutMs) : void 0;
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      reject(error);
+    });
+    child.on("close", (exitCode) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve({ exitCode, stdout, stderr, timedOut: false });
+    });
+  });
+}
+function commandFor(file) {
+  if (file.endsWith(".sh")) return { command: "bash", args: [file] };
+  if (file.endsWith(".mjs") || file.endsWith(".js")) {
+    if (!importsSourceTypescript(file)) return { command: process.execPath, args: [file] };
+  }
+  const localTsx = path.join(runnerDir, "node_modules/.bin/tsx");
+  const tsxBin = process.env.TSX_BIN || (existsSync(localTsx) ? localTsx : path.join(
+    resolveRequiredLocalProtocolRoot("TypeScript live adapter execution"),
+    "node_modules/.bin/tsx"
+  ));
+  return { command: tsxBin, args: [file] };
+}
+function importsSourceTypescript(file) {
+  return importsSourceTypescriptFrom(file, /* @__PURE__ */ new Set());
+}
+function importsSourceTypescriptFrom(file, visited) {
+  const absolute = path.resolve(file);
+  if (visited.has(absolute)) return false;
+  visited.add(absolute);
+  const source = readFileSync(file, "utf8");
+  const importPattern = /(?:from\s+|import\(\s*)['"]([^'"]+)['"]/gu;
+  for (const match of source.matchAll(importPattern)) {
+    const specifier = match[1] ?? "";
+    if (specifier.endsWith(".ts")) return true;
+    if (!specifier.startsWith(".")) continue;
+    if (!specifier.endsWith(".mjs") && !specifier.endsWith(".js")) continue;
+    if (importsSourceTypescriptFrom(path.resolve(path.dirname(absolute), specifier), visited)) {
+      return true;
+    }
+  }
+  return false;
+}
+async function resolveLiveAdapter(platform, action) {
+  return firstExecutablePath(candidatePaths(platform, action));
+}
+const CORE_WORKSPACE_PACKAGES = [
+  "@metamask/base-controller",
+  "@metamask/messenger",
+  "@metamask/controller-utils",
+  "@metamask/keyring-controller"
+];
+async function platformAdapterEnv(platform, projectRoot, tempDir) {
+  if (platform !== "core") return {};
+  const paths = {};
+  for (const pkg of CORE_WORKSPACE_PACKAGES) {
+    const packageDir = path.join(projectRoot, "packages", pkg.replace("@metamask/", ""));
+    const distEntry = path.join(packageDir, "dist/index.cjs");
+    if (existsSync(distEntry)) continue;
+    const srcDir = path.join(packageDir, "src");
+    if (!existsSync(path.join(srcDir, "index.ts"))) continue;
+    paths[pkg] = [path.join(srcDir, "index.ts")];
+    paths[`${pkg}/*`] = [path.join(srcDir, "*")];
+  }
+  if (Object.keys(paths).length === 0) return {};
+  const tsconfigPath = path.join(tempDir, "core-adapter.tsconfig.json");
+  await writeFile(
+    tsconfigPath,
+    `${JSON.stringify({ compilerOptions: { baseUrl: projectRoot, paths } }, null, 2)}
+`
+  );
+  return { TSX_TSCONFIG_PATH: tsconfigPath };
+}
+async function runLiveAdapterScript({ platform, action, node, context }) {
+  const script = await resolveLiveAdapter(platform, action);
+  if (!script) return null;
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "mm-harness-live-adapter-"));
+  const inputPath = path.join(tempDir, "input.json");
+  const outputPath = path.join(tempDir, "output.json");
+  const input = {
+    schemaVersion: 1,
+    platform,
+    action,
+    node,
+    context: {
+      nodeId: context.nodeId,
+      projectRoot: context.projectRoot,
+      artifactsDir: context.artifactsDir
+    },
+    outputPath
+  };
+  await writeFile(inputPath, `${JSON.stringify(input, null, 2)}
+`);
+  const command = commandFor(script);
+  const platformEnv = await platformAdapterEnv(platform, context.projectRoot, tempDir);
+  const result = await runProcess(command.command, [...command.args, inputPath], {
+    cwd: context.projectRoot,
+    env: {
+      ...process.env,
+      ...context.env,
+      ...platformEnv,
+      METAMASK_RECIPE_ADAPTER_INPUT: inputPath,
+      METAMASK_RECIPE_ADAPTER_OUTPUT: outputPath
+    },
+    timeoutMs: Number(node.live_adapter_timeout_ms ?? node.timeout_ms ?? 6e4)
+  });
+  try {
+    if (result.timedOut) {
+      throw new Error(`Live adapter ${script} timed out after ${Number(node.live_adapter_timeout_ms ?? node.timeout_ms ?? 6e4)}ms.`);
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(`Live adapter ${script} exited ${result.exitCode}: ${result.stderr || result.stdout}`);
+    }
+    let parsed = null;
+    try {
+      parsed = JSON.parse(await readFile(outputPath, "utf8"));
+    } catch (_error) {
+      const stdout = result.stdout.trim();
+      if (!stdout) throw new Error(`Live adapter ${script} did not write JSON output.`);
+      parsed = JSON.parse(stdout);
+    }
+    return { script, result: parsed };
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+export {
+  resolveLiveAdapter,
+  runLiveAdapterScript
+};

package/dist/manifest.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { manifestPath, readJson, importRecipeProtocol } from "./paths.js";
+function loadMetaMaskMobileActionManifest() {
+  return asActionManifest(readJson(manifestPath("mobile")));
+}
+function loadMetaMaskExtensionActionManifest() {
+  return asActionManifest(readJson(manifestPath("extension")));
+}
+function loadMetaMaskCoreActionManifest() {
+  return asActionManifest(readJson(manifestPath("core")));
+}
+function loadActionManifest(adapter, overridePath) {
+  if (overridePath) return asActionManifest(readJson(path.resolve(overridePath)));
+  if (adapter === "mobile") return loadMetaMaskMobileActionManifest();
+  if (adapter === "core") return loadMetaMaskCoreActionManifest();
+  return loadMetaMaskExtensionActionManifest();
+}
+async function validateManifest(manifest) {
+  const { validateRecipeActionManifestDocument } = await importRecipeProtocol();
+  const result = validateRecipeActionManifestDocument(manifest);
+  if (result.status === "invalid") {
+    throw new Error(
+      `Manifest invalid: ${result.findings.map((finding) => `${finding.code} ${finding.path}`).join(", ")}`
+    );
+  }
+  return result;
+}
+function asActionManifest(value) {
+  return value;
+}
+export {
+  loadActionManifest,
+  loadMetaMaskCoreActionManifest,
+  loadMetaMaskExtensionActionManifest,
+  loadMetaMaskMobileActionManifest,
+  validateManifest
+};