@deeeed/metamask-harness 0.3.9 → 0.5.0

package/dist/runner.js

@@ -0,0 +1,88 @@
+import { execSync } from "node:child_process";
+import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
+import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
+import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
+import { importRecipeHarness, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from "./paths.js";
+async function createMetaMaskMobileRunner(options = {}) {
+  return createMetaMaskRunner(
+    "mobile",
+    options.actionManifest ?? loadMetaMaskMobileActionManifest()
+  );
+}
+async function createMetaMaskExtensionRunner(options = {}) {
+  return createMetaMaskRunner(
+    "extension",
+    options.actionManifest ?? loadMetaMaskExtensionActionManifest()
+  );
+}
+async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
+  const {
+    createRecipeRunner,
+    createStandardCoreAdapters,
+    createStandardUiAdapters
+  } = await importRecipeHarness();
+  const { createCdpWebUiTransport } = await importRecipeHarnessRuntimeCdp();
+  const { createReactNativeBridgeUiTransport } = await importRecipeHarnessRuntimeReactNativeBridge();
+  const actions = [
+    ...actionManifest.supported_official_actions,
+    ...(actionManifest.custom_actions ?? []).map((entry) => entry.name)
+  ];
+  const declaredActions = new Set(actions);
+  const core = createStandardCoreAdapters({ actions });
+  const projectOwnedOfficialActions = /* @__PURE__ */ new Set(["app.status"]);
+  const ui = createStandardUiAdapters({
+    actions: actions.filter((action) => !projectOwnedOfficialActions.has(action)),
+    transport: createMetaMaskUiTransport(adapter, {
+      createCdpWebUiTransport,
+      createReactNativeBridgeUiTransport
+    })
+  });
+  const existing = new Set([...core, ...ui].map((entry) => entry.action));
+  const custom = createMetaMaskAdapters(adapter).filter(
+    (entry) => declaredActions.has(entry.action) && !existing.has(entry.action)
+  );
+  const autoHudDisabled = process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false";
+  const logger = options.quietStdout ? new console.Console(process.stderr) : console;
+  return createRecipeRunner({
+    actionManifest,
+    adapters: [...core, ...ui, ...custom],
+    logger,
+    recording: {
+      targetProvider: createMetaMaskRecordingTargetProvider(adapter)
+    },
+    runner: runnerProvenance(),
+    hud: autoHudDisabled ? false : {
+      enabled: true,
+      display: {
+        layout: "docked-bottom",
+        position: "bottom",
+        showTitle: false,
+        showDebug: false,
+        maxDetailLines: 2
+      }
+    }
+  });
+}
+function runnerProvenance() {
+  return {
+    source: runnerDir,
+    git_ref: runnerGitRef(),
+    name: "@metamask/recipe-runner"
+  };
+}
+function runnerGitRef() {
+  try {
+    return execSync("git rev-parse HEAD", {
+      cwd: runnerDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+export {
+  createMetaMaskExtensionRunner,
+  createMetaMaskMobileRunner,
+  createMetaMaskRunner
+};

package/docs/ADAPTER-SURFACE.md

@@ -0,0 +1,119 @@
+# The adapter surface — one seam for per-platform behavior
+
+`mm-harness` runs against three platforms (mobile | extension | core). The
+danger is that every command re-derives "what does this platform do?" with its
+own `if (adapter === 'mobile') … else if (adapter === 'extension') …` ladder.
+When it does, a platform gets forgotten in one command but not another — the
+class of bug where `doctor` reported a live runtime section for mobile only,
+`stop` refused every non-mobile adapter, and `logs` knew a single extension log
+file instead of all three. Those are *platform-blind* commands.
+
+The **adapter surface** is the fix: one interface per platform, resolved through
+a registry, that owns the behavior a command would otherwise branch on.
+
+## The interface
+
+`src/adapters/surface.ts` defines `AdapterSurface` and the registry
+`getAdapterSurface(adapter)`. Each platform ships one implementation:
+
+- `src/adapters/mobile/surface.ts`
+- `src/adapters/extension/surface.ts`
+- `src/adapters/core/surface.ts`
+
+```ts
+interface AdapterSurface {
+  readonly adapter: MetaMaskRecipeAdapter;
+  readonly headless: boolean;                       // core runs no app/dev server
+  resolveSlotPorts(target: string): void;           // context > pool > formula (no-op for core)
+  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>; // read-only readiness for doctor
+  devServer: {
+    describe(): string;                             // "Metro" | "webpack watcher" | "no dev server (headless)"
+    stop(target: string): AdapterDevServerStop;     // idempotent, slot-scoped; headless = teach
+  };
+  logSources(target: string): AdapterLogSource[];   // ordered candidate log files (empty for core)
+  hints: { launch: string; relaunch: string };      // platform-phrased Next: hints
+}
+```
+
+`runtimeStatus` returns a normalized shape so `doctor` renders one line the same
+way for every platform:
+
+```ts
+interface AdapterRuntimeStatus {
+  decision: string;
+  reasonCode?: string;
+  reasons: string[];
+  deps?: string;
+  devServer?: { label: string; status: string };    // absent for headless core
+}
+```
+
+The implementations are thin: they delegate to the readiness/port plumbing that
+already existed (`decideExtensionReadiness`, `mobileRuntimeStatus`, the slot-port
+resolvers and the webpack-watcher stop, all re-homed to
+`src/adapters/slot-ports.ts`). The surface is an organizing seam, not a rewrite.
+
+## The rule
+
+**A command never branches on adapter for behavior the surface owns.**
+
+- Do not write `if (adapter === 'core')` — ask `surface.headless`.
+- Do not write `adapter === 'mobile' ? metroPorts() : extensionPorts()` — call
+  `surface.resolveSlotPorts(target)`.
+- Do not print `adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness
+  launch'` — use `surface.hints.launch`.
+
+A new platform behavior is added by **extending the surface** (a new member on
+the interface plus its three implementations), never by adding another branch to
+a command. TypeScript then makes it impossible to ship a platform that forgot the
+new member, because each implementation is annotated `: AdapterSurface`.
+
+What the surface deliberately does **not** own: a command may still branch on
+adapter for a *mechanism* that is genuinely platform-specific and not part of the
+interface — e.g. `fixtures set` uses a shell arm on mobile and the engine path on
+extension. Those branches select a mechanism; they never re-derive readiness,
+ports, log locations, dev-server lifecycle, or Next: phrasing, which are the
+surface's responsibility.
+
+## Migration status
+
+Every command that used to branch on adapter now resolves through the surface:
+
+| command | surface-backed | uses |
+| --- | --- | --- |
+| `doctor` | yes | `resolveSlotPorts` + `runtimeStatus` (mobile/extension/core runtime section) |
+| `launch` | yes | `resolveSlotPorts` |
+| `stop` | yes | `resolveSlotPorts` + `devServer.stop` (+ headless teaching) |
+| `logs` | yes | `logSources` + `hints.launch` + `headless` |
+| `debug` | yes | `headless` + `hints.relaunch` (core teaching); flag semantics stay per-command |
+| `fixtures` | yes | `headless` + `hints` (retry/launch); the set *mechanism* stays per-platform |
+| `run` / `call` | n/a | engine path; core-headless is handled by the heal contract, not the surface |
+| `flows` | no (by design) | recipe-library flows are adapter-global; not a platform-owned behavior |
+| `completion-candidates` | partial | `actions` scope to the detected checkout adapter; `flows` are adapter-global |
+
+`flows` is intentionally not surface-backed: a recipe-library flow can compose
+actions across platforms, so flows are adapter-global by design rather than a
+platform-blind gap. `completion-candidates actions` already resolves the adapter
+from the checkout context (cwd/`--target`); only the adapter-global `flows`
+candidates are unscoped, matching the flows model.
+
+## How this composes with the UX principles
+
+`docs/UX-PRINCIPLES.md` principle 1 (*Context-aware by default* — "output is
+scoped to the platform… help, flag lists, and completion candidates shrink to
+what applies here") states the intent. The adapter surface is its **enforcement
+mechanism**: a command that resolves platform behavior through the surface is
+context-aware by construction, and one that hand-rolls an adapter ladder is the
+exact failure principle 1 warns against. When adding a command or output path,
+satisfy principle 1 by going through the surface.
+
+## Adding a platform behavior — checklist
+
+1. Add the member to `AdapterSurface` in `src/adapters/surface.ts`.
+2. Implement it in all three `src/adapters/*/surface.ts` (TypeScript will not
+   compile until you do).
+3. Have the command call `getAdapterSurface(adapter).<member>` instead of
+   branching.
+4. Cover the closed blind spot with a contract test (see
+   `tests/contract/adapter-surface.test.sh`), and keep the registry-completeness
+   assertion green.

package/docs/CLI-SPEC.md

@@ -304,6 +304,30 @@ Recovery is silent in human mode. With `--json`: `"recovered": ["metro.restarted
 **Maps-to:** `sync` ← C:`sync`, D:`sync`,`update\|sync-runtime`; `set` ← C:`setup-wallet\|wallet-setup`,`unlock`,`setup:ios/android`(wallet half).
 **Extension `set`:** [GAP] no standalone path today — the first-run wallet is seeded by the legacy `mme-recipe up`; the end-state home is `fixtures set` (launch / `launch --verify` never seed).
 
+
+## `provision` (REAL → thin mobile setup path)
+
+**Synopsis:** `mm-harness provision [runway ios] [flags]`
+
+Installs the cached Runway iOS dev client onto a prepared mobile slot. It does not install JavaScript dependencies or start Metro; launch owns those at dispatch time. The legacy `install --runway` compatibility path maps to the same adapter surface; new farm callers should use `provision`.
+
+| Flag | Type | Default | ENV (agent) | Audience | Description |
+|---|---|---|---|---|---|
+| `--adapter <mobile\|extension\|core>` | adapter | auto | — | agent | Mobile installs Runway; extension/core teach |
+| `--target <path>` | path | cwd | — | agent | Slot checkout |
+| `--platform <ios>` | string | `ios` | `PLATFORM` | agent | Provisioned platform |
+| `--simulator <name\|udid>` / `--device <name\|udid>` | string | runtime context | `IOS_SIMULATOR` | agent | Target simulator |
+| `--runtime <id>` | string | runtime context | `IOS_RUNTIME` | agent | iOS runtime for simulator creation |
+| `--device-type <id>` | string | runtime context | `IOS_DEVICE_TYPE` | agent | Device type for simulator creation |
+| `--branch <ref>` / `--default-branch <ref>` / `--run <id>` | string | git branch / main | — | agent | Runway artifact selection |
+| `--cache-root <dir>` | path | XDG cache | — | agent | Shared artifact cache |
+| `--slot <id>` | string | runtime context | — | agent | Farm slot id recorded in the provision baseline |
+| `--watcher-port <port>` | number | runtime context | `WATCHER_PORT`/`METRO_PORT` | agent | Metro/watcher port carried through context and rerun hints |
+| `--runtime-dir <dir>` | relative path | `temp/recipe/runtime` | `RECIPE_RUNTIME_DIR` | agent | Runtime directory containing `agentic-runtime.json` and receiving `runway-provision.json` |
+| `--force` | bool | false | — | agent | Reinstall even when the bundle is already present |
+| `--resolve-only` | bool | false | — | agent | Resolve run/revision/artifact metadata only; no simulator creation, cache write, download, install, or baseline write |
+| `--json` | bool | false | — | agent | Machine envelope on stdout; progress/errors on stderr |
+
 ## `run` (ROUTES-NOW → main PROVE verb)
 
 **Synopsis:** `mm-harness run <recipe.json> [flags]` — validate (adapter-aware) + execute a recipe, write evidence.
@@ -714,9 +738,9 @@ a flag + default (`[ENV-GAP]`); internal/agent-only vars are KEEP-INTERNAL;
 **Implemented:** the `[ENV-GAP]` flags exist with resolution order **flag > env >
 config/default** (the flag sets the env var the porcelain reads, so it wins; an
 absent flag leaves the agent/CI env untouched):
-- `launch --device` (`IOS_SIMULATOR` for ios · `ADB_SERIAL`/`ANDROID_SERIAL`/`ANDROID_DEVICE` for android)
+- `launch --device` (`IOS_SIMULATOR` for ios · `ADB_SERIAL`/`ANDROID_SERIAL`/`ANDROID_DEVICE` for android); `provision --device` is an alias for `--simulator`
 - `launch --cdp-port` (`CDP_PORT`/`RECIPE_CDP_PORT`) · `launch --watcher-port` (`WATCHER_PORT`/`METRO_PORT`/`RECIPE_WATCHER_PORT`) — numeric, teaching error otherwise
-- `launch --build` covers `MOBILE_PREFLIGHT_MODE` (tier) · `logs --full`/`--events` cover `RECIPE_LOG_UI`/`RECIPE_LOG_EVENTS`
+- `launch --build` covers `MOBILE_PREFLIGHT_MODE` (tier) · `provision --slot --runtime-dir --watcher-port` accepts farm slot context · `logs --full`/`--events` cover `RECIPE_LOG_UI`/`RECIPE_LOG_EVENTS`
 - `fixtures set --fixture` (`RECIPE_WALLET_FIXTURE`) · `run`/`flows --library` (`RECIPE_LIBRARY_PATH`)
 - `MM_PASSWORD` stays flag-less by design — `fixtures set` reads the password FROM the fixture.
 
@@ -951,4 +975,3 @@ cheapest next action so the path converges rather than rebuilding from scratch):
   tab (closing strays, reopening if needed) and confirms it with the health probe.
 - **Health probe** — read-only liveness probe for the running extension over CDP;
   the final gate of convergence and the standalone answer for `verify`.
-

package/docs/UX-PRINCIPLES.md

@@ -19,6 +19,9 @@ The CLI answers relative to the checkout it is standing in.
   hardcode pool prefixes (they go stale on rename).
 - Output is scoped to the platform: an extension-only field is noise on a mobile
   slot; help, flag lists, and completion candidates shrink to what applies here.
+- Enforcement: platform-specific behavior is resolved through the adapter surface
+  (`getAdapterSurface(adapter)`), never a per-command `if (adapter === …)` ladder —
+  that ladder is how commands go platform-blind. See docs/ADAPTER-SURFACE.md.
 
 ## 2. Never silent, never opaque
 Long operations show intent immediately and progress continuously.

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.9",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
   },
   "scripts": {
+    "build": "node scripts/build-dist.mjs",
+    "prepack": "npm run build",
     "dev:link-farmslot": "node scripts/link-local-farmslot.mjs",
     "check": "node scripts/check.mjs",
     "self-test": "bin/mm-harness self-test",
@@ -26,8 +28,13 @@
     "ws": "8.21.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "esbuild": "0.28.1",
+    "eslint": "^9",
+    "globals": "^17.7.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8"
   },
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -42,6 +49,7 @@
   },
   "files": [
     "bin",
+    "dist",
     "src",
     "adapters",
     "library",

package/src/adapters/core/surface.ts

@@ -0,0 +1,71 @@
+// Core surface: headless. No app, no dev server — dependency presence is the
+// only runtime signal, and lifecycle commands teach the reachable headless path.
+import path from 'node:path';
+
+import { depsCheck } from '@farmslot/recipe-harness/runtime/deps-readiness';
+
+import type {
+  AdapterDevServerStop,
+  AdapterLogSource,
+  AdapterRuntimeStatus,
+  AdapterRunwayProvisionResult,
+  AdapterSurface,
+} from '../surface.ts';
+
+export const coreSurface: AdapterSurface = {
+  adapter: 'core',
+  headless: true,
+
+  resolveSlotPorts(): void {
+    // Headless: no ports or device to resolve.
+  },
+
+  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
+    const deps = depsCheck(path.resolve(target));
+    const ready = deps.status === 'current';
+    return {
+      decision: ready ? 'ready' : 'install',
+      reasonCode: ready ? 'deps-present' : `deps-${deps.status}`,
+      reasons: [
+        ready
+          ? 'Core is headless; dependencies are installed. Run recipes with mm-harness run.'
+          : 'Core is headless; dependencies are not fully installed.',
+      ],
+      deps: deps.status,
+    };
+  },
+
+  runwayProvision: {
+    async run(target, options): Promise<AdapterRunwayProvisionResult> {
+      return {
+        schemaVersion: 1,
+        command: 'provision',
+        adapter: 'core',
+        target: path.resolve(target),
+        status: 'fail',
+        exitCode: 2,
+        error: { code: 'UNSUPPORTED_ADAPTER', message: 'core is headless and has no mobile simulator to provision.', userAction: options.rerunCommand || 'mm-harness run <recipe> --adapter core' },
+      };
+    },
+  },
+
+  devServer: {
+    describe: () => 'no dev server (headless)',
+    stop(): AdapterDevServerStop {
+      return {
+        kind: 'headless',
+        message: 'core is headless — no dev server runs for a core checkout',
+        userAction: 'use mm-harness verify (readiness) or mm-harness run (execute a recipe)',
+      };
+    },
+  },
+
+  logSources(): AdapterLogSource[] {
+    return [];
+  },
+
+  hints: {
+    launch: 'mm-harness run <recipe>   # run recipes against the headless core',
+    relaunch: 'mm-harness verify',
+  },
+};

package/src/adapters/extension/surface.ts

@@ -0,0 +1,88 @@
+// Extension surface: delegates to the existing extension readiness/port plumbing
+// and the webpack watcher stop.
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { recipeRuntimePath } from '../../paths.ts';
+import { resolveExtensionSlotPorts, stopExtensionWatcher } from '../slot-ports.ts';
+import { decideExtensionReadiness } from './runtime-decision.ts';
+import type {
+  AdapterDevServerStop,
+  AdapterLogSource,
+  AdapterRuntimeStatus,
+  AdapterRunwayProvisionResult,
+  AdapterSurface,
+} from '../surface.ts';
+
+// Map the webpack watch-log health onto a dev-server up/down/building/errors
+// status doctor renders the same way as mobile's Metro line.
+function watcherStatus(buildLog: string): string {
+  if (buildLog === 'ok') return 'up';
+  if (buildLog === 'no-watch') return 'down';
+  return buildLog; // 'building' | 'errors'
+}
+
+export const extensionSurface: AdapterSurface = {
+  adapter: 'extension',
+  headless: false,
+
+  resolveSlotPorts(target: string): void {
+    resolveExtensionSlotPorts(target);
+  },
+
+  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
+    const cdpPort = process.env.CDP_PORT ? parseInt(process.env.CDP_PORT, 10) : undefined;
+    const report = await decideExtensionReadiness(target, { cdpPort });
+    return {
+      decision: report.decision,
+      reasonCode: report.reasonCode,
+      reasons: report.reasons,
+      deps: report.checks.deps.status,
+      devServer: { label: 'webpack', status: watcherStatus(report.checks.buildLog.status) },
+    };
+  },
+
+  runwayProvision: {
+    async run(target, options): Promise<AdapterRunwayProvisionResult> {
+      return {
+        schemaVersion: 1,
+        command: 'provision',
+        adapter: 'extension',
+        target: path.resolve(target),
+        status: 'fail',
+        exitCode: 2,
+        error: {
+          code: 'UNSUPPORTED_ADAPTER',
+          message: 'extension uses a browser runtime; Runway mobile provisioning is not supported.',
+          userAction: options.rerunCommand || 'mm-harness provision --adapter extension',
+        },
+      };
+    },
+  },
+
+  devServer: {
+    describe: () => 'webpack watcher',
+    stop(target: string): AdapterDevServerStop {
+      const signalled = stopExtensionWatcher(target);
+      const port = process.env.WATCHER_PORT ?? 'default';
+      spawnSync('tmux', ['kill-window', '-t', `webpack-${port}`], { stdio: 'ignore', timeout: 2000 });
+      const summary = signalled > 0
+        ? `stopped webpack watcher (${signalled} process${signalled === 1 ? '' : 'es'}) for ${target}`
+        : `webpack watcher not running for ${target} — nothing to stop`;
+      return { kind: 'stopped', status: 0, summary, signalled };
+    },
+  },
+
+  logSources(target: string): AdapterLogSource[] {
+    return [
+      { label: 'webpack', path: recipeRuntimePath(target, 'webpack.log') },
+      { label: 'watcher', path: recipeRuntimePath(target, 'recipe-harness-webpack.log') },
+      { label: 'rebuild', path: recipeRuntimePath(target, 'rebuild.log') },
+    ];
+  },
+
+  hints: {
+    launch: 'mm-harness launch',
+    relaunch: 'mm-harness launch --build',
+  },
+};