@deeeed/metamask-harness 0.42.0 → 0.44.0

package/dist/run-diagnostics.js

@@ -8,6 +8,7 @@ import { ensureExtensionConsoleCapture } from "./adapters/extension/console-capt
 const MAX_CAPTURE_BYTES = 512 * 1024;
 const MAX_FINDINGS = 20;
 const MAX_PREVIEW_CHARS = 320;
+const RAW_APP_LOG_ARTIFACT = "diagnostics-app-log.txt";
 function readRunDiagnosticsDocument(diagnosticsPath) {
   if (typeof diagnosticsPath !== "string" || diagnosticsPath.length === 0) return null;
   try {
@@ -53,11 +54,15 @@ function finishRunDiagnostics(baseline, result) {
   if (!baseline) return result;
   try {
     const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
-    const diagnostics = collectRunDiagnostics(baseline, bufferedIssues);
+    const { diagnostics, rawAppLog } = collectRunDiagnosticsCapture(baseline, bufferedIssues);
     const artifactsDir = path.dirname(result.summaryPath);
     const diagnosticsPath = path.join(artifactsDir, "diagnostics.json");
     fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}
 `);
+    fs.writeFileSync(
+      path.join(artifactsDir, RAW_APP_LOG_ARTIFACT),
+      redactDiagnosticText(rawAppLog.toString("utf8"))
+    );
     indexDiagnosticArtifact(result.artifactManifestPath);
     indexDiagnosticSummary(result.summaryPath, diagnostics);
     return {
@@ -83,6 +88,9 @@ function finishRunDiagnostics(baseline, result) {
   }
 }
 function collectRunDiagnostics(baseline, bufferedIssues) {
+  return collectRunDiagnosticsCapture(baseline, bufferedIssues).diagnostics;
+}
+function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
   const stat = safeStat(baseline.source.path);
   const source = {
     label: baseline.source.label,
@@ -91,9 +99,11 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
     endOffset: stat?.size ?? baseline.offset,
     bytesRead: 0,
     truncated: false,
-    inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected"
+    inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected",
+    rawArtifact: RAW_APP_LOG_ARTIFACT,
+    redacted: true
   };
-  let text = "";
+  let rawAppLog = Buffer.alloc(0);
   if (stat) {
     const sameFile = baseline.inode === void 0 || baseline.inode === stat.ino;
     const startOffset = sameFile && stat.size >= baseline.offset ? baseline.offset : 0;
@@ -103,8 +113,9 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
     source.endOffset = stat.size;
     source.bytesRead = bytesToRead;
     source.truncated = available > MAX_CAPTURE_BYTES;
-    if (bytesToRead > 0) text = readSlice(baseline.source.path, startOffset, bytesToRead);
+    if (bytesToRead > 0) rawAppLog = readSlice(baseline.source.path, startOffset, bytesToRead);
   }
+  const text = rawAppLog.toString("utf8");
   const allFindings = dedupeFindings(
     [
       ...text.split(/\r?\n/u).map(classifyLine).filter((finding) => finding !== null),
@@ -113,9 +124,10 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
   );
   const findings = allFindings.slice(0, MAX_FINDINGS);
   const counts = countFindings(allFindings);
+  const omittedFindingCount = Math.max(0, allFindings.length - findings.length);
   const status = counts.total > 0 ? "review" : stat || bufferedIssues !== void 0 && bufferedIssues !== null ? "clean" : "unavailable";
-  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
-  return {
+  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; showing ${findings.length} preview(s) and omitting ${omittedFindingCount}. Relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
+  return { diagnostics: {
     schemaVersion: 1,
     scope: "recipe-run-application",
     status,
@@ -123,8 +135,10 @@ function collectRunDiagnostics(baseline, bufferedIssues) {
     note,
     source,
     counts,
+    displayedFindingCount: findings.length,
+    omittedFindingCount,
     findings
-  };
+  }, rawAppLog };
 }
 function classifyLine(line) {
   const trimmed = line.trim();
@@ -180,7 +194,10 @@ function runMobileIssueCommand(projectRoot, command) {
   }
 }
 function redactPreview(value) {
-  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
+  return redactDiagnosticText(value).slice(0, MAX_PREVIEW_CHARS);
+}
+function redactDiagnosticText(value) {
+  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/(["'])(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\1\s*:\s*(?:"[^"]*"|'[^']*'|[^,\s}\]]+)/giu, '$1$2$1:"[REDACTED]"').replace(/\b(api[-_]?key|password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization|vault)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]");
 }
 function dedupeFindings(findings) {
   const byFingerprint = /* @__PURE__ */ new Map();
@@ -201,7 +218,7 @@ function readSlice(filePath, offset, length) {
   try {
     const buffer = Buffer.alloc(length);
     const bytesRead = fs.readSync(fd, buffer, 0, length, offset);
-    return buffer.subarray(0, bytesRead).toString("utf8");
+    return buffer.subarray(0, bytesRead);
   } finally {
     fs.closeSync(fd);
   }
@@ -218,12 +235,18 @@ function indexDiagnosticArtifact(manifestPath) {
   if (!manifest) return;
   const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
   manifest.artifacts = [
-    ...artifacts.filter((artifact) => !isRecord(artifact) || artifact.path !== "diagnostics.json"),
+    ...artifacts.filter((artifact) => !isRecord(artifact) || !["diagnostics.json", RAW_APP_LOG_ARTIFACT].includes(String(artifact.path))),
     {
       path: "diagnostics.json",
       type: "json",
       label: "Run-scoped application diagnostics",
       category: "diagnostic"
+    },
+    {
+      path: RAW_APP_LOG_ARTIFACT,
+      type: "log",
+      label: "Redacted run-scoped application log slice",
+      category: "diagnostic"
     }
   ];
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
@@ -236,7 +259,9 @@ function indexDiagnosticSummary(summaryPath, diagnostics) {
     status: diagnostics.status,
     nonBlocking: true,
     counts: diagnostics.counts,
-    diagnosticsPath: "diagnostics.json"
+    diagnosticsPath: "diagnostics.json",
+    appLogPath: RAW_APP_LOG_ARTIFACT,
+    appLogRedacted: true
   };
   fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}
 `);

package/dist/runner.js

@@ -2,6 +2,7 @@ import { execFileSync, execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
 import { bridgeCommand } from "../library/actions/mobile/platform/bridge.mjs";
+import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 import {
   mobileSourceFingerprint,
   recordMobileSourceBaseline
@@ -334,21 +335,29 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
   fingerprint: mobileSourceFingerprint,
   record: recordMobileSourceBaseline
 }, processIdentity = {
-  readIosPid: readIosAppPid
+  readIosPid: readIosAppPid,
+  readAndroidPid: readAndroidAppPid
 }) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
     ...entry,
     async execute(node, context) {
-      if (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") {
+      const command = node.command ?? node.event ?? node.state;
+      const opaqueRuntime = context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
+      const requiresProcessContinuity = command !== "restart" && node.require_process_continuity === true;
+      if (opaqueRuntime && !requiresProcessContinuity) {
         return entry.execute(node, context);
       }
-      const command = node.command ?? node.event ?? node.state;
-      const reloadsSource = command === "launch" || command === "foreground" || command === "restart";
-      const checksIosContinuity = command === "foreground" && !isAndroidLifecycle(node, context.env ?? {});
-      const processBefore = checksIosContinuity ? processIdentity.readIosPid(node, context) : void 0;
-      const fingerprint = reloadsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
-      const androidRestart = command === "restart" && isAndroidLifecycle(node, context.env ?? {});
+      const reloadsSource = !opaqueRuntime && (command === "launch" || command === "foreground" || command === "restart");
+      const recordsSource = !opaqueRuntime && command === "restart";
+      const androidLifecycle = isAndroidLifecycle(node, context.env ?? {});
+      const checksIosContinuity = command === "foreground" && !androidLifecycle;
+      const checksRequiredContinuity = requiresProcessContinuity;
+      const recordsProcessIdentity = checksIosContinuity || checksRequiredContinuity;
+      const readProcessId = androidLifecycle ? processIdentity.readAndroidPid ?? readAndroidAppPid : processIdentity.readIosPid;
+      const processBefore = recordsProcessIdentity ? readProcessId(node, context) : void 0;
+      const fingerprint = recordsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
+      const androidRestart = command === "restart" && androidLifecycle;
       const initialNode = androidRestart ? { ...node, settle_ms: 0 } : node;
       const initialResult = await entry.execute(initialNode, context);
       let result = initialResult;
@@ -362,22 +371,26 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
       if (reloadsSource) {
         await readinessProbe(node, context);
       }
-      if (checksIosContinuity) {
-        const processAfter = processIdentity.readIosPid(node, context);
-        const actualTransition = processBefore !== null && processBefore === processAfter ? "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
+      if (recordsProcessIdentity) {
+        const processAfter = readProcessId(node, context);
+        const processPreserved = processBefore !== null && processBefore === processAfter;
+        const actualTransition = processPreserved ? command === "background" ? "background_same_process" : "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
+        const processContinuity = processPreserved ? "preserved" : processAfter === null ? "unknown" : "changed";
         const resultRecord = asRecord(result);
         result = {
           ...resultRecord,
           output: {
             ...asRecord(resultRecord.output),
             actualTransition,
+            processContinuity,
             processBefore,
             processAfter
           }
         };
-        if (node.require_process_continuity === true && actualTransition !== "foreground_resume") {
+        if (checksRequiredContinuity && !processPreserved) {
+          const platform = androidLifecycle ? "Android" : "iOS";
           throw new Error(
-            `iOS foreground did not preserve the app process (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample is a cold relaunch, not a reconnect.`
+            `${platform} ${String(command)} did not prove app-process continuity (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample cannot be classified as a same-process reconnect.`
           );
         }
       }
@@ -390,6 +403,24 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
     }
   }));
 }
+function readAndroidAppPid(node, context) {
+  const env = context.env ?? {};
+  const device = node.adb_serial ?? node.android_device ?? node.device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+  const packageId = node.package_id ?? node.packageName ?? node.app_id ?? env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask";
+  if (typeof device !== "string" || typeof packageId !== "string") return null;
+  try {
+    const adb = resolveMobileToolPath("adb", { required: true });
+    const output = execFileSync(
+      adb,
+      ["-s", device, "shell", "pidof", packageId],
+      { encoding: "utf8", timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const pid = Number.parseInt(output.trim().split(/\s+/u)[0] ?? "", 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
 function readIosAppPid(node, context) {
   const env = context.env ?? {};
   const device = node.simulator ?? node.ios_simulator ?? env.SIM_UDID ?? env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;

package/docs/PERFORMANCE-CAPTURE.md

@@ -0,0 +1,33 @@
+# UI smoothness capture
+
+`app.performance_capture` attributes CDP trace samples to the exact Recipe Protocol v1 nodes that run inside an explicit window. Mobile and Extension use the same action contract.
+
+```json
+{
+  "action": "app.performance_capture",
+  "phase": "start",
+  "id": "market-scroll",
+  "max_duration_ms": 60000,
+  "intent": "Start UI smoothness capture",
+  "next": "scroll"
+}
+```
+
+End the same ID with `phase: "end"`. The action writes bounded JSON and a self-contained HTML report. `app.performance_assert` can require a status, minimum frame count, and specific node intervals.
+
+## Sources and status
+
+- Mobile uses React Native's `Tracing.start`, `Tracing.dataCollected`, and `Tracing.end` implementation. iOS frame timings come from its built-in `CADisplayLink` observer. Android frame timings come from `Window.FrameMetrics`. The app build must report `unstable_frameRecordingEnabled: true`; otherwise native UI coverage is partial or unavailable.
+- Extension uses Chromium's implementation of the same CDP Tracing domain. Frame and JavaScript data count only after the harness proves they belong to the MetaMask renderer. Unresolved browser-wide events produce partial or unavailable coverage.
+- The harness records a CDP clock marker and maps trace timestamps onto recipe-node timestamps. It waits for `Tracing.tracingComplete` before writing evidence.
+- The JSON report includes bounded trace evidence counts for `BeginFrame`, `DrawFrame`, `RunTask`, and `ProfileChunk`, plus data-loss and retention-overflow flags.
+- UI frames and JavaScript work remain separate sources. `RunTask` events produce JavaScript task summaries. Sampling `ProfileChunk` events prove profiler data exists but are not converted to task timing or FPS. JavaScript work is never labelled as UI or JS FPS.
+- `complete`, `partial`, and `unavailable` describe source coverage. Missing data is never converted to zero.
+
+`app.performance_assert.minimum_frame_count` applies only to native UI or Chromium renderer frames. JavaScript task count cannot satisfy it.
+
+Capture is explicit only. Use the action for comparisons on the same runtime and build. Automatic capture remains disabled until its overhead passes a matched benchmark.
+
+## Sentry promotion boundary
+
+This action does not send data to Sentry. A future product integration may promote only bounded aggregates after release-build overhead is independently accepted: source status, stable node/action name, frame count, p50/p95/p99, jank percentage, and longest frame. Do not send raw frame samples, recipe parameters, wallet/account identity, URLs, or artifact contents.

package/docs/RECIPES.md

@@ -269,6 +269,13 @@ events. The result distinguishes complete, partial, and unavailable evidence
 so a target rotation cannot be misreported as zero requests. See
 [Recipe-scoped network capture](NETWORK-CAPTURE.md).
 
+## Capture UI smoothness
+
+Use explicit `app.performance_capture` start/end nodes to correlate Mobile or
+Extension CDP trace samples with recipe-node boundaries.
+`app.performance_assert` checks the resulting evidence contract. Capture is
+not automatic; see [UI smoothness capture](PERFORMANCE-CAPTURE.md).
+
 ## Share a library
 
 ```text