@deeeed/metamask-harness 0.4.0 → 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/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/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.4.0",
+  "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",
@@ -28,6 +30,7 @@
   "devDependencies": {
     "@eslint/js": "^9",
     "@types/node": "^22.0.0",
+    "esbuild": "0.28.1",
     "eslint": "^9",
     "globals": "^17.7.0",
     "typescript": "^5.6.0",
@@ -46,6 +49,7 @@
   },
   "files": [
     "bin",
+    "dist",
     "src",
     "adapters",
     "library",

package/src/adapters/core/surface.ts

@@ -8,6 +8,7 @@ import type {
   AdapterDevServerStop,
   AdapterLogSource,
   AdapterRuntimeStatus,
+  AdapterRunwayProvisionResult,
   AdapterSurface,
 } from '../surface.ts';
 
@@ -34,6 +35,20 @@ export const coreSurface: AdapterSurface = {
     };
   },
 
+  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 {

package/src/adapters/extension/surface.ts

@@ -1,6 +1,7 @@
 // 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';
@@ -9,6 +10,7 @@ import type {
   AdapterDevServerStop,
   AdapterLogSource,
   AdapterRuntimeStatus,
+  AdapterRunwayProvisionResult,
   AdapterSurface,
 } from '../surface.ts';
 
@@ -40,11 +42,28 @@ export const extensionSurface: AdapterSurface = {
     };
   },
 
+  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);
-      // Best-effort: close the webpack tail window this checkout's watcher owned.
       const port = process.env.WATCHER_PORT ?? 'default';
       spawnSync('tmux', ['kill-window', '-t', `webpack-${port}`], { stdio: 'ignore', timeout: 2000 });
       const summary = signalled > 0
@@ -55,8 +74,6 @@ export const extensionSurface: AdapterSurface = {
   },
 
   logSources(target: string): AdapterLogSource[] {
-    // Most-relevant first: the live webpack log, the harness-owned watcher log,
-    // then the quick-relaunch rebuild log. `logs` tails the first that exists.
     return [
       { label: 'webpack', path: recipeRuntimePath(target, 'webpack.log') },
       { label: 'watcher', path: recipeRuntimePath(target, 'recipe-harness-webpack.log') },