@deeeed/metamask-harness 0.2.0 → 0.3.1

package/{runner/src → src}/commands/shared.ts

@@ -1,12 +1,11 @@
 // Shared helpers for the mm-harness command modules: flag parsing, adapter
-// resolution, porcelain composition, and the teaching-error emitter. Each command
-// module (launch/logs/debug/fixtures) composes mobile/extension porcelain scripts
-// that live under orchestration/porcelain/; these helpers are the common seam.
+// resolution, script composition, and the teaching-error emitter. Each command
+// module composes adapters/ scripts directly via spawnScript.
 //
-// Composition seams (overridable for CI/agents and contract tests):
-//   MM_HARNESS_MM_RECIPE_BIN  — mobile porcelain (default: <runner>/orchestration/porcelain/mm-recipe)
-//   MM_HARNESS_MME_RECIPE_BIN — extension porcelain (default: <runner>/orchestration/porcelain/mme-recipe)
-// A stub that records argv against one of these paths is the contract-test lever.
+// Composition seam (overridable for contract tests):
+//   MM_HARNESS_SCRIPT_BIN_<STEM>  — override a specific script by its basename.
+//   For node invocations (bin === process.execPath) the stem is derived from the
+//   script path in args[0], e.g. MM_HARNESS_SCRIPT_BIN_OPEN_DEBUG_MJS.
 
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
@@ -89,50 +88,61 @@ export function resolveAdapter(
   return detectAdapter(target);
 }
 
-function porcelainBin(adapter: DeviceAdapter): string {
-  if (adapter === 'mobile') {
-    return process.env.MM_HARNESS_MM_RECIPE_BIN ?? path.join(runnerDir, 'orchestration', 'porcelain', 'mm-recipe');
-  }
-  return process.env.MM_HARNESS_MME_RECIPE_BIN ?? path.join(runnerDir, 'orchestration', 'porcelain', 'mme-recipe');
-}
-
-export interface PorcelainResult {
+export interface ScriptResult {
   status: number;
   output: string;
 }
 
-// Compose the porcelain. Output is always captured (needed for heal
-// classification) and, in human mode, forwarded to our stderr so the human still
-// sees it. --json keeps stdout clean for the machine summary.
-export function spawnPorcelain(
-  adapter: DeviceAdapter,
+// Compose an adapters/ script directly. Output is always captured (needed for
+// heal classification) and, in human mode, forwarded to stderr. --json keeps
+// stdout clean for the machine summary.
+export function spawnScript(
+  script: string,
   args: string[],
-  target: string,
+  cwd: string,
   json: boolean,
-): PorcelainResult {
-  const bin = porcelainBin(adapter);
-  const result = spawnSync(bin, args, {
-    cwd: target,
+): ScriptResult {
+  // For node invocations (script === process.execPath) the seam stem is derived
+  // from args[0] so each spawned script has its own override key.
+  const isNodeScript = script === process.execPath && args.length > 0;
+  const stem = isNodeScript
+    ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase()
+    : path.basename(script).replace(/[^A-Za-z0-9]/gu, '_').toUpperCase();
+  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
+  const bin = override ?? script;
+  const spawnArgs = override !== undefined && isNodeScript ? args.slice(1) : args;
+  const result = spawnSync(bin, spawnArgs, {
+    cwd,
     encoding: 'utf8',
     env: process.env,
     maxBuffer: 64 * 1024 * 1024,
   });
   if (result.error) {
-    return { status: 1, output: `porcelain could not start: ${result.error.message}` };
+    return { status: 1, output: `script could not start (${path.basename(script)}): ${result.error.message}` };
   }
   const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
   if (!json && output) process.stderr.write(output);
   return { status: result.status ?? 1, output };
 }
 
-// Teaching-error emitter (exit 2, machine-readable in --json).
-export function usageOut(json: boolean, command: string, message: string): number {
+// Both escapes from a failed repo-type detection (defined at the detection source
+// in harness.ts): where to run it (checkout/target) and how to force it (adapter).
+export { ADAPTER_DETECT_NEXT } from '../harness.ts';
+
+// Teaching-error emitter (exit 2, machine-readable in --json). `userAction` is
+// REQUIRED: a teaching error without a reachable escape must not compile, so the
+// escape is a typed parameter rather than free-form prose spliced into `message`.
+export function usageOut(json: boolean, command: string, message: string, userAction: string): number {
   if (json) {
     console.log(
-      JSON.stringify({ schemaVersion: 1, command, status: 'fail', exitCode: EXIT.usage, error: { code: 'USAGE', message } }, null, 2),
+      JSON.stringify(
+        { schemaVersion: 1, command, status: 'fail', exitCode: EXIT.usage, error: { code: 'USAGE', message, userAction } },
+        null,
+        2,
+      ),
     );
   } else {
-    console.error(`✗ mm-harness ${command}: ${message}`);
+    console.error(`✗ mm-harness ${command}: ${message}\n  Next: ${userAction}`);
   }
   return EXIT.usage;
 }

package/src/commands/update.ts

@@ -0,0 +1,316 @@
+// update — keep the globally-installed mm-harness current against the npm registry.
+// `mm-harness update` upgrades to the published latest; `--check` reports without
+// touching anything; `--json` carries { current, latest, updateAvailable }. A
+// passive once-a-day nudge (maybeNudge) prints a single stderr line when a newer
+// version exists — it never blocks, never auto-updates, and stays off stdout so
+// the --json contract of every other command is untouched. Every failure path
+// (no npm, registry unreachable, permission-denied global dir) names its escape.
+//
+// Two fetch strategies:
+//   fetchLatest    — spawnSync(`npm view`) used by the explicit `update` command;
+//                    respects the user's npm registry config; bounded by timeoutMs.
+//   fetchLatestAsync — native fetch() used by the passive nudge; never spawns a
+//                    subprocess; hard-aborts at timeoutMs so it cannot block the
+//                    event loop beyond that bound.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { runnerDir } from '../paths.ts';
+import { EXIT, flag, parseFlags } from './shared.ts';
+
+export const PACKAGE_NAME = '@deeeed/metamask-harness';
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const NUDGE_FETCH_TIMEOUT_MS = 300;
+
+export function currentVersion(): string {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(runnerDir, 'package.json'), 'utf8')) as { version?: string };
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function parseVersion(value: string): { nums: number[]; pre: string } {
+  const cleaned = value.replace(/^v/u, '');
+  const dash = cleaned.indexOf('-');
+  const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
+  const pre = dash === -1 ? '' : cleaned.slice(dash + 1);
+  const nums = core.split('.').map((part) => Number.parseInt(part, 10) || 0);
+  while (nums.length < 3) nums.push(0);
+  return { nums, pre };
+}
+
+// True when `candidate` is a strictly higher version than `base`. A release outranks
+// a prerelease of the same core (1.0.0 > 1.0.0-rc.1); prereleases compare lexically.
+export function isNewer(candidate: string, base: string): boolean {
+  const a = parseVersion(candidate);
+  const b = parseVersion(base);
+  for (let i = 0; i < 3; i += 1) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
+  }
+  if (a.pre === b.pre) return false;
+  if (a.pre === '') return true;
+  if (b.pre === '') return false;
+  return a.pre > b.pre;
+}
+
+export interface FetchResult {
+  latest?: string;
+  error?: { kind: 'no-npm' | 'unreachable'; message: string };
+}
+
+// Query the registry dist-tag `latest` via `npm view`. `timeoutMs` bounds the
+// wait; callers MUST pass a finite value — an unbounded registry call can hang
+// indefinitely. When the timeout fires, spawnSync sets result.signal to SIGTERM.
+export function fetchLatest(timeoutMs: number): FetchResult {
+  const result = spawnSync('npm', ['view', PACKAGE_NAME, 'dist-tags.latest'], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error) {
+    const code = (result.error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return { error: { kind: 'no-npm', message: 'npm was not found on PATH' } };
+    return { error: { kind: 'unreachable', message: result.error.message } };
+  }
+  if (result.signal) {
+    return { error: { kind: 'unreachable', message: `registry fetch timed out after ${timeoutMs}ms` } };
+  }
+  if (result.status !== 0) {
+    return { error: { kind: 'unreachable', message: (result.stderr ?? '').trim() || `npm view exited ${result.status}` } };
+  }
+  const latest = (result.stdout ?? '').trim();
+  if (!latest) return { error: { kind: 'unreachable', message: 'npm returned no dist-tag for latest' } };
+  return { latest };
+}
+
+// Async variant for the passive nudge: uses the native fetch() API so it never
+// spawns a subprocess and never blocks the event loop. Hard-aborts at timeoutMs.
+// Skips silently on any error (nudge is best-effort).
+async function fetchLatestAsync(timeoutMs: number): Promise<FetchResult> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) return { error: { kind: 'unreachable', message: `registry returned HTTP ${res.status}` } };
+    const data = (await res.json()) as Record<string, string>;
+    const latest = data['latest'];
+    if (!latest) return { error: { kind: 'unreachable', message: 'npm registry returned no latest dist-tag' } };
+    return { latest };
+  } catch (err) {
+    const msg = (err as Error).name === 'AbortError'
+      ? `registry fetch timed out after ${timeoutMs}ms`
+      : (err as Error).message;
+    return { error: { kind: 'unreachable', message: msg } };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Non-zero on every failure (EXIT.infra = 3) so it never collides with `--check`'s
+// exit 1 = "update available"; each carries the exact reachable escape.
+function teachFailure(
+  json: boolean,
+  current: string,
+  code: string,
+  message: string,
+  userAction: string,
+): number {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: 'update', status: 'fail', current, error: { code, message, userAction } },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(`✗ mm-harness update: ${message}\n  Next: ${userAction}`);
+  }
+  return EXIT.infra;
+}
+
+function emitFetchError(json: boolean, error: NonNullable<FetchResult['error']>, current: string): number {
+  if (error.kind === 'no-npm') {
+    return teachFailure(
+      json,
+      current,
+      'NO_NPM',
+      'npm was not found on PATH — cannot check for updates',
+      'install Node.js (which bundles npm) from https://nodejs.org, then re-run: mm-harness update',
+    );
+  }
+  return teachFailure(
+    json,
+    current,
+    'REGISTRY_UNREACHABLE',
+    `could not reach the npm registry (${error.message})`,
+    'check your network, then re-run: mm-harness update — or inspect the registry with: npm config get registry',
+  );
+}
+
+export async function handleUpdate(argv: string[]): Promise<number> {
+  const { options } = parseFlags(argv, new Set(['check', 'json']));
+  const json = flag(options, 'json');
+  const checkOnly = flag(options, 'check');
+  const current = currentVersion();
+
+  const fetched = fetchLatest(30_000);
+  if (fetched.error) return emitFetchError(json, fetched.error, current);
+  const latest = fetched.latest as string;
+  const updateAvailable = isNewer(latest, current);
+
+  if (checkOnly) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest, updateAvailable }, null, 2));
+    } else if (updateAvailable) {
+      console.error(`mm-harness ${current} → ${latest} available · run: mm-harness update`);
+    } else {
+      console.log(`mm-harness is up to date (${current}).`);
+    }
+    // exit 1 signals "update available"; exit 0 signals up-to-date.
+    return updateAvailable ? EXIT.runtime : EXIT.ok;
+  }
+
+  if (!updateAvailable) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest, updateAvailable: false, updated: false }, null, 2));
+    } else {
+      console.log(`mm-harness is up to date (${current}).`);
+    }
+    return EXIT.ok;
+  }
+
+  const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+  const install = spawnSync('npm', ['i', '-g', `${PACKAGE_NAME}@latest`], {
+    encoding: 'utf8',
+    timeout: INSTALL_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (install.error) {
+    const code = (install.error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return emitFetchError(json, { kind: 'no-npm', message: 'npm was not found on PATH' }, current);
+    return teachFailure(json, current, 'INSTALL_FAILED', `global install failed (${install.error.message})`, `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`);
+  }
+  if (install.signal) {
+    return teachFailure(
+      json,
+      current,
+      'INSTALL_FAILED',
+      `global install timed out after ${INSTALL_TIMEOUT_MS / 1000}s — slow network or registry unavailable`,
+      `check your network, then retry: mm-harness update — or install manually: npm i -g ${PACKAGE_NAME}@latest`,
+    );
+  }
+  const combined = `${install.stdout ?? ''}${install.stderr ?? ''}`;
+  if (install.status !== 0) {
+    if (/EACCES|permission denied|EPERM/iu.test(combined)) {
+      return teachFailure(
+        json,
+        current,
+        'GLOBAL_DIR_PERMISSION',
+        'global install denied — the npm global directory is not writable',
+        'either re-run with sudo, or point npm at a user-writable prefix: npm config set prefix ~/.npm-global (then add ~/.npm-global/bin to PATH) and re-run: mm-harness update',
+      );
+    }
+    return teachFailure(
+      json,
+      current,
+      'INSTALL_FAILED',
+      `global install failed (${combined.trim() || `npm exited ${install.status}`})`,
+      `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`,
+    );
+  }
+
+  // Re-check the registry so the reported new version is the one that resolved,
+  // not merely the tag we asked for. Best-effort — fall back to the tag if slow.
+  const rechecked = fetchLatest(30_000);
+  const installed = rechecked.latest ?? latest;
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest: installed, updateAvailable: true, updated: true, from: current, to: installed }, null, 2));
+  } else {
+    console.log(`mm-harness updated ${current} → ${installed}.`);
+  }
+  return EXIT.ok;
+}
+
+// --- Passive update nudge ----------------------------------------------------
+
+interface NudgeCache {
+  lastCheck: number;
+  latest: string;
+}
+
+function cacheFile(): string {
+  const override = process.env.MM_HARNESS_UPDATE_CACHE;
+  if (override) return override;
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'mm-harness', 'update-check.json');
+}
+
+function readCache(file: string): NudgeCache | null {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<NudgeCache>;
+    if (typeof data.lastCheck === 'number' && typeof data.latest === 'string') {
+      return { lastCheck: data.lastCheck, latest: data.latest };
+    }
+  } catch {
+    // Missing or corrupt cache = no prior state; a fresh probe will rebuild it.
+  }
+  return null;
+}
+
+function writeCache(file: string, cache: NudgeCache): void {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+  } catch {
+    // Best-effort; a cache we cannot persist just means the next run re-probes.
+  }
+}
+
+// Suppressed in CI and when the user opts out — the nudge is for interactive use.
+export function nudgeDisabled(): boolean {
+  return process.env.MM_HARNESS_NO_UPDATE_CHECK === '1' || Boolean(process.env.CI);
+}
+
+// Pure decision, testable without a clock or network.
+export function nudgeLine(current: string, latest: string): string | null {
+  return isNewer(latest, current) ? `mm-harness ${current} → ${latest} available · run: mm-harness update` : null;
+}
+
+// One throttled, bounded, stderr-only line when a newer version is published.
+// Called via setImmediate in mm-harness-cli.ts so no nudge code runs before
+// parse/dispatch starts. Prints AFTER command output via process.once('exit'),
+// giving cleaner UX than mid-output interleaving. The `latest` closure variable
+// is captured by the exit handler; an async probe that resolves before
+// process.exit() fires updates it automatically. Offline / timeout / no network
+// skip silently. Cache timestamp is stamped before the fetch so an abandoned
+// probe (process exits within 300ms) does not re-probe on the next invocation.
+export async function maybeNudge(now: number = Date.now()): Promise<void> {
+  if (nudgeDisabled()) return;
+  const file = cacheFile();
+  const cache = readCache(file);
+  const current = currentVersion();
+  // Mutable: exit handler closes over this so a probe result that arrives before
+  // process.exit() automatically updates what gets printed.
+  let latest = cache?.latest ?? '';
+  // Register once — checks nudgeLine at exit time, picking up the freshest value.
+  process.once('exit', () => {
+    const line = nudgeLine(current, latest);
+    if (line) process.stderr.write(`${line}\n`);
+  });
+  if (!cache || now - cache.lastCheck >= NUDGE_INTERVAL_MS) {
+    // Stamp before the fetch so a killed probe does not re-probe next run.
+    writeCache(file, { lastCheck: now, latest });
+    const fetched = await fetchLatestAsync(NUDGE_FETCH_TIMEOUT_MS);
+    if (fetched.latest) {
+      latest = fetched.latest;
+      writeCache(file, { lastCheck: now, latest });
+    }
+  }
+}