@deeeed/metamask-harness 0.3.9 → 0.5.0

package/dist/commands/debug.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { runnerDir } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from "./shared.js";
+const DEBUG_BOOLEANS = /* @__PURE__ */ new Set(["worker", "devMenu", "json"]);
+async function handleDebug(argv) {
+  const { options } = parseFlags(argv, DEBUG_BOOLEANS);
+  const json = flag(options, "json");
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+  if (!adapter) return usageOut(json, "debug", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) return usageOut(json, "debug", "core is headless; there is no debug console.", surface.hints.relaunch);
+  const worker = flag(options, "worker");
+  const devMenu = flag(options, "devMenu");
+  if (adapter === "mobile" && worker) {
+    return usageOut(
+      json,
+      "debug",
+      "--worker is extension-only (service-worker DevTools). Use --dev-menu on mobile.",
+      "mm-harness debug --dev-menu"
+    );
+  }
+  if (adapter === "extension" && devMenu) {
+    return usageOut(
+      json,
+      "debug",
+      "--dev-menu is mobile-only (RN developer menu). Use --worker on the extension.",
+      "mm-harness debug --worker"
+    );
+  }
+  const openDebug = path.join(runnerDir, "adapters/shared/open-debug.mjs");
+  const debugArgs = ["--adapter", adapter];
+  if (adapter === "extension") {
+    if (process.env.CDP_PORT) debugArgs.push("--cdp-port", process.env.CDP_PORT);
+    debugArgs.push("--target", worker ? "worker" : "page");
+  } else {
+    if (process.env.WATCHER_PORT) debugArgs.push("--port", process.env.WATCHER_PORT);
+    debugArgs.push("--action", devMenu ? "dev-menu" : "debug");
+  }
+  if (json) debugArgs.push("--json");
+  const result = spawnScript(process.execPath, [openDebug, ...debugArgs], target, json);
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: "debug", adapter, mode: worker ? "worker" : devMenu ? "dev-menu" : "default", exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime },
+        null,
+        2
+      )
+    );
+  }
+  return result.status === 0 ? EXIT.ok : EXIT.runtime;
+}
+export {
+  handleDebug
+};

package/dist/commands/fixtures.js

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runnerDir, walletFixturePath } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from "./shared.js";
+const FIXTURES_BOOLEANS = /* @__PURE__ */ new Set(["json"]);
+const RECOVERABLE_SETUP_WALLET_PATTERNS = [
+  "CDP not reachable",
+  "CDP bridge",
+  "is not installed",
+  "Engine.context.KeyringController not available",
+  "Engine does not exist",
+  "Cannot read property 'transactions'",
+  "bridge-not-ready",
+  "debug-target-missing",
+  "CDP eval failed",
+  "CDP eval-async failed"
+];
+function isRecoverableSetupWalletFailure(output) {
+  return RECOVERABLE_SETUP_WALLET_PATTERNS.some((p) => output.includes(p));
+}
+async function handleFixtures(argv, deps) {
+  const { positional, options } = parseFlags(argv, FIXTURES_BOOLEANS);
+  const json = flag(options, "json");
+  const sub = positional[0];
+  if (sub !== "sync" && sub !== "set") {
+    return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <sync|set>", "mm-harness fixtures sync   or   mm-harness fixtures set");
+  }
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+  if (!adapter) {
+    return usageOut(json, "fixtures", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) return usageOut(json, "fixtures", "core is headless; it has no wallet fixture.", surface.hints.launch);
+  const canonicalFixture = walletFixturePath(target);
+  const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures set`;
+  if (sub === "sync") {
+    const exitCode = fixturesSync(adapter, target, json);
+    if (json) {
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: "fixtures", action: "sync", adapter, fixture: canonicalFixture, exitCode },
+          null,
+          2
+        )
+      );
+    }
+    return exitCode;
+  }
+  const fixturePath = path.resolve(str(options, "fixture") ?? process.env.RECIPE_WALLET_FIXTURE ?? canonicalFixture);
+  let status;
+  if (adapter === "mobile") {
+    const setupWalletSh = path.join(runnerDir, "adapters/mobile/bridge-runtime/setup-wallet.sh");
+    const previousAppRoot = process.env.APP_ROOT;
+    process.env.APP_ROOT = target;
+    try {
+      let result = spawnScript(setupWalletSh, ["--fixture", fixturePath], target, json);
+      if (result.status !== 0 && isRecoverableSetupWalletFailure(result.output) && !process.env["RECIPE_SETUP_WALLET_RETRIED"]) {
+        process.env["RECIPE_SETUP_WALLET_RETRIED"] = "1";
+        if (!json) process.stderr.write("  setup-wallet: recoverable failure \u2014 restarting Metro and retrying\n  Next: wait for relaunch, then wallet setup will retry automatically\n");
+        const { prepareMobile } = await import("../adapters/mobile/prepare.js");
+        const platform = str(options, "platform") ?? process.env["MOBILE_PLATFORM"] ?? "ios";
+        const relaunchResult = await prepareMobile(target, { platform, json, preflightMode: "auto", clearMetro: true });
+        if (relaunchResult.status === 0) {
+          result = spawnScript(setupWalletSh, ["--fixture", fixturePath], target, json);
+        }
+      }
+      status = result.status === 0 ? "pass" : "fail";
+    } finally {
+      delete process.env["RECIPE_SETUP_WALLET_RETRIED"];
+      if (previousAppRoot === void 0) delete process.env.APP_ROOT;
+      else process.env.APP_ROOT = previousAppRoot;
+    }
+    if (!json && status === "fail") {
+      console.error(`  Next: ${retryHint}`);
+    }
+  } else {
+    if (!fs.existsSync(fixturePath)) {
+      return usageOut(
+        json,
+        "fixtures",
+        `no wallet fixture at ${fixturePath}.`,
+        "create it (or pass --fixture <path>), then re-run: mm-harness fixtures set"
+      );
+    }
+    const previousFixtureEnv = process.env.RECIPE_WALLET_FIXTURE;
+    process.env.RECIPE_WALLET_FIXTURE = fixturePath;
+    try {
+      const result = await deps.runOneNode("extension", "metamask.wallet.setup", {}, target, str(options, "actionManifest"));
+      status = result.status;
+    } finally {
+      if (previousFixtureEnv === void 0) delete process.env.RECIPE_WALLET_FIXTURE;
+      else process.env.RECIPE_WALLET_FIXTURE = previousFixtureEnv;
+    }
+    if (!json && status === "fail") {
+      console.error(`  Next: ${retryHint}`);
+    }
+  }
+  const teaching = `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}`;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "fixtures",
+          action: "set",
+          adapter,
+          fixture: fixturePath,
+          canonicalFixture,
+          status,
+          exitCode: status === "pass" ? EXIT.ok : EXIT.runtime,
+          message: teaching,
+          error: status === "fail" ? {
+            code: "SETUP_WALLET_FAILED",
+            message: "wallet fixture setup failed",
+            userAction: retryHint
+          } : null
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(teaching);
+  }
+  return status === "pass" ? EXIT.ok : EXIT.runtime;
+}
+function fixturesSync(adapter, target, json) {
+  const mmHarnessBin = path.join(runnerDir, "bin/mm-harness");
+  const installResult = spawnScript(
+    mmHarnessBin,
+    ["install", "--adapter", adapter, "--target", target],
+    target,
+    json
+  );
+  if (installResult.status !== 0) {
+    if (!json) {
+      console.error(`\u2717 mm-harness fixtures sync: overlay reinstall failed.
+  Next: mm-harness install --target ${target}   # diagnose the install failure`);
+    }
+    return EXIT.runtime;
+  }
+  const syncFixtureSh = path.join(runnerDir, "adapters/shared/sync-wallet-fixture.sh");
+  const syncArgs = ["--target", target];
+  if (process.env.CDP_PORT) syncArgs.push("--cdp-port", process.env.CDP_PORT);
+  if (process.env.RECIPE_SLOT_ID) syncArgs.push("--slot-id", process.env.RECIPE_SLOT_ID);
+  spawnScript(syncFixtureSh, syncArgs, target, json);
+  return EXIT.ok;
+}
+export {
+  handleFixtures
+};

package/dist/commands/launch.js

@@ -0,0 +1,325 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { color } from "../cli-color.js";
+import { handleHarness } from "../harness.js";
+import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } from "../paths.js";
+import { prepareMobile } from "../adapters/mobile/prepare.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { stopExtensionWatcher } from "../adapters/slot-ports.js";
+import {
+  ADAPTER_DETECT_NEXT,
+  EXIT,
+  flag,
+  parseFlags,
+  resolveAdapter,
+  spawnScript,
+  spawnScriptStreaming,
+  str,
+  targetOf,
+  usageOut
+} from "./shared.js";
+import {
+  RECOVERY_CODE,
+  checkHealBounds,
+  ensureOverlay,
+  newHealState,
+  parseHeal
+} from "../heal-bounds.js";
+const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
+  "build",
+  "watch",
+  "verify",
+  "sidepanel",
+  "fullscreen",
+  "runway",
+  "json",
+  "jsonStream",
+  "yes"
+]);
+async function handleLaunch(argv) {
+  const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
+  const json = flag(options, "json");
+  const target = targetOf(options);
+  const heal = parseHeal(options, "auto");
+  if (typeof heal !== "string") return usageOut(json, "launch", heal.error, "use --heal off|infra-only|auto");
+  const posToken = positional[0];
+  const mobileTargetToken = posToken === "ios" || posToken === "android" ? posToken : void 0;
+  const platformFlag = str(options, "platform");
+  const platformMobileToken = platformFlag === "ios" || platformFlag === "android" ? platformFlag : void 0;
+  const mobileTarget = mobileTargetToken ?? platformMobileToken;
+  const adapterHint = mobileTarget ? "mobile" : void 0;
+  const adapter = resolveAdapter(options, target, adapterHint);
+  if (!adapter) {
+    return usageOut(json, "launch", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  if (adapter === "core") {
+    return usageOut(json, "launch", "core is headless; there is nothing to launch.", "mm-harness verify");
+  }
+  if (adapter === "mobile" && !mobileTarget) {
+    return usageOut(
+      json,
+      "launch",
+      "target is required for mobile.",
+      "mm-harness launch ios   or   mm-harness launch android"
+    );
+  }
+  const wantBuild = flag(options, "build");
+  const wantVerify = flag(options, "verify");
+  const wantWatch = flag(options, "watch");
+  const wantRunway = flag(options, "runway");
+  if (wantRunway && adapter !== "mobile") {
+    return usageOut(json, "launch", "runway is mobile-only.", "drop --runway for the extension");
+  }
+  const displayMode = flag(options, "sidepanel") && !flag(options, "fullscreen") ? "sidepanel" : "fullscreen";
+  for (const portFlag of ["cdpPort", "watcherPort"]) {
+    const value = str(options, portFlag);
+    if (value !== void 0 && !/^\d+$/u.test(value)) {
+      return usageOut(
+        json,
+        "launch",
+        `--${portFlag === "cdpPort" ? "cdp-port" : "watcher-port"} must be numeric (got: ${value}).`,
+        `pass a numeric port, e.g. --${portFlag === "cdpPort" ? "cdp-port 6663" : "watcher-port 8081"}`
+      );
+    }
+  }
+  applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
+  const tier = wantVerify ? "verify" : wantBuild ? "build" : "quick";
+  const state = newHealState();
+  if (tier === "quick" && nativeInputsChanged(target, adapter)) {
+    return usageOut(
+      json,
+      "launch",
+      "native build inputs changed since last build.",
+      `mm-harness launch ${adapter === "mobile" ? `${mobileTarget} ` : ""}--build`
+    );
+  }
+  const ensured = await ensureOverlay(adapter, target, heal, state, json);
+  if (!ensured.ok) {
+    return launchFail(json, adapter, mobileTarget, tier, state, {
+      code: "OVERLAY_INSTALL_FAILED",
+      message: ensured.error ?? "overlay install failed",
+      recoverable: false,
+      exitCode: EXIT.infra
+    });
+  }
+  if (tier === "verify") {
+    const liveArgs = ["live", "--adapter", adapter, "--target", target];
+    if (adapter === "mobile" && mobileTarget) liveArgs.push("--platform", mobileTarget);
+    if (json) liveArgs.push("--json");
+    const code = await handleHarness(liveArgs);
+    return code;
+  }
+  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
+  if (attempt.status === 0) {
+    return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);
+  }
+  if (heal === "off") {
+    return launchFail(json, adapter, mobileTarget, tier, state, {
+      code: "LAUNCH_FAILED",
+      message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed (healing off)`,
+      recoverable: false,
+      exitCode: EXIT.infra
+    });
+  }
+  const bound = checkHealBounds(target, attempt.output, state);
+  if (bound !== null) {
+    return launchFail(json, adapter, mobileTarget, tier, state, {
+      code: bound.code,
+      message: bound.message,
+      recoverable: false,
+      userAction: bound.userAction,
+      exitCode: bound.exitCode,
+      originalError: bound.originalError
+    });
+  }
+  const recoveryCode = RECOVERY_CODE[adapter];
+  state.attemptedRecoveries.push(recoveryCode);
+  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
+  if (attempt.status === 0) {
+    state.recovered.push(recoveryCode);
+    return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);
+  }
+  return launchFail(json, adapter, mobileTarget, tier, state, {
+    code: "SAME_RECOVERY_TWICE",
+    message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed again after ${recoveryCode} recovery \u2014 refusing to loop.`,
+    recoverable: false,
+    exitCode: EXIT.bounded,
+    originalError: attempt.output.trim() || void 0
+  });
+}
+function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
+  getAdapterSurface(adapter).resolveSlotPorts(target);
+  const device = str(options, "device");
+  if (device && adapter === "mobile") {
+    if (mobileTarget === "android") {
+      process.env.ADB_SERIAL = device;
+      process.env.ANDROID_SERIAL = device;
+      process.env.ANDROID_DEVICE = device;
+    } else {
+      process.env.IOS_SIMULATOR = device;
+    }
+  }
+  const cdpPort = str(options, "cdpPort");
+  if (cdpPort) {
+    process.env.CDP_PORT = cdpPort;
+    process.env.RECIPE_CDP_PORT = cdpPort;
+  }
+  const watcherPort = str(options, "watcherPort");
+  if (watcherPort) {
+    process.env.WATCHER_PORT = watcherPort;
+    process.env.RECIPE_WATCHER_PORT = watcherPort;
+    process.env.METRO_PORT = watcherPort;
+  }
+}
+function nativeInputsChanged(target, adapter) {
+  const baselineFile = recipeRuntimePath(target, ".last-build-ref");
+  let baseline;
+  try {
+    baseline = fs.readFileSync(baselineFile, "utf8").trim();
+  } catch {
+    return false;
+  }
+  if (!baseline) return false;
+  const paths = adapter === "mobile" ? ["ios", "android", "package.json", "yarn.lock"] : ["package.json", "yarn.lock", "webpack.config.js"];
+  try {
+    const diff = execFileSync("git", ["-C", target, "diff", "--name-only", baseline, "--", ...paths], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return diff.length > 0;
+  } catch {
+    return false;
+  }
+}
+async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json) {
+  if (adapter === "mobile") {
+    const platform = mobileTarget ?? "ios";
+    const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;
+    const preflightMode = tier === "build" ? "auto" : "fast";
+    return prepareMobile(target, { platform, json, watcherPort, preflightMode });
+  }
+  if (!wantWatch && tier === "quick") {
+    return extensionRebuild(target, json);
+  }
+  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);
+}
+async function extensionRebuild(target, json) {
+  const runtimeDirRel = recipeRuntimeDir();
+  const runtimeAbs = path.join(target, runtimeDirRel);
+  const rebuildLog = path.join(runtimeAbs, "rebuild.log");
+  stopExtensionWatcher(target);
+  fs.mkdirSync(path.dirname(rebuildLog), { recursive: true });
+  fs.writeFileSync(rebuildLog, "");
+  const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
+  const liveArgs = ["--target", target, "--start-watch"];
+  if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
+  if (process.env.WATCHER_PORT) liveArgs.push("--watcher-port", process.env.WATCHER_PORT);
+  console.error(`\u2192 extension quick relaunch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`);
+  const result = await spawnScriptStreaming(liveScript, liveArgs, target);
+  if (result.output) {
+    try {
+      fs.appendFileSync(rebuildLog, result.output);
+    } catch {
+    }
+  }
+  return result;
+}
+function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state) {
+  if (adapter === "extension" && displayMode === "sidepanel") {
+    const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
+    const sidepanelArgs = ["open"];
+    if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, json);
+    if (sidepanel.status !== 0) {
+      return launchFail(json, adapter, mobileTarget, tier, state, {
+        code: "SIDEPANEL_OPEN_FAILED",
+        message: "app launched but opening the side panel failed.",
+        recoverable: false,
+        userAction: `bash adapters/extension/sidepanel-toggle.sh open --cdp-port ${process.env.CDP_PORT ?? "<CDP_PORT>"}`,
+        exitCode: EXIT.runtime,
+        originalError: sidepanel.output.trim() || void 0
+      });
+    }
+  }
+  return launchPass(json, adapter, mobileTarget, tier, displayMode, state);
+}
+function launchPass(json, adapter, mobileTarget, tier, displayMode, state) {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "launch",
+          adapter,
+          platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
+          tier,
+          status: "pass",
+          phase: "launch",
+          recovered: state.recovered,
+          mutations: state.mutations,
+          exitCode: EXIT.ok
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    const device = adapter === "mobile" ? process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || "booted device" : displayMode;
+    const tierNote = tier === "quick" ? "quick relaunch, no native build" : tier;
+    const devNote = process.env.MM_HARNESS_BIN ? ` ${color("dim", "[dev: MM_HARNESS_BIN]")}` : "";
+    console.error(
+      `${color("ok", "\u2713")} launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} \u2014 ${color("ok", String(device))} \xB7 ${tierNote} \xB7 app + bridge ready${devNote}`
+    );
+  }
+  return EXIT.ok;
+}
+function launchFail(json, adapter, mobileTarget, tier, state, failure) {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "launch",
+          adapter,
+          platform: mobileTarget ?? null,
+          tier,
+          status: "fail",
+          phase: state.attemptedRecoveries.length ? "recover" : "launch",
+          recovered: state.recovered,
+          mutations: state.mutations,
+          recoverable: failure.recoverable,
+          attemptedRecoveries: state.attemptedRecoveries,
+          exitCode: failure.exitCode,
+          error: {
+            code: failure.code,
+            message: failure.message,
+            retryable: failure.recoverable,
+            userAction: failure.userAction ?? null,
+            // The classification note is in `message`; the REAL failure text lives
+            // here verbatim so it is never lost.
+            originalError: failure.originalError ?? null
+          }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(
+      `\u2717 launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed
+  ${failure.message}` + (failure.originalError ? `
+  --- original failure ---
+${failure.originalError}` : "") + (failure.userAction ? `
+  Next: ${failure.userAction}` : "")
+    );
+  }
+  return failure.exitCode;
+}
+export {
+  handleLaunch
+};

package/dist/commands/logs.js

@@ -0,0 +1,73 @@
+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, spawnScript, str, targetOf, usageOut } from "./shared.js";
+const LOGS_BOOLEANS = /* @__PURE__ */ new Set(["full", "json"]);
+async function handleLogs(argv) {
+  const { options } = parseFlags(argv, LOGS_BOOLEANS);
+  const json = flag(options, "json");
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+  if (!adapter) {
+    return usageOut(json, "logs", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  const surface = getAdapterSurface(adapter);
+  if (surface.headless) {
+    return usageOut(json, "logs", "core is headless; it has no dev server logs.", surface.hints.launch);
+  }
+  const logSources = surface.logSources(target);
+  const sourceLabels = logSources.map((entry) => entry.label);
+  const defaultSource = sourceLabels[0];
+  const source = str(options, "source") ?? defaultSource;
+  const validSources = [...sourceLabels, "app"];
+  if (!validSources.includes(source)) {
+    return usageOut(json, "logs", `--source must be one of: ${validSources.join(", ")}.`, `mm-harness logs --source ${defaultSource}`);
+  }
+  const events = str(options, "events");
+  if (events !== void 0) {
+    if (!/^\d+$/u.test(events)) {
+      return usageOut(json, "logs", `--events must be numeric (got: ${events}).`, "mm-harness logs --events 20");
+    }
+    process.env.RECIPE_LOG_EVENTS = events;
+  }
+  const requested = logSources.find((entry) => entry.label === source);
+  const ordered = requested ? [requested, ...logSources.filter((entry) => entry !== requested)] : logSources;
+  const logFile = ordered.find((entry) => fs.existsSync(entry.path))?.path;
+  if (!logFile) {
+    const names = logSources.map((entry) => path.basename(entry.path)).join(" / ");
+    return usageOut(
+      json,
+      "logs",
+      `nothing running for this checkout (no ${names}).`,
+      surface.hints.launch
+    );
+  }
+  const full = flag(options, "full");
+  if (full) {
+    const result2 = spawnScript("tail", ["-n", "+1", "-F", logFile], target, json);
+    return result2.status === 0 ? EXIT.ok : EXIT.runtime;
+  }
+  const logTui = path.join(runnerDir, "adapters/shared/log-tui.mjs");
+  const eventCount = process.env.RECIPE_LOG_EVENTS ?? "20";
+  const uiMode = process.env.RECIPE_LOG_UI_MODE ?? "compact";
+  const result = spawnScript(
+    process.execPath,
+    [logTui, "tail", "--log", logFile, "--events", eventCount, "--follow", "--mode", uiMode],
+    target,
+    json
+  );
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: "logs", adapter, source, logFile, exitCode: result.status === 0 ? EXIT.ok : EXIT.runtime },
+        null,
+        2
+      )
+    );
+  }
+  return result.status === 0 ? EXIT.ok : EXIT.runtime;
+}
+export {
+  handleLogs
+};