@deeeed/metamask-harness 0.2.0

package/orchestration/doctor.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// doctor.mjs — orchestration feature-surface doctor
+//
+// Purpose:
+//   Verifies orchestration/manifest.json against reality: every entry point
+//   exists; every script entry answers --help with exit 0; and every script
+//   under orchestration/{mobile,extension,core} is listed (no doc drift).
+//
+// Inputs (flags): --json (machine-readable report)
+// Outputs: per-feature lines (or JSON report) on stdout.
+//   Exit 0 — surface healthy; 1 — missing entry, failing --help, or
+//   unlisted script; 2 — bad args.
+// Never touches: anything (read-only + --help subprocesses).
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+let json = false;
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--json') json = true;
+  else if (arg === '-h' || arg === '--help') {
+    console.log('Usage: doctor.mjs [--json]');
+    process.exit(0);
+  } else {
+    console.error(`Unknown arg: ${arg}`);
+    process.exit(2);
+  }
+}
+
+const orchestrationDir = path.dirname(fileURLToPath(import.meta.url));
+const runnerRoot = path.resolve(orchestrationDir, '..');
+const manifest = JSON.parse(fs.readFileSync(path.join(orchestrationDir, 'manifest.json'), 'utf8'));
+
+const results = [];
+for (const feature of manifest.features) {
+  const entryAbs = path.join(runnerRoot, feature.entry);
+  const checks = { exists: fs.existsSync(entryAbs), help: null };
+  if (checks.exists && (feature.kind === 'bash' || feature.kind === 'node')) {
+    const runner = feature.kind === 'bash' ? 'bash' : process.execPath;
+    const run = spawnSync(runner, [entryAbs, '--help'], { encoding: 'utf8', timeout: 30000 });
+    checks.help = run.status === 0;
+  }
+  const ok = checks.exists && (checks.help === null || checks.help === true);
+  results.push({ id: feature.id, entry: feature.entry, kind: feature.kind, ...checks, ok });
+}
+
+// drift guard: every script in the orchestration trees must be listed
+const listed = new Set(manifest.features.map((feature) => feature.entry));
+const unlisted = [];
+for (const platform of ['mobile', 'extension', 'core', 'lib']) {
+  const dir = path.join(orchestrationDir, platform);
+  if (!fs.existsSync(dir)) continue;
+  for (const entry of fs.readdirSync(dir)) {
+    const rel = `orchestration/${platform}/${entry}`;
+    if (!/\.(?:sh|mjs|cjs|json)$/u.test(entry)) continue;
+    if (!listed.has(rel)) unlisted.push(rel);
+  }
+}
+
+const failed = results.filter((result) => !result.ok);
+const status = failed.length === 0 && unlisted.length === 0 ? 'pass' : 'fail';
+if (json) {
+  console.log(JSON.stringify({ status, features: results, unlisted }, null, 2));
+} else {
+  for (const result of results) {
+    console.log(`${result.ok ? 'ok  ' : 'FAIL'} ${result.id} (${result.entry})${result.help === false ? ' [--help failed]' : ''}${result.exists ? '' : ' [missing]'}`);
+  }
+  for (const rel of unlisted) console.log(`FAIL unlisted script not in manifest: ${rel}`);
+  console.log(`orchestration surface: ${status} (${results.length - failed.length}/${results.length} features, ${unlisted.length} unlisted)`);
+}
+process.exit(status === 'pass' ? 0 : 1);

package/orchestration/extension/cleanup.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// cleanup.mjs — remove the extension harness overlay
+//
+// Purpose:
+//   Removes exactly the .git/info/exclude entries the install recorded,
+//   then deletes the target's extension harness dir. Overlay-only: no
+//   product files are involved.
+//
+// Inputs (flags / env):
+//   --target <metamask-extension> (default $PWD); env RECIPE_HARNESS_ROOT
+//
+// Outputs:
+//   Removes <harness>/extension; confirmation line on stdout.
+//   Exit 0 — cleaned (idempotent if nothing installed); 2 — bad args.
+//
+// Never touches: product files; .git/info/exclude lines it did not record.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { recipeHarnessRoot } from '../lib/recipe-paths.mjs';
+
+function usage() { console.error('Usage: cleanup-extension-harness.mjs [--target <metamask-extension>]'); }
+let target = process.cwd();
+for (let i = 2; i < process.argv.length; i += 1) {
+  const arg = process.argv[i];
+  if (arg === '--target') {
+    if (i + 1 >= process.argv.length) { usage(); process.exit(2); }
+    target = process.argv[++i];
+  } else if (arg === '-h' || arg === '--help') {
+    usage(); process.exit(0);
+  } else {
+    console.error(`cleanup-extension-harness: unknown arg: ${arg}`);
+    usage(); process.exit(2);
+  }
+}
+
+target = path.resolve(target);
+const harnessRoot = harnessRootValue();
+const harnessDir = path.join(target, harnessRoot, 'extension');
+removeRecordedGitExcludeEntries(target, path.join(harnessDir, 'added-git-exclude'));
+fs.rmSync(harnessDir, { recursive: true, force: true });
+console.log(`Cleaned extension recipe harness from ${target}`);
+
+function harnessRootValue() {
+  return recipeHarnessRoot();
+}
+
+function removeRecordedGitExcludeEntries(repo, recordFile) {
+  if (!fs.existsSync(recordFile)) return;
+  const gitDirResult = spawnSync('git', ['-C', repo, 'rev-parse', '--git-dir'], { encoding: 'utf8' });
+  if (gitDirResult.status !== 0) return;
+  let gitDir = gitDirResult.stdout.trim();
+  if (!path.isAbsolute(gitDir)) gitDir = path.join(repo, gitDir);
+  const excludeFile = path.join(gitDir, 'info/exclude');
+  if (!fs.existsSync(excludeFile)) return;
+  const remove = new Set(fs.readFileSync(recordFile, 'utf8').split('\n').filter(Boolean));
+  const kept = fs.readFileSync(excludeFile, 'utf8').split('\n').filter((line) => !remove.has(line));
+  fs.writeFileSync(excludeFile, `${kept.join('\n').replace(/\n+$/u, '')}\n`);
+}

package/orchestration/extension/console-tail.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// console-tail.mjs — live stream of the running extension's console.
+//
+// Connects to a Chrome CDP endpoint and tails the console output of every
+// extension target — the MV3 service worker AND extension UI pages
+// (chrome-extension:// pages) — printing each console call / runtime
+// exception / log entry as a single line. Intended to host a tmux window so
+// the tab shows live extension logs (the equivalent of the Metro/webpack tabs).
+//
+// Usage:
+//   console-tail.mjs --cdp-port <port> [--log <file>]
+//
+// Resilience: MV3 service workers cycle on idle and UI pages open/close, so we
+// re-poll /json/list every ~2s and (re)attach to any extension target that is
+// not currently connected. A dropped websocket simply frees the target for the
+// next poll to re-attach (printed as a [reconnect] note).
+//
+// Requires Node 22+ (global WebSocket).
+'use strict';
+
+import { appendFileSync } from 'node:fs';
+
+function parseArgs(argv) {
+  const args = { cdpPort: null, log: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--cdp-port':
+        args.cdpPort = argv[++i];
+        break;
+      case '--log':
+        args.log = argv[++i];
+        break;
+      case '-h':
+      case '--help':
+        process.stdout.write(
+          'Usage: console-tail.mjs --cdp-port <port> [--log <file>]\n',
+        );
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cdpPort = Number(args.cdpPort);
+if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
+  throw new Error('console-tail requires a numeric --cdp-port.');
+}
+const HOST = `127.0.0.1:${cdpPort}`;
+
+if (typeof WebSocket === 'undefined') {
+  throw new Error('console-tail requires Node 22+ with a global WebSocket.');
+}
+
+// targetId -> { ws, label, opened }
+const attached = new Map();
+// targetId -> epoch ms until which re-attach is skipped (targets that errored
+// before ever connecting, so a dead/non-debuggable target is not retried every poll).
+const cooldown = new Map();
+
+function out(line) {
+  process.stdout.write(`${line}\n`);
+  if (args.log) appendFileSync(args.log, `${line}\n`);
+}
+
+function stamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+function shortLabel(target) {
+  if (target.type === 'service_worker') return 'sw';
+  let tail = target.url || '';
+  try {
+    const u = new URL(target.url);
+    tail = u.pathname.split('/').filter(Boolean).pop() || u.host;
+  } catch {
+    // Non-URL target url (rare); fall back to the raw string below.
+    tail = (target.url || target.type || 'page').slice(-24);
+  }
+  return `page:${tail}`;
+}
+
+function isExtensionTarget(target) {
+  if (!target || !target.webSocketDebuggerUrl) return false;
+  if (target.type !== 'service_worker' && target.type !== 'page') return false;
+  return String(target.url || '').startsWith('chrome-extension://');
+}
+
+function previewArg(arg) {
+  if (!arg || typeof arg !== 'object') return String(arg);
+  if ('value' in arg && arg.value !== undefined) {
+    return typeof arg.value === 'object'
+      ? JSON.stringify(arg.value)
+      : String(arg.value);
+  }
+  if (arg.unserializableValue) return String(arg.unserializableValue);
+  if (arg.description) return arg.description;
+  if (arg.preview?.description) return arg.preview.description;
+  return arg.subtype || arg.type || '?';
+}
+
+function emitConsole(label, params) {
+  const level = String(params.type || 'log').toUpperCase();
+  const text = (params.args || []).map(previewArg).join(' ');
+  out(`${stamp()} [${label}] ${level}  ${text}`);
+}
+
+function emitException(label, params) {
+  const d = params.exceptionDetails || {};
+  const text =
+    d.exception?.description ||
+    d.exception?.value ||
+    d.text ||
+    'uncaught exception';
+  out(`${stamp()} [${label}] EXCEPTION  ${text}`);
+}
+
+function emitLogEntry(label, params) {
+  const e = params.entry || {};
+  const level = String(e.level || 'log').toUpperCase();
+  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`);
+}
+
+function handleMessage(label, data) {
+  let message;
+  try {
+    message = JSON.parse(data);
+  } catch {
+    // Non-JSON frame; nothing actionable to stream.
+    return;
+  }
+  if (message.id != null) return; // command ack, not an event
+  switch (message.method) {
+    case 'Runtime.consoleAPICalled':
+      emitConsole(label, message.params || {});
+      break;
+    case 'Runtime.exceptionThrown':
+      emitException(label, message.params || {});
+      break;
+    case 'Log.entryAdded':
+      emitLogEntry(label, message.params || {});
+      break;
+    default:
+      break;
+  }
+}
+
+function attach(target) {
+  const label = shortLabel(target);
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  const entry = { ws, label, opened: false };
+  attached.set(target.id, entry);
+
+  ws.addEventListener('open', () => {
+    entry.opened = true;
+    let id = 0;
+    for (const method of ['Runtime.enable', 'Log.enable']) {
+      ws.send(JSON.stringify({ id: ++id, method, params: {} }));
+    }
+    out(`${stamp()} [${label}] [attached]`);
+  });
+  ws.addEventListener('message', (event) => {
+    handleMessage(label, typeof event.data === 'string' ? event.data : '');
+  });
+  const drop = () => {
+    if (attached.get(target.id) !== entry) return;
+    attached.delete(target.id);
+    if (entry.opened) {
+      out(`${stamp()} [${label}] [reconnect] target detached; will re-attach`);
+    } else {
+      // Never connected (target gone / not debuggable yet): back off so a dead
+      // target is not retried — and logged — on every 2s poll.
+      cooldown.set(target.id, Date.now() + 10000);
+    }
+  };
+  ws.addEventListener('close', drop);
+  ws.addEventListener('error', drop);
+}
+
+async function poll() {
+  let targets;
+  try {
+    const response = await fetch(`http://${HOST}/json/list`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    targets = await response.json();
+  } catch {
+    // CDP not reachable this tick (browser starting/restarting); retry next poll.
+    return;
+  }
+  for (const target of Array.isArray(targets) ? targets : []) {
+    if (!isExtensionTarget(target)) continue;
+    if (attached.has(target.id)) continue;
+    const until = cooldown.get(target.id);
+    if (until !== undefined) {
+      if (Date.now() < until) continue;
+      cooldown.delete(target.id);
+    }
+    attach(target);
+  }
+  // Drop expired cooldown entries so the map cannot grow unbounded across a
+  // long session of service-worker / page churn.
+  for (const [id, until] of cooldown) {
+    if (Date.now() >= until) cooldown.delete(id);
+  }
+}
+
+function shutdown() {
+  for (const { ws } of attached.values()) {
+    try {
+      ws.close();
+    } catch {
+      // Best-effort close on exit.
+    }
+  }
+  process.exit(0);
+}
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+
+out(`${stamp()} [console-tail] streaming extension console via cdp ${cdpPort}`);
+await poll();
+setInterval(poll, 2000);