@deeeed/metamask-harness 0.2.0

package/orchestration/lib/activate-repo-node.sh

@@ -0,0 +1,144 @@
+# activate-repo-node.sh — pin the target repo's declared Node for non-interactive spawns
+#
+# Sourced by orchestration scripts that run yarn/webpack in tmux, nohup, or other
+# environments whose PATH may not match an interactive dev shell (.tool-versions and
+# asdf shims are not applied automatically).
+#
+# On success sets:
+#   REPO_NODE_VERSION — e.g. 24.13.0 (no leading v)
+#   REPO_NODE_BIN     — absolute path to the node binary
+#   REPO_NODE_BIN_DIR — dirname of REPO_NODE_BIN
+#   REPO_NODE_PATH_PREFIX — "${REPO_NODE_BIN_DIR}:" when resolved, else empty
+#
+# Also prepends REPO_NODE_BIN_DIR to PATH in the current shell when resolved.
+#
+# Usage (after cd to target repo, or pass directory as $1):
+#   . /path/to/activate-repo-node.sh
+#   activate_repo_node [target-dir]
+#
+# Returns 0 when a declared version exists and a matching node binary was resolved;
+# 1 when no version is declared; 2 when declared but no manager provided it.
+
+_repo_node_matches_req() {
+  local req="$1" actual="${2:-}"
+  [ -n "$actual" ] || actual="$("$REPO_NODE_BIN" -v 2>/dev/null || true)"
+  [ -n "$actual" ] || return 1
+  actual="${actual#v}"
+  [ "$actual" = "$req" ] && return 0
+  case "$req" in
+    *.*.*) return 1 ;;
+    *.*) [[ "$actual" == "$req."* ]] ;;
+    *) [[ "$actual" == "$req"* ]] ;;
+  esac
+}
+
+_repo_node_set_from_bin() {
+  local candidate="$1"
+  [ -n "$candidate" ] && [ -x "$candidate" ] || return 1
+  REPO_NODE_BIN="$candidate"
+  REPO_NODE_BIN_DIR="$(cd "$(dirname "$REPO_NODE_BIN")" && pwd)"
+  REPO_NODE_PATH_PREFIX="${REPO_NODE_BIN_DIR}:"
+  export PATH="${REPO_NODE_BIN_DIR}:${PATH}"
+  return 0
+}
+
+_repo_node_try_req() {
+  local target="$1" req="$2" manager=""
+  [ -n "$req" ] || return 1
+  REPO_NODE_VERSION="$req"
+
+  if command -v asdf >/dev/null 2>&1; then
+    local asdf_root
+    asdf_root="$(asdf where nodejs "$req" 2>/dev/null || true)"
+    if [ -n "$asdf_root" ] && _repo_node_set_from_bin "$asdf_root/bin/node" && _repo_node_matches_req "$req"; then
+      manager=asdf
+      echo "[env] node $("$REPO_NODE_BIN" -v) from .tool-versions/.nvmrc via asdf ($req)" >&2
+      return 0
+    fi
+  fi
+
+  if command -v fnm >/dev/null 2>&1; then
+    local fnm_bin
+    fnm_bin="$(fnm exec --using "$req" -- which node 2>/dev/null || true)"
+    if _repo_node_set_from_bin "$fnm_bin" && _repo_node_matches_req "$req"; then
+      echo "[env] node $("$REPO_NODE_BIN" -v) from .tool-versions/.nvmrc via fnm ($req)" >&2
+      return 0
+    fi
+  fi
+
+  if command -v mise >/dev/null 2>&1; then
+    local mise_bin
+    mise_bin="$(mise x -C "$target" -- which node 2>/dev/null || true)"
+    if _repo_node_set_from_bin "$mise_bin" && _repo_node_matches_req "$req"; then
+      echo "[env] node $("$REPO_NODE_BIN" -v) from .tool-versions/.nvmrc via mise ($req)" >&2
+      return 0
+    fi
+  fi
+  return 1
+}
+
+activate_repo_node() {
+  local target="${1:-.}"
+  REPO_NODE_VERSION=""
+  REPO_NODE_BIN=""
+  REPO_NODE_BIN_DIR=""
+  REPO_NODE_PATH_PREFIX=""
+
+  local declared=false tool_ver="" nvmrc="" req="" nvm_dir path_node
+  if [ -f "$target/.tool-versions" ]; then
+    declared=true
+    tool_ver="$(awk '/^nodejs / {print $2; exit}' "$target/.tool-versions")"
+    _repo_node_try_req "$target" "$tool_ver" && return 0
+  fi
+  if [ -f "$target/.nvmrc" ]; then
+    declared=true
+    nvmrc="$(tr -d ' \t\r\nv' < "$target/.nvmrc")"
+    _repo_node_try_req "$target" "$nvmrc" && return 0
+    case "$nvmrc" in
+      *.*.*) ;;
+      *.*) _repo_node_try_req "$target" "${nvmrc}.0" && return 0 ;;
+    esac
+  fi
+
+  if [ "$declared" != true ]; then
+    echo "[env] no node version declared in .nvmrc or .tool-versions" >&2
+    return 1
+  fi
+
+  req="${tool_ver:-$nvmrc}"
+  if [ -z "$req" ]; then
+    echo "[env] node version file present but no nodejs entry in .tool-versions / .nvmrc" >&2
+    return 1
+  fi
+  REPO_NODE_VERSION="$req"
+  nvm_dir="${NVM_DIR:-$HOME/.nvm}"
+  if [ -s "$nvm_dir/nvm.sh" ]; then
+    # shellcheck disable=SC1090,SC1091
+    . "$nvm_dir/nvm.sh"
+    nvm use "$req" >/dev/null 2>&1 || nvm install "$req" >/dev/null 2>&1 || true
+  fi
+
+  path_node="$(command -v node 2>/dev/null || true)"
+  if _repo_node_set_from_bin "$path_node" && _repo_node_matches_req "$req"; then
+    echo "[env] node $("$REPO_NODE_BIN" -v) already on PATH ($req)" >&2
+    return 0
+  fi
+
+  REPO_NODE_BIN=""
+  REPO_NODE_BIN_DIR=""
+  REPO_NODE_PATH_PREFIX=""
+  echo "[env] need node ${req} (from .nvmrc / .tool-versions) but no installed manager provided it" >&2
+  return 2
+}
+
+require_repo_node() {
+  local target="${1:-.}"
+  if ! command -v activate_repo_node >/dev/null 2>&1; then
+    echo "[env] activate-repo-node.sh is not sourced; reinstall the harness (recipe sync)" >&2
+    return 1
+  fi
+  activate_repo_node "$target" || {
+    echo "[env] refusing to run yarn/webpack without a pinned Node for $target" >&2
+    return 1
+  }
+}

package/orchestration/lib/cli-color.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * cli-color.mjs — shared ANSI styling for recipe CLI human output.
+ *
+ * Honors NO_COLOR, RECIPE_NO_COLOR, FORCE_COLOR, RECIPE_COLOR, and TTY detection.
+ */
+
+const STYLES = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  label: '\x1b[1;36m',
+  cmd: '\x1b[1m',
+  ok: '\x1b[1;32m',
+  warn: '\x1b[1;33m',
+  err: '\x1b[1;31m',
+  info: '\x1b[0;37m',
+  accent: '\x1b[1;35m',
+  path: '\x1b[2m',
+  comment: '\x1b[2m',
+  active: '\x1b[1m',
+};
+
+export function colorEnabled(stream = process.stderr) {
+  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);
+}
+
+export function stripAnsi(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/gu, '');
+}
+
+export function color(style, text, { stream = process.stderr } = {}) {
+  const value = String(text);
+  if (!colorEnabled(stream)) return value;
+  const code = STYLES[style];
+  if (!code) return value;
+  return `${code}${value}${STYLES.reset}`;
+}
+
+export function colorKv(label, value, valueStyle = 'info', { stream = process.stderr } = {}) {
+  return `${color('label', `${label}:`, { stream })} ${color(valueStyle, value, { stream })}`;
+}
+
+export function colorStatusWord(word, { stream = process.stderr } = {}) {
+  const normalized = String(word || '').toLowerCase();
+  if (['up', 'ready', 'yes', 'pass', 'running', 'present', 'healthy'].includes(normalized)) {
+    return color('ok', word, { stream });
+  }
+  if (['down', 'stopped', 'no', 'fail', 'failed', 'missing', 'blocked', 'unknown'].includes(normalized)) {
+    return color('err', word, { stream });
+  }
+  if (['compiling', 'bundling', 'starting', 'waiting', 'warn'].includes(normalized)) {
+    return color('warn', word, { stream });
+  }
+  return color('info', word, { stream });
+}
+
+export function classifyLogEvent(event) {
+  const text = String(event || '');
+  if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
+    return 'err';
+  }
+  if (/compiled successfully|compiled with [0-9]+ warning|PASS runtime-launch|launch pass|verify pass|build complete/iu.test(text)) {
+    return 'ok';
+  }
+  if (/phase [0-9]\/[0-9]|prepare pipeline|snapshot|fixture:|dist-freshness|build-health/iu.test(text)) {
+    return 'label';
+  }
+  if (/webpack [0-9]+%|Bundl(ed|ing)|(iOS|Android).*%/iu.test(text)) {
+    return 'warn';
+  }
+  return 'info';
+}
+
+export function colorLogEvent(event, { latest = false, stream = process.stderr } = {}) {
+  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

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * cli-commands.mjs — 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 */
+
+/** @type {{ shared: CommandSpec[], extension: CommandSpec[], mobile: CommandSpec[], shim: CommandSpec[] }} */
+export const SPEC = {
+  shim: [
+    { name: 'sync', desc: 'Copy fixture, write slot context, install harness', flags: ['--dry-run', '--no-install'] },
+    { name: 'help', aliases: ['-h', '--help'], desc: 'Show usage' },
+  ],
+  shared: [
+    { name: 'status', aliases: ['health', 'home'], desc: 'Home status + next commands', flags: ['--json'] },
+    { name: 'ports', desc: 'Slot ports and runtime paths', flags: ['--json'] },
+    { name: 'up', desc: 'Decide + run minimum work to reach ready', flags: ['--json', '--dry-run'] },
+    { name: 'sync', desc: 'Refresh harness + canonicalize wallet fixture', flags: ['--json'] },
+    { name: 'logs', aliases: ['tail'], desc: 'Compact build events or full log', flags: ['--full', '-f'] },
+    { name: 'debug', aliases: ['devtools', 'inspect'], desc: 'Open DevTools UI', flags: ['--json', '--no-open'] },
+    { name: 'actions', desc: 'List runnable recipe actions', flags: ['--json'] },
+    { name: 'doctor', desc: 'Check harness/orchestration health', flags: ['--json'] },
+    { name: 'run', desc: 'Execute a proof recipe', args: ['recipe.json'] },
+    { name: 'interactive', aliases: ['menu'], desc: 'Interactive command menu' },
+    { name: 'prepare', desc: 'Install harness (+ optional validate)', flags: ['--target', '--runtime-dir', '--json'] },
+    { name: 'runtime-status', desc: 'Structured runtime status JSON', flags: ['--json', '--target', '--cdp-port', '--runtime-dir'] },
+  ],
+  extension: [
+    { name: 'decision', aliases: ['decide'], desc: 'Runtime decision (what next?)' },
+    { name: 'update', aliases: ['sync-runtime'], desc: 'Perform recommended runtime action' },
+    { 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: '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'] },
+  ],
+  mobile: [
+    { name: 'ios', aliases: ['start'], desc: 'Start Metro + launch iOS dev client' },
+    { 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' },
+    { name: 'navigate', desc: 'Navigate by route name', args: ['RouteName'] },
+    { name: 'back', aliases: ['go-back'], desc: 'Navigate back' },
+    { name: 'unlock', desc: 'Unlock with fixture password', args: ['password'] },
+    { name: 'setup-wallet', aliases: ['wallet-setup'], desc: 'Apply wallet fixture', args: ['fixture.json'] },
+    { name: 'accounts', aliases: ['list-accounts'], desc: 'List accounts' },
+    { name: 'select-account', aliases: ['switch-account'], desc: 'Switch account', args: ['address'] },
+    { name: 'screenshot', desc: 'Capture simulator/device screenshot', args: ['path'] },
+    { name: 'dev-menu', aliases: ['devmenu'], desc: 'Open RN developer menu', flags: ['--json', '--no-open'] },
+    { name: 'prepare', flags: ['--target', '--platform', '--preflight-mode', '--port', '--simulator', '--adb-serial', '--runtime-dir', '--wallet-setup', '--wallet-fixture'] },
+    { name: 'debug', flags: ['--json', '--no-open', '--action'] },
+  ],
+};
+
+const GLOBAL_FLAGS = ['--json', '--dry-run', '--full', '-f', '--help', '-h', '--no-open', '--no-color'];
+
+function mergeCommands(adapter) {
+  const byName = new Map();
+  const add = (cmd) => {
+    const existing = byName.get(cmd.name);
+    if (!existing) {
+      byName.set(cmd.name, {
+        ...cmd,
+        aliases: [...(cmd.aliases || [])],
+        flags: [...(cmd.flags || [])],
+        args: [...(cmd.args || [])],
+      });
+      return;
+    }
+    existing.aliases = [...new Set([...(existing.aliases || []), ...(cmd.aliases || [])])];
+    existing.flags = [...new Set([...(existing.flags || []), ...(cmd.flags || [])])];
+    existing.args = [...new Set([...(existing.args || []), ...(cmd.args || [])])];
+    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);
+  return [...byName.values()];
+}
+
+export function commandTokens(adapter, { includeAliases = true } = {}) {
+  const tokens = new Set();
+  for (const cmd of mergeCommands(adapter)) {
+    tokens.add(cmd.name);
+    if (includeAliases) for (const alias of cmd.aliases || []) tokens.add(alias);
+  }
+  return [...tokens].sort();
+}
+
+export function shimCommandTokens() {
+  const tokens = new Set();
+  for (const cmd of SPEC.shim) {
+    tokens.add(cmd.name);
+    for (const alias of cmd.aliases || []) tokens.add(alias);
+  }
+  return [...tokens].sort();
+}
+
+export function lookupCommand(adapter, token) {
+  for (const cmd of mergeCommands(adapter)) {
+    if (cmd.name === token) return cmd;
+    if ((cmd.aliases || []).includes(token)) return cmd;
+  }
+  for (const cmd of SPEC.shim) {
+    if (cmd.name === token) return cmd;
+    if ((cmd.aliases || []).includes(token)) return cmd;
+  }
+  return null;
+}
+
+export function flagsForPosition(adapter, commandToken) {
+  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) {
+  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 = [
+  (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();
+  for (const resolveDir of RUN_RECIPE_DIRS) {
+    const dir = resolveDir(adapter, root);
+    if (!fs.existsSync(dir)) continue;
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.recipe.json') || byBase.has(name)) continue;
+      byBase.set(name, path.join(dir, name));
+    }
+  }
+  return [...byBase.values()]
+    .map((abs) => path.relative(cwd, abs))
+    .sort();
+}
+
+function usage() {
+  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
+`);
+}
+
+async function main() {
+  const { parseArgs } = await import('node:util');
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    args: process.argv.slice(2),
+    options: {
+      adapter: { type: 'string' },
+      command: { type: 'string' },
+      aliases: { type: 'boolean', default: true },
+      index: { type: 'string', default: '0' },
+      root: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+  });
+
+  const command = positionals[0];
+  if (!command || command === '--help' || command === '-h') {
+    usage();
+    process.exit(command ? 0 : 2);
+  }
+
+  if (command === 'global-flags') {
+    process.stdout.write(`${GLOBAL_FLAGS.join('\n')}\n`);
+    return;
+  }
+
+  const adapter = values.adapter;
+  if (!adapter && command !== 'global-flags') {
+    usage();
+    process.exit(2);
+  }
+
+  if (command === 'dump') {
+    process.stdout.write(`${commandTokens(adapter, { includeAliases: values.aliases }).join('\n')}\n`);
+    return;
+  }
+
+  if (command === 'describe') {
+    const rows = adapter === 'shim' ? SPEC.shim : mergeCommands(adapter);
+    for (const cmd of rows) {
+      const aliases = (cmd.aliases || []).join('|');
+      const label = aliases ? `${cmd.name}|${aliases}` : cmd.name;
+      process.stdout.write(`${label}\t${cmd.desc || cmd.name}\n`);
+    }
+    return;
+  }
+
+  if (command === 'flags') {
+    process.stdout.write(`${flagsForPosition(adapter, 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`);
+    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`);
+    return;
+  }
+
+  usage();
+  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) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}