@deeeed/metamask-harness 0.6.2 → 0.7.0

package/dist/commands/launch/extension.js

@@ -1,17 +1,88 @@
+import { execFileSync } from "node:child_process";
+import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
+import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
+import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { spawnScriptStreaming } from "../shared.js";
+function extensionDepsBlock(target) {
+  if (!fs.existsSync(path.join(target, "package.json"))) return null;
+  const deps = depsCheck(target);
+  const userAction = "yarn install --immutable   # then re-run: mm-harness launch";
+  if (deps.status === "missing") {
+    return { message: "extension dependencies are not installed (no yarn install-state markers).", userAction };
+  }
+  if (deps.status === "stale") {
+    return {
+      message: "extension dependencies are stale (package.json/yarn.lock changed since the last install) \u2014 webpack would crash mid-build.",
+      userAction
+    };
+  }
+  return null;
+}
 async function launchExtension(target, tier, wantWatch) {
-  if (!wantWatch && tier === "quick") {
+  if (wantWatch) {
+    const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
+    const watchArgs = ["--target", target];
+    if (process.env.WATCHER_PORT) watchArgs.push("--watcher-port", process.env.WATCHER_PORT);
+    console.error(`\u2192 extension watch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`);
+    return spawnScriptStreaming(startWatchSh, watchArgs, target);
+  }
+  if (tier === "build") {
     return extensionRebuild(target);
   }
-  const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
-  const watchArgs = ["--target", target];
-  if (process.env.WATCHER_PORT) watchArgs.push("--watcher-port", process.env.WATCHER_PORT);
-  console.error(`\u2192 extension ${wantWatch ? "watch" : "build"} \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`);
-  return spawnScriptStreaming(startWatchSh, watchArgs, target);
+  if (await extensionRuntimeReusable(target)) {
+    return extensionReattach(target);
+  }
+  return extensionRebuild(target);
+}
+async function extensionRuntimeReusable(target) {
+  const watcherPort = process.env.WATCHER_PORT;
+  const cdpPort = process.env.CDP_PORT;
+  if (!watcherPort || !cdpPort) return false;
+  if (!portHasListener(watcherPort)) return false;
+  if (!await cdpVersionReachable(cdpPort)) return false;
+  if (isExtensionDistStale(target)) return false;
+  return true;
+}
+function portHasListener(port) {
+  try {
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.split(/\s+/u).some((value) => /^\d+$/u.test(value));
+  } catch {
+    return false;
+  }
+}
+function cdpVersionReachable(port) {
+  return new Promise((resolve) => {
+    const request = http.get(
+      { host: "127.0.0.1", port: Number(port), path: "/json/version", timeout: 2e3 },
+      (response) => {
+        response.resume();
+        const code = response.statusCode ?? 0;
+        resolve(code >= 200 && code < 300);
+      }
+    );
+    request.on("timeout", () => {
+      request.destroy();
+      resolve(false);
+    });
+    request.on("error", () => resolve(false));
+  });
+}
+async function extensionReattach(target) {
+  const reattachScript = recipeHarnessPath(target, "extension", "scripts", "reattach.sh");
+  const reattachArgs = ["--target", target];
+  if (process.env.CDP_PORT) reattachArgs.push("--cdp-port", process.env.CDP_PORT);
+  if (process.env.WATCHER_PORT) reattachArgs.push("--watcher-port", process.env.WATCHER_PORT);
+  if (process.env.EXTENSION_START_URL) reattachArgs.push("--start-url", process.env.EXTENSION_START_URL);
+  console.error(`\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 extensionRebuild(target) {
   const runtimeDirRel = recipeRuntimeDir();
@@ -35,6 +106,9 @@ async function extensionRebuild(target) {
   return result;
 }
 export {
+  extensionDepsBlock,
+  extensionReattach,
   extensionRebuild,
+  extensionRuntimeReusable,
   launchExtension
 };

package/dist/commands/launch/index.js

@@ -23,7 +23,7 @@ import {
   newHealState,
   parseHeal
 } from "../../heal-bounds.js";
-import { launchExtension } from "./extension.js";
+import { extensionDepsBlock, extensionRuntimeReusable, launchExtension } from "./extension.js";
 import { launchMobile } from "./mobile.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
@@ -111,6 +111,15 @@ async function handleLaunch(argv) {
     if (json) liveArgs.push("--json");
     return handleHarness(liveArgs);
   }
+  if (adapter === "extension") {
+    const willBuild = wantWatch || tier === "build" || !await extensionRuntimeReusable(target);
+    if (willBuild) {
+      const depsBlock = extensionDepsBlock(target);
+      if (depsBlock) {
+        return usageOut(json, "launch", depsBlock.message, depsBlock.userAction);
+      }
+    }
+  }
   let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
   if (attempt.status === 0) {
     return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);

package/dist/commands/list-executables.js

@@ -0,0 +1,48 @@
+import { loadActionManifest } from "../manifest.js";
+import { importRecipeHarness, importRecipeProtocol } from "../paths.js";
+import { EXIT } from "./shared.js";
+import { optionFlag, optionString, resolveAdapter } from "./parse-args.js";
+import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+const finalSegment = (name) => name.split(".").pop() ?? name;
+async function listFlowIds() {
+  try {
+    const sources = await resolveMetaMaskLibrarySources(void 0);
+    if (!sources || sources.length === 0) return [];
+    const harness = await importRecipeHarness();
+    const resolution = await harness.loadRecipeLibraries(sources);
+    return [...resolution.flows.keys()].sort();
+  } catch {
+    return [];
+  }
+}
+async function handleListExecutables(command, options) {
+  const json = optionFlag(options, "json");
+  const { adapter } = resolveAdapter(options);
+  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+  const names = getRecipeActionManifestActionNames(manifest).slice().sort();
+  const shortCounts = /* @__PURE__ */ new Map();
+  for (const name of names) shortCounts.set(finalSegment(name), (shortCounts.get(finalSegment(name)) ?? 0) + 1);
+  const actions = names.map((name) => {
+    const short = finalSegment(name);
+    return { name, short: shortCounts.get(short) === 1 ? short : null };
+  });
+  const flows = await listFlowIds();
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, actions, flows }, null, 2));
+    return EXIT.ok;
+  }
+  console.log(`invocable for ${adapter}:`);
+  console.log(`  actions (mm-harness call <name> \u2014 short or full):`);
+  for (const entry of actions) {
+    console.log(entry.short ? `    ${entry.short}  (${entry.name})` : `    ${entry.name}  (full name only \u2014 ambiguous short)`);
+  }
+  if (flows.length > 0) {
+    console.log(`  flows (mm-harness run <flow>):`);
+    for (const flow of flows) console.log(`    ${flow}`);
+  }
+  return EXIT.ok;
+}
+export {
+  handleListExecutables
+};

package/dist/commands/logs.js

@@ -2,8 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnInherit, str, targetOf, usageOut } from "./shared.js";
-const LOGS_BOOLEANS = /* @__PURE__ */ new Set(["full", "json"]);
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnInherit, spawnScript, str, targetOf, usageOut } from "./shared.js";
+const LOGS_BOOLEANS = /* @__PURE__ */ new Set(["full", "json", "window"]);
 async function handleLogs(argv) {
   const { options } = parseFlags(argv, LOGS_BOOLEANS);
   const json = flag(options, "json");
@@ -43,6 +43,29 @@ async function handleLogs(argv) {
       surface.hints.launch
     );
   }
+  if (flag(options, "window")) {
+    surface.resolveSlotPorts(target);
+    const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "default";
+    const windowName = adapter === "mobile" ? `metro-${port}` : `webpack-${port}`;
+    const devLog = logSources[0].path;
+    const leaf = path.join(runnerDir, "adapters/shared/open-log-window.sh");
+    const result = spawnScript(
+      leaf,
+      ["--window", windowName, "--log", devLog, "--runtime-dir", path.dirname(devLog)],
+      target,
+      json
+    );
+    if (json) {
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: "logs", action: "window", adapter, window: windowName, logFile: devLog, exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime },
+          null,
+          2
+        )
+      );
+    }
+    return result.status === 0 ? EXIT.ok : EXIT.runtime;
+  }
   if (json) {
     console.log(JSON.stringify({ schemaVersion: 1, command: "logs", adapter, source, logFile, exitCode: EXIT.ok }, null, 2));
     return EXIT.ok;

package/dist/commands/manifest.js

@@ -1,4 +1,5 @@
 import { loadActionManifest, validateManifest } from "../manifest.js";
+import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
   isRecord,
@@ -19,9 +20,22 @@ async function handleActions({ options }) {
   const { adapter } = resolveAdapter(options);
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   await validateManifest(manifest);
+  const json = optionFlag(options, "json");
   const action = optionString(options, "action");
-  const actions = describeManifestActions(manifest, action);
-  if (optionFlag(options, "json")) {
+  const all = describeManifestActions(manifest);
+  const actions = action ? fuzzyResolveActions(all, action) : all;
+  if (action && actions.length === 0) {
+    const message = `no action matches "${action}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter}   # list the vocabulary`;
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  if (json) {
     console.log(JSON.stringify({ adapter, actions }, null, 2));
   } else {
     for (const entry of actions) {
@@ -31,7 +45,15 @@ async function handleActions({ options }) {
   }
   return 0;
 }
-function describeManifestActions(manifest, filterAction) {
+function fuzzyResolveActions(entries, query) {
+  const exactFull = entries.filter((e) => e.name === query);
+  if (exactFull.length > 0) return exactFull;
+  const finalSegment = (name) => name.split(".").pop() ?? name;
+  const exactSegment = entries.filter((e) => finalSegment(e.name) === query);
+  if (exactSegment.length > 0) return exactSegment;
+  return entries.filter((e) => finalSegment(e.name).includes(query));
+}
+function describeManifestActions(manifest) {
   const manifestRecord = isRecord(manifest) ? manifest : {};
   const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
   const official = Array.isArray(manifestRecord.supported_official_actions) ? manifestRecord.supported_official_actions.filter((value) => typeof value === "string") : [];
@@ -45,12 +67,10 @@ function describeManifestActions(manifest, filterAction) {
     }
     return [];
   }) : [];
-  const entries = [
+  return [
     ...official.map((name) => describeManifestAction(name, "official", metadata[name])),
     ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata))
-  ].filter((entry) => !filterAction || entry.name === filterAction);
-  if (filterAction && entries.length === 0) throw new Error(`Action not found in manifest: ${filterAction}`);
-  return entries;
+  ];
 }
 function describeManifestAction(name, kind, metadata) {
   const record = isRecord(metadata) ? metadata : {};

package/dist/commands/parse-args.js

@@ -23,6 +23,7 @@ function parseArgs(argv, command) {
     "startWatch",
     "record",
     "plan",
+    "list",
     "raw",
     "fix",
     "force",

package/dist/commands/run.js

@@ -3,13 +3,11 @@ import path from "node:path";
 import { walletFixturePath } from "../paths.js";
 import { EXIT } from "./shared.js";
 import {
-  adapterOption,
   optionFlag,
   optionString,
   requiredOption,
   resolveAdapter,
   runtimeOptionsFromCli,
-  targetPath,
   usageError
 } from "./parse-args.js";
 import {
@@ -21,13 +19,14 @@ import {
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
+import { handleListExecutables } from "./list-executables.js";
 async function handleRun({ positional, options }) {
+  if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
   if (!targetRecipe) throw usageError("run requires <recipe.json>.");
   if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
-  const adapter = adapterOption(options);
+  const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
-  const target = targetPath(options);
   const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
   const prepared = await prepareHeal(adapter, target, options, json);
   if (typeof prepared === "number") return prepared;

package/dist/live-adapter-contract.js

@@ -119,18 +119,39 @@ function runProcess(command, args, options) {
     });
   });
 }
-function commandFor(file) {
+function commandFor(file, projectRoot, platform) {
   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 needsTsx = platform === "core" || importsSourceTypescript(file);
+  if (!needsTsx && (file.endsWith(".mjs") || file.endsWith(".js"))) {
+    return { command: process.execPath, args: [file] };
+  }
+  const tsxBin = resolveTsxBin(projectRoot);
+  if (!tsxBin) {
+    const where = projectRoot ?? "the checkout";
+    const error = new Error(
+      `this action runs TypeScript from the checkout but no tsx runtime was found.
+  Next: run 'yarn install' in ${where} (tsx is a dev dependency of the checkout); if package imports still fail, run 'yarn build' there`
+    );
+    error.exitCode = 2;
+    throw error;
   }
-  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 resolveTsxBin(projectRoot) {
+  if (process.env.TSX_BIN) return process.env.TSX_BIN;
+  const candidates = [];
+  if (projectRoot) candidates.push(path.join(projectRoot, "node_modules/.bin/tsx"));
+  candidates.push(path.join(runnerDir, "node_modules/.bin/tsx"));
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  try {
+    const protocolTsx = path.join(resolveRequiredLocalProtocolRoot("TypeScript live adapter execution"), "node_modules/.bin/tsx");
+    if (existsSync(protocolTsx)) return protocolTsx;
+  } catch {
+  }
+  return null;
+}
 function importsSourceTypescript(file) {
   return importsSourceTypescriptFrom(file, /* @__PURE__ */ new Set());
 }
@@ -201,7 +222,7 @@ async function runLiveAdapterScript({ platform, action, node, context }) {
   };
   await writeFile(inputPath, `${JSON.stringify(input, null, 2)}
 `);
-  const command = commandFor(script);
+  const command = commandFor(script, context.projectRoot, platform);
   const platformEnv = await platformAdapterEnv(platform, context.projectRoot, tempDir);
   const result = await runProcess(command.command, [...command.args, inputPath], {
     cwd: context.projectRoot,

package/dist/mm-harness-cli.js

@@ -230,8 +230,10 @@ Example:
   Launch the app \u2014 quick relaunch by default; --build for a full native/webpack build.
   Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
   --sidepanel to override). core is headless (teaching error \u2014 use verify/run).
+  Extension quick launch REUSES a healthy live runtime (reload in place, no rebuild);
+  --build is the escape hatch that always clean-builds + relaunches a fresh runtime.
 
-  --build                            Full native/webpack build tier (default = quick relaunch)
+  --build                            Full clean build + relaunch (escape hatch; skips extension reuse)
   --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
   --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
   --watch                            Persistent webpack watcher then relaunch (extension only)

package/dist/paths.js

@@ -47,6 +47,9 @@ function recipeWatchLogCandidates() {
 }
 function resolveLocalProtocolRoot() {
   const candidates = [
+    // Orchestrator-neutral name is primary; FARMSLOT_ROOT stays a back-compat alias
+    // for one release (the installer injects METAMASK_RUNNER_PROTOCOL_ROOT).
+    process.env.METAMASK_RUNNER_PROTOCOL_ROOT,
     process.env.FARMSLOT_ROOT,
     readConfiguredProtocolRoot(),
     findProtocolRoot(runnerDir),
@@ -59,7 +62,7 @@ function resolveRequiredLocalProtocolRoot(reason) {
   const root = resolveLocalProtocolRoot();
   if (!root) {
     throw new Error(
-      `${reason} requires a local protocol/runtime checkout. Set FARMSLOT_ROOT or create .farmslot-root for this dev-only path.`
+      `${reason} requires a local protocol/runtime checkout. Set METAMASK_RUNNER_PROTOCOL_ROOT (or the legacy FARMSLOT_ROOT), or create .farmslot-root for this dev-only path.`
     );
   }
   return root;

package/package.json

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