npm - @deeeed/metamask-harness - Versions diffs - 0.46.0 → 0.47.1 - Mend

@deeeed/metamask-harness 0.46.0 → 0.47.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/CHANGELOG.md +28 -0
package/README.md +1 -1
package/adapters/manifest.json +12 -4
package/adapters/mobile/wait-for-bridge.cjs +550 -0
package/adapters/mobile/wait-for-bridge.sh +11 -148
package/bin/mm-harness +7 -2
package/dist/adapters/mobile/prepare.js +26 -18
package/dist/adapters/mobile/runtime-decision.js +1 -0
package/dist/cli-commands.js +2 -0
package/dist/command-contract.js +7 -0
package/dist/commands/checklist.js +1 -0
package/dist/commands/help.js +76 -0
package/dist/commands/parse-args.js +2 -1
package/dist/commands/recipe-quality.js +1 -1
package/dist/commands/tutorial.js +46 -0
package/dist/mm-harness-cli.js +45 -6
package/docs/CONTRIBUTING.md +2 -0
package/docs/QA.md +2 -2
package/library/actions/mobile/perps/perps.mjs +1 -1
package/package.json +2 -2
package/scripts/site-contrast.mjs +6 -2
package/site/assets/help-recipes.json +113 -0
package/site/architecture.html +0 -497
package/site/assets/metamask-fox.svg +0 -24
package/site/assets/progress.mjs +0 -323
package/site/assets/style.css +0 -1066
package/site/cheatsheet.html +0 -307
package/site/ecosystem.html +0 -162
package/site/how-it-works.html +0 -692
package/site/index.html +0 -184
package/site/perps-advanced-orders-qa.html +0 -96
package/site/perps.html +0 -265
package/site/recipes.html +0 -423
package/site/reviewers.html +0 -375
package/site/tutorials/index.html +0 -181
package/site/tutorials/v1.html +0 -212
package/site/tutorials/v2.html +0 -207
package/site/tutorials/v3.html +0 -258
package/site/tutorials/v4.html +0 -196
package/site/tutorials/v5.html +0 -164
package/site/tutorials/v6.html +0 -166
package/site/tutorials/v7.html +0 -185

package/site/reviewers.html DELETED Viewed

@@ -1,375 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>For Reviewers — how to read an evidence bundle</title>
-<meta name="description" content="An annotated walkthrough of a real mm-harness evidence bundle: summary.json, trace.json, diagnostics, and what an honest degraded capture looks like.">
-<link rel="icon" href="assets/metamask-fox.svg" type="image/svg+xml">
-<link rel="stylesheet" href="assets/style.css?v=4">
-</head>
-<body data-progress-page="reviewers">
-<a class="skip" href="#summary">Skip to the walkthrough</a>
-<header class="topbar">
-  <div class="wrap topbar-inner">
-    <a class="brand" href="index.html">
-      <img class="brand-mark" src="assets/metamask-fox.svg" alt="" width="22" height="22">
-      <span class="brand-name">recipes</span>
-    </a>
-    <nav class="nav" aria-label="Main">
-      <a class="nav-cta" href="index.html#prompt">Quick start</a>
-      <a href="how-it-works.html">How it works</a>
-      <a href="perps.html">Team / Perps</a>
-      <a href="cheatsheet.html">Cheatsheet</a>
-      <a href="architecture.html">Architecture</a>
-      <a href="tutorials/index.html">Tutorials</a>
-    </nav>
-  </div>
-</header>
-<main>
-<section class="wrap hero" style="padding-bottom:1rem">
-  <span class="eyebrow">For reviewers</span>
-  <h1>How to read an evidence bundle</h1>
-  <p class="lede">
-    Someone attached a run to a pull request and claimed it proves something. You have five minutes.
-    Here is where to look, in what order, and what would make you distrust it.
-  </p>
-  <div class="hero-meta">
-    <span>real run, values redacted</span>
-    <span>6 nodes, 6.3s</span>
-    <span>read in 5 minutes</span>
-  </div>
-</section>
-<section class="wrap">
-  <div class="note plain">
-    <span class="note-title">About this example</span>
-    <p>
-      Everything below is an actual run of the bundled <code>wallet.smoke</code> recipe on a real
-      Extension checkout. Paths, addresses, account identifiers, and internal package names are
-      redacted; structure, verdicts, and timings are untouched — including a wrinkle in the screenshot
-      step that is the most instructive part of the bundle.
-    </p>
-  </div>
-  <h2 id="order">Read it in this order</h2>
-  <div class="grid grid-3">
-    <div class="card">
-      <h3>1 · report.md</h3>
-      <p>The story in one page. Skim this first. If it does not match the PR description, stop here and ask.</p>
-    </div>
-    <div class="card">
-      <h3>2 · summary.json</h3>
-      <p>The verdict and the counts. Is it green, how many nodes, and what content was in scope.</p>
-    </div>
-    <div class="card">
-      <h3>3 · trace.json</h3>
-      <p>What actually happened per step. Every number you cite comes from here, never from prose.</p>
-    </div>
-  </div>
-</section>
-<section class="wrap">
-  <h2 id="report">The report</h2>
-  <p>Written for humans. Six steps, each with its action, duration, and a one-line result.</p>
-  <div class="out"># MetaMask Recipe Run
-Status: <span class="ok">pass</span>
-Duration: 6.3s
-Nodes: 6/6 passed
-## Steps
-- <span class="ok">PASS</span> status (app.status, 9ms): platform=extension
-- <span class="ok">PASS</span> fixture (metamask.wallet.fixture_status, 17ms): path=temp/recipe/runtime/wallet-fixture.json
-- <span class="ok">PASS</span> unlock (metamask.wallet.ensure_unlocked, 100ms): proof=extension-unlocked-state
-- <span class="ok">PASS</span> state (metamask.wallet.read_state, 94ms): proof=extension-wallet-state
-- <span class="ok">PASS</span> screenshot (ui.screenshot, 6.0s): path=screenshots/wallet-smoke.png
-- <span class="ok">PASS</span> done (end, 0ms)</div>
-  <p>
-    Five steps take 220ms between them; the screenshot takes six seconds. The trace explains it, and the
-    explanation is a reason to trust this bundle rather than doubt it.
-  </p>
-</section>
-<section class="wrap">
-  <h2 id="summary">summary.json — the verdict</h2>
-  <div class="annot">
-    <div class="out">{
-  "status": <span class="ok">"pass"</span>,
-  "total": 6,
-  "passed": 6,
-  "failed": 0,
-  "startedAt": "2026-07-22T15:23:56.367Z",
-  "endedAt": "2026-07-22T15:24:02.638Z",
-  "durationMs": 6271,
-  "runner": {
-    "source": "&lt;redacted checkout path&gt;",
-    "git_ref": "62c93ba5130…"
-  },
-  "recipeLibraries": {
-    "sources": [
-      {
-        "name": "metamask",
-        "root": "&lt;redacted&gt;/library",
-        "recipeCount": 6,
-        "provenance": {
-          "kind": "bundled",
-          "trust": <span class="ok">"trusted"</span>,
-          "name": "metamask"
-        }
-      }
-    ],
-    "shadowed": []
-  },
-  "sideFindings": {
-    "status": <span class="ok">"clean"</span>,
-    "nonBlocking": true,
-    "counts": { "total": 0, "warning": 0,
-                "error": 0, "exception": 0 },
-    "diagnosticsPath": "diagnostics.json"
-  }
-}</div>
-    <div class="annot-notes">
-      <div class="annot-note">
-        <b>status</b>
-        <p>The verdict for the whole run. <code>pass</code> only if every node passed; there is no partial credit here.</p>
-      </div>
-      <div class="annot-note">
-        <b>total / passed / failed</b>
-        <p>Node counts. Check these against the claim in the PR. "It proves six things" should mean <code>total: 6</code>, and if it does not, ask why.</p>
-      </div>
-      <div class="annot-note">
-        <b>git_ref</b>
-        <p>The exact commit of the tooling that produced this. Two bundles that disagree are often two different refs — this is the first thing to compare.</p>
-      </div>
-      <div class="annot-note">
-        <b>recipeLibraries.provenance</b>
-        <p>Where the recipe came from and how much it is trusted. <code>kind: bundled</code> means it shipped with the harness. A recipe from an untrusted source is labelled as such rather than silently executed as equal.</p>
-      </div>
-      <div class="annot-note">
-        <b>shadowed</b>
-        <p>Recipes that were overridden by a higher-priority library. If this is non-empty, the recipe that ran may not be the one you were reading. Check it.</p>
-      </div>
-      <div class="annot-note">
-        <b>sideFindings</b>
-        <p>App warnings and errors, kept <em>out</em> of the verdict (<code>nonBlocking: true</code>). Noise from an unrelated subsystem cannot fail someone's proof, and a clean verdict cannot hide it either. When this is not <code>clean</code>, open <code>diagnostics.json</code>.</p>
-      </div>
-    </div>
-  </div>
-</section>
-<section class="wrap">
-  <h2 id="trace">trace.json — what actually happened</h2>
-  <p>
-    One entry per node, in execution order, each with the intent it declared, its timing, its verdict,
-    and its full output. This is the authoritative record.
-  </p>
-  <div class="annot">
-    <div class="out">{
-  "nodeId": "unlock",
-  "action": "metamask.wallet.ensure_unlocked",
-  "intent": "Ensure the fixture-backed wallet is unlocked",
-  "startedAt": "2026-07-22T15:23:56.409Z",
-  "endedAt": "2026-07-22T15:23:56.509Z",
-  "durationMs": 100,
-  "ok": <span class="ok">true</span>,
-  "next": "state",
-  "output": {
-    "unlocked": true,
-    "alreadyUnlocked": true,
-    "proofPath": "extension-unlocked-state",
-    "cdpPort": 9500,
-    "targetUrl": "chrome-extension://&lt;redacted&gt;/home.html#/",
-    "liveAdapter": "&lt;redacted&gt;/library/actions/
-                    extension/wallet/ensure_unlocked.mjs"
-  }
-}</div>
-    <div class="annot-notes">
-      <div class="annot-note">
-        <b>intent</b>
-        <p>Written by the author, in the recipe, before the run. Read them top to bottom and you have the argument the bundle makes. If they do not add up to the claim, the bundle does not support it — however green.</p>
-      </div>
-      <div class="annot-note">
-        <b>ok</b>
-        <p>The per-node verdict. To triage a failed run, find the first <code>"ok": false</code>; everything after it is consequence, not cause.</p>
-      </div>
-      <div class="annot-note">
-        <b>alreadyUnlocked</b>
-        <p>This step did not <em>do</em> anything; it confirmed a state that already held. A legitimate pass — but if a PR claims "proves unlocking works", this node did not prove it.</p>
-      </div>
-      <div class="annot-note">
-        <b>liveAdapter</b>
-        <p>The file that executed — a real adapter on disk, not a stub. A missing adapter raises rather than returning a plausible object, which is why a green node means a real one ran.</p>
-      </div>
-      <div class="annot-note">
-        <b>next</b>
-        <p>The edge taken out of this node. Following <code>next</code> from the entry point reconstructs the path actually taken, which matters when a recipe branches.</p>
-      </div>
-    </div>
-  </div>
-</section>
-<section class="wrap">
-  <h2 id="degraded">The most instructive node in this bundle</h2>
-  <p>
-    Here is the six-second screenshot. It passed. Read what it recorded about <em>how</em> it passed:
-  </p>
-  <div class="out">{
-  "nodeId": "screenshot",
-  "action": "ui.screenshot",
-  "intent": "Record the visible wallet state as evidence",
-  "durationMs": 5996,
-  "ok": <span class="ok">true</span>,
-  "output": {
-    "captured": true,
-    "path": "screenshots/wallet-smoke.png",
-    "artifact": {
-      "type": "screenshot",
-      "metadata": {
-        "provider": <span class="hint">"dom-raster"</span>,
-        "mode": "computed-style-viewport",
-        "fallbackFrom": <span class="hint">"capture-helper+cdp"</span>,
-        "captureHelperError": <span class="bad">"capture-helper snapshot failed for pid &lt;redacted&gt;: could not create image from window"</span>,
-        "cdpError": <span class="bad">"Chrome Page.captureScreenshot timed out after 5000ms."</span>
-      }
-    }
-  }
-}</div>
-  <div class="doctrine">
-    <p>
-      <span class="k">The node passed, and still wrote down both failures.</span> The preferred capture
-      path failed, the fallback timed out after five seconds, and a DOM raster — weaker evidence —
-      produced the PNG. All of it is in the metadata. Nothing forced it to tell you.
-    </p>
-  </div>
-  <p>
-    This is what to check when deciding whether to trust a bundle at all: a system that quietly upgraded
-    "degraded capture" to "screenshot captured" would produce cleaner-looking and worse evidence. From
-    this node specifically:
-  </p>
-  <ul>
-    <li><strong>The PNG is real but weaker than usual.</strong> A computed-style DOM raster is not a true screen capture. If the claim depends on pixel-accurate rendering, this image does not carry it.</li>
-    <li><strong>The six seconds were a timeout, not slow work.</strong> Timing anomalies in a bundle usually have an explanation in the metadata. Look before assuming.</li>
-    <li><strong>Always open the image.</strong> The trace tells you a PNG was registered and how; only your eyes tell you it shows what the author says it shows.</li>
-  </ul>
-</section>
-<section class="wrap">
-  <h2 id="diagnostics">diagnostics.json — the quarantine</h2>
-  <p>
-    Application warnings and errors captured during the run, kept structurally separate from the
-    verdict so that neither can contaminate the other.
-  </p>
-  <div class="out">{
-  "scope": "recipe-run-application",
-  "status": <span class="ok">"clean"</span>,
-  "nonBlocking": true,
-  "note": "No application warnings or errors were emitted during the recipe run.",
-  "source": {
-    "label": "extension",
-    "path": "&lt;redacted&gt;/temp/recipe/runtime/extension-console.log",
-    "startOffset": 16337832,
-    "endOffset": 16338586,
-    "bytesRead": 754,
-    "truncated": false
-  },
-  "counts": { "total": 0, "warning": 0, "error": 0, "exception": 0 },
-  "findings": []
-}</div>
-  <p>
-    The offsets are the honest part: the log is bracketed to the run window — 754 bytes — so "clean" is
-    a claim about <em>this run</em>, not that the log file is empty. <code>truncated: false</code>
-    confirms nothing was dropped from that window.
-  </p>
-</section>
-<section class="wrap">
-  <h2 id="checklist">A reviewer's checklist</h2>
-  <div class="table-scroll">
-    <table>
-      <thead><tr><th>Check</th><th>Where</th><th>What should worry you</th></tr></thead>
-      <tbody>
-        <tr>
-          <td>Does the run match the claim?</td>
-          <td>node <code>intent</code>s in <code>trace.json</code></td>
-          <td>Intents that do not add up to what the PR says was proven.</td>
-        </tr>
-        <tr>
-          <td>Are the counts real?</td>
-          <td><code>summary.json</code>, not the description</td>
-          <td>A number in prose that no field supports.</td>
-        </tr>
-        <tr>
-          <td>Did the recipe you read actually run?</td>
-          <td><code>recipe.json</code>, <code>shadowed</code></td>
-          <td>A non-empty <code>shadowed</code> list.</td>
-        </tr>
-        <tr>
-          <td>Where did the recipe come from?</td>
-          <td><code>recipeLibraries.provenance</code></td>
-          <td>A trust level the change does not warrant.</td>
-        </tr>
-        <tr>
-          <td>Did any step merely observe an existing state?</td>
-          <td>node outputs, e.g. <code>alreadyUnlocked</code></td>
-          <td>A confirmation being sold as a demonstration.</td>
-        </tr>
-        <tr>
-          <td>How was the visual evidence obtained?</td>
-          <td>artifact <code>metadata.provider</code></td>
-          <td><code>fallbackFrom</code> present and the claim depends on rendering.</td>
-        </tr>
-        <tr>
-          <td>Was the app healthy while this ran?</td>
-          <td><code>diagnostics.json</code></td>
-          <td>Errors in the window that the author never mentioned.</td>
-        </tr>
-        <tr>
-          <td>Does the screenshot show what they say?</td>
-          <td><code>screenshots/</code></td>
-          <td>Not opening it. Open it.</td>
-        </tr>
-      </tbody>
-    </table>
-  </div>
-  <div class="note">
-    <span class="note-title">The one rule</span>
-    <p>
-      Numbers come from <code>trace.json</code> — not the summary paragraph, not the PR description, not
-      what an agent wrote about its own work. A claim with no field behind it is not evidence yet, and
-      "which node shows that?" is a reasonable review comment.
-    </p>
-  </div>
-  <hr class="sep">
-  <div class="btn-row">
-    <a class="btn btn-primary" href="how-it-works.html#steps">Produce your own bundle →</a>
-    <a class="btn btn-ghost" href="architecture.html">How the pieces fit</a>
-  </div>
-</section>
-</main>
-<footer class="footer">
-  <div class="wrap">
-    <p>Internal getting-started guide for proving MetaMask changes with recipes. Not official MetaMask product documentation.</p>
-    <p>Example bundle is a real run with identifying values redacted. Sample output moves between releases; trust your terminal over this page.</p>
-  </div>
-</footer>
-<script type="module" src="assets/progress.mjs?v=4"></script>
-</body>
-</html>

package/site/tutorials/index.html DELETED Viewed

@@ -1,181 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Tutorials — the series</title>
-<meta name="description" content="Seven tutorials taking a new engineer from an empty terminal to pull requests that carry proof.">
-<link rel="icon" href="../assets/metamask-fox.svg" type="image/svg+xml">
-<link rel="stylesheet" href="../assets/style.css?v=4">
-</head>
-<body data-progress-page="tutorials">
-<a class="skip" href="#series">Skip to the series</a>
-<header class="topbar">
-  <div class="wrap-wide topbar-inner">
-    <a class="brand" href="../index.html">
-      <img class="brand-mark" src="../assets/metamask-fox.svg" alt="" width="22" height="22">
-      <span class="brand-name">recipes</span>
-    </a>
-    <nav class="nav" aria-label="Main">
-      <a class="nav-cta" href="../index.html#prompt">Quick start</a>
-      <a href="../how-it-works.html">How it works</a>
-      <a href="../perps.html">Team / Perps</a>
-      <a href="../cheatsheet.html">Cheatsheet</a>
-      <a href="../architecture.html">Architecture</a>
-      <a href="index.html" aria-current="page">Tutorials</a>
-    </nav>
-  </div>
-</header>
-<main>
-<section class="wrap-wide hero" style="padding-bottom:1.5rem">
-  <span class="eyebrow">The series</span>
-  <h1>Seven tutorials</h1>
-  <p class="lede">
-    From an empty terminal to pull requests that carry proof. Each covers one flow and ends with one
-    artifact.
-  </p>
-  <div class="hero-meta">
-    <span>7 pages, readable now</span>
-    <span>videos in production</span>
-  </div>
-</section>
-<section class="wrap-wide">
-  <div class="note plain">
-    <span class="note-title">The page is the tutorial</span>
-    <p>
-      Every page below is complete and usable today. The video is its visual companion, slotted in as
-      each is recorded — the page doubles as the recording script, which is why the two cannot drift.
-    </p>
-  </div>
-  <h2 id="series">The series</h2>
-  <div class="grid grid-3" style="margin-top:1.5rem">
-    <a class="vid" href="v1.html">
-      <div class="vid-thumb"><span class="vid-id">V1</span></div>
-      <div class="vid-body">
-        <h3>Getting started with recipes</h3>
-        <p>Install, doctor, launch, discover, drive, prove. The whole arc, and the shortest path into everything else.</p>
-        <div class="vid-foot">
-          <span class="badge dur">5 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">video soon</span>
-        </div>
-      </div>
-    </a>
-    <a class="vid" href="v2.html">
-      <div class="vid-thumb"><span class="vid-id">V2</span></div>
-      <div class="vid-body">
-        <h3>Reading the evidence</h3>
-        <p>One finished run, file by file, and the two rules that make a green verdict worth believing.</p>
-        <div class="vid-foot">
-          <span class="badge dur">6 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">video soon</span>
-        </div>
-      </div>
-    </a>
-    <a class="vid" href="v3.html">
-      <div class="vid-thumb"><span class="vid-id">V3</span></div>
-      <div class="vid-body">
-        <h3>Skills and your team's library</h3>
-        <p>Install the skills, declare your library, prove discovery sees it. Worked through with the perps library.</p>
-        <div class="vid-foot">
-          <span class="badge dur">5 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">video soon</span>
-        </div>
-      </div>
-    </a>
-    <a class="vid" href="v4.html">
-      <div class="vid-thumb"><span class="vid-id">V4</span></div>
-      <div class="vid-body">
-        <h3>Cook a recipe from an acceptance criterion</h3>
-        <p>One criterion in, a rerunnable proof out. Discovery sets the boundary; you pick the template.</p>
-        <div class="vid-foot">
-          <span class="badge dur">8–10 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">video soon</span>
-        </div>
-      </div>
-    </a>
-    <a class="vid" href="v5.html">
-      <div class="vid-thumb"><span class="vid-id">V5</span></div>
-      <div class="vid-body">
-        <h3>PR QA review from one link</h3>
-        <p>One pull request URL in, a per-criterion verdict table out. Nothing gets posted without you.</p>
-        <div class="vid-foot">
-          <span class="badge dur">8–10 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">skill not merged</span>
-        </div>
-      </div>
-    </a>
-    <a class="vid" href="v6.html">
-      <div class="vid-thumb"><span class="vid-id">V6</span></div>
-      <div class="vid-body">
-        <h3>Release validation</h3>
-        <p>One team's changes on a frozen release candidate, reported with four verdicts including NOT RUN.</p>
-        <div class="vid-foot">
-          <span class="badge dur">6 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">skill not merged</span>
-        </div>
-      </div>
-    </a>
-    <a class="vid" href="v7.html">
-      <div class="vid-thumb"><span class="vid-id">V7</span></div>
-      <div class="vid-body">
-        <h3>A ticket end to end</h3>
-        <p>Ordinary work, start to finish: implement, cook the proof, open a pull request a reviewer can check.</p>
-        <div class="vid-foot">
-          <span class="badge dur">10 min</span>
-          <span class="badge live">page ready</span>
-          <span class="badge soon">video soon</span>
-        </div>
-      </div>
-    </a>
-  </div>
-</section>
-<section class="wrap-wide">
-  <hr class="sep">
-  <h2>Series rules</h2>
-  <div class="grid grid-2">
-    <div class="card">
-      <h3>One flow per tutorial</h3>
-      <p>Setup is never mixed with usage. Each ends with the artifact it produced and one command to try yourself.</p>
-    </div>
-    <div class="card">
-      <h3>Nothing is staged</h3>
-      <p>Real repos, real evidence. Where a run takes minutes the recording cuts to the result; it never fakes one. Failures stay in — watching someone follow an error to its fix is the most useful thing here.</p>
-    </div>
-  </div>
-  <div class="btn-row">
-    <a class="btn btn-primary" href="v1.html">Start with V1 →</a>
-    <a class="btn btn-ghost" href="../how-it-works.html#steps">Or the full walkthrough</a>
-  </div>
-</section>
-</main>
-<footer class="footer">
-  <div class="wrap-wide">
-    <p>Internal getting-started guide for proving MetaMask changes with recipes. Not official MetaMask product documentation.</p>
-    <p>Sample output moves between releases; trust your terminal over this page.</p>
-  </div>
-</footer>
-<script type="module" src="../assets/progress.mjs?v=4"></script>
-</body>
-</html>