@deeeed/metamask-harness 0.2.0

package/orchestration/lib/cli-version.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * cli-version.mjs — 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) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readPackageVersion(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function gitHead(dir) {
+  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 }) {
+  const manifest = readJson(manifestPath);
+  const reasons = [];
+  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;
+
+  if (installedRevision && installedRevision !== 'unknown' && installedRevision !== currentRevision) {
+    reasons.push(`runner revision ${installedRevision.slice(0, 8)} != ${currentRevision.slice(0, 8)}`);
+  }
+  if (installedVersion && installedVersion !== currentVersion) {
+    reasons.push(`runner package ${installedVersion} != ${currentVersion}`);
+  }
+
+  return {
+    stale: reasons.length > 0,
+    reasons,
+    installedRevision,
+    currentRevision,
+    installedVersion,
+    currentVersion,
+  };
+}
+
+function usage() {
+  console.error(`Usage:
+  cli-version.mjs check --runner-root <dir> --manifest <path> [--installed-sha <path>] [--json]`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { values } = parseArgs({
+    args: rest,
+    allowPositionals: false,
+    options: {
+      'runner-root': { type: 'string' },
+      manifest: { type: 'string' },
+      'installed-sha': { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+  });
+
+  if (!command || command === '--help' || command === '-h') {
+    usage();
+    process.exit(command ? 0 : 2);
+  }
+
+  if (command !== 'check') {
+    usage();
+    process.exit(2);
+  }
+
+  const runnerRoot = values['runner-root'];
+  const manifestPath = values.manifest;
+  if (!runnerRoot || !manifestPath) {
+    usage();
+    process.exit(2);
+  }
+
+  const payload = {
+    ...checkHarness({
+      runnerRoot,
+      manifestPath,
+      installedShaPath: values['installed-sha'],
+    }),
+    manifest: manifestPath,
+  };
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  if (payload.stale) {
+    process.stderr.write(`recipe: harness stale (${payload.reasons.join('; ')})\n`);
+    process.stderr.write('recipe: run: recipe sync\n');
+    process.exit(1);
+  }
+  process.stdout.write('harness up to date\n');
+}
+
+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/ensure-runner-deps.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# ensure-runner-deps.sh — idempotent install of runner npm dependencies.
+#
+# Source checkout runs TypeScript via Node/tsx and imports @farmslot/recipe-harness.
+# Cloned runner checkouts under product temp/ often have no node_modules; parent
+# product repos may ship a .yarnrc.yml that the runner's pinned Yarn rejects, so
+# use npm here (not yarn install).
+#
+# Usage: ensure-runner-deps.sh [RUNNER_DIR]
+# Env:   FARMSLOT_ROOT / METAMASK_RUNNER_PROTOCOL_ROOT — optional local link target
+set -euo pipefail
+
+RUNNER_DIR="${1:-}"
+if [ -z "$RUNNER_DIR" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  RUNNER_DIR="$(cd "$SCRIPT_DIR/../.." && pwd -P)"
+fi
+RUNNER_DIR="$(cd "$RUNNER_DIR" && pwd -P)"
+
+deps_ready() {
+  [ -f "$RUNNER_DIR/node_modules/@farmslot/recipe-harness/package.json" ]
+}
+
+if deps_ready; then
+  exit 0
+fi
+
+if [ ! -f "$RUNNER_DIR/package.json" ]; then
+  echo "mm-harness: runner package.json missing: $RUNNER_DIR" >&2
+  exit 1
+fi
+
+PROTOCOL_ROOT="${METAMASK_RUNNER_PROTOCOL_ROOT:-${METAMASK_RUNNER_FARMSLOT_ROOT:-${FARMSLOT_ROOT:-}}}"
+if [ -z "$PROTOCOL_ROOT" ] && [ -f "$RUNNER_DIR/.farmslot-root" ]; then
+  PROTOCOL_ROOT="$(cat "$RUNNER_DIR/.farmslot-root")"
+fi
+if [ -n "$PROTOCOL_ROOT" ] && [ -f "$RUNNER_DIR/scripts/link-local-farmslot.mjs" ]; then
+  if [ -f "$PROTOCOL_ROOT/packages/recipe-harness/package.json" ]; then
+    FARMSLOT_ROOT="$(cd "$PROTOCOL_ROOT" && pwd -P)" \
+      node "$RUNNER_DIR/scripts/link-local-farmslot.mjs" >&2 || true
+    if deps_ready; then
+      exit 0
+    fi
+  fi
+fi
+
+echo "mm-harness: installing runner dependencies via npm in $RUNNER_DIR" >&2
+(
+  cd "$RUNNER_DIR"
+  npm install --ignore-scripts >&2
+)
+
+if ! deps_ready; then
+  echo "mm-harness: runner dependencies still missing after npm install: $RUNNER_DIR" >&2
+  exit 1
+fi

package/orchestration/lib/harness-path.sh

@@ -0,0 +1,55 @@
+# harness-path.sh — shared, configurable recipe-harness injection root.
+# Sourced (not executed) by both adapters and wrappers so every host uses one
+# definition. Override RECIPE_HARNESS_ROOT (relative to the target repo);
+# defaults to the path in path-defaults.json (under the gitignored temp/, so installs
+# need no extra git-exclude).
+#
+# An empty/unset value falls back to the default; a set value is validated
+# (relative, safe charset, no '.'/'..' components) so a hostile/typo'd value
+# can't make install/cleanup write or rm -rf outside the target, and is safe to
+# embed in shell/JSON without quoting surprises.
+# Returns non-zero on an invalid value; callers run under `set -e`.
+_recipe_path_defaults_file="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/path-defaults.json"
+
+_recipe_path_default() {
+  local key="$1"
+  sed -n 's/.*"'"$key"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$_recipe_path_defaults_file" | head -1
+}
+
+harness_root() {
+  local root="${RECIPE_HARNESS_ROOT:-$(_recipe_path_default recipeHarnessRoot)}"
+  case "$root" in
+    ""|/*) echo "RECIPE_HARNESS_ROOT must be a non-empty relative path: '$root'" >&2; return 1 ;;
+    *[!A-Za-z0-9._/-]*) echo "RECIPE_HARNESS_ROOT may only contain A-Za-z0-9 and . _ / - : '$root'" >&2; return 1 ;;
+  esac
+  local IFS=/ part
+  for part in $root; do
+    case "$part" in
+      .|..) echo "RECIPE_HARNESS_ROOT must not contain '.' or '..' path components: '$root'" >&2; return 1 ;;
+    esac
+  done
+  printf '%s' "$root"
+}
+
+# harness_dir <target> [adapter] -> absolute install dir for the adapter.
+harness_dir() {
+  printf '%s/%s/%s' "$1" "$(harness_root)" "${2:-extension}"
+}
+
+
+# recipe_runtime_dir -> relative runtime state dir for recipe-local config/secrets.
+# Override RECIPE_RUNTIME_DIR (relative to target repo); default lives in path-defaults.json.
+recipe_runtime_dir() {
+  local root="${RECIPE_RUNTIME_DIR:-$(_recipe_path_default recipeRuntimeDir)}"
+  case "$root" in
+    ""|/*) echo "RECIPE_RUNTIME_DIR must be a non-empty relative path: '$root'" >&2; return 1 ;;
+    *[!A-Za-z0-9._/-]*) echo "RECIPE_RUNTIME_DIR may only contain A-Za-z0-9 and . _ / - : '$root'" >&2; return 1 ;;
+  esac
+  local IFS=/ part
+  for part in $root; do
+    case "$part" in
+      .|..) echo "RECIPE_RUNTIME_DIR must not contain '.' or '..' path components: '$root'" >&2; return 1 ;;
+    esac
+  done
+  printf '%s' "$root"
+}

package/orchestration/lib/hash-helpers.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+digest_file() {
+  local file="$1"
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file" | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" | awk '{print $1}'
+  elif command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 "$file" | awk '{print $NF}'
+  else
+    echo "Error: need shasum, sha256sum, or openssl for mobile harness hashing." >&2
+    exit 1
+  fi
+}
+
+digest_stdin() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | awk '{print $1}'
+  elif command -v openssl >/dev/null 2>&1; then
+    openssl dgst -sha256 | awk '{print $NF}'
+  else
+    echo "Error: need shasum, sha256sum, or openssl for mobile harness hashing." >&2
+    exit 1
+  fi
+}
+
+hash_path() {
+  local rel="$1"
+  if [ ! -e "$TARGET/$rel" ]; then
+    printf 'MISSING'
+  elif [ -d "$TARGET/$rel" ]; then
+    (
+      cd "$TARGET"
+      find "$rel" -type f | LC_ALL=C sort | while IFS= read -r file; do
+        printf '%s  %s\n' "$(digest_file "$file")" "$file"
+      done | digest_stdin
+    )
+  else
+    (cd "$TARGET" && digest_file "$rel")
+  fi
+}

package/orchestration/lib/json-field.sh

@@ -0,0 +1,23 @@
+# json-field.sh — shared JSON-field reader for recipe-harness scripts.
+# Sourced (not executed). read_runtime_context_field <json-path> <dotted.field>
+# prints the value (empty string if absent); returns 1 if the file is missing.
+read_runtime_context_field() {
+  local context_path="$1"
+  local field="$2"
+  [ -f "$context_path" ] || return 1
+  node -e '
+const fs = require("node:fs");
+const [path, field] = process.argv.slice(-2);
+try {
+  const data = JSON.parse(fs.readFileSync(path, "utf8"));
+  const value = field.split(".").reduce((node, key) => {
+    if (node === undefined || node === null) return undefined;
+    return node[key];
+  }, data);
+  if (value !== undefined && value !== null && value !== "") process.stdout.write(String(value));
+} catch (error) {
+  process.stderr.write(String(error && error.message ? error.message : error) + "\n");
+  process.exitCode = 1;
+}
+' "$context_path" "$field"
+}

package/orchestration/lib/log-tui.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * log-tui.mjs — compact build-log UX: last N events + pointer to full log.
+ */
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import { color, colorLogEvent } from './cli-color.mjs';
+
+const DEFAULT_EVENTS = 10;
+
+function usage() {
+  console.error(`Usage:
+  log-tui.mjs watch --log <path> [--events <n>] [--mode compact|full|quiet]
+      [--success-pattern <regex>] [--poll-ms <ms>] [--label <text>]
+  log-tui.mjs tail --log <path> [--events <n>] [--follow] [--mode compact|full]
+  log-tui.mjs events --log <path> [--events <n>] [--json]`);
+}
+
+function isSignificantLine(line) {
+  const text = String(line || '').trim();
+  if (!text) return false;
+  if (/^<s> \[webpack\.Progress\]/u.test(text)) {
+    return /(9[0-9]%|100%|emitting|sealing after seal|done plugins)/u.test(text);
+  }
+  if (/^\[webpack\.Progress\]/u.test(text)) return false;
+  return (
+    /\[recipe-harness\]/u.test(text)
+    || /\[fixture\]/u.test(text)
+    || /MetaMask/u.test(text)
+    || /compiled successfully/u.test(text)
+    || /compiled with [0-9]+ warning/u.test(text)
+    || /Module build failed/u.test(text)
+    || /^ERROR in /u.test(text)
+    || /Bundle end:/u.test(text)
+    || /BUILD FAILED/u.test(text)
+    || /webpack.*compiled/u.test(text)
+    || /(iOS|Android).*[0-9]+%/u.test(text)
+    || /Bundl(ed|ing)/u.test(text)
+    || /Launching Extension/u.test(text)
+    || /Extension harness/u.test(text)
+    || /phase [0-9]\/[0-9]/u.test(text)
+    || /snapshotting dist/u.test(text)
+    || /runtime-dist snapshot/u.test(text)
+    || /yarn start compiled/u.test(text)
+    || /prepare pipeline/u.test(text)
+    || /Extension harness launch pass/u.test(text)
+    || /Extension harness verify pass/u.test(text)
+    || /Extension live validation summary/u.test(text)
+    || /PASS runtime-launch/u.test(text)
+    || /dist-freshness:/u.test(text)
+    || /build-health:/u.test(text)
+    || /Fixture status:/u.test(text)
+    || /recorded deps\/cache baseline/u.test(text)
+  );
+}
+
+function formatEvent(line) {
+  const text = String(line || '').trim().replace(/\s+/gu, ' ');
+  if (/^<s> \[webpack\.Progress\]/u.test(text)) {
+    const match = text.match(/\[webpack\.Progress\] (.*)$/u);
+    return match ? `webpack ${match[1]}` : text;
+  }
+  return text
+    .replace(/^<s> /u, '')
+    .replace(/^\[recipe-harness\] /u, '')
+    .replace(/^\[fixture\] /u, 'fixture: ')
+    .replace(/^[•*]\s+/u, '');
+}
+
+function extractEvents(text, limit) {
+  const events = [];
+  for (const raw of text.split(/\r?\n/u)) {
+    if (!isSignificantLine(raw)) continue;
+    const formatted = formatEvent(raw);
+    if (!formatted) continue;
+    if (events.length > 0 && events[events.length - 1] === formatted) continue;
+    events.push(formatted);
+  }
+  return events.slice(-limit);
+}
+
+function readNewContent(file, offset) {
+  if (!fs.existsSync(file)) return { text: '', offset: 0 };
+  const stat = fs.statSync(file);
+  if (stat.size < offset) offset = 0;
+  const fd = fs.openSync(file, 'r');
+  try {
+    const length = stat.size - offset;
+    if (length <= 0) return { text: '', offset };
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, offset);
+    return { text: buffer.toString('utf8'), offset: stat.size };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function renderHeader(label, logPath, title) {
+  return [
+    `${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('bold', title || label, { stream: process.stderr })}`,
+    `${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('path', `full log: ${logPath}`, { stream: process.stderr })}`,
+    `${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('comment', 'full stream: recipe logs --full', { stream: process.stderr })}`,
+    '',
+  ];
+}
+
+function renderEventLines(events, { stream = process.stderr } = {}) {
+  if (events.length === 0) {
+    return [`  ${color('dim', '*', { stream })} ${color('comment', '(waiting for first build event...)', { stream })}`];
+  }
+  return events.map((event, index) => {
+    const latest = index === events.length - 1;
+    return `  ${color('dim', '*', { stream })} ${colorLogEvent(event, { latest, stream })}`;
+  });
+}
+
+function renderCompact({ label, logPath, events, quiet }) {
+  if (quiet) return;
+  const header = renderHeader(label, logPath, label);
+  const body = renderEventLines(events, { stream: process.stderr });
+  const block = [...header, ...body].join('\n');
+  if (process.stderr.isTTY) {
+    process.stderr.write(`\x1b[2J\x1b[H${block}\n`);
+    return;
+  }
+  process.stderr.write(`${block}\n`);
+}
+
+function renderTail({ logPath, events, follow }) {
+  const title = follow ? 'tailing last events' : 'recent build events';
+  const lines = [
+    ...renderHeader('build', logPath, title),
+    ...renderEventLines(events, { stream: process.stdout }),
+    '',
+  ];
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function matchesPattern(text, pattern) {
+  if (!pattern) return false;
+  return new RegExp(pattern, 'iu').test(text);
+}
+
+async function watchLog(options) {
+  const {
+    logPath,
+    eventsLimit,
+    mode,
+    successPattern,
+    pollMs,
+    label,
+  } = options;
+
+  if (mode === 'full') {
+    const { spawn } = await import('node:child_process');
+    const child = spawn('tail', ['-n', '20', '-F', logPath], { stdio: 'inherit' });
+    await new Promise((resolve) => child.on('exit', resolve));
+    return child.exitCode ?? 0;
+  }
+
+  let offset = fs.existsSync(logPath) ? fs.statSync(logPath).size : 0;
+  let lastRendered = '';
+  const started = Date.now();
+
+  while (true) {
+    const chunk = readNewContent(logPath, offset);
+    offset = chunk.offset;
+    const allText = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '';
+    const events = extractEvents(allText, eventsLimit);
+
+    if (matchesPattern(allText, 'Module build failed|^ERROR in |compiled with [1-9][0-9]* error|FAIL runtime-launch|Extension harness launch fail')) {
+      renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
+      return 1;
+    }
+    if (matchesPattern(allText, successPattern)) {
+      renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
+      if (mode !== 'quiet') {
+        const elapsed = Math.round((Date.now() - started) / 1000);
+        process.stderr.write(`${color('label', 'recipe', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('ok', `build complete (${elapsed}s)`, { stream: process.stderr })}\n`);
+      }
+      return 0;
+    }
+
+    const snapshot = JSON.stringify(events);
+    if (snapshot !== lastRendered) {
+      renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
+      lastRendered = snapshot;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+async function tailLog(options) {
+  const { logPath, eventsLimit, follow, mode } = options;
+  if (mode === 'full' && follow) {
+    const { spawn } = await import('node:child_process');
+    const child = spawn('tail', ['-f', logPath], { stdio: 'inherit' });
+    await new Promise((resolve) => child.on('exit', resolve));
+    return child.exitCode ?? 0;
+  }
+
+  if (!follow) {
+    const text = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '';
+    renderTail({ logPath, events: extractEvents(text, eventsLimit), follow: false });
+    return 0;
+  }
+
+  let offset = fs.existsSync(logPath) ? fs.statSync(logPath).size : 0;
+  let lastRendered = '';
+  while (true) {
+    const chunk = readNewContent(logPath, offset);
+    offset = chunk.offset;
+    const allText = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '';
+    const events = extractEvents(allText, eventsLimit);
+    const snapshot = JSON.stringify(events);
+    if (snapshot !== lastRendered) {
+      renderTail({ logPath, events, follow: true });
+      lastRendered = snapshot;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+}
+
+async function main() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    args: process.argv.slice(2),
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      log: { type: 'string' },
+      events: { type: 'string', default: String(DEFAULT_EVENTS) },
+      mode: { type: 'string', default: process.env.RECIPE_LOG_UI || 'compact' },
+      'success-pattern': {
+        type: 'string',
+        default: 'compiled successfully|compiled with [0-9]+ warning|MetaMask .* compiled|Bundle end:',
+      },
+      'poll-ms': { type: 'string', default: '2000' },
+      label: { type: 'string', default: 'build' },
+      follow: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+  });
+
+  const command = positionals[0];
+  if (values.help || command === '--help' || command === '-h') {
+    usage();
+    process.exit(0);
+  }
+  if (!command) {
+    usage();
+    process.exit(2);
+  }
+
+  const logPath = values.log;
+  if (!logPath) {
+    usage();
+    process.exit(2);
+  }
+
+  const eventsLimit = Number.parseInt(values.events, 10) || DEFAULT_EVENTS;
+  const pollMs = Number.parseInt(values['poll-ms'], 10) || 2000;
+
+  if (command === 'watch') {
+    const code = await watchLog({
+      logPath,
+      eventsLimit,
+      mode: values.mode,
+      successPattern: values['success-pattern'],
+      pollMs,
+      label: values.label,
+    });
+    process.exit(code);
+  }
+
+  if (command === 'tail') {
+    const code = await tailLog({
+      logPath,
+      eventsLimit,
+      follow: values.follow,
+      mode: values.mode,
+    });
+    process.exit(code);
+  }
+
+  if (command === 'events') {
+    const text = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '';
+    const events = extractEvents(text, eventsLimit);
+    if (values.json) {
+      process.stdout.write(`${JSON.stringify({ log: logPath, events }, null, 2)}\n`);
+    } else {
+      renderTail({ logPath, events, follow: false });
+    }
+    return;
+  }
+
+  usage();
+  process.exit(2);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});