@deeeed/metamask-harness 0.2.0

package/orchestration/lib/open-debug.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * open-debug.mjs — open human-facing debugger UIs for recipe runtimes.
+ *
+ * Mobile: Metro /open-debugger or /open-dev-menu HTTP endpoints.
+ * Extension: Chrome DevTools frontend for an extension page or service worker.
+ */
+import { spawnSync } from 'node:child_process';
+
+function usage() {
+  console.error(`Usage:
+  open-debug.mjs --adapter mobile [--port <watcher>] [--action debug|dev-menu] [--json] [--no-open]
+  open-debug.mjs --adapter extension [--cdp-port <port>] [--target page|worker] [--json] [--no-open]
+
+Actions (mobile):
+  debug     Open React Native DevTools / Hermes debugger (default)
+  dev-menu  Open the React Native developer menu
+
+Targets (extension):
+  page      Extension UI page, preferring home.html (default)
+  worker    Extension service worker background context`);
+}
+
+function parseArgs(argv) {
+  const args = {
+    adapter: null,
+    port: null,
+    cdpPort: null,
+    action: 'debug',
+    target: 'page',
+    json: false,
+    open: true,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--adapter':
+        args.adapter = argv[++i];
+        break;
+      case '--port':
+        args.port = argv[++i];
+        break;
+      case '--cdp-port':
+        args.cdpPort = argv[++i];
+        break;
+      case '--action':
+        args.action = argv[++i];
+        break;
+      case '--target':
+        args.target = argv[++i];
+        break;
+      case '--json':
+        args.json = true;
+        break;
+      case '--no-open':
+        args.open = false;
+        break;
+      case '-h':
+      case '--help':
+        args.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function emit(result, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (result.ok) {
+    const detail = result.method ? ` via ${result.method}` : '';
+    const where = result.port ? ` (port ${result.port})` : result.cdpPort ? ` (cdp ${result.cdpPort})` : '';
+    console.log(`Opened debugger${detail}${where}`);
+    if (result.target?.url) console.log(`Target: ${result.target.url}`);
+    if (result.configureHint) console.log(`Configure chrome://inspect target: ${result.configureHint}`);
+    return;
+  }
+  console.error(result.error || 'Failed to open debugger');
+  if (result.hint) console.error(result.hint);
+  process.exitCode = 1;
+}
+
+async function fetchOk(url, init) {
+  const response = await fetch(url, init);
+  return response.ok;
+}
+
+async function fetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} for ${url}`);
+  }
+  const body = await response.json();
+  return body;
+}
+
+function openUrl(url) {
+  if (process.platform === 'darwin') {
+    if (url.startsWith('devtools://') || url.startsWith('chrome://')) {
+      const chrome = spawnSync('open', ['-a', 'Google Chrome', url], { stdio: 'ignore' });
+      if (chrome.status === 0) return 'chrome';
+    }
+    spawnSync('open', [url], { stdio: 'ignore' });
+    return 'open';
+  }
+  if (process.platform === 'linux') {
+    spawnSync('xdg-open', [url], { stdio: 'ignore' });
+    return 'xdg-open';
+  }
+  return null;
+}
+
+async function openMobileDebugger(port, action, shouldOpen) {
+  const normalizedAction = action === 'dev-menu' ? 'dev-menu' : 'debug';
+  const path = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
+  const numericPort = Number.parseInt(String(port), 10);
+  if (!Number.isInteger(numericPort) || numericPort <= 0) {
+    return { ok: false, adapter: 'mobile', action: normalizedAction, error: 'invalid-port', port };
+  }
+
+  try {
+    const opened = await fetchOk(`http://127.0.0.1:${numericPort}${path}`, { method: 'POST' });
+    if (opened) {
+      return {
+        ok: true,
+        adapter: 'mobile',
+        action: normalizedAction,
+        method: 'metro-http',
+        port: numericPort,
+        opened: shouldOpen,
+      };
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: normalizedAction,
+      method: 'metro-http',
+      port: numericPort,
+      error: error instanceof Error ? error.message : String(error),
+      hint: 'Metro may be down or the debug target is not ready. Try recipe refresh, then recipe runtime-status.',
+      fallback: 'cdp-eval',
+    };
+  }
+
+  return {
+    ok: false,
+    adapter: 'mobile',
+    action: normalizedAction,
+    method: 'metro-http',
+    port: numericPort,
+    error: 'metro-http-failed',
+    hint: 'Metro rejected the open-debugger request. Try recipe refresh, then recipe runtime-status.',
+    fallback: 'cdp-eval',
+  };
+}
+
+function pickExtensionTarget(targets, targetKind) {
+  const extensionTargets = targets.filter((target) => String(target.url || '').startsWith('chrome-extension://'));
+  if (targetKind === 'worker') {
+    return (
+      extensionTargets.find((target) => target.type === 'service_worker')
+      || targets.find((target) => target.type === 'service_worker' && String(target.url || '').startsWith('chrome-extension://'))
+      || null
+    );
+  }
+
+  const pages = extensionTargets.filter((target) => target.type === 'page');
+  return (
+    pages.find((target) => String(target.url || '').includes('/home.html'))
+    || pages.find((target) => !String(target.url || '').includes('/popup-init.html'))
+    || pages[0]
+    || null
+  );
+}
+
+async function openExtensionDevtools(cdpPort, targetKind, shouldOpen) {
+  const numericPort = Number.parseInt(String(cdpPort), 10);
+  if (!Number.isInteger(numericPort) || numericPort <= 0) {
+    return { ok: false, adapter: 'extension', error: 'invalid-cdp-port', cdpPort };
+  }
+
+  const inspectUrl = 'chrome://inspect/#devices';
+  const configureHint = `127.0.0.1:${numericPort}`;
+
+  try {
+    await fetchJson(`http://127.0.0.1:${numericPort}/json/version`);
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'cdp-unreachable',
+      inspectUrl,
+      configureHint,
+      hint: `Start the extension runtime first (recipe reopen). Then open chrome://inspect and add ${configureHint}.`,
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let targets;
+  try {
+    targets = await fetchJson(`http://127.0.0.1:${numericPort}/json/list`);
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'cdp-list-failed',
+      inspectUrl,
+      configureHint,
+      hint: `CDP is up but /json/list failed. Open chrome://inspect and add ${configureHint}.`,
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  if (!Array.isArray(targets)) {
+    return {
+      ok: false,
+      adapter: 'extension',
+      targetKind,
+      cdpPort: numericPort,
+      error: 'cdp-list-invalid',
+      inspectUrl,
+      configureHint,
+      hint: `Open chrome://inspect and add ${configureHint}.`,
+    };
+  }
+
+  const picked = pickExtensionTarget(targets, targetKind);
+  if (picked?.devtoolsFrontendUrl && shouldOpen) {
+    openUrl(picked.devtoolsFrontendUrl);
+    return {
+      ok: true,
+      adapter: 'extension',
+      targetKind,
+      method: 'devtools-frontend',
+      cdpPort: numericPort,
+      target: {
+        type: picked.type,
+        url: picked.url,
+        title: picked.title || null,
+      },
+      devtoolsUrl: picked.devtoolsFrontendUrl,
+      inspectUrl,
+      configureHint,
+      opened: true,
+    };
+  }
+
+  if (shouldOpen) {
+    openUrl(inspectUrl);
+  }
+
+  return {
+    ok: true,
+    adapter: 'extension',
+    targetKind,
+    method: picked?.devtoolsFrontendUrl ? 'devtools-frontend' : 'chrome-inspect',
+    cdpPort: numericPort,
+    target: picked
+      ? { type: picked.type, url: picked.url, title: picked.title || null }
+      : null,
+    devtoolsUrl: picked?.devtoolsFrontendUrl || null,
+    inspectUrl,
+    configureHint,
+    opened: shouldOpen,
+    hint: picked
+      ? 'Opened chrome://inspect because no devtools frontend URL was available for the selected target.'
+      : `No extension targets are registered yet. Open chrome://inspect and add ${configureHint}.`,
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    process.exit(0);
+  }
+  if (!args.adapter) {
+    usage();
+    process.exit(2);
+  }
+
+  let result;
+  if (args.adapter === 'mobile') {
+    result = await openMobileDebugger(args.port || process.env.WATCHER_PORT || '8081', args.action, args.open);
+  } else if (args.adapter === 'extension') {
+    result = await openExtensionDevtools(
+      args.cdpPort || process.env.CDP_PORT || process.env.RECIPE_CDP_PORT,
+      args.target === 'worker' ? 'worker' : 'page',
+      args.open,
+    );
+  } else {
+    throw new Error(`Unsupported adapter: ${args.adapter}`);
+  }
+
+  emit(result, args.json);
+  if (!result.ok) process.exit(1);
+}
+
+main().catch((error) => {
+  const payload = { ok: false, error: error instanceof Error ? error.message : String(error) };
+  if (process.argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    console.error(payload.error);
+  }
+  process.exit(1);
+});

package/orchestration/lib/path-defaults.json

@@ -0,0 +1,4 @@
+{
+  "recipeHarnessRoot": "temp/recipe/harness",
+  "recipeRuntimeDir": "temp/recipe/runtime"
+}

package/orchestration/lib/progress.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * progress.mjs — structured progress events for long recipe CLI operations.
+ *
+ * Human mode: short lines on stderr.
+ * Machine mode: JSONL on stderr when --json or RECIPE_PROGRESS_JSON=1.
+ */
+import { parseArgs } from 'node:util';
+import { color } from './cli-color.mjs';
+
+function shouldEmitJson(explicit) {
+  if (explicit) return true;
+  const env = process.env.RECIPE_PROGRESS_JSON;
+  return env === '1' || env === 'true';
+}
+
+export function emitProgress(event, { json = false } = {}) {
+  const payload = {
+    schemaVersion: 1,
+    type: 'progress',
+    ts: new Date().toISOString(),
+    ...event,
+  };
+  if (json || shouldEmitJson(false)) {
+    process.stderr.write(`${JSON.stringify(payload)}\n`);
+    return;
+  }
+  const stream = process.stderr;
+  const prefix = color('label', 'recipe', { stream });
+  if (payload.phase === 'done') {
+    const statusStyle = payload.status === 'pass' ? 'ok' : 'err';
+    const statusWord = payload.status === 'pass' ? 'done' : 'failed';
+    const verb = payload.verb ? color('cmd', `${payload.verb}`, { stream }) : '';
+    const elapsed = Number.isFinite(payload.elapsedMs)
+      ? color('comment', ` (${Math.round(payload.elapsedMs / 1000)}s)`, { stream })
+      : '';
+    process.stderr.write(`${prefix}: ${verb} ${color(statusStyle, statusWord, { stream })} ${payload.message || ''}${elapsed}\n`);
+    return;
+  }
+  const verb = payload.verb ? `${color('cmd', payload.verb, { stream })}: ` : '';
+  const phase = payload.phase ? `${color('accent', `[${payload.phase}]`, { stream })} ` : '';
+  const elapsed = Number.isFinite(payload.elapsedMs)
+    ? color('comment', ` (${Math.round(payload.elapsedMs / 1000)}s)`, { stream })
+    : '';
+  process.stderr.write(`${prefix}: ${verb}${phase}${payload.message || ''}${elapsed}\n`);
+}
+
+function usage() {
+  console.error(`Usage:
+  progress.mjs emit --verb <name> --phase <id> --message <text> [--elapsed-ms <n>] [--json]
+  progress.mjs done --verb <name> --status pass|fail --message <text> [--elapsed-ms <n>] [--json]`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h') {
+    usage();
+    process.exit(command ? 0 : 2);
+  }
+
+  const { values } = parseArgs({
+    args: rest,
+    options: {
+      verb: { type: 'string' },
+      phase: { type: 'string' },
+      message: { type: 'string' },
+      status: { type: 'string' },
+      'elapsed-ms': { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  const elapsedMs = values['elapsed-ms'] ? Number.parseInt(values['elapsed-ms'], 10) : undefined;
+  const json = values.json || shouldEmitJson(false);
+
+  if (command === 'emit') {
+    emitProgress({
+      verb: values.verb || 'recipe',
+      phase: values.phase || 'working',
+      message: values.message || '',
+      elapsedMs: Number.isFinite(elapsedMs) ? elapsedMs : undefined,
+    }, { json });
+    return;
+  }
+
+  if (command === 'done') {
+    emitProgress({
+      verb: values.verb || 'recipe',
+      phase: 'done',
+      status: values.status || 'pass',
+      message: values.message || '',
+      elapsedMs: Number.isFinite(elapsedMs) ? elapsedMs : undefined,
+    }, { json });
+    return;
+  }
+
+  usage();
+  process.exit(2);
+}
+
+if (import.meta.url === new URL(process.argv[1], 'file:').href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/orchestration/lib/recipe-paths.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const defaultsPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'path-defaults.json');
+const defaults = JSON.parse(fs.readFileSync(defaultsPath, 'utf8'));
+
+export const DEFAULT_RECIPE_HARNESS_ROOT = defaults.recipeHarnessRoot;
+export const DEFAULT_RECIPE_RUNTIME_DIR = defaults.recipeRuntimeDir;
+
+export function validateRelativeRecipePath(name, value) {
+  if (!value || path.isAbsolute(value)) throw new Error(`${name} must be a non-empty relative path: ${value}`);
+  if (!/^[A-Za-z0-9._/-]+$/u.test(value)) throw new Error(`${name} contains unsupported characters: ${value}`);
+  for (const part of value.split('/')) {
+    if (!part || part === '.' || part === '..') throw new Error(`${name} contains unsafe path component: ${value}`);
+  }
+  return value;
+}
+
+export function recipeHarnessRoot(env = process.env) {
+  return validateRelativeRecipePath('RECIPE_HARNESS_ROOT', env.RECIPE_HARNESS_ROOT || DEFAULT_RECIPE_HARNESS_ROOT);
+}
+
+export function recipeRuntimeDir(env = process.env) {
+  return validateRelativeRecipePath('RECIPE_RUNTIME_DIR', env.RECIPE_RUNTIME_DIR || DEFAULT_RECIPE_RUNTIME_DIR);
+}

package/orchestration/lib/resolve-farmslot-ports.sh

@@ -0,0 +1,144 @@
+# resolve-farmslot-ports.sh — resolve CDP + watcher ports for an extension checkout
+#
+# Farmslot pool JSON is authoritative when a slot repo matches; otherwise fall back
+# to the local-extension-N formula (6660+N / 9010+N).
+#
+# Usage:
+#   . resolve-farmslot-ports.sh
+#   resolve_extension_runtime_ports /path/to/metamask-extension-N
+#     -> prints CDP_PORT=... WATCHER_PORT=... SLOT_ID=... lines
+
+resolve_farmslot_ports_by_repo() {
+  local repo="$1"
+  local farmslot_root="${FARMSLOT_ROOT:-}"
+  [ -n "$repo" ] || return 1
+  repo="$(cd "$repo" && pwd -P)"
+
+  local root candidate match
+  for root in "$farmslot_root" "$HOME/dev/farmslot"; do
+    [ -n "$root" ] && [ -d "$root/pool" ] || continue
+    match="$(POOL_ROOT="$root" REPO_TARGET="$repo" python3 - <<'PY'
+import glob, json, os, re, sys
+
+pool_root = os.environ["POOL_ROOT"]
+repo = os.path.realpath(os.environ["REPO_TARGET"])
+base = os.path.basename(repo)
+slot_suffix = None
+m = re.search(r"-(\d+)$", base)
+if m:
+    slot_suffix = m.group(1)
+
+def score_slot(slot):
+    resources = slot.get("resources") or {}
+    cdp = (resources.get("browser") or {}).get("cdp_port")
+    port = (resources.get("dev-server") or {}).get("port")
+    session = slot.get("session") or ""
+    slot_id = slot.get("id") or ""
+    score = 0
+    if cdp is not None:
+        score += 100
+    if port is not None:
+        score += 10
+    if slot_suffix:
+        if session == f"mme-{slot_suffix}":
+            score += 50
+        if slot_id.endswith(f"mme-{slot_suffix}") or f"-mme-{slot_suffix}" in slot_id:
+            score += 40
+    if "demo" not in slot_id.lower():
+        score += 5
+    return score, cdp, port, slot_id
+
+best = None
+for path in sorted(glob.glob(os.path.join(pool_root, "pool", "*.json"))):
+    if ".bak." in os.path.basename(path):
+        continue
+    try:
+        data = json.load(open(path, encoding="utf-8"))
+    except Exception:
+        continue
+    for slot in data.get("slots") or []:
+        slot_repo = slot.get("repo") or ""
+        if not slot_repo:
+            continue
+        try:
+            if os.path.realpath(slot_repo) != repo:
+                continue
+        except Exception:
+            continue
+        scored = score_slot(slot)
+        if best is None or scored[0] > best[0]:
+            best = scored
+
+if best is None:
+    sys.exit(1)
+
+_, cdp, port, slot_id = best
+if cdp is not None:
+    print(f"CDP_PORT={cdp}")
+if port is not None:
+    print(f"WATCHER_PORT={port}")
+if slot_id:
+    print(f"SLOT_ID={slot_id}")
+sys.exit(0)
+PY
+)" || continue
+    [ -n "$match" ] || continue
+    printf '%s\n' "$match"
+    return 0
+  done
+  return 1
+}
+
+infer_extension_slot_suffix() {
+  local repo="$1" base
+  base="$(basename "$repo")"
+  if [[ "$base" =~ -([0-9]+)$ ]]; then
+    printf '%s' "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+resolve_default_extension_ports() {
+  local repo="$1" n
+  n="$(infer_extension_slot_suffix "$repo" || true)"
+  [ -n "$n" ] || return 1
+  printf 'CDP_PORT=%s\n' "$((6660 + n))"
+  printf 'WATCHER_PORT=%s\n' "$((9010 + n))"
+  printf 'SLOT_ID=local-extension-%s\n' "$n"
+}
+
+resolve_extension_runtime_ports() {
+  local repo="${1:-.}"
+  if resolve_farmslot_ports_by_repo "$repo"; then
+    return 0
+  fi
+  resolve_default_extension_ports "$repo"
+}
+
+apply_resolved_extension_ports() {
+  local repo="${1:-.}" line key val from_pool=false resolved=""
+  if resolved="$(resolve_farmslot_ports_by_repo "$repo" 2>/dev/null)"; then
+    from_pool=true
+  elif resolved="$(resolve_default_extension_ports "$repo" 2>/dev/null)"; then
+    from_pool=false
+  else
+    return 0
+  fi
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    key="${line%%=*}"
+    val="${line#*=}"
+    case "$key" in
+      CDP_PORT)
+        if [ "$from_pool" = true ] || [ -z "${CDP_PORT:-}" ]; then CDP_PORT="$val"; fi
+        ;;
+      WATCHER_PORT)
+        if [ "$from_pool" = true ] || [ -z "${WATCHER_PORT:-}" ]; then WATCHER_PORT="$val"; fi
+        ;;
+      SLOT_ID)
+        if [ "$from_pool" = true ] || [ -z "${RECIPE_SLOT_ID:-}" ]; then RECIPE_SLOT_ID="$val"; fi
+        ;;
+    esac
+  done <<< "$resolved"
+}