@deeeed/metamask-harness 0.46.0 → 0.47.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## 0.47.1 - 2026-09-04
+
+### Fixed
+
+- Open the tutorial on the protected MetaMask GitHub Pages site instead of the public unpkg CDN.
+- Stop shipping the static HTML site in the public npm package; retain only the recipe-help JSON required by the CLI.
+
+## 0.47.0 - 2026-09-04
+
+### Added
+
+- Add `mm-harness help` for the full human recipe guide and `mm-harness help --json` for the same content as structured agent context. The recipe tutorial renders the same versioned source.
+- Add `mm-harness tutorial` to open the visual tutorial published with the installed harness version.
+- Identify Perps as the most optimized recipe library and invite other teams to add composable domain recipes with support from Arthur.
+- Show that recipes cover functional, visual, analytics, log, and performance proof across development, PR review, and release testing.
+- Add a Performance path to the landing-page work prompts and install the matching Recipe Performance skill during setup.
+- Describe the landing page as MetaMask's trust layer for agentic development instead of using a generic confidence slogan.
+- Keep the still-experimental release validation flow out of the landing-page setup and work prompts.
+- Explain that the pre-1.0 package uses Arthur's npm scope and will move to a MetaMask-owned package at 1.0.
+- Link Farmslot references to `https://farmslot.io` in the site and contributor documentation.
+- Order the landing-page work prompts around the common development flow and label the combined workflow as `QA + Review PR`.
+
+### Fixed
+
+- Replace the checkout-owned Mobile console forwarder before bridge readiness checks so `launch` recovers from a live but unresponsive broker left across Metro or Hermes runtime generations.
+- Bound Mobile bridge readiness by one absolute deadline and fail early when a visible React Native target repeatedly cannot answer CDP or never installs `__AGENTIC__`.
+- Preserve provider readiness diagnostics in Mobile Perps start-state failures so authentication and network errors are reported instead of collapsing to a generic not-ready result.
+
 ## 0.46.0 - 2026-09-04
 
 ### Added

package/README.md

@@ -7,7 +7,7 @@ and runtime paths are detected automatically.
 - **Action:** one typed operation.
 - **Recipe:** a reusable, parameterized graph of actions and called recipes.
 
-The generic graph engine and evidence schemas live in Farmslot packages.
+The generic graph engine and evidence schemas live in [Farmslot](https://farmslot.io) packages.
 `mm-harness` owns MetaMask runtime control and domain capabilities.
 
 ## Getting started from zero

package/adapters/manifest.json

@@ -22,7 +22,7 @@
       "id": "mobile/start-console-forwarder",
       "entry": "adapters/mobile/start-console-forwarder.sh",
       "kind": "bash",
-      "purpose": "Ensure one runner-owned Mobile application console collector is alive after bridge readiness.",
+      "purpose": "Ensure one runner-owned Mobile application console collector and broker is alive before bridge readiness depends on it.",
       "inputs": "--target --port --quiet; env WATCHER_PORT, METRO_PORT, METAMASK_RECIPE_CONSOLE_FORWARD",
       "outputs": "app-console.log + collector PID file; exit 0 ready / 1 startup failed / 2 bad args"
     },
@@ -110,9 +110,17 @@
       "id": "mobile/wait-for-bridge",
       "entry": "adapters/mobile/wait-for-bridge.sh",
       "kind": "bash",
-      "purpose": "Poll the CDP bridge (cdp-bridge.cjs status) until a route target registers; progressive diagnostics on failure.",
-      "inputs": "--target --port --max-polls; env WATCHER_PORT, MOBILE_BRIDGE_READY_POLLS",
-      "outputs": "progress on stderr; exit 0 bridge ready / 1 timeout"
+      "purpose": "Wait until a platform-bound CDP bridge route is stable under one absolute readiness deadline; classify absent and unresponsive runtimes.",
+      "inputs": "--target --port --platform --timeout-ms --max-polls; env WATCHER_PORT, MOBILE_BRIDGE_READY_TIMEOUT_MS, MOBILE_BRIDGE_READY_POLLS",
+      "outputs": "progress on stderr; exit 0 bridge ready / 1 classified readiness failure / 2 bad args"
+    },
+    {
+      "id": "mobile/wait-for-bridge-runtime",
+      "entry": "adapters/mobile/wait-for-bridge.cjs",
+      "kind": "node",
+      "purpose": "Apply the bounded Mobile bridge readiness deadline across Metro HTTP probes, CDP status requests, and retry delays.",
+      "inputs": "--target --port --platform --timeout-ms --max-polls; env WATCHER_PORT, MOBILE_BRIDGE_READY_TIMEOUT_MS, MOBILE_BRIDGE_READY_POLLS",
+      "outputs": "progress on stderr; exit 0 bridge ready / 1 classified readiness failure / 2 bad args"
     },
     {
       "id": "mobile/inject",

package/adapters/mobile/wait-for-bridge.cjs

@@ -0,0 +1,550 @@
+#!/usr/bin/env node
+// Wait for one platform-bound Mobile bridge without letting a slow CDP probe
+// extend the caller's readiness deadline.
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const { performance } = require('node:perf_hooks');
+
+const {
+  describeRequested,
+  describeTargets,
+  hasMatchingRoute,
+} = require('./bridge-runtime/lib/match-bridge-target.cjs');
+const {
+  rankRuntimeCandidates,
+} = require('./bridge-runtime/lib/target-discovery.cjs');
+
+const DEFAULT_MAX_POLLS = 90;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_PROBE_TIMEOUT_MS = 1_500;
+const DEFAULT_AGENTIC_GRACE_MS = 15_000;
+const DEFAULT_UNRESPONSIVE_GRACE_MS = 12_000;
+const PROGRESS_INTERVAL_MS = 10_000;
+const MAX_HTTP_BODY_BYTES = 2 * 1024 * 1024;
+
+function parsePositiveInteger(value, label, minimum = 1) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < minimum) {
+    throw new Error(`${label} must be an integer of at least ${minimum}.`);
+  }
+  return parsed;
+}
+
+function parseArgs(argv, env = process.env) {
+  const options = {
+    target: process.cwd(),
+    port: env.WATCHER_PORT || env.METRO_PORT || '8081',
+    platform: '',
+    maxPolls: env.MOBILE_BRIDGE_READY_POLLS || String(DEFAULT_MAX_POLLS),
+    timeoutMs: env.MOBILE_BRIDGE_READY_TIMEOUT_MS || '',
+    help: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = () => {
+      if (index + 1 >= argv.length) throw new Error(`Missing value for ${arg}`);
+      index += 1;
+      return argv[index];
+    };
+    if (arg === '--target') options.target = next();
+    else if (arg === '--port') options.port = next();
+    else if (arg === '--platform') options.platform = next();
+    else if (arg === '--max-polls') options.maxPolls = next();
+    else if (arg === '--timeout-ms') options.timeoutMs = next();
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`unknown arg: ${arg}`);
+  }
+
+  const maxPolls = parsePositiveInteger(
+    options.maxPolls,
+    '--max-polls',
+    2,
+  );
+  const pollIntervalMs = parsePositiveInteger(
+    env.MOBILE_BRIDGE_POLL_INTERVAL_MS || String(DEFAULT_POLL_INTERVAL_MS),
+    'MOBILE_BRIDGE_POLL_INTERVAL_MS',
+  );
+  const timeoutMs = options.timeoutMs
+    ? parsePositiveInteger(options.timeoutMs, '--timeout-ms', 100)
+    : maxPolls * pollIntervalMs;
+  const probeTimeoutMs = parsePositiveInteger(
+    env.MOBILE_BRIDGE_PROBE_TIMEOUT_MS || String(DEFAULT_PROBE_TIMEOUT_MS),
+    'MOBILE_BRIDGE_PROBE_TIMEOUT_MS',
+  );
+  const agenticGraceMs = parsePositiveInteger(
+    env.MOBILE_BRIDGE_AGENTIC_GRACE_MS || String(DEFAULT_AGENTIC_GRACE_MS),
+    'MOBILE_BRIDGE_AGENTIC_GRACE_MS',
+  );
+  const unresponsiveGraceMs = parsePositiveInteger(
+    env.MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS ||
+      String(DEFAULT_UNRESPONSIVE_GRACE_MS),
+    'MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS',
+  );
+
+  return {
+    ...options,
+    target: path.resolve(options.target),
+    maxPolls,
+    timeoutMs,
+    pollIntervalMs,
+    probeTimeoutMs,
+    agenticGraceMs,
+    unresponsiveGraceMs,
+  };
+}
+
+function fetchJson(port, pathname, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const request = http.get(
+      { host: 'localhost', port, path: pathname },
+      (response) => {
+        let body = '';
+        response.setEncoding('utf8');
+        response.on('data', (chunk) => {
+          body += chunk;
+          if (Buffer.byteLength(body) > MAX_HTTP_BODY_BYTES) {
+            request.destroy(new Error('Metro response exceeded its bound'));
+          }
+        });
+        response.on('end', () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch (error) {
+            reject(new Error(`Metro returned invalid JSON: ${error.message}`));
+          }
+        });
+      },
+    );
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`Metro request timed out after ${timeoutMs}ms`));
+    });
+    request.on('error', reject);
+  });
+}
+
+function runBridgeStatus({ bridgePath, target, timeoutMs, env }) {
+  const result = spawnSync(process.execPath, [bridgePath, 'status'], {
+    cwd: target,
+    env: {
+      ...env,
+      APP_ROOT: target,
+      CDP_TIMEOUT: String(timeoutMs),
+    },
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    killSignal: 'SIGTERM',
+    maxBuffer: MAX_HTTP_BODY_BYTES,
+  });
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  let value;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    value = undefined;
+  }
+  return {
+    value,
+    output:
+      stdout || stderr
+        ? `${stdout}${stderr}`.trimEnd()
+        : result.error?.code === 'ETIMEDOUT'
+          ? `bridge status probe exceeded ${timeoutMs}ms`
+          : '',
+    timedOut: result.error?.code === 'ETIMEDOUT',
+  };
+}
+
+function rawTargetMatchesRequest(target, platform, env) {
+  const deviceName = String(target?.deviceName || '');
+  if (platform === 'ios') {
+    const simulator = env.IOS_SIMULATOR || '';
+    return simulator ? deviceName === simulator : true;
+  }
+  if (platform === 'android') {
+    const androidName =
+      env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE || '';
+    if (!androidName) return true;
+    return (
+      deviceName === androidName || deviceName.startsWith(`${androidName} -`)
+    );
+  }
+  return true;
+}
+
+function snapshotMatchesRequest(snapshot, platform, env) {
+  if (!snapshot || typeof snapshot !== 'object') return false;
+  const deviceName = String(snapshot.deviceName || '');
+  if (platform === 'ios') {
+    if (snapshot.platform && snapshot.platform !== 'ios') return false;
+    return env.IOS_SIMULATOR
+      ? deviceName === env.IOS_SIMULATOR
+      : snapshot.platform === 'ios';
+  }
+  if (platform === 'android') {
+    if (snapshot.platform && snapshot.platform !== 'android') return false;
+    const androidName =
+      env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE || '';
+    return androidName
+      ? deviceName === androidName || deviceName.startsWith(`${androidName} -`)
+      : snapshot.platform === 'android';
+  }
+  return !platform;
+}
+
+function matchingSnapshots(value, platform, env) {
+  const snapshots = Array.isArray(value) ? value : [value];
+  return snapshots.filter((snapshot) =>
+    snapshotMatchesRequest(snapshot, platform, env),
+  );
+}
+
+async function observeBridge(config, remainingMs, dependencies = {}) {
+  const now = dependencies.now || (() => performance.now());
+  const fetch = dependencies.fetchJson || fetchJson;
+  const statusProbe = dependencies.runBridgeStatus || runBridgeStatus;
+  const startedAt = now();
+  const httpTimeoutMs = Math.max(
+    1,
+    Math.min(1_000, remainingMs, config.probeTimeoutMs),
+  );
+  let rawTargets;
+  try {
+    rawTargets = await fetch(config.port, '/json/list', httpTimeoutMs);
+  } catch (error) {
+    return {
+      metro: 'unreachable',
+      statusValue: undefined,
+      statusOutput: String(error.message || error),
+    };
+  }
+  const runtimeTargets = rankRuntimeCandidates(rawTargets).filter((target) =>
+    rawTargetMatchesRequest(target, config.platform, config.env),
+  );
+  if (runtimeTargets.length === 0) {
+    return {
+      metro: 'no-target',
+      statusValue: undefined,
+      statusOutput: '[]',
+    };
+  }
+
+  const remainingAfterHttpMs = remainingMs - (now() - startedAt);
+  if (remainingAfterHttpMs <= 0) {
+    return {
+      metro: 'target-visible',
+      statusValue: undefined,
+      statusOutput:
+        'bridge status probe skipped: readiness deadline exhausted during Metro target discovery',
+      statusTimedOut: true,
+    };
+  }
+
+  const probeTimeoutMs = Math.max(
+    1,
+    Math.min(config.probeTimeoutMs, remainingAfterHttpMs),
+  );
+  const status = statusProbe({
+    bridgePath: config.bridgePath,
+    target: config.target,
+    timeoutMs: probeTimeoutMs,
+    env: config.env,
+  });
+  return {
+    metro: 'target-visible',
+    statusValue: status.value,
+    statusOutput: status.output,
+    statusTimedOut: status.timedOut,
+  };
+}
+
+function waitReason(observation, state, config) {
+  if (observation.metro === 'unreachable') {
+    return `Metro not reachable on port ${config.port}`;
+  }
+  if (observation.metro === 'no-target') {
+    return 'Metro running; no React Native debug target yet';
+  }
+  if (state.agenticMissingSince !== null) {
+    return 'React Native target answered; in-app bridge not installed yet';
+  }
+  if (state.unresponsiveSince !== null) {
+    return 'React Native target visible; CDP is not answering';
+  }
+  return 'React Native target answered; waiting for an in-app route';
+}
+
+function failure(kind, startedAt, deadline, now, attempts, lastObservation) {
+  return {
+    ok: false,
+    kind,
+    attempts,
+    elapsedMs: Math.max(0, now - startedAt),
+    remainingMs: Math.max(0, deadline - now),
+    lastObservation,
+  };
+}
+
+async function waitForBridge(config, dependencies = {}) {
+  const now = dependencies.now || (() => performance.now());
+  const sleep =
+    dependencies.sleep ||
+    ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const observe = dependencies.observe || observeBridge;
+  const progress = dependencies.progress || (() => undefined);
+  const status = dependencies.status || (() => undefined);
+  const startedAt = now();
+  const deadline = startedAt + config.timeoutMs;
+  const state = {
+    readyStreak: 0,
+    unresponsiveSince: null,
+    agenticMissingSince: null,
+  };
+  let attempts = 0;
+  let nextProgressAt = startedAt;
+  let lastObservation = {
+    metro: 'unreachable',
+    statusValue: undefined,
+    statusOutput: '',
+  };
+
+  while (now() < deadline) {
+    attempts += 1;
+    const beforeProbe = now();
+    lastObservation = await observe(config, deadline - beforeProbe);
+    status(lastObservation.statusOutput || '');
+    const afterProbe = now();
+    if (afterProbe > deadline) break;
+    const snapshots = matchingSnapshots(
+      lastObservation.statusValue,
+      config.platform,
+      config.env,
+    );
+
+    if (hasMatchingRoute(lastObservation.statusValue, config.env)) {
+      state.readyStreak += 1;
+      state.unresponsiveSince = null;
+      state.agenticMissingSince = null;
+      if (state.readyStreak >= 2) {
+        return {
+          ok: true,
+          attempts,
+          elapsedMs: Math.max(0, afterProbe - startedAt),
+          remainingMs: Math.max(0, deadline - afterProbe),
+          lastObservation,
+        };
+      }
+    } else {
+      state.readyStreak = 0;
+      const agenticMissing = snapshots.some(
+        (snapshot) => snapshot.agenticPresent === false,
+      );
+      if (agenticMissing) {
+        state.agenticMissingSince ??= afterProbe;
+        state.unresponsiveSince = null;
+        if (afterProbe - state.agenticMissingSince >= config.agenticGraceMs) {
+          return failure(
+            'agentic-missing',
+            startedAt,
+            deadline,
+            afterProbe,
+            attempts,
+            lastObservation,
+          );
+        }
+      } else {
+        state.agenticMissingSince = null;
+        const targetUnresponsive =
+          lastObservation.metro === 'target-visible' && snapshots.length === 0;
+        if (targetUnresponsive) state.unresponsiveSince ??= afterProbe;
+        else state.unresponsiveSince = null;
+        if (
+          state.unresponsiveSince !== null &&
+          afterProbe - state.unresponsiveSince >= config.unresponsiveGraceMs
+        ) {
+          return failure(
+            'target-unresponsive',
+            startedAt,
+            deadline,
+            afterProbe,
+            attempts,
+            lastObservation,
+          );
+        }
+      }
+    }
+
+    if (afterProbe >= nextProgressAt) {
+      progress({
+        attempts,
+        elapsedMs: afterProbe - startedAt,
+        remainingMs: Math.max(0, deadline - afterProbe),
+        reason: waitReason(lastObservation, state, config),
+      });
+      nextProgressAt = afterProbe + PROGRESS_INTERVAL_MS;
+    }
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) break;
+    await sleep(Math.min(config.pollIntervalMs, remainingMs));
+  }
+
+  const endedAt = now();
+  return failure(
+    'deadline',
+    startedAt,
+    deadline,
+    endedAt,
+    attempts,
+    lastObservation,
+  );
+}
+
+function bundleProgress(logPath) {
+  let source;
+  try {
+    source = fs.readFileSync(logPath, 'utf8');
+  } catch {
+    return '';
+  }
+  const matches = source
+    .split(/\r?\n/u)
+    .filter((line) => {
+      const trimmed = line.trimStart();
+      return (
+        /^(?:iOS|Android).*index\.(?:js|tsx?).*%/u.test(trimmed) ||
+        line.includes('Bundled') ||
+        line.includes('Bundling') ||
+        line.includes('Finished')
+      );
+    });
+  return matches.length > 0 ? ` (${matches.at(-1)})` : '';
+}
+
+function formatSeconds(ms) {
+  return `${(Math.max(0, ms) / 1_000).toFixed(1)}s`;
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`wait-for-bridge: ${error.message}\n`);
+    process.exit(2);
+  }
+  if (parsed.help) {
+    process.stdout.write(
+      'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--timeout-ms <n>] [--max-polls <n>] [--platform ios|android]\n',
+    );
+    return;
+  }
+  if (!['', 'ios', 'android'].includes(parsed.platform)) {
+    process.stderr.write(
+      'wait-for-bridge: --platform must be ios or android.\n',
+    );
+    process.exit(2);
+  }
+  if (!fs.existsSync(parsed.target)) {
+    process.stderr.write(
+      `wait-for-bridge: target does not exist: ${parsed.target}\n`,
+    );
+    process.exit(2);
+  }
+
+  const runtimeRelative =
+    process.env.MM_HARNESS_WAIT_RUNTIME_DIR ||
+    process.env.RECIPE_RUNTIME_DIR ||
+    path.join('temp', 'recipe', 'runtime');
+  const logDir = path.join(parsed.target, runtimeRelative);
+  const statusLog = path.join(logDir, 'bridge-status.log');
+  const metroLog = path.join(logDir, 'metro.log');
+  const bridgePath = path.join(
+    __dirname,
+    'bridge-runtime',
+    'cdp-bridge.cjs',
+  );
+  if (!fs.existsSync(bridgePath)) {
+    process.stderr.write(
+      `wait-for-bridge: cdp-bridge.cjs not found at ${bridgePath}\n`,
+    );
+    process.exit(1);
+  }
+  fs.mkdirSync(logDir, { recursive: true });
+
+  const env = {
+    ...process.env,
+    WAIT_FOR_BRIDGE_PLATFORM: parsed.platform,
+  };
+  const config = {
+    ...parsed,
+    bridgePath,
+    env,
+  };
+  const result = await waitForBridge(config, {
+    progress(update) {
+      process.stderr.write(
+        `Waiting for Mobile bridge (${formatSeconds(update.elapsedMs)} elapsed, ${formatSeconds(update.remainingMs)} remaining): ${update.reason}${bundleProgress(metroLog)}\n`,
+      );
+    },
+    status(output) {
+      fs.writeFileSync(statusLog, output ? `${output}\n` : '[]\n');
+    },
+  });
+
+  if (result.ok) {
+    process.stderr.write(
+      `Mobile bridge ready (${formatSeconds(result.elapsedMs)})\n`,
+    );
+    return;
+  }
+
+  try {
+    process.stderr.write(fs.readFileSync(statusLog, 'utf8'));
+  } catch {}
+  const requested = describeRequested(env);
+  if (result.kind === 'target-unresponsive') {
+    process.stderr.write(
+      `wait-for-bridge: React Native target for ${requested} was visible but CDP did not answer for ${formatSeconds(parsed.unresponsiveGraceMs)} (${formatSeconds(result.elapsedMs)} elapsed, ${formatSeconds(result.remainingMs)} remaining).\n`,
+    );
+  } else if (result.kind === 'agentic-missing') {
+    process.stderr.write(
+      `wait-for-bridge: React Native target for ${requested} answered without __AGENTIC__ for ${formatSeconds(parsed.agenticGraceMs)}.\n`,
+    );
+  } else {
+    process.stderr.write(
+      `wait-for-bridge: readiness deadline expired after ${formatSeconds(result.elapsedMs)} on port ${parsed.port}.\n`,
+    );
+  }
+  process.stderr.write(
+    `wait-for-bridge: no bridge target matched the requested ${requested} on port ${parsed.port}.\n`,
+  );
+  process.stderr.write(`  requested: ${requested}\n`);
+  process.stderr.write(
+    `  answered:  ${describeTargets(result.lastObservation.statusValue)}\n`,
+  );
+  process.stderr.write(
+    `  Next: check ${statusLog} — or run mm-harness status --json\n`,
+  );
+  process.exit(1);
+}
+
+if (require.main === module) {
+  void main().catch((error) => {
+    process.stderr.write(`wait-for-bridge: ${error.message || error}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  matchingSnapshots,
+  observeBridge,
+  parseArgs,
+  rawTargetMatchesRequest,
+  runBridgeStatus,
+  waitForBridge,
+};