@deeeed/metamask-harness 0.91.1 → 0.91.3

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.91.3 - 2026-10-13
+
+### Fixed
+
+- Give Mobile `perps.smoke` executable `smoke` and `cleanup` proof targets for live conformance. Assert live controller reads, bind a HUD screenshot to the smoke, and observe wallet home in teardown, including after a failed smoke.
+
+## 0.91.2 - 2026-10-13
+
+### Added
+
+- Support the registered terminal-backend pack through the public provider, with pack-owned startup, invocation-owned teardown and indexed attempt logs. Backend recipes inherit the shared engine.
+- Forward existing shared QA suite, recipe digest, owned-process and portability helpers through the public provider so dependency-free packs can use their installed tooling.
+
 ## 0.91.1 - 2026-10-12
 
 ### Fixed

package/adapters/terminal-backend/action-manifest.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://farmslot.io/schemas/action-manifest-v1.schema.json",
+  "actions": {
+    "end": { "description": "Finish a headless recipe.", "examples": [{ "action": "end", "status": "pass" }] }
+  }
+}

package/dist/adapters/terminal-backend/provider.js

@@ -0,0 +1,152 @@
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { defineAdapter } from "@farmslot/adapter-sdk";
+import { indexArtifactManifest, isRecipeExecution, usageError, writeContainedArtifact } from "@farmslot/recipe-cli/harness";
+import { validatePackPortability } from "@farmslot/protocol/node/pack-portability";
+async function createBackendProvider(context) {
+  if (!context.project?.root || !path.isAbsolute(context.project.root)) {
+    throw usageError("terminal-backend requires a registered project root.");
+  }
+  const root = fs.realpathSync(context.project.root);
+  const lifecycle = fs.realpathSync(path.join(root, "scripts/backend.mjs"));
+  if (!lifecycle.startsWith(root + path.sep)) throw usageError("Backend lifecycle must belong to the registered pack.");
+  const { configuration, health, main } = await import(pathToFileURL(lifecycle).href);
+  const target = context.target.value;
+  const ports = context.slot && "ports" in context.slot ? context.slot.ports : {};
+  const cfg = () => {
+    const state = path.join(target, ".agent/terminal-backend/service.json");
+    const record = fs.existsSync(state) ? JSON.parse(fs.readFileSync(state, "utf8")) : {};
+    return configuration(
+      target,
+      context.options?.watcherPort ?? ports.port ?? ports.devServerPort ?? record.api,
+      ports.redis_port ?? record.redis,
+      context.slot?.value ?? record.slot
+    );
+  };
+  const args = (action) => {
+    const c = cfg();
+    return [action, c.checkout, String(c.api), String(c.redis), c.slot];
+  };
+  const executing = isRecipeExecution(context.command, context.options ?? {});
+  if (executing) cfg();
+  const owner = executing ? randomBytes(16).toString("hex") : void 0;
+  const previous = /* @__PURE__ */ new Map();
+  const setEnv = (key, value) => {
+    if (!previous.has(key)) previous.set(key, process.env[key]);
+    process.env[key] = value;
+  };
+  const serviceLog = path.join(target, ".agent/terminal-backend/service.log");
+  const logOffset = fs.existsSync(serviceLog) ? fs.statSync(serviceLog).size : 0;
+  const output = path.resolve(target, String(context.options?.artifactsDir ?? context.project.artifactDir));
+  const manifest = path.join(output, "artifact-manifest.json");
+  const manifestIdentity = () => {
+    try {
+      const s = fs.statSync(manifest, { bigint: true });
+      return [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].join(":");
+    } catch (error) {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    }
+  };
+  const previousManifest = manifestIdentity();
+  if (owner) {
+    setEnv("BACKEND_OWNER_ID", owner);
+    setEnv("BACKEND_LIFECYCLE_SCRIPT", lifecycle);
+  }
+  const cleanup = async () => {
+    if (owner) await main([...args("stop"), owner]);
+  };
+  const logSource = () => ({ label: "NestJS and monitor", path: serviceLog });
+  const hint = "Prepare the selected slot with the full profile.";
+  const runtime = defineAdapter({
+    id: "terminal-backend",
+    sdkVersion: 1,
+    targets: ["cli"],
+    headless: true,
+    resolveSlotPorts() {
+      const c = cfg();
+      setEnv("BACKEND_API_PORT", String(c.api));
+      setEnv("BACKEND_REDIS_PORT", String(c.redis));
+      setEnv("BACKEND_SLOT_ID", c.slot);
+    },
+    async runtimeStatus() {
+      try {
+        await health(cfg());
+        return { decision: "ready", reasons: ["Redis and a fresh complete v3 snapshot are ready."] };
+      } catch (error) {
+        return { decision: "blocked", reasons: [error.message], nextAction: hint };
+      }
+    },
+    readiness: { statusRuntime: true, captureProviders: [], readyIndicator: () => "OK" },
+    logSources: () => [logSource()],
+    appLogSource: logSource,
+    hints: { launch: hint, relaunch: hint, runtimeProbeRecovery: () => "Inspect the slot service.log and run farmslot doctor --conformance." },
+    devServer: {
+      label: "NestJS",
+      describe: () => "Slot backend",
+      stop() {
+        const result = spawnSync(process.execPath, [lifecycle, ...args("stop"), owner ?? ""], { encoding: "utf8", timeout: 3e4 });
+        if (result.error || result.status !== 0) throw result.error ?? new Error(result.stderr);
+        return { kind: "headless", message: "Backend stopped; Redis volume retained.", userAction: hint };
+      }
+    },
+    harness: {
+      // Installation and destructive cleanup belong to the pack's lifecycle hooks.
+      install: { entry: "", fallback: "" },
+      cleanup: { entry: "", fallback: "" },
+      verify: () => ({ inProcess: async () => async (_args, io) => {
+        const result = await validatePackPortability(root);
+        if (result.length) throw new Error(result.join("\n"));
+        io.out("Portable headless API provider; capture and HUD are unsupported.");
+        return 0;
+      } })
+    },
+    runtimeContext: { forbiddenFields: ["cdpPort", "metroPort", "simulator", "adbSerial", "extensionId"] },
+    launch: async () => {
+      await main(args("start"));
+      return 0;
+    },
+    actions: {
+      manifestPath: () => {
+        const product = path.join(target, "tests/recipes/action-manifest.json");
+        return fs.existsSync(product) ? product : fileURLToPath(new URL("../../../adapters/terminal-backend/action-manifest.json", import.meta.url));
+      },
+      semantic: [],
+      cdpTarget: { transport: "none", probePath: "" }
+    }
+  });
+  if (executing) runtime.resolveSlotPorts();
+  let finalized = false;
+  return {
+    runtime,
+    ...owner ? {
+      cancel: cleanup,
+      async finalize() {
+        if (finalized) return;
+        finalized = true;
+        try {
+          try {
+            await cleanup();
+          } finally {
+            const currentManifest = manifestIdentity();
+            if (fs.existsSync(serviceLog) && currentManifest !== void 0 && currentManifest !== previousManifest) {
+              await writeContainedArtifact(output, "logs/backend.log", fs.readFileSync(serviceLog).subarray(logOffset), "Backend logs");
+              await indexArtifactManifest(manifest, [{ category: "log", label: "Backend and monitor logs", path: "logs/backend.log", type: "text" }]);
+            }
+          }
+        } finally {
+          for (const [key, value] of previous) {
+            if (value === void 0) delete process.env[key];
+            else process.env[key] = value;
+          }
+        }
+      }
+    } : {}
+  };
+}
+export {
+  createBackendProvider
+};

package/dist/provider.js

@@ -9,6 +9,7 @@ import {
   optionStrings,
   usageError
 } from "@farmslot/recipe-cli/harness";
+import { createAdapterRegistry } from "@farmslot/adapter-sdk";
 import { MAINNET_RUN_OWNER_ENV } from "../library/actions/shared/perps/mainnet-order-ledger.mjs";
 import { adoptPluginAdapter, afterAdapterLoad, configuredLibrarySources, operatorLibraryEnv } from "./adapters/plugin-surface.js";
 import { abortRunMainnetOrders, cancelRunMainnetOrders } from "./adapters/perps-mainnet-cleanup.js";
@@ -20,14 +21,26 @@ import { providerHost } from "./host.js";
 import { configureProviderReadiness, doctorOptions } from "./provider-doctor.js";
 import { statusOptions, stopOptions } from "./provider-lifecycle.js";
 import { createLogsOptions } from "./provider-logs.js";
+import { createBackendProvider } from "./adapters/terminal-backend/provider.js";
 import { providerHost as providerHost2 } from "./host.js";
 import { PUBLIC_COMMANDS } from "./command-contract.js";
+import { digestRecipeDocument, RECIPE_SUITE_SCOPE_SCHEMA_URL, validateRecipeActionManifestDocument } from "@farmslot/protocol";
+import { validatePackPortability, packMachineNames } from "@farmslot/protocol/node/pack-portability";
+import { freezeRecipeSuiteScope, finalizeRecipeSuite, digestRecipeLibrary } from "@farmslot/recipe-runner";
+import { runOwnedRecipeProcess } from "@farmslot/recipe-runner/adapters/core";
+import { withRecipeSignals } from "@farmslot/recipe-cli/harness";
 async function createProvider(context) {
   configureHarnessHost(context.host ?? providerHost);
   configureHarnessAdapters(adapterRegistry);
   const selection = context.adapter?.value;
   if (!selection) throw usageError("The MetaMask provider requires a resolved adapter.");
   const adapter = adapterForPlatform(selection) ?? selection;
+  if (adapter === "terminal-backend") {
+    const registry = createAdapterRegistry();
+    for (const id of adapterRegistry.list()) registry.register(adapterRegistry.get(id));
+    configureHarnessAdapters(registry);
+    return createBackendProvider(context);
+  }
   const options = {
     ...context.options,
     ...!context.options?.platform && (selection === "ios" || selection === "android") ? { platform: selection } : {}
@@ -73,7 +86,17 @@ async function createProvider(context) {
   };
 }
 export {
+  RECIPE_SUITE_SCOPE_SCHEMA_URL,
   createProvider,
+  digestRecipeDocument,
+  digestRecipeLibrary,
+  finalizeRecipeSuite,
+  freezeRecipeSuiteScope,
+  packMachineNames,
   PUBLIC_COMMANDS as providerCommands,
-  providerHost2 as providerHost
+  providerHost2 as providerHost,
+  runOwnedRecipeProcess,
+  validatePackPortability,
+  validateRecipeActionManifestDocument,
+  withRecipeSignals
 };

package/docs/TERMINAL-BACKEND-PROVIDER.md

@@ -0,0 +1,21 @@
+# Terminal backend provider
+
+Registered backend packs select `@deeeed/metamask-harness/provider` and adapter `terminal-backend`. The pool supplies the installed package through `MM_HARNESS_PACKAGE_ROOT`. The shared project loader supplies `project.root`, the directory containing the registered pack's `project.json`.
+
+The provider imports that pack's `scripts/backend.mjs` and uses its existing `configuration`, `health` and `main` functions. The pack owns service startup, health checks, Redis ports, startup recovery and volumes. Slot resources must supply the API port and `redis_port`; there is no default Redis port. Installation and destructive cleanup run through pack hooks, not harness overlay installation.
+
+Backend recipes inherit the shared engine. Their action manifest lives at the selected checkout's `tests/recipes/action-manifest.json`; a packaged `end` manifest supports an empty checkout during planning. Recipe assets remain with the backend code. No backend recipes or generic runner implementations are bundled here.
+
+Executing `run` and `call` invocations assign a unique `BACKEND_OWNER_ID` and expose `BACKEND_LIFECYCLE_SCRIPT` and slot ports to action children. Cancellation and finalization stop only that owner through the pack lifecycle. Finalization indexes the current attempt's service log when this invocation creates or updates the shared artifact manifest and restores caller environment values. Early startup failures leave previous evidence packages untouched; service diagnostics remain in the slot's runtime log. Attached services keep their existing ownership. Previews assign no owner and start no services. Capture and HUD are unsupported for this headless runtime.
+
+The public provider forwards these existing shared APIs for dependency-free packs. Their contracts and versions remain owned by the listed packages:
+
+| Package | Forwarded exports |
+| --- | --- |
+| `@farmslot/protocol` | `digestRecipeDocument`, `RECIPE_SUITE_SCOPE_SCHEMA_URL`, `validateRecipeActionManifestDocument` |
+| `@farmslot/protocol/node/pack-portability` | `validatePackPortability`, `packMachineNames` |
+| `@farmslot/recipe-runner` | `freezeRecipeSuiteScope`, `finalizeRecipeSuite`, `digestRecipeLibrary` |
+| `@farmslot/recipe-runner/adapters/core` | `runOwnedRecipeProcess` |
+| `@farmslot/recipe-cli/harness` | `withRecipeSignals` |
+
+The backend pack's mandatory QA gate consumes the suite, digest, process and signal APIs. Its CI and prerequisite hooks consume portability. Packs import the public provider export and do not resolve private files or transitive package paths.

package/library/recipes/mobile/perps/smoke-observation.recipe.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "MetaMask Mobile Perps smoke observation",
+  "description": "Observe live Perps positions and orders and capture the current screen. Caller opens Perps before this read-only proof.",
+  "workflow": {
+    "entry": "read-positions",
+    "nodes": {
+      "read-positions": {
+        "action": "metamask.perps.read_positions",
+        "next": "assert-positions",
+        "intent": "Read live Perps positions without changing account state"
+      },
+      "assert-positions": {
+        "action": "assert_output",
+        "source": "read-positions",
+        "assert": {
+          "all": [
+            {
+              "path": "$.source",
+              "operator": "eq",
+              "value": "mobile-perps-controller"
+            },
+            {
+              "path": "$.count",
+              "operator": "gte",
+              "value": 0
+            },
+            {
+              "path": "$.positions",
+              "operator": "not_null"
+            }
+          ]
+        },
+        "next": "read-orders",
+        "intent": "Verify the live controller returned Perps positions"
+      },
+      "read-orders": {
+        "action": "metamask.perps.read_orders",
+        "next": "assert-orders",
+        "intent": "Read live Perps orders without changing account state"
+      },
+      "assert-orders": {
+        "action": "assert_output",
+        "source": "read-orders",
+        "assert": {
+          "all": [
+            {
+              "path": "$.source",
+              "operator": "eq",
+              "value": "mobile-perps-controller-open-orders"
+            },
+            {
+              "path": "$.count",
+              "operator": "gte",
+              "value": 0
+            },
+            {
+              "path": "$.orders",
+              "operator": "not_null"
+            }
+          ]
+        },
+        "next": "capture",
+        "intent": "Verify the live controller returned Perps orders"
+      },
+      "capture": {
+        "action": "ui.screenshot",
+        "path": "screenshots/perps-smoke.png",
+        "next": "done",
+        "intent": "Keep a view of the Perps screen after verifying live account reads"
+      },
+      "done": {
+        "action": "end",
+        "status": "pass"
+      }
+    }
+  }
+}

package/library/recipes/mobile/perps/smoke.recipe.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "MetaMask Mobile Perps smoke",
-  "description": "Non-mutating Perps domain smoke for MetaMask Mobile: verifies the live bridge, unlocks if needed, opens the Perps market list, and reads live Perps positions and orders.",
+  "description": "Non-mutating Perps domain smoke for debug-enabled MetaMask Mobile: unlock if needed, open Perps, assert live positions and orders, and retain a HUD screenshot. Teardown observes wallet home. Does not close positions or stop the app.",
   "workflow": {
     "entry": "status",
     "nodes": {
@@ -27,23 +27,64 @@
       "open-perps": {
         "action": "ui.navigate",
         "page": "perps",
-        "next": "read-positions",
+        "next": "observe-perps",
         "intent": "Show the Perps market list"
       },
-      "read-positions": {
-        "action": "metamask.perps.read_positions",
-        "next": "read-orders",
-        "intent": "Read live Perps positions without mutating account state"
-      },
-      "read-orders": {
-        "action": "metamask.perps.read_orders",
+      "observe-perps": {
+        "action": "call",
+        "ref": "perps.smoke-observation",
+        "proves": [
+          "smoke"
+        ],
         "next": "done",
-        "intent": "Read live Perps open orders without mutating account state"
+        "intent": "Verify live Perps reads and capture the screen with its intent HUD"
       },
       "done": {
         "action": "end",
         "status": "pass"
+      },
+      "cleanup-home": {
+        "action": "ui.navigate",
+        "page": "home",
+        "next": "cleanup-state",
+        "intent": "Return wallet home after Perps smoke"
+      },
+      "cleanup-state": {
+        "action": "metamask.wallet.read_state",
+        "next": "cleanup-assert",
+        "intent": "Observe the wallet route after returning home"
+      },
+      "cleanup-assert": {
+        "action": "assert_output",
+        "source": "cleanup-state",
+        "assert": {
+          "path": "$.route.name",
+          "operator": "eq",
+          "value": "WalletView"
+        },
+        "proves": [
+          "cleanup"
+        ],
+        "next": "cleanup-done",
+        "intent": "Verify wallet home was reached during cleanup"
+      },
+      "cleanup-done": {
+        "action": "end",
+        "status": "pass"
       }
+    },
+    "teardown": "cleanup-home"
+  },
+  "proofTargets": [
+    {
+      "id": "smoke",
+      "claim": "The live Mobile Perps controller returns positions and open orders.",
+      "proofMode": "state"
+    },
+    {
+      "id": "cleanup",
+      "claim": "The wallet reports WalletView after returning home from Perps.",
+      "proofMode": "state"
     }
-  }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.91.1",
+  "version": "0.91.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"