@deeeed/metamask-harness 0.7.5 → 0.9.0

package/dist/commands/status.js

@@ -0,0 +1,88 @@
+import { color } from "../cli-color.js";
+import { detectAdapter } from "../harness.js";
+import { assertAdapter } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { listConnectedDevices } from "../devices.js";
+import { deviceSelected, renderDeviceList } from "./device-target.js";
+import { probeMobileLiveState } from "./status-probe.js";
+import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
+import { optionFlag, targetPath } from "./parse-args.js";
+async function handleStatus({ options }) {
+  const target = targetPath(options);
+  const json = optionFlag(options, "json");
+  const fast = optionFlag(options, "fast");
+  const adapter = detectAdapter(target);
+  if (!adapter) {
+    return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  assertAdapter(adapter);
+  const devices = adapter === "mobile" ? listConnectedDevices().map((device) => ({ ...device, selected: deviceSelected(device) })) : [];
+  const next = getAdapterSurface(adapter).hints.relaunch;
+  if (json) {
+    const doProbe = !fast && adapter === "mobile" && devices.length > 0;
+    if (doProbe) {
+      const liveMap = await probeMobileLiveState(target, devices);
+      const devicesWithLive = devices.map((d) => mergeDeviceLive(d, liveMap.get(d.id)));
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: "status", adapter, target, devices: devicesWithLive, next },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(
+        JSON.stringify({ schemaVersion: 1, command: "status", adapter, target, devices, next }, null, 2)
+      );
+    }
+    return EXIT.ok;
+  }
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  console.log(`${out("label", "status")} ${out("bold", adapter)} ${out("dim", target)}`);
+  if (adapter === "mobile") renderDeviceList(devices, out);
+  console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
+  if (!fast && adapter === "mobile" && devices.length > 0) {
+    const liveMap = await probeMobileLiveState(target, devices);
+    renderLiveBlock(devices, liveMap, out);
+  }
+  return EXIT.ok;
+}
+function mergeDeviceLive(device, live) {
+  if (!live) return device;
+  return {
+    ...device,
+    fixtureStatus: live.fixtureStatus,
+    ...live.liveState !== void 0 ? { liveState: live.liveState } : {},
+    ...live.currentScreen !== void 0 ? { currentScreen: live.currentScreen } : {},
+    ...live.walletState !== void 0 ? { walletState: live.walletState } : {},
+    ...live.selectedAccount !== void 0 ? { selectedAccount: live.selectedAccount } : {}
+  };
+}
+function renderLiveBlock(devices, liveMap, out) {
+  console.log(`${out("label", "live:")}`);
+  for (const device of devices) {
+    const live = liveMap.get(device.id);
+    const prefix = `  ${device.platform} ${out("dim", device.id)}${device.name ? ` (${device.name})` : ""}`;
+    if (!live || live.liveState === "no-bridge") {
+      console.log(`${prefix}: ${out("dim", "(no-bridge)")}`);
+      continue;
+    }
+    if (live.liveState === "bridge-absent") {
+      console.log(`${prefix}: ${out("warn", "(bridge-absent \u2014 app attached, build lacks __AGENTIC__; rebuild/reinstall a dev build)")}`);
+      continue;
+    }
+    const parts = [];
+    if (live.currentScreen !== void 0) parts.push(`screen=${out("cmd", live.currentScreen)}`);
+    if (live.walletState !== void 0) parts.push(`wallet=${out(live.walletState === "unlocked" ? "ok" : "warn", live.walletState)}`);
+    if (live.selectedAccount !== void 0) {
+      parts.push(`account=${live.selectedAccount.label} ${out("dim", `(${live.selectedAccount.address})`)}`);
+    }
+    if (live.fixtureStatus !== void 0) {
+      parts.push(`fixture=${out(live.fixtureStatus === "READY" ? "ok" : "warn", live.fixtureStatus)}`);
+    }
+    console.log(`${prefix}: ${parts.join("  ")}`);
+  }
+}
+export {
+  handleStatus
+};

package/dist/devices.js

@@ -0,0 +1,66 @@
+import { execFileSync } from "node:child_process";
+function listConnectedDevices(platform) {
+  const devices = [];
+  if (!platform || platform === "android") devices.push(...listAndroidDevices());
+  if (!platform || platform === "ios") devices.push(...listIosSimulators());
+  return devices;
+}
+function listAndroidDevices() {
+  let output;
+  try {
+    output = execFileSync("adb", ["devices", "-l"], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return [];
+  }
+  const devices = [];
+  for (const line of output.split("\n").slice(1)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const fields = trimmed.split(/\s+/u);
+    const id = fields[0];
+    const state = fields[1] ?? "unknown";
+    if (!id) continue;
+    const modelField = fields.find((f) => f.startsWith("model:"));
+    const name = modelField ? modelField.slice("model:".length) : void 0;
+    devices.push({ platform: "android", id, state, ...name ? { name } : {} });
+  }
+  return devices;
+}
+function listIosSimulators() {
+  let output;
+  try {
+    output = execFileSync("xcrun", ["simctl", "list", "devices", "booted", "-j"], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(output);
+  } catch {
+    return [];
+  }
+  const devices = [];
+  for (const runtimeDevices of Object.values(parsed.devices ?? {})) {
+    for (const device of runtimeDevices) {
+      if (!device.udid) continue;
+      devices.push({
+        platform: "ios",
+        id: device.udid,
+        state: device.state ?? "unknown",
+        ...device.name ? { name: device.name } : {}
+      });
+    }
+  }
+  return devices;
+}
+export {
+  listConnectedDevices
+};

package/dist/mm-harness-cli.js

@@ -10,6 +10,40 @@ globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
 const rawArgv = process.argv.slice(2);
 const REAL = [
+  {
+    name: "status",
+    aliases: ["health", "home"],
+    summary: "Home dashboard for a checkout: detected adapter, next command, and (mobile) connected devices with the selected target.",
+    example: "mm-harness status",
+    helpText: `mm-harness status [flags]
+
+  Home dashboard for the current checkout \u2014 the detected adapter, the next command
+  to run, and (mobile only) the connected devices with live app state. Aliases: health, home.
+
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable envelope { adapter, target, devices[], next }
+  --fast                             Skip all live-state probes (instant output, safe for scripts)
+
+  Human output: static device list prints immediately; live-state lines append
+  after the ~2s probe window (screen, wallet, account, fixture per device).
+
+  The devices[] section carries per device:
+    { platform, id, name, state, selected }   always present
+    { currentScreen, walletState, selectedAccount, fixtureStatus }  when bridge reachable
+    { liveState: 'no-bridge' }   when bridge unreachable or --fast
+
+  All RN targets attached to the checkout's Metro are probed and matched to their
+  devices; a device whose target cannot be confidently matched (Metro's device
+  description matches neither the serial nor the model name) degrades to
+  liveState:'no-bridge'. An attached target whose build predates __AGENTIC__
+  reports liveState:'bridge-absent'.
+  Extension/core live-state probing is V1-pending (use doctor for runtime status).
+
+Example:
+  mm-harness status
+  mm-harness status --json
+  mm-harness status --fast`
+  },
   {
     name: "actions",
     summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
@@ -64,6 +98,7 @@ Example:
 
   --list                             List everything invocable for the adapter (actions + flows); no <action> needed
   --arg k=v                          Action field value (repeatable)
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (default: temp dir)
@@ -103,6 +138,7 @@ Example:
 
   --list                             List everything invocable for the adapter (actions + flows); no <recipe> needed
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (required unless --plan)
@@ -128,6 +164,7 @@ Example:
   --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
   --expect-live                      Exit 0 iff the runtime is live (extension: watcher+CDP; mobile: Metro+bridge; core: deps), non-zero + teaching escape otherwise
   --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
+  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). doctor reports the connected devices; it never gates on ambiguity.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
@@ -417,7 +454,7 @@ const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
     blurb: "what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)",
-    commands: ["launch", "stop", "logs", "debug", "fixtures"]
+    commands: ["status", "launch", "stop", "logs", "debug", "fixtures"]
   },
   {
     title: "DISCOVER",
@@ -530,7 +567,9 @@ const pkgVersion = (() => {
 const program = new Command();
 program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").version(pkgVersion, "-v, --version", "Print the mm-harness version").helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
 for (const command of REAL) {
-  program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help").configureHelp({ formatHelp: () => `${command.helpText}
+  const registered = program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help");
+  if (command.aliases?.length) registered.aliases(command.aliases);
+  registered.configureHelp({ formatHelp: () => `${command.helpText}
 ` }).argument("[args...]").action(async () => {
     if (command.name === "update") {
       process.exit(await handleUpdate(rawArgv.slice(1)));

package/docs/CLI-SPEC.md

@@ -437,6 +437,76 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ---
 
+## `--device <id>` — first-class mobile device targeting (REAL)
+
+`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. It sets the **same env `launch` does** before the engine reads `process.env`, so the engine needs no changes: an Android serial → `ADB_SERIAL` + `ANDROID_SERIAL` + `ANDROID_DEVICE`; an iOS UDID/simulator name → `IOS_SIMULATOR`. The android-vs-ios decision comes from matching the id against the connected-device lists (`adb devices -l` + booted `xcrun simctl` simulators); an id that matches neither list is a teaching usage error that lists the connected devices.
+
+| Verb | `--device` given | `--device` omitted (mobile) |
+|---|---|---|
+| `run` / `call` | resolve id → set serial/simulator env; proceed | **ambiguity gate:** >1 connected mobile device (across both android and ios, counting only targetable ones: android state `device`, iOS state `Booted`) → fail fast (exit 2), listing connected devices and `--device <id>` hints. Exactly one targetable (or zero — existing engine errors speak) → unchanged behavior. |
+| `doctor` | resolve id → set env | no gate — doctor is diagnostic and **reports** the device list (`devices[]`) instead. |
+
+`--device` on the **extension/core** adapter is a teaching usage error (those adapters have no device to target). `run --plan` is static (touches no device) and is exempt from the gate.
+
+## `status` (aliases `health`, `home`) — home dashboard + devices[] (REAL)
+
+`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section with live app state. Extension/core checkouts report an empty `devices[]`. Additive envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "status",
+  "adapter": "mobile",
+  "target": "/path/to/checkout",
+  "devices": [
+    {
+      "platform": "android", "id": "emulator-5554", "name": "Pixel_6",
+      "state": "device", "selected": true,
+      "currentScreen": "Wallet", "walletState": "unlocked",
+      "selectedAccount": { "label": "Account 1", "address": "0xabcd…ef12" },
+      "fixtureStatus": "READY"
+    },
+    {
+      "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15",
+      "state": "Booted", "selected": false,
+      "fixtureStatus": "READY", "liveState": "no-bridge"
+    }
+  ],
+  "next": "mm-harness launch ios"
+}
+```
+
+**Per-device live fields** (additive — absent or null when unreachable):
+
+| Field | Type | Description |
+|---|---|---|
+| `currentScreen` | string | Active route/screen in the running app (mobile bridge `status` route field) |
+| `walletState` | `'locked'\|'unlocked'\|'onboarding'` | Derived from bridge status: account present → unlocked; onboarding route → onboarding; else locked |
+| `selectedAccount` | `{ label, address }` | Active account name + address truncated to `0x1234…abcd` form |
+| `fixtureStatus` | `'READY'\|'missing'` | Checkout-level: whether `wallet-fixture.json` is present and well-formed |
+| `liveState` | `'no-bridge'\|'bridge-absent'` | Set when the bridge is unreachable/times out (`no-bridge`) or the target answers but `__AGENTIC__` is absent (`bridge-absent`); live fields omitted in both cases |
+
+**`--fast` flag:** skips all live-state probes. Output is instant (same envelope shape, live fields absent). Safe for scripts and CI where probe latency is unacceptable.
+
+**Human output** is progressive: static info (adapter, device list, next) prints immediately; a `live:` block appends after the ~2s probe window closes. `--fast` suppresses the live block entirely.
+
+`selected` is `true` when the device id matches `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
+
+The mobile bridge probes all connected RN targets in one call and returns an array; each device is matched to its entry by name or platform-uniqueness, so multi-device checkouts (e.g. Android + iOS simulator) receive per-device live state.
+
+`liveState` in the JSON envelope (absent = fully enriched):
+
+| Value | Meaning |
+|---|---|
+| `'no-bridge'` | No matching/responding target on Metro — bridge genuinely unreachable or app not running. |
+| `'bridge-absent'` | Target IS reachable and answered Runtime.evaluate, but `typeof globalThis.__AGENTIC__ === 'undefined'` — the installed build predates the bridge. Reinstall a dev build to get live state. |
+
+Extension/core live-state probing (CDP home-tab route) is V1-pending — use `doctor` for runtime status.
+
+**Exit:** 0 (2 when the repo type cannot be detected).
+
+---
+
 ## DISCOVER — agent composition input
 
 > **Decided (Arthur):** DISCOVER is a distinct group, not a sub-PROVE. The audience