@deeeed/metamask-harness 0.2.0 → 0.3.0

package/{runner/src → src}/adapters.ts

@@ -2,8 +2,8 @@ import http from 'node:http';
 import path from 'node:path';
 import { compatibilityMode, fixtureSummary, repoShape } from './doctor.ts';
 import { runLiveAdapterScript } from './live-adapter-contract.ts';
-import { withExtensionPage } from '../../library/actions/extension/platform/cdp.mjs';
-import { bridgeCommand, evalSync, simulatorScreenshot } from '../../library/actions/mobile/platform/bridge.mjs';
+import { withExtensionPage } from '../library/actions/extension/platform/cdp.mjs';
+import { bridgeCommand, evalSync, simulatorScreenshot } from '../library/actions/mobile/platform/bridge.mjs';
 import type {
   ActionAdapter,
   ActionExecutionContext,
@@ -284,7 +284,7 @@ function mobileProbeOutput(status: unknown, input: MetaMaskUiActionInput, projec
 }
 
 function mobileBridgePath(_projectRoot: string): string {
-  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || 'runner:library/actions/mobile/bridge-runtime/cdp-bridge.cjs';
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || 'runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs';
 }
 
 async function waitForMobileTarget(input: ReturnType<typeof uiInputFor>, payload: ActionNode) {

package/{orchestration/lib/cli-color.mjs → src/cli-color.ts}

@@ -1,11 +1,14 @@
-#!/usr/bin/env node
 /**
- * cli-color.mjs — shared ANSI styling for recipe CLI human output.
+ * cli-color.ts — shared ANSI styling for recipe CLI human output.
  *
  * Honors NO_COLOR, RECIPE_NO_COLOR, FORCE_COLOR, RECIPE_COLOR, and TTY detection.
  */
 
-const STYLES = {
+type StyleName =
+  | 'reset' | 'bold' | 'dim' | 'label' | 'cmd' | 'ok' | 'warn'
+  | 'err' | 'info' | 'accent' | 'path' | 'comment' | 'active';
+
+const STYLES: Record<StyleName, string> = {
   reset: '\x1b[0m',
   bold: '\x1b[1m',
   dim: '\x1b[2m',
@@ -21,32 +24,37 @@ const STYLES = {
   active: '\x1b[1m',
 };
 
-export function colorEnabled(stream = process.stderr) {
+export function colorEnabled(stream: NodeJS.WriteStream = process.stderr): boolean {
   if (process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0') {
     return false;
   }
   if (process.env.RECIPE_NO_COLOR === '1') return false;
   if (process.env.RECIPE_COLOR === '1' || process.env.FORCE_COLOR === '1') return true;
-  return Boolean(stream?.isTTY);
+  return Boolean((stream as NodeJS.WriteStream & { isTTY?: boolean })?.isTTY);
 }
 
-export function stripAnsi(text) {
+export function stripAnsi(text: string): string {
   return String(text).replace(/\x1b\[[0-9;]*m/gu, '');
 }
 
-export function color(style, text, { stream = process.stderr } = {}) {
+export function color(style: string, text: string, { stream = process.stderr }: { stream?: NodeJS.WriteStream } = {}): string {
   const value = String(text);
   if (!colorEnabled(stream)) return value;
-  const code = STYLES[style];
+  const code = STYLES[style as StyleName];
   if (!code) return value;
   return `${code}${value}${STYLES.reset}`;
 }
 
-export function colorKv(label, value, valueStyle = 'info', { stream = process.stderr } = {}) {
+export function colorKv(
+  label: string,
+  value: string,
+  valueStyle = 'info',
+  { stream = process.stderr }: { stream?: NodeJS.WriteStream } = {},
+): string {
   return `${color('label', `${label}:`, { stream })} ${color(valueStyle, value, { stream })}`;
 }
 
-export function colorStatusWord(word, { stream = process.stderr } = {}) {
+export function colorStatusWord(word: string, { stream = process.stderr }: { stream?: NodeJS.WriteStream } = {}): string {
   const normalized = String(word || '').toLowerCase();
   if (['up', 'ready', 'yes', 'pass', 'running', 'present', 'healthy'].includes(normalized)) {
     return color('ok', word, { stream });
@@ -60,7 +68,7 @@ export function colorStatusWord(word, { stream = process.stderr } = {}) {
   return color('info', word, { stream });
 }
 
-export function classifyLogEvent(event) {
+export function classifyLogEvent(event: string): string {
   const text = String(event || '');
   if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
     return 'err';
@@ -77,8 +85,8 @@ export function classifyLogEvent(event) {
   return 'info';
 }
 
-export function colorLogEvent(event, { latest = false, stream = process.stderr } = {}) {
+export function colorLogEvent(event: string, { latest = false, stream = process.stderr }: { latest?: boolean; stream?: NodeJS.WriteStream } = {}): string {
   const style = classifyLogEvent(event);
   const painted = color(style === 'label' ? 'label' : style, event, { stream });
   return latest ? color('active', painted, { stream }) : painted;
-}
+}

package/{orchestration/lib/cli-commands.mjs → src/cli-commands.ts}

@@ -1,15 +1,26 @@
-#!/usr/bin/env node
 /**
- * cli-commands.mjs — single source of truth for recipe CLI tab completion.
+ * cli-commands.ts — single source of truth for recipe CLI tab completion.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-/** @typedef {{ name: string, aliases?: string[], desc?: string, flags?: string[], args?: string[] }} CommandSpec */
+interface CommandSpec {
+  name: string;
+  aliases?: string[];
+  desc?: string;
+  flags?: string[];
+  args?: string[];
+}
+
+interface CommandSpecMap {
+  shared: CommandSpec[];
+  extension: CommandSpec[];
+  mobile: CommandSpec[];
+  shim: CommandSpec[];
+}
 
-/** @type {{ shared: CommandSpec[], extension: CommandSpec[], mobile: CommandSpec[], shim: CommandSpec[] }} */
-export const SPEC = {
+export const SPEC: CommandSpecMap = {
   shim: [
     { name: 'sync', desc: 'Copy fixture, write slot context, install harness', flags: ['--dry-run', '--no-install'] },
     { name: 'help', aliases: ['-h', '--help'], desc: 'Show usage' },
@@ -34,9 +45,7 @@ export const SPEC = {
     { name: 'ready', aliases: ['ensure-ready'], desc: 'Ensure one healthy extension home tab' },
     { name: 'watch', aliases: ['start-watch', 'watcher'], desc: 'Start/reuse webpack watcher', flags: ['--full', '-f'] },
     { name: 'stop', aliases: ['stop-watch', 'stop-watcher'], desc: 'Stop this checkout watcher' },
-    { name: 'rebuild', aliases: ['reset', 'reopen', 'reload', 'browser', 'launch', 'full-launch', 'runtime-launch'], desc: 'Clean webpack + browser launch', flags: ['--json', '--dry-run', '--full'] },
-    { name: 'refresh', aliases: ['build'], desc: 'Fast refresh with active watcher' },
-    { name: 'refresh:once', aliases: ['refresh-once', 'build:once', 'build-once'], desc: 'One-shot refresh-build helper' },
+    { name: 'rebuild', aliases: ['reset', 'reopen', 'reload', 'browser', 'launch', 'full-launch', 'runtime-launch', 'build', 'build:once', 'build-once', 'refresh-once'], desc: 'Clean webpack + browser launch', flags: ['--json', '--dry-run', '--full'] },
     { name: 'sidepanel', desc: 'Side panel helper', args: ['cycle', 'open', 'close', 'toggle', 'status'] },
     { name: 'prepare', flags: ['--target', '--cdp-port', '--runtime-dir', '--validate'] },
     { name: 'debug', args: ['page', 'worker'], flags: ['--json', '--no-open'] },
@@ -46,7 +55,6 @@ export const SPEC = {
     { name: 'android', desc: 'Start Metro + launch Android dev client' },
     { name: 'setup:ios', desc: 'iOS launch + wallet fixture setup' },
     { name: 'setup:android', desc: 'Android launch + wallet fixture setup' },
-    { name: 'refresh', aliases: ['reload', 'relaunch'], desc: 'Refresh Metro + relaunch dev client' },
     { name: 'stop', desc: 'Stop Metro for this slot' },
     { name: 'app-status', aliases: ['bridge-status'], desc: 'Bridge/runtime status' },
     { name: 'route', aliases: ['get-route'], desc: 'Current navigation route' },
@@ -65,9 +73,9 @@ export const SPEC = {
 
 const GLOBAL_FLAGS = ['--json', '--dry-run', '--full', '-f', '--help', '-h', '--no-open', '--no-color'];
 
-function mergeCommands(adapter) {
-  const byName = new Map();
-  const add = (cmd) => {
+function mergeCommands(adapter: string): CommandSpec[] {
+  const byName = new Map<string, CommandSpec & { aliases: string[]; flags: string[]; args: string[] }>();
+  const add = (cmd: CommandSpec) => {
     const existing = byName.get(cmd.name);
     if (!existing) {
       byName.set(cmd.name, {
@@ -84,12 +92,12 @@ function mergeCommands(adapter) {
     if (!existing.desc && cmd.desc) existing.desc = cmd.desc;
   };
   for (const cmd of SPEC.shared) add(cmd);
-  for (const cmd of SPEC[adapter] || []) add(cmd);
+  for (const cmd of SPEC[adapter as keyof CommandSpecMap] || []) add(cmd);
   return [...byName.values()];
 }
 
-export function commandTokens(adapter, { includeAliases = true } = {}) {
-  const tokens = new Set();
+export function commandTokens(adapter: string, { includeAliases = true }: { includeAliases?: boolean } = {}): string[] {
+  const tokens = new Set<string>();
   for (const cmd of mergeCommands(adapter)) {
     tokens.add(cmd.name);
     if (includeAliases) for (const alias of cmd.aliases || []) tokens.add(alias);
@@ -97,8 +105,8 @@ export function commandTokens(adapter, { includeAliases = true } = {}) {
   return [...tokens].sort();
 }
 
-export function shimCommandTokens() {
-  const tokens = new Set();
+export function shimCommandTokens(): string[] {
+  const tokens = new Set<string>();
   for (const cmd of SPEC.shim) {
     tokens.add(cmd.name);
     for (const alias of cmd.aliases || []) tokens.add(alias);
@@ -106,7 +114,7 @@ export function shimCommandTokens() {
   return [...tokens].sort();
 }
 
-export function lookupCommand(adapter, token) {
+export function lookupCommand(adapter: string, token: string): CommandSpec | null {
   for (const cmd of mergeCommands(adapter)) {
     if (cmd.name === token) return cmd;
     if ((cmd.aliases || []).includes(token)) return cmd;
@@ -118,28 +126,27 @@ export function lookupCommand(adapter, token) {
   return null;
 }
 
-export function flagsForPosition(adapter, commandToken) {
+export function flagsForPosition(adapter: string, commandToken: string): string[] {
   const cmd = lookupCommand(adapter, commandToken);
   const flags = new Set(GLOBAL_FLAGS);
   if (cmd) for (const flag of cmd.flags || []) flags.add(flag);
   return [...flags].sort();
 }
 
-export function argsForPosition(adapter, commandToken, argIndex) {
+export function argsForPosition(adapter: string, commandToken: string, argIndex: number): string[] {
   const cmd = lookupCommand(adapter, commandToken);
   if (!cmd?.args?.length) return [];
   const value = cmd.args[Math.max(0, argIndex)];
   return value ? [value] : cmd.args;
 }
 
-const RUN_RECIPE_DIRS = [
+const RUN_RECIPE_DIRS: ((adapter: string, root: string) => string)[] = [
   (adapter, root) => path.join(root, 'temp/recipe/harness', adapter, 'runner/recipes'),
   (adapter, root) => path.join(root, 'temp/agentic/recipe-harness', adapter, 'runner/recipes'),
 ];
 
-/** Harness runner recipes only — used for `recipe run <tab>`. */
-export function listRunRecipes(adapter, root, cwd = process.cwd()) {
-  const byBase = new Map();
+export function listRunRecipes(adapter: string, root: string, cwd = process.cwd()): string[] {
+  const byBase = new Map<string, string>();
   for (const resolveDir of RUN_RECIPE_DIRS) {
     const dir = resolveDir(adapter, root);
     if (!fs.existsSync(dir)) continue;
@@ -153,20 +160,20 @@ export function listRunRecipes(adapter, root, cwd = process.cwd()) {
     .sort();
 }
 
-function usage() {
+function usage(): void {
   process.stderr.write(`Usage:
-  cli-commands.mjs dump --adapter extension|mobile|shim [--aliases]
-  cli-commands.mjs describe --adapter extension|mobile|shim
-  cli-commands.mjs flags --adapter <adapter> --command <name>
-  cli-commands.mjs args --adapter <adapter> --command <name> [--index <n>]
-  cli-commands.mjs run-recipes --adapter extension|mobile --root <repo> [--cwd <dir>]
-  cli-commands.mjs global-flags
+  cli-commands dump --adapter extension|mobile|shim [--aliases]
+  cli-commands describe --adapter extension|mobile|shim
+  cli-commands flags --adapter <adapter> --command <name>
+  cli-commands args --adapter <adapter> --command <name> [--index <n>]
+  cli-commands run-recipes --adapter extension|mobile --root <repo> [--cwd <dir>]
+  cli-commands global-flags
 `);
 }
 
-async function main() {
-  const { parseArgs } = await import('node:util');
-  const { values, positionals } = parseArgs({
+async function main(): Promise<void> {
+  const { parseArgs: parseArgsUtil } = await import('node:util');
+  const { values, positionals } = parseArgsUtil({
     allowPositionals: true,
     args: process.argv.slice(2),
     options: {
@@ -197,12 +204,12 @@ async function main() {
   }
 
   if (command === 'dump') {
-    process.stdout.write(`${commandTokens(adapter, { includeAliases: values.aliases }).join('\n')}\n`);
+    process.stdout.write(`${commandTokens(adapter as string, { includeAliases: values.aliases }).join('\n')}\n`);
     return;
   }
 
   if (command === 'describe') {
-    const rows = adapter === 'shim' ? SPEC.shim : mergeCommands(adapter);
+    const rows = adapter === 'shim' ? SPEC.shim : mergeCommands(adapter as string);
     for (const cmd of rows) {
       const aliases = (cmd.aliases || []).join('|');
       const label = aliases ? `${cmd.name}|${aliases}` : cmd.name;
@@ -212,20 +219,20 @@ async function main() {
   }
 
   if (command === 'flags') {
-    process.stdout.write(`${flagsForPosition(adapter, values.command || '').join('\n')}\n`);
+    process.stdout.write(`${flagsForPosition(adapter as string, values.command || '').join('\n')}\n`);
     return;
   }
 
   if (command === 'args') {
-    const index = Number.parseInt(values.index, 10) || 0;
-    process.stdout.write(`${argsForPosition(adapter, values.command || '', index).join('\n')}\n`);
+    const index = Number.parseInt(values.index as string, 10) || 0;
+    process.stdout.write(`${argsForPosition(adapter as string, values.command || '', index).join('\n')}\n`);
     return;
   }
 
   if (command === 'run-recipes') {
     const root = values.root ? path.resolve(values.root) : process.cwd();
     const cwd = values.cwd ? path.resolve(values.cwd) : process.cwd();
-    process.stdout.write(`${listRunRecipes(adapter, root, cwd).join('\n')}\n`);
+    process.stdout.write(`${listRunRecipes(adapter as string, root, cwd).join('\n')}\n`);
     return;
   }
 
@@ -233,11 +240,11 @@ async function main() {
   process.exit(2);
 }
 
-const entry = process.argv[1] ? path.resolve(process.argv[1]) : '';
-const self = fileURLToPath(import.meta.url);
-if (entry === self) {
-  main().catch((error) => {
+const _filename = fileURLToPath(import.meta.url);
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === _filename;
+if (isMain) {
+  main().catch((error: unknown) => {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     process.exit(1);
   });
-}
+}

package/{orchestration/lib/cli-version.mjs → src/cli-version.ts}

@@ -1,13 +1,12 @@
-#!/usr/bin/env node
 /**
- * cli-version.mjs — detect stale installed harness scripts vs the active runner.
+ * cli-version.ts — detect stale installed harness scripts vs the active runner.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
 
-function readJson(file) {
+function readJson(file: string): unknown {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch {
@@ -15,31 +14,49 @@ function readJson(file) {
   }
 }
 
-function readPackageVersion(dir) {
+function readPackageVersion(dir: string): string {
   try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')) as { version?: string };
     return pkg.version || 'unknown';
   } catch {
     return 'unknown';
   }
 }
 
-function gitHead(dir) {
+function gitHead(dir: string): string {
   const result = spawnSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
   return result.status === 0 ? result.stdout.trim() : 'unknown';
 }
 
-export function checkHarness({ runnerRoot, manifestPath, installedShaPath }) {
+interface HarnessCheckInput {
+  runnerRoot: string;
+  manifestPath: string;
+  installedShaPath?: string;
+}
+
+interface HarnessCheckResult {
+  stale: boolean;
+  reasons: string[];
+  installedRevision?: string | null;
+  currentRevision?: string;
+  installedVersion?: string | null;
+  currentVersion?: string;
+  manifest?: string;
+}
+
+export function checkHarness({ runnerRoot, manifestPath }: HarnessCheckInput): HarnessCheckResult {
   const manifest = readJson(manifestPath);
-  const reasons = [];
+  const reasons: string[] = [];
   if (!manifest) {
     return { stale: false, reasons: ['no harness manifest'] };
   }
 
   const currentRevision = gitHead(runnerRoot);
   const currentVersion = readPackageVersion(runnerRoot);
-  const installedRevision = manifest.source?.runnerRevision || null;
-  const installedVersion = manifest.runnerPackageVersion || null;
+  const manifestRecord = manifest as Record<string, unknown>;
+  const source = manifestRecord.source as Record<string, unknown> | undefined;
+  const installedRevision = (source?.runnerRevision as string) || null;
+  const installedVersion = (manifestRecord.runnerPackageVersion as string) || null;
 
   if (installedRevision && installedRevision !== 'unknown' && installedRevision !== currentRevision) {
     reasons.push(`runner revision ${installedRevision.slice(0, 8)} != ${currentRevision.slice(0, 8)}`);
@@ -58,12 +75,12 @@ export function checkHarness({ runnerRoot, manifestPath, installedShaPath }) {
   };
 }
 
-function usage() {
+function usage(): void {
   console.error(`Usage:
-  cli-version.mjs check --runner-root <dir> --manifest <path> [--installed-sha <path>] [--json]`);
+  cli-version check --runner-root <dir> --manifest <path> [--installed-sha <path>] [--json]`);
 }
 
-async function main() {
+async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
   const { values } = parseArgs({
     args: rest,
@@ -93,7 +110,7 @@ async function main() {
     process.exit(2);
   }
 
-  const payload = {
+  const payload: HarnessCheckResult & { manifest: string } = {
     ...checkHarness({
       runnerRoot,
       manifestPath,
@@ -115,9 +132,10 @@ async function main() {
   process.stdout.write('harness up to date\n');
 }
 
-if (import.meta.url === new URL(process.argv[1], 'file:').href) {
-  main().catch((error) => {
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename ?? '');
+if (isMain) {
+  main().catch((error: unknown) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   });
-}
+}

package/{runner/src → src}/cli.ts

@@ -23,10 +23,10 @@ import {
   checkHealBounds,
 } from './heal-bounds.ts';
 import type { HealPolicy, HealState, HealBoundViolation } from './heal-bounds.ts';
-import { ensureExtensionReady } from '../../orchestration/extension/ensure-ready.ts';
-import { resolveExtensionId } from '../../orchestration/extension/extension-id.ts';
-import { decideExtensionReadiness } from '../../orchestration/extension/runtime-decision.ts';
-import { decideMobileReadiness } from '../../orchestration/mobile/runtime-decision.ts';
+import { ensureExtensionReady } from './adapters/extension/ensure-ready.ts';
+import { resolveExtensionId } from './adapters/extension/extension-id.ts';
+import { decideExtensionReadiness } from './adapters/extension/runtime-decision.ts';
+import { decideMobileReadiness } from './adapters/mobile/runtime-decision.ts';
 // NOTE: extension-runtime.ts loads the recipe harness at module scope, so it
 // is imported LAZILY (dynamic import) only inside the handlers that drive a live
 // runtime. Static-import it here and every command — manifest, doctor,
@@ -372,7 +372,7 @@ async function prepareRuntimeIfNeeded(
   runtimeOptions: RuntimeOptions,
 ): Promise<void> {
   if (adapter !== 'extension' || runtimeOptions.skipExtensionRuntimePrepare === true) return;
-  const { prepareExtensionRuntime } = await import('../../orchestration/extension/runtime.ts');
+  const { prepareExtensionRuntime } = await import('./adapters/extension/runtime.ts');
   await prepareExtensionRuntime({
     projectRoot,
     cdpPort: runtimeOptions.cdpPort,
@@ -390,7 +390,7 @@ function restoreEnv(key: string, value: string | undefined) {
 async function runSelfTest(options: CliOptions) {
   const root = optionString(options, 'artifactsDir')
     ? path.resolve(requiredOption(options, 'artifactsDir', 'self-test artifacts dir missing.'))
-    : await mkdtemp(path.join(os.tmpdir(), 'metamask-recipe-runner-'));
+    : await mkdtemp(path.join(os.tmpdir(), 'mm-harness-runner-'));
   const previousAutoHud = process.env.METAMASK_RECIPE_AUTO_HUD;
   const runs = [];
   try {
@@ -596,7 +596,7 @@ async function handleRuntimeHealth({ options }: ParsedArgs): Promise<number> {
     optionString(options, 'cdpPort') ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
     'runtime-health requires --cdp-port <port>.',
   );
-  const { checkExtensionRuntimeHealth, formatHealthFailure } = await import('../../orchestration/extension/runtime.ts');
+  const { checkExtensionRuntimeHealth, formatHealthFailure } = await import('./adapters/extension/runtime.ts');
   const report = await checkExtensionRuntimeHealth(target, cdpPort);
   if (optionFlag(options, 'json')) console.log(JSON.stringify(report, null, 2));
   else if (report.status === 'PASS') console.log(`PASS extension runtime cdp=${cdpPort} target=${report.targetUrl}`);
@@ -645,7 +645,7 @@ async function handleRuntimeLaunch({ options }: ParsedArgs): Promise<number> {
       cdpPort,
       artifactsDir,
       reason: 'harness_live_script_missing',
-      fix: `Run metamask-recipe extension prepare --target ${shellQuote(target)}, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir)}`,
+      fix: `Run mm-harness install --adapter extension --target ${shellQuote(target)}, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir)}`,
       command,
     });
     printRuntimeLaunchReport(report, optionFlag(options, 'json'));
@@ -710,7 +710,7 @@ async function handleRuntimeLaunch({ options }: ParsedArgs): Promise<number> {
 }
 
 function runtimeLaunchCommand(target: string, cdpPort: number, chromeUserDataDir?: string, startWatch = false): string {
-  const base = `metamask-recipe runtime-launch --adapter extension --target ${shellQuote(target)} --cdp-port ${cdpPort}`;
+  const base = `mm-harness runtime-launch --adapter extension --target ${shellQuote(target)} --cdp-port ${cdpPort}`;
   const withMode = startWatch ? `${base} --start-watch` : base;
   return chromeUserDataDir ? `${withMode} --chrome-user-data-dir ${shellQuote(chromeUserDataDir)}` : withMode;
 }
@@ -828,7 +828,7 @@ async function handleEnsureReady({ options }: ParsedArgs): Promise<number> {
 //   5 validation failure (run, run --plan, call — adapter-aware validation errors).
 const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 } as const;
 
-// Typed exit-code error: carries exitCode so both the global catch (metamask-recipe bin)
+// Typed exit-code error: carries exitCode so both the global catch (mm-harness bin)
 // and the mm-harness delegate() wrapper classify the error correctly rather than always
 // returning 1.  Usage errors (bad args / unsupported flags) carry EXIT.usage (2);
 // validation errors carry EXIT.validation (5).  Never throw a plain new Error() for
@@ -1184,7 +1184,7 @@ async function handleCall(argv: string[]): Promise<number> {
     heal,
     state,
   );
-  if (violation !== null) return emitHealViolation(json, 'call', result, violation, state);
+  if (violation !== null) return emitHealViolation(json, 'call', result, violation, state, adapter);
 
   if (json) {
     console.log(
@@ -1286,7 +1286,7 @@ function synthesizeOneNodeRecipe(action: string, args: Record<string, string>):
 
 // Reusable one-node engine path (the same machinery `call` uses), exposed so
 // `fixtures set` can apply the canonical wallet fixture through the real engine on
-// the extension (which has no standalone porcelain set arm).
+// the extension (which has no standalone shell set arm).
 async function runOneNode(
   adapter: MetaMaskRecipeAdapter,
   action: string,
@@ -1520,7 +1520,7 @@ async function handleRun({ positional, options }: ParsedArgs): Promise<number> {
     heal,
     state,
   );
-  if (violation !== null) return emitHealViolation(json, 'run', result, violation, state);
+  if (violation !== null) return emitHealViolation(json, 'run', result, violation, state, adapter);
   const exitCode = result.status === 'pass' ? EXIT.ok : EXIT.runtime;
   if (json) {
     // mm-harness envelope (matches launch/verify/doctor): the engine's result is
@@ -1619,7 +1619,14 @@ function emitHealViolation(
   result: RecipeRunResult,
   violation: HealBoundViolation,
   state: HealState,
+  adapter?: MetaMaskRecipeAdapter,
 ): number {
+  // core is headless: `fixtures set` is blocked. Teach the env-var / recipe-node
+  // path instead so the user has a reachable next step.
+  const userAction =
+    adapter === 'core' && violation.code === 'WALLET_STATE_REQUIRED'
+      ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x…> in env, or add "account": "<0x…>" to the node block in the recipe'
+      : violation.userAction;
   if (json) {
     console.log(
       JSON.stringify(
@@ -1639,7 +1646,7 @@ function emitHealViolation(
             code: violation.code,
             message: violation.message,
             retryable: false,
-            userAction: violation.userAction ?? null,
+            userAction: userAction ?? null,
             originalError: violation.originalError ?? null,
           },
         },
@@ -1651,7 +1658,7 @@ function emitHealViolation(
     console.error(
       `✗ mm-harness ${command}: ${violation.message}` +
         (violation.originalError ? `\n  --- original failure ---\n${violation.originalError}` : '') +
-        (violation.userAction ? `\n  Next: ${violation.userAction}` : ''),
+        (userAction ? `\n  Next: ${userAction}` : ''),
     );
   }
   return violation.exitCode;
@@ -1792,7 +1799,7 @@ export async function main(argv: string[]): Promise<number> {
     }
     return code;
   }
-  // launch/logs/debug/fixtures compose the porcelain paths and own policy,
+  // launch/logs/debug/fixtures compose adapter scripts directly and own policy,
   // healing, teaching, and the --json contract.
   if (command === 'launch') return handleLaunch(argv.slice(1));
   if (command === 'logs') return handleLogs(argv.slice(1));
@@ -1803,8 +1810,8 @@ export async function main(argv: string[]): Promise<number> {
   return handler(parseArgs(argv.slice(1), command));
 }
 
-// Auto-run only when this file IS the process entry (orchestration/porcelain/metamask-recipe
-// execs it directly). The commander front (`runner/src/mm-harness-cli.ts`) sets this flag
+// Auto-run only when this file IS the process entry (bin/mm-harness execs it
+// directly). The commander front (`src/mm-harness-cli.ts`) sets this flag
 // before importing so it can reuse `main` without triggering a second dispatch.
 if (!(globalThis as Record<string, unknown>).__MM_HARNESS_WRAPPER__) {
   try {

package/src/commands/debug.ts

@@ -0,0 +1,61 @@
+// debug — open the debug console by composing open-debug.mjs directly:
+// extension `debug` (--worker → service-worker target); mobile `debug`
+// (--dev-menu → developer menu). Cross-platform flag misuse teaches (exit 2).
+
+import path from 'node:path';
+
+import { runnerDir } from '../paths.ts';
+import { EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from './shared.ts';
+
+const DEBUG_BOOLEANS = new Set(['worker', 'devMenu', 'json']);
+
+export async function handleDebug(argv: string[]): Promise<number> {
+  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}`);
+  if (adapter === 'core') return usageOut(json, 'debug', 'core is headless; there is no debug console.');
+
+  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.\n  Next: 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.\n  Next: mm-harness debug --worker',
+    );
+  }
+
+  const openDebug = path.join(runnerDir, 'adapters/shared/open-debug.mjs');
+  const debugArgs: string[] = ['--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;
+}