@deeeed/metamask-harness 0.4.0 → 0.5.1

package/dist/adapters/extension/runtime-decision.js

@@ -0,0 +1,305 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  depsCheck,
+  INSTALL_MARKERS,
+  recordDepsBaseline
+} from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { recipeHarnessPath, recipeWatchLogCandidates } from "../../paths.js";
+const WEBPACK_DIRECT_INPUTS = ["package.json", "yarn.lock", ".yarnrc.yml", ".tool-versions"];
+const WEBPACK_RECURSIVE_INPUTS = ["development/webpack"];
+const WEBPACK_CACHE_DIR = "node_modules/.cache/webpack";
+const WATCH_LOG_CANDIDATES = recipeWatchLogCandidates();
+function git(target, args) {
+  try {
+    return execFileSync("git", ["-C", target, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function gitRaw(target, args) {
+  try {
+    return execFileSync("git", ["-C", target, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return "";
+  }
+}
+function addFile(hash, target, rel) {
+  const abs = path.join(target, rel);
+  const stat = fs.statSync(abs);
+  hash.update(rel);
+  hash.update(String(stat.size));
+  hash.update(fs.readFileSync(abs));
+}
+function walk(hash, target, relDir) {
+  const absDir = path.join(target, relDir);
+  if (!fs.existsSync(absDir)) return;
+  for (const name of fs.readdirSync(absDir).sort()) {
+    const rel = path.join(relDir, name);
+    const stat = fs.statSync(path.join(target, rel));
+    if (stat.isDirectory()) walk(hash, target, rel);
+    else if (stat.isFile() && /\.(c?m?[jt]sx?|json)$/u.test(rel)) addFile(hash, target, rel);
+  }
+}
+function webpackFingerprint(target) {
+  const hash = crypto.createHash("sha256");
+  for (const rel of WEBPACK_DIRECT_INPUTS) {
+    if (fs.existsSync(path.join(target, rel))) addFile(hash, target, rel);
+  }
+  for (const dir of WEBPACK_RECURSIVE_INPUTS) walk(hash, target, dir);
+  return { gitHead: git(target, ["rev-parse", "HEAD"]) ?? "unknown", fingerprint: hash.digest("hex") };
+}
+function stateDir(target) {
+  return recipeHarnessPath(target, "extension", "decision-state");
+}
+function readBaseline(target, name) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(stateDir(target), name), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeBaseline(target, name, value) {
+  const dir = stateDir(target);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, name), `${JSON.stringify(value, null, 2)}
+`);
+}
+function newestMtime(target, rels) {
+  let newest = 0;
+  for (const rel of rels) {
+    const abs = path.join(target, rel);
+    if (fs.existsSync(abs)) newest = Math.max(newest, fs.statSync(abs).mtimeMs);
+  }
+  return newest;
+}
+function webpackCacheCheck(target) {
+  const cachePresent = fs.existsSync(path.join(target, WEBPACK_CACHE_DIR));
+  if (!cachePresent) return { cachePresent: false, status: "no-cache", hasBaseline: false };
+  const baseline = readBaseline(target, "webpack-cache-state.json");
+  if (!baseline) {
+    const cacheMtime = fs.statSync(path.join(target, WEBPACK_CACHE_DIR)).mtimeMs;
+    const poisoned = newestMtime(target, ["yarn.lock", ...INSTALL_MARKERS]) > cacheMtime;
+    return { cachePresent: true, status: poisoned ? "stale" : "current", hasBaseline: false };
+  }
+  const current = webpackFingerprint(target);
+  const status = baseline.fingerprint === current.fingerprint && baseline.gitHead === current.gitHead ? "current" : "stale";
+  return { cachePresent: true, status, hasBaseline: true };
+}
+function buildLogCheck(target, watchLog) {
+  const candidates = (watchLog ? [path.isAbsolute(watchLog) ? watchLog : path.join(target, watchLog)] : WATCH_LOG_CANDIDATES.map((rel) => path.join(target, rel))).filter((file) => fs.existsSync(file));
+  if (!candidates.length) return { status: "no-watch" };
+  const newestFirst = [...candidates].sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  const lines = fs.readFileSync(newestFirst[0], "utf8").split("\n");
+  const ERR = /Module build failed|^ERROR in |compiled with [1-9]\d* error/u;
+  const OK = /compiled successfully|compiled with \d+ warning|MetaMask .* compiled|Bundle end: service worker|Bundle end:.*app-init/iu;
+  let lastErr = -1;
+  let lastOk = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (ERR.test(lines[i])) lastErr = i;
+    if (OK.test(lines[i])) lastOk = i;
+  }
+  if (lastErr > lastOk) {
+    const excerpt = lines.slice(lastErr, lastErr + 3).join(" | ").slice(0, 400);
+    const staleCache = /ENOENT/u.test(excerpt) && /node_modules/u.test(excerpt);
+    return { status: "errors", reason: staleCache ? "stale-cache" : "build-error", excerpt };
+  }
+  if (lastOk >= 0) return { status: "ok" };
+  return { status: "building" };
+}
+function uncommittedSource(target) {
+  const dirs = ["ui", "app", "shared", "development"].filter((d) => fs.existsSync(path.join(target, d)));
+  if (!dirs.length) return [];
+  const SRC = /\.(ts|tsx|js|jsx|cjs|mjs|json|scss|css)$/iu;
+  const records = gitRaw(target, ["-c", "core.quotePath=false", "status", "--porcelain", "-z", "--", ...dirs]).split("\0").filter(Boolean);
+  const dirty = [];
+  for (const record of records) {
+    const file = /^.. /u.test(record) ? record.slice(3) : record;
+    if (SRC.test(file)) dirty.push(file);
+  }
+  return dirty;
+}
+function latestFileMtime(target, files) {
+  let latest = 0;
+  for (const file of files) {
+    const absolute = path.join(target, file);
+    if (!fs.existsSync(absolute)) continue;
+    const stat = fs.statSync(absolute);
+    if (stat.isFile()) latest = Math.max(latest, stat.mtimeMs);
+  }
+  return latest;
+}
+function latestDistMtime(target) {
+  const distDir = path.join(target, "dist/chrome");
+  let latest = 0;
+  function walk2(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      const absolute = path.join(dir, entry);
+      const stat = fs.statSync(absolute);
+      if (stat.isDirectory()) walk2(absolute);
+      else if (stat.isFile()) latest = Math.max(latest, stat.mtimeMs);
+    }
+  }
+  walk2(distDir);
+  return latest;
+}
+function distCheck(target) {
+  const manifestPath = path.join(target, "dist/chrome/manifest.json");
+  if (!fs.existsSync(manifestPath)) return { status: "no-build" };
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return { status: "no-build" };
+  }
+  const description = typeof manifest.description === "string" ? manifest.description : "";
+  const match = /from git id:\s*([0-9a-f]{7,40})/iu.exec(description);
+  const head = (git(target, ["rev-parse", "HEAD"]) ?? "").toLowerCase();
+  const headShort = head ? head.slice(0, 8) : void 0;
+  if (!match) return { status: "unknown", head: headShort };
+  const distGitId = match[1].toLowerCase();
+  const distShort = distGitId.slice(0, 8);
+  if (!head) return { status: "unknown", distGitId: distShort };
+  if (!head.startsWith(distGitId)) {
+    return { status: "stale", reason: "commit-mismatch", distGitId: distShort, head: headShort };
+  }
+  const dirty = uncommittedSource(target);
+  if (dirty.length) {
+    const dirtySinceBuild = latestFileMtime(target, dirty) > latestDistMtime(target);
+    if (dirtySinceBuild) {
+      return { status: "stale", reason: "uncommitted-source", distGitId: distShort, head: headShort, modified: dirty.slice(0, 10) };
+    }
+  }
+  return { status: "fresh", distGitId: distShort, head: headShort };
+}
+async function cdpCheck(target, cdpPort) {
+  if (!cdpPort) return { status: "skipped" };
+  try {
+    const { checkExtensionRuntimeHealth } = await import("./runtime.js");
+    const report = await checkExtensionRuntimeHealth(target, cdpPort);
+    return report.status === "PASS" ? { status: "pass" } : { status: "fail", findings: report.findings };
+  } catch (error) {
+    return { status: "fail", findings: [error instanceof Error ? error.message : String(error)] };
+  }
+}
+function recordReadinessBaseline(target) {
+  recordDepsBaseline(target);
+  const cache = webpackFingerprint(target);
+  writeBaseline(target, "webpack-cache-state.json", cache);
+}
+async function decideExtensionReadiness(target, options = {}) {
+  const resolved = path.resolve(target);
+  if (options.record) recordReadinessBaseline(resolved);
+  const deps = depsCheck(resolved);
+  const webpackCache = webpackCacheCheck(resolved);
+  const buildLog = buildLogCheck(resolved, options.watchLog);
+  const dist = distCheck(resolved);
+  const cdp = await cdpCheck(resolved, options.cdpPort);
+  const checks = { deps, webpackCache, buildLog, dist, cdp };
+  const install = [{ id: "yarn-install", argv: ["yarn", "install", "--immutable"], cwd: resolved }];
+  const relaunch = [{ id: "relaunch-browser" }];
+  const cacheStale = buildLog.reason === "stale-cache";
+  const rules = [
+    {
+      when: deps.status === "missing",
+      decision: "install",
+      reasonCode: "deps-missing",
+      reasons: ["Dependencies are not installed (no yarn install-state markers)."],
+      actions: install
+    },
+    {
+      when: deps.status === "stale",
+      decision: "install",
+      reasonCode: "deps-stale",
+      reasons: ["package.json/yarn.lock changed since the recorded install."],
+      actions: install
+    },
+    {
+      when: buildLog.status === "errors",
+      decision: "build",
+      clean: cacheStale,
+      reasonCode: cacheStale ? "webpack-cache-stale" : "build-errors",
+      reasons: [
+        cacheStale ? "Webpack is failing on a poisoned cache (ENOENT on a deduped module)." : "Webpack build has errors; fix the source/build before validating.",
+        ...buildLog.excerpt ? [buildLog.excerpt] : []
+      ],
+      actions: buildAction(resolved, cacheStale)
+    },
+    {
+      when: webpackCache.status === "stale",
+      decision: "build",
+      clean: true,
+      reasonCode: "webpack-cache-stale",
+      reasons: ["Webpack build inputs changed since the cache was recorded; clear cache and rebuild."],
+      actions: buildAction(resolved, true)
+    },
+    {
+      when: dist.status === "no-build",
+      decision: "build",
+      reasonCode: "dist-missing",
+      reasons: ["No dist/chrome build present."],
+      actions: buildAction(resolved, false)
+    },
+    {
+      when: dist.status === "stale",
+      decision: "build",
+      reasonCode: "dist-stale",
+      reasons: [dist.reason === "uncommitted-source" ? `Uncommitted source since the build (${dist.modified?.length ?? 0} file(s)); rebuild.` : `dist git id ${dist.distGitId} != HEAD ${dist.head}; rebuild.`],
+      actions: buildAction(resolved, false)
+    },
+    {
+      when: cdp.status === "pass",
+      decision: "ready",
+      reasonCode: "healthy",
+      reasons: ["Build is fresh and the extension runtime is healthy over CDP."],
+      actions: []
+    },
+    {
+      when: cdp.status === "fail",
+      decision: "relaunch",
+      reasonCode: "runtime-unhealthy",
+      reasons: [
+        "Build is fresh but the live extension is unhealthy; relaunch the browser.",
+        ...cdp.findings?.slice(0, 3) ?? []
+      ],
+      actions: relaunch
+    }
+  ];
+  const fallback = {
+    decision: "relaunch",
+    reasonCode: "cdp-unknown",
+    reasons: ["Build is fresh; browser liveness unverified (pass --cdp-port to confirm `ready`)."],
+    actions: relaunch
+  };
+  const core = rules.find((rule) => rule.when) ?? fallback;
+  return {
+    schemaVersion: 1,
+    adapter: "extension",
+    target: resolved,
+    decision: core.decision,
+    clean: core.clean ?? false,
+    reasonCode: core.reasonCode,
+    reasons: core.reasons,
+    checks,
+    actions: core.actions
+  };
+}
+function buildAction(target, clean) {
+  const actions = [];
+  if (clean) actions.push({ id: "clear-webpack-cache", paths: [WEBPACK_CACHE_DIR] });
+  actions.push({ id: "start-webpack-watch", argv: ["yarn", "start"], cwd: target });
+  return actions;
+}
+export {
+  decideExtensionReadiness,
+  recordReadinessBaseline
+};

package/dist/adapters/extension/runtime.js

@@ -0,0 +1,324 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, recipeRuntimeDir, resolveLocalProtocolRoot, resolveRequiredLocalProtocolRoot, runnerDir } from "../../paths.js";
+const { CdpSession, jsonGet, sleep } = await importRecipeHarnessRuntimeCdp();
+const { extensionIdFromTarget } = await importRecipeHarnessRuntimeBrowserExtension();
+async function prepareExtensionRuntime(options) {
+  const projectRoot = path.resolve(options.projectRoot);
+  const slot = resolveExtensionSlot(projectRoot, options.slot);
+  const cdpPort = resolveCdpPort(options.cdpPort, slot);
+  let launch = null;
+  if (options.launchExistingDist) {
+    if (!slot) {
+      throw new Error(
+        `Cannot launch host-managed Extension runtime for ${projectRoot}: no configured slot maps to this repo. Pass --slot <slot-id> or add the checkout to pool/*.json.`
+      );
+    }
+    launch = await launchHostValidationBrowser({
+      projectRoot,
+      cdpPort,
+      slotId: slot.id,
+      validationRuntimeDir: options.validationRuntimeDir ?? `${recipeRuntimeDir()}/validation-${cdpPort}`
+    });
+  }
+  const health = await assertHealthyExtensionRuntime({
+    projectRoot,
+    cdpPort,
+    timeoutMs: options.healthTimeoutMs
+  });
+  return { launch, health };
+}
+async function assertHealthyExtensionRuntime(options) {
+  const timeoutMs = options.timeoutMs ?? 3e4;
+  const deadline = Date.now() + timeoutMs;
+  let lastReport = null;
+  while (Date.now() <= deadline) {
+    lastReport = await checkExtensionRuntimeHealth(options.projectRoot, options.cdpPort);
+    if (lastReport.status === "PASS") return lastReport;
+    await sleep(500);
+  }
+  const report = lastReport ?? failReport(options.cdpPort, ["CDP runtime was not probed."], {});
+  throw new Error(formatHealthFailure(report, options.projectRoot));
+}
+async function checkExtensionRuntimeHealth(projectRoot, cdpPort) {
+  const findings = [];
+  let targets = [];
+  try {
+    await jsonGet(`http://127.0.0.1:${cdpPort}/json/version`);
+    const rawTargets = await jsonGet(`http://127.0.0.1:${cdpPort}/json/list`);
+    targets = Array.isArray(rawTargets) ? rawTargets : [];
+  } catch (error) {
+    return failReport(cdpPort, [`CDP is not reachable on port ${cdpPort}: ${messageOf(error)}`], {});
+  }
+  const extensionTargets = targets.filter(
+    (target2) => target2.type === "page" && String(target2.url ?? "").startsWith("chrome-extension://") && String(target2.url ?? "").includes("/home.html") && Boolean(target2.webSocketDebuggerUrl)
+  );
+  if (extensionTargets.length !== 1) {
+    findings.push(`Expected exactly one MetaMask extension home page target, found ${extensionTargets.length}.`);
+  }
+  const target = extensionTargets[0];
+  if (!target?.webSocketDebuggerUrl) {
+    return failReport(cdpPort, findings, {
+      targetUrls: targets.map((entry) => entry.url).filter(Boolean)
+    });
+  }
+  if (String(target.url ?? "").startsWith("chrome-error://")) {
+    findings.push(`Extension target resolved to chrome-error page: ${target.url}`);
+  }
+  const session = await CdpSession.connect(target.webSocketDebuggerUrl);
+  try {
+    await session.call("Runtime.enable");
+    await session.call("Page.enable");
+    const runtime = await evaluateHealth(session);
+    if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
+      findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
+    }
+    if (runtime.backgroundUnresponsive === true) {
+      findings.push("Extension UI reports background connection unresponsive.");
+    }
+    if (runtime.hasSubmitRequest !== true) {
+      findings.push("stateHooks.submitRequestToBackground is unavailable.");
+    }
+    if (runtime.hasStore !== true) {
+      findings.push("stateHooks.store is unavailable.");
+    }
+    if (runtime.hasPerpsStreamManager !== true) {
+      findings.push("stateHooks.getPerpsStreamManager is unavailable.");
+    }
+    if (runtime.backgroundProbeOk !== true) {
+      findings.push(`Perps background read probe failed: ${runtime.backgroundProbeError ?? "unknown error"}.`);
+    }
+    const extensionId = safeExtensionId(target);
+    return {
+      status: findings.length === 0 ? "PASS" : "FAIL",
+      cdpPort,
+      targetUrl: target.url,
+      extensionId,
+      extensionPageTargets: extensionTargets.length,
+      findings,
+      details: {
+        projectRoot,
+        targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+        runtime
+      }
+    };
+  } finally {
+    session.close();
+  }
+}
+function failReport(cdpPort, findings, details) {
+  return {
+    status: "FAIL",
+    cdpPort,
+    extensionPageTargets: 0,
+    findings,
+    details
+  };
+}
+async function evaluateHealth(session) {
+  const result = await session.call("Runtime.evaluate", {
+    expression: `(() => {
+      const hooks = globalThis.stateHooks || {};
+      const bodyText = document.body?.innerText || '';
+      const storeState = hooks.store?.getState?.() || {};
+      const manager = hooks.getPerpsStreamManager?.();
+      const accountCache = manager?.account?.cache;
+      return Promise.race([
+        (async () => {
+          let backgroundProbeOk = false;
+          let backgroundProbeError = null;
+          if (typeof hooks.submitRequestToBackground === 'function') {
+            try {
+              const accountState = await hooks.submitRequestToBackground('perpsGetAccountState', []);
+              backgroundProbeOk = Boolean(accountState && typeof accountState === 'object');
+              if (!backgroundProbeOk) backgroundProbeError = 'perpsGetAccountState returned an empty result';
+            } catch (error) {
+              backgroundProbeError = String(error?.message || error);
+            }
+          } else {
+            backgroundProbeError = 'submitRequestToBackground is not a function';
+          }
+          return {
+            href: location.href,
+            title: document.title,
+            hookKeys: Object.keys(hooks),
+            hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
+            hasStore: Boolean(hooks.store),
+            hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
+            backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+            activeProvider: storeState.metamask?.activeProvider || null,
+            isTestnet: Boolean(storeState.metamask?.isTestnet),
+            perpsManagerInitialized: Boolean(manager?.isInitialized?.()),
+            positionsCacheIsArray: Array.isArray(manager?.positions?.cache),
+            ordersCacheIsArray: Array.isArray(manager?.orders?.cache),
+            accountCachePresent: Boolean(accountCache && typeof accountCache === 'object'),
+            backgroundProbeOk,
+            backgroundProbeError,
+          };
+        })(),
+        new Promise((resolve) => setTimeout(() => resolve({
+          href: location.href,
+          title: document.title,
+          hookKeys: Object.keys(hooks),
+          hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
+          hasStore: Boolean(hooks.store),
+          hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
+          backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+          backgroundProbeOk: false,
+          backgroundProbeError: 'perpsGetAccountState timed out after 5000ms',
+        }), 5000)),
+      ]);
+    })()`,
+    awaitPromise: true,
+    returnByValue: true
+  });
+  if (result.exceptionDetails) {
+    throw new Error(
+      result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Extension runtime health evaluation failed."
+    );
+  }
+  return result.result?.value ?? {};
+}
+function formatHealthFailure(report, projectRoot) {
+  return [
+    `Extension runtime health check failed for ${projectRoot} on CDP port ${report.cdpPort}.`,
+    ...report.findings.map((finding) => `- ${finding}`),
+    "Use the host-managed validation launcher, for example:",
+    `  mm-harness run <recipe.json> --adapter extension --target ${projectRoot} --slot <slot-id> --cdp-port ${report.cdpPort} --launch-existing-dist --artifacts-dir <artifacts-dir>`,
+    `Health details: ${JSON.stringify(report.details)}`
+  ].join("\n");
+}
+function resolveCdpPort(rawPort, slot) {
+  const raw = rawPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT ?? slot?.cdpPort;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error("Extension runtime requires --cdp-port, CDP_PORT, RECIPE_CDP_PORT, or a configured slot with resources.browser.cdp_port.");
+  }
+  return port;
+}
+function resolveExtensionSlot(projectRoot, requestedSlot) {
+  const protocolRoot = resolveLocalProtocolRoot();
+  if (!protocolRoot) {
+    if (requestedSlot) throw new Error("Extension slot lookup requires a local host checkout when --slot is provided.");
+    return null;
+  }
+  const poolsDir = path.join(protocolRoot, "pool");
+  if (!fs.existsSync(poolsDir)) return null;
+  for (const file of fs.readdirSync(poolsDir)) {
+    if (!file.endsWith(".json") || file.includes(".bak")) continue;
+    const pool = JSON.parse(fs.readFileSync(path.join(poolsDir, file), "utf8"));
+    for (const rawSlot of pool.slots ?? []) {
+      if (!rawSlot || typeof rawSlot !== "object") continue;
+      const slot = rawSlot;
+      if (requestedSlot && slot.id !== requestedSlot) continue;
+      if (!requestedSlot) {
+        const repo = String(slot.repo ?? "");
+        if (!path.isAbsolute(repo) || path.resolve(repo) !== projectRoot) continue;
+      }
+      return {
+        id: String(slot.id),
+        repo: path.resolve(String(slot.repo)),
+        cdpPort: Number(slot.resources?.browser?.cdp_port || slot.resources?.browser?.cdpPort || void 0) || void 0
+      };
+    }
+  }
+  return null;
+}
+async function launchHostValidationBrowser(options) {
+  const protocolRoot = resolveRequiredLocalProtocolRoot("Extension validation browser launch");
+  const script = path.join(protocolRoot, "projects/metamask-extension-farm/setup/launch-validation-browser.sh");
+  if (!fs.existsSync(script)) {
+    throw new Error(`Extension validation launcher not found: ${script}`);
+  }
+  await killCdpPort(options.cdpPort);
+  const result = await runProcess("bash", [
+    script,
+    options.slotId,
+    "--cdp-port",
+    String(options.cdpPort),
+    "--runtime-dir",
+    options.validationRuntimeDir,
+    "--no-landing"
+  ], {
+    cwd: protocolRoot,
+    env: process.env,
+    timeoutMs: 18e4
+  });
+  if (result.timedOut) {
+    throw new Error(`Extension validation launcher timed out after 180000ms.
+${result.stdout}
+${result.stderr}`);
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(`Extension validation launcher failed with exit ${result.exitCode}.
+${result.stdout}
+${result.stderr}`);
+  }
+  return {
+    launched: true,
+    slotId: options.slotId,
+    cdpPort: options.cdpPort,
+    runtimeDir: options.validationRuntimeDir,
+    stdout: result.stdout
+  };
+}
+function runProcess(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    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.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    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 });
+    });
+  });
+}
+async function killCdpPort(cdpPort) {
+  if (process.platform !== "darwin" && process.platform !== "linux") return;
+  await runProcess("bash", ["-lc", `lsof -ti tcp:${cdpPort} -sTCP:LISTEN | xargs -r kill -TERM || true; sleep 1; lsof -ti tcp:${cdpPort} -sTCP:LISTEN | xargs -r kill -KILL || true`], {
+    cwd: runnerDir,
+    env: process.env,
+    timeoutMs: 1e4
+  });
+}
+function safeExtensionId(target) {
+  try {
+    return extensionIdFromTarget(target);
+  } catch (_error) {
+    return void 0;
+  }
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  assertHealthyExtensionRuntime,
+  checkExtensionRuntimeHealth,
+  formatHealthFailure,
+  prepareExtensionRuntime
+};

package/dist/adapters/extension/surface.js

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { recipeRuntimePath } from "../../paths.js";
+import { resolveExtensionSlotPorts, stopExtensionWatcher } from "../slot-ports.js";
+import { decideExtensionReadiness } from "./runtime-decision.js";
+function watcherStatus(buildLog) {
+  if (buildLog === "ok") return "up";
+  if (buildLog === "no-watch") return "down";
+  return buildLog;
+}
+const extensionSurface = {
+  adapter: "extension",
+  headless: false,
+  resolveSlotPorts(target) {
+    resolveExtensionSlotPorts(target);
+  },
+  async runtimeStatus(target) {
+    const cdpPort = process.env.CDP_PORT ? parseInt(process.env.CDP_PORT, 10) : void 0;
+    const report = await decideExtensionReadiness(target, { cdpPort });
+    return {
+      decision: report.decision,
+      reasonCode: report.reasonCode,
+      reasons: report.reasons,
+      deps: report.checks.deps.status,
+      devServer: { label: "webpack", status: watcherStatus(report.checks.buildLog.status) }
+    };
+  },
+  runwayProvision: {
+    async run(target, options) {
+      return {
+        schemaVersion: 1,
+        command: "provision",
+        adapter: "extension",
+        target: path.resolve(target),
+        status: "fail",
+        exitCode: 2,
+        error: {
+          code: "UNSUPPORTED_ADAPTER",
+          message: "extension uses a browser runtime; Runway mobile provisioning is not supported.",
+          userAction: options.rerunCommand || "mm-harness provision --adapter extension"
+        }
+      };
+    }
+  },
+  devServer: {
+    describe: () => "webpack watcher",
+    stop(target) {
+      const signalled = stopExtensionWatcher(target);
+      const port = process.env.WATCHER_PORT ?? "default";
+      spawnSync("tmux", ["kill-window", "-t", `webpack-${port}`], { stdio: "ignore", timeout: 2e3 });
+      const summary = signalled > 0 ? `stopped webpack watcher (${signalled} process${signalled === 1 ? "" : "es"}) for ${target}` : `webpack watcher not running for ${target} \u2014 nothing to stop`;
+      return { kind: "stopped", status: 0, summary, signalled };
+    }
+  },
+  logSources(target) {
+    return [
+      { label: "webpack", path: recipeRuntimePath(target, "webpack.log") },
+      { label: "watcher", path: recipeRuntimePath(target, "recipe-harness-webpack.log") },
+      { label: "rebuild", path: recipeRuntimePath(target, "rebuild.log") }
+    ];
+  },
+  hints: {
+    launch: "mm-harness launch",
+    relaunch: "mm-harness launch --build"
+  }
+};
+export {
+  extensionSurface
+};