@deeeed/metamask-harness 0.2.0 → 0.3.1

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,
@@ -57,7 +57,7 @@ import type {
   RecipeValidationResult,
 } from '@farmslot/protocol';
 import type { MetaMaskRecipeAdapter } from './types.ts';
-import { usageOut } from './commands/shared.ts';
+import { ADAPTER_DETECT_NEXT, usageOut } from './commands/shared.ts';
 
 type CliOptionValue = string | boolean;
 type CliOptions = Record<string, CliOptionValue>;
@@ -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 {
@@ -455,11 +455,7 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
   const explicitAdapter = optionString(options, 'adapter') ?? optionString(options, 'platform');
   const adapter = explicitAdapter ?? detectAdapter(target);
   if (!adapter) {
-    return usageOut(
-      json,
-      'doctor',
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --adapter mobile|extension|core`,
-    );
+    return usageOut(json, 'doctor', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
   const actionManifestPath = actionManifestPathOption(options, adapter);
@@ -596,7 +592,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 +641,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 +706,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 +824,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
@@ -853,9 +849,7 @@ function resolveAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter;
   const explicit = optionString(options, 'adapter') ?? optionString(options, 'platform');
   const adapter = explicit ?? detectAdapter(target);
   if (!adapter) {
-    throw usageError(
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --adapter mobile|extension|core`,
-    );
+    throw usageError(`could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`);
   }
   try {
     assertAdapter(adapter);
@@ -867,20 +861,24 @@ function resolveAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter;
 
 // Adapter-aware recipe validation: schema (validateRecipeDocument) + action
 // existence/platform against the adapter's manifest (validateRecipeWithManifest).
-// This is the "run validates first" contract, shared by `run --plan` and `call`.
-//
-// NOTE (pinned deps): recipes that reference library flows by `call.ref` need
-// `externalFlowIds` sourced from resolveRecipeLibrarySources, which lands with
-// @farmslot/recipe-harness >= 0.3.3 (pending publish). Until then, self-contained
-// recipes (all in-repo recipes + every one-node `call` recipe) validate fully;
-// library-ref recipes would surface their refs here. Extends when 0.3.3 lands.
+// When librarySources are provided (resolved from --library / personal / team
+// tiers), external flow IDs from those sources are declared so `call.ref` nodes
+// targeting library-defined flows pass schema validation.
 async function validateRecipeAdapterAware(
   recipe: unknown,
   manifest: RecipeActionManifestDocument,
+  librarySources?: MetaMaskLibrarySource[],
 ): Promise<RecipeValidationResult> {
   const { validateRecipeDocument, validateRecipeWithManifest } = await importRecipeProtocol();
-  const schema = validateRecipeDocument(recipe);
-  const withManifest = validateRecipeWithManifest(recipe, manifest);
+  let externalFlowIds: ReadonlySet<string> | undefined;
+  if (librarySources && librarySources.length > 0) {
+    const harness = await importRecipeHarness();
+    const resolution = await harness.loadRecipeLibraries(librarySources);
+    externalFlowIds = new Set(resolution.flows.keys());
+  }
+  const validationOptions = externalFlowIds !== undefined ? { externalFlowIds } : undefined;
+  const schema = validateRecipeDocument(recipe, validationOptions);
+  const withManifest = validateRecipeWithManifest(recipe, manifest, validationOptions);
   const findings = [...schema.findings, ...withManifest.findings];
   const errors = findings.filter((finding) => finding.severity === 'error').length;
   const warnings = findings.length - errors;
@@ -905,9 +903,10 @@ function countRecipeNodes(recipe: unknown): number | undefined {
 // Static, adapter-aware recipe validation shared by `run --plan` and the `run`
 // execute path so both "validate first" the same way: read the file (missing /
 // unparseable → usage error, nothing to validate), check the manifest, then run
-// the adapter-aware schema + action-existence validation. Touches nothing and
-// resolves no libraries, so it never emits the engine's "Recipe libraries: …"
-// log — safe to call before the machine-contract JSON is written.
+// the adapter-aware schema + action-existence validation. Loads library flow IDs
+// from --library (so `call.ref` nodes to external flows resolve correctly), but
+// never emits the engine's "Recipe libraries: …" log — safe to call before the
+// machine-contract JSON is written.
 interface RunRecipeStaticValidation {
   recipe: unknown;
   recipeFile: string;
@@ -958,8 +957,10 @@ async function validateRunRecipeStatic(
   }
 
   // validate.schema + validate.actions (static) — adapter-aware recipe validation.
+  // Library sources are resolved here so external `call.ref` flows validate correctly.
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, 'library'));
   const validation = manifestOk
-    ? await validateRecipeAdapterAware(recipe, manifest)
+    ? await validateRecipeAdapterAware(recipe, manifest, librarySources)
     : { status: 'invalid' as const, findings: [], summary: { errors: 1, warnings: 0 } };
   findings.push(...validation.findings);
 
@@ -1184,7 +1185,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 +1287,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 +1521,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 +1620,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 +1647,7 @@ function emitHealViolation(
             code: violation.code,
             message: violation.message,
             retryable: false,
-            userAction: violation.userAction ?? null,
+            userAction: userAction ?? null,
             originalError: violation.originalError ?? null,
           },
         },
@@ -1651,7 +1659,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 +1800,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 +1811,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,63 @@
+// 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 { ADAPTER_DETECT_NEXT, 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}`, ADAPTER_DETECT_NEXT);
+  if (adapter === 'core') return usageOut(json, 'debug', 'core is headless; there is no debug console.', 'mm-harness verify');
+
+  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: 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;
+}