@deeeed/metamask-harness 0.41.1 → 0.42.0

package/library/actions/shared/app/network-assert.mjs

@@ -0,0 +1,154 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+
+import { resolveNetworkArtifact } from './network-artifact.mjs';
+
+export async function assertNetwork(input) {
+  const node = input.node ?? {};
+  const id = String(node.id ?? '').trim();
+  const artifactsDir = input.context?.artifactsDir;
+  if (!id || !artifactsDir) {
+    throw new Error('app.network_assert requires id and artifactsDir.');
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`,
+  );
+  const artifactFile = resolveNetworkArtifact(artifactsDir, artifactPath);
+  const handle = await open(
+    artifactFile,
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  );
+  let summary;
+  try {
+    const artifactStat = await handle.stat();
+    if (!artifactStat.isFile() || artifactStat.size > 5 * 1024 * 1024) {
+      throw new Error(
+        'app.network_assert summary is not a bounded regular file.',
+      );
+    }
+    summary = JSON.parse(await handle.readFile('utf8'));
+  } finally {
+    await handle.close();
+  }
+  validateSummary(summary, id);
+
+  const requiredStatus = node.required_status;
+  if (requiredStatus && summary.status !== requiredStatus) {
+    throw new Error(
+      `app.network_assert expected ${requiredStatus}, got ${summary.status}.`,
+    );
+  }
+  const requiredMinRequests = node.required_min_requests;
+  const requiredMaxRequests = node.required_max_requests;
+  const requiredTypes = node.required_types ?? [];
+  const forbiddenTypes = node.forbidden_types ?? [];
+  if (
+    (requiredTypes.length > 0 || forbiddenTypes.length > 0) &&
+    !summary.projectedBodyFields.includes('type')
+  ) {
+    throw new Error(
+      'app.network_assert type assertions require body_json_fields to include type.',
+    );
+  }
+  if (
+    (requiredMaxRequests !== undefined || forbiddenTypes.length > 0) &&
+    requiredStatus !== 'complete'
+  ) {
+    throw new Error(
+      'app.network_assert negative assertions require required_status=complete.',
+    );
+  }
+  for (const [name, value] of [
+    ['required_min_requests', requiredMinRequests],
+    ['required_max_requests', requiredMaxRequests],
+  ]) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+      throw new Error(`app.network_assert ${name} is invalid.`);
+    }
+  }
+  if (
+    Number.isInteger(requiredMinRequests) &&
+    Number.isInteger(requiredMaxRequests) &&
+    requiredMinRequests > requiredMaxRequests
+  ) {
+    throw new Error('app.network_assert request assertion range is invalid.');
+  }
+  if (
+    Number.isInteger(requiredMinRequests) &&
+    summary.totalRequests < requiredMinRequests
+  ) {
+    throw new Error(
+      `app.network_assert expected at least ${requiredMinRequests} request(s), got ${summary.totalRequests}.`,
+    );
+  }
+  if (
+    Number.isInteger(requiredMaxRequests) &&
+    summary.totalRequests > requiredMaxRequests
+  ) {
+    throw new Error(
+      `app.network_assert expected at most ${requiredMaxRequests} request(s), got ${summary.totalRequests}.`,
+    );
+  }
+  for (const type of requiredTypes) {
+    if (!hasPositiveOwnCount(summary.requestsByType, type)) {
+      throw new Error(`app.network_assert did not observe required type ${type}.`);
+    }
+  }
+  for (const type of forbiddenTypes) {
+    if (hasPositiveOwnCount(summary.requestsByType, type)) {
+      throw new Error(`app.network_assert observed forbidden type ${type}.`);
+    }
+  }
+
+  return {
+    action: input.action,
+    id,
+    artifactPath,
+    status: summary.status,
+    totalRequests: summary.totalRequests,
+  };
+}
+
+function hasPositiveOwnCount(counts, key) {
+  return (
+    Object.hasOwn(counts, key) &&
+    Number.isInteger(counts[key]) &&
+    counts[key] > 0
+  );
+}
+
+function validateSummary(summary, expectedId) {
+  if (
+    !summary ||
+    typeof summary !== 'object' ||
+    Array.isArray(summary) ||
+    summary.schemaVersion !== 1 ||
+    summary.id !== expectedId ||
+    !['complete', 'partial', 'unavailable'].includes(summary.status) ||
+    !Number.isInteger(summary.totalRequests) ||
+    summary.totalRequests < 0 ||
+    !Array.isArray(summary.requests) ||
+    summary.requests.length !== summary.totalRequests ||
+    !Number.isInteger(summary.uninspectableBodyRequests) ||
+    summary.uninspectableBodyRequests < 0 ||
+    !Array.isArray(summary.projectedBodyFields) ||
+    summary.projectedBodyFields.some((field) => typeof field !== 'string') ||
+    !summary.requestsByType ||
+    typeof summary.requestsByType !== 'object' ||
+    Array.isArray(summary.requestsByType)
+  ) {
+    throw new Error('app.network_assert summary contract is invalid.');
+  }
+  const typeCounts = Object.values(summary.requestsByType);
+  for (const count of typeCounts) {
+    if (!Number.isInteger(count) || count < 1) {
+      throw new Error('app.network_assert summary type counts are invalid.');
+    }
+  }
+  if (
+    typeCounts.reduce((total, count) => total + count, 0) !==
+    summary.totalRequests
+  ) {
+    throw new Error('app.network_assert summary type counts are inconsistent.');
+  }
+}

package/library/manifests/extension.action-manifest.json

@@ -1119,6 +1119,94 @@
         }
       ]
     },
+    "app.network_capture": {
+      "description": "Capture redacted HTTP requests between named Recipe Protocol v1 nodes through the adapter's persistent Network observer.",
+      "examples": [
+        {
+          "action": "app.network_capture",
+          "phase": "start",
+          "id": "perps-home",
+          "url_includes": ["api.hyperliquid.xyz/info"],
+          "methods": ["POST"],
+          "body_json_fields": ["type", "req.coin", "dex"],
+          "intent": "Start the redacted request window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "app.network_capture",
+          "phase": "end",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "intent": "End and index the redacted request window",
+          "next": "assert-network"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": { "type": "string", "enum": ["start", "end"] },
+          "id": { "type": "string" },
+          "url_includes": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "methods": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "body_json_fields": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "max_requests": { "type": "integer" },
+          "max_duration_ms": { "type": "integer" },
+          "artifact_path": { "type": "string" }
+        },
+        "required": ["phase", "id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
+    "app.network_assert": {
+      "description": "Assert a previously indexed app.network_capture summary without hiding its diagnostics on failure.",
+      "examples": [
+        {
+          "action": "app.network_assert",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "required_status": "complete",
+          "required_min_requests": 1,
+          "required_types": ["allMids"],
+          "forbidden_types": ["candleSnapshot"],
+          "intent": "Assert the indexed request summary",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "artifact_path": { "type": "string" },
+          "required_status": {
+            "type": "string",
+            "enum": ["complete", "partial", "unavailable"]
+          },
+          "required_min_requests": { "type": "integer" },
+          "required_max_requests": { "type": "integer" },
+          "required_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "forbidden_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
     "app.status": {
       "description": "Report the adapter's static status — platform, project root, resolved checkout shape, and headless compatibility mode (no live route or account).",
       "examples": [

package/library/manifests/mobile.action-manifest.json

@@ -1112,6 +1112,113 @@
       },
       "execution_capabilities": ["app-mutation"]
     },
+    "app.network_capture": {
+      "description": "Capture redacted HTTP requests between named Recipe Protocol v1 nodes through the adapter's persistent Network observer.",
+      "examples": [
+        {
+          "action": "app.network_capture",
+          "phase": "start",
+          "id": "perps-home",
+          "url_includes": ["api.hyperliquid.xyz/info"],
+          "methods": ["POST"],
+          "body_json_fields": ["type", "req.coin", "dex"],
+          "intent": "Start the redacted request window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "app.network_capture",
+          "phase": "end",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "intent": "End and index the redacted request window",
+          "next": "assert-network"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "type": "string",
+            "enum": ["start", "end"]
+          },
+          "id": {
+            "type": "string"
+          },
+          "url_includes": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "methods": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "body_json_fields": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "max_requests": {
+            "type": "integer"
+          },
+          "max_duration_ms": {
+            "type": "integer"
+          },
+          "artifact_path": {
+            "type": "string"
+          }
+        },
+        "required": ["phase", "id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
+    "app.network_assert": {
+      "description": "Assert a previously indexed app.network_capture summary without hiding its diagnostics on failure.",
+      "examples": [
+        {
+          "action": "app.network_assert",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "required_status": "complete",
+          "required_min_requests": 1,
+          "required_types": ["allMids"],
+          "forbidden_types": ["candleSnapshot"],
+          "intent": "Assert the indexed request summary",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "artifact_path": {
+            "type": "string"
+          },
+          "required_status": {
+            "type": "string",
+            "enum": ["complete", "partial", "unavailable"]
+          },
+          "required_min_requests": {
+            "type": "integer"
+          },
+          "required_max_requests": {
+            "type": "integer"
+          },
+          "required_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "forbidden_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
     "app.status": {
       "description": "Report the adapter's static status — platform, project root, resolved checkout shape, and headless compatibility mode (no live route or account).",
       "examples": [

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

@@ -168,25 +168,25 @@
         "value": "{{params.content_variant}}",
         "equals": "trending",
         "cases": {
-          "match": "assert-no-positions"
+          "match": "ensure-no-positions"
         },
         "default": "assert-position",
-        "intent": "Prove either the existing position or the empty account before timing"
+        "intent": "Prepare either the existing position or an empty account before timing"
       },
-      "assert-no-positions": {
-        "action": "metamask.perps.assert_positions",
+      "ensure-no-positions": {
+        "action": "metamask.perps.ensure_positions",
         "state": "none",
         "mode": "all",
-        "timeout_ms": 30000,
-        "intent": "Prove the market-only account has no open positions",
-        "next": "assert-no-orders"
+        "timeout_ms": 120000,
+        "intent": "Close all positions outside timing so the market-only account is empty",
+        "next": "ensure-no-orders"
       },
-      "assert-no-orders": {
-        "action": "metamask.perps.assert_orders",
+      "ensure-no-orders": {
+        "action": "metamask.perps.ensure_orders",
         "state": "none",
         "mode": "all",
-        "timeout_ms": 30000,
-        "intent": "Prove the market-only account has no open orders",
+        "timeout_ms": 120000,
+        "intent": "Cancel all orders outside timing so the market-only account is empty",
         "next": "select-account-switch-preparation"
       },
       "assert-position": {

package/package.json

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

package/scripts/completions.sh

@@ -29,7 +29,7 @@ _mmh_bin() {
   return 1
 }
 
-_mmh_commands="launch stop logs debug fixtures actions call run doctor check checklist execution-template recipe-quality install verify cleanup completions"
+_mmh_commands="launch stop logs debug reload fixtures actions call run doctor check checklist execution-template recipe-quality install verify cleanup completions"
 
 # Per-command flags (static, from the mm-harness surface).
 _mmh_flags_for() {
@@ -38,6 +38,7 @@ _mmh_flags_for() {
     stop)     printf '%s' "--port --target --json" ;;
     logs)     printf '%s' "--full --events --source --adapter --target --json" ;;
     debug)    printf '%s' "--worker --dev-menu --adapter --target --json" ;;
+    reload)   printf '%s' "--adapter --platform --target --json" ;;
     fixtures) printf '%s' "--from --dev --force --fixture --adapter --target --json" ;;
     checklist) printf '%s' "" ;;
     execution-template) printf '%s' "--dir --domain-dir --project-worker --project-name --package-templates --package-id --flow --run-mode --platform --domain --id --provenance --include-shadowed --no-include-shadowed --title --force --json" ;;