npm - @deeeed/metamask-harness - Versions diffs - 0.28.0 → 0.29.0 - Mend

@deeeed/metamask-harness 0.28.0 → 0.29.0

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 (52) hide show

package/CHANGELOG.md +19 -0
package/README.md +41 -0
package/adapters/extension/build-lavamoat.sh +2 -1
package/adapters/extension/ensure-browser.sh +82 -9
package/adapters/extension/inject.mjs +1 -0
package/adapters/extension/launch-browser.cjs +83 -1
package/adapters/extension/lib/chrome-args.cjs +325 -1
package/adapters/extension/lib/playwright-cdp.cjs +34 -0
package/adapters/extension/lib/slot-title.cjs +2 -4
package/adapters/extension/lib/validation-launch-supervisor.cjs +292 -0
package/adapters/extension/lib/validation-process-ownership.cjs +69 -0
package/adapters/extension/reattach.sh +2 -1
package/adapters/extension/sidepanel-toggle.sh +14 -96
package/adapters/extension/wallet-fixture-state.cjs +8 -31
package/adapters/manifest.json +16 -0
package/adapters/shared/private-atomic-write.cjs +47 -0
package/adapters/shared/setup-base.sh +864 -0
package/dist/adapters/extension/runtime.js +367 -24
package/dist/adapters/extension/validation-process-ownership.js +10 -0
package/dist/cli-commands.js +1 -0
package/dist/command-contract.js +12 -0
package/dist/commands/launch/extension.js +130 -19
package/dist/commands/setup-base.js +24 -0
package/dist/mm-harness-cli.js +28 -2
package/library/actions/extension/analytics/consent.mjs +203 -0
package/library/actions/extension/analytics/set_consent.mjs +19 -143
package/library/actions/extension/perps/perps.mjs +2 -16
package/library/actions/extension/perps/state.mjs +20 -0
package/library/actions/extension/wallet/list_accounts.mjs +3 -25
package/library/actions/extension/wallet/read_state.mjs +3 -23
package/library/actions/extension/wallet/select_account.mjs +6 -33
package/library/actions/extension/wallet/setup.mjs +2 -20
package/library/actions/extension/wallet/state.mjs +111 -0
package/library/recipes/runner/action-validation.extension.recipe.json +1 -1
package/library/recipes/runner/action-validation.mobile.recipe.json +1 -1
package/package.json +7 -4
package/scripts/site-contrast.mjs +538 -0
package/site/architecture.html +415 -0
package/site/assets/progress.mjs +272 -0
package/site/assets/style.css +808 -0
package/site/cheatsheet.html +305 -0
package/site/index.html +643 -0
package/site/recipes.html +396 -0
package/site/reviewers.html +374 -0
package/site/tutorials/index.html +180 -0
package/site/tutorials/v1.html +211 -0
package/site/tutorials/v2.html +207 -0
package/site/tutorials/v3.html +214 -0
package/site/tutorials/v4.html +195 -0
package/site/tutorials/v5.html +163 -0
package/site/tutorials/v6.html +165 -0
package/site/tutorials/v7.html +184 -0

package/site/recipes.html ADDED Viewed

@@ -0,0 +1,396 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>What is a recipe?</title>
+<meta name="description" content="The anatomy of a recipe: a JSON graph of typed actions, human-authored intent, first-class assertions, and a verdict derived from the trace.">
+<link rel="stylesheet" href="assets/style.css">
+</head>
+<body data-progress-page="recipes">
+<a class="skip" href="#anatomy">Skip to the anatomy</a>
+<header class="topbar">
+  <div class="wrap topbar-inner">
+    <a class="brand" href="index.html">
+      <span class="brand-mark" aria-hidden="true"></span>
+      <span class="brand-name">mm-harness</span>
+    </a>
+    <nav class="nav" aria-label="Main">
+      <a href="index.html">Start Here</a>
+      <a href="recipes.html" aria-current="page">Recipes</a>
+      <a href="cheatsheet.html">Cheatsheet</a>
+      <a href="architecture.html">Architecture</a>
+      <a href="tutorials/index.html">Tutorials</a>
+      <a href="reviewers.html">For Reviewers</a>
+    </nav>
+  </div>
+</header>
+<main>
+<section class="wrap hero" style="padding-bottom:1rem">
+  <span class="eyebrow">The central idea</span>
+  <h1>What is a recipe?</h1>
+  <p class="lede">
+    A recipe turns "I checked, it works" into something a reviewer can verify without trusting you —
+    and something that objects later if the behaviour breaks.
+  </p>
+</section>
+<section class="wrap">
+  <div class="doctrine">
+    <p>
+      <span class="k">A recipe proves a task with actions.</span> A JSON graph whose nodes are typed
+      actions drawn only from what this checkout discovered, each carrying a human-written intent,
+      executed against a real build, ending in a verdict computed from what happened rather than
+      asserted in prose.
+    </p>
+  </div>
+  <p>Every clause there does a job against a specific failure mode. Here they are, one at a time.</p>
+</section>
+<section class="wrap">
+  <h2 id="anatomy">The anatomy of a real one</h2>
+  <p>
+    <code>perps.lifecycle</code> ships with the harness. Abridged here — the full graph has eighteen
+    nodes — but nothing is invented; read it all with
+    <code>mm-harness run perps.lifecycle --describe</code>.
+  </p>
+  <div class="annot">
+    <div class="out">{
+  "title": "MetaMask Perps lifecycle smoke",
+  "description": "Proves a deterministic Perps prestate,
+    opens a small ETH testnet position, verifies it,
+    closes it, and tears down to a clean state.",
+  "workflow": {
+    "entry": <span class="hint">"status"</span>,
+    "nodes": {
+      "status": {
+        "action": <span class="hint">"app.status"</span>,
+        "intent": "Read runner compatibility status",
+        "next": "fixture"
+      },
+      <span class="dim">… wallet fixture, unlock, account select …</span>
+      "start-state": {
+        "action": "metamask.perps.start_state",
+        "market": "ETH",
+        "positions": { "state": "none" },
+        "intent": "Prepare clean ETH testnet Perps state",
+        "next": "assert-clean-position"
+      },
+      <span class="hint">"assert-clean-position"</span>: {
+        "action": "metamask.perps.assert_positions",
+        "market": "ETH",
+        "state": "none",
+        "intent": "Confirm ETH position state is clean",
+        "next": "place-order"
+      },
+      "place-order": {
+        "action": "metamask.perps.place_order",
+        "market": "ETH", "side": "long",
+        "amount": "11", "leverage": 3,
+        "intent": "Open a small ETH 3x long position",
+        "next": "assert-open"
+      },
+      <span class="hint">"assert-open"</span>: {
+        "action": "metamask.perps.assert_positions",
+        "market": "ETH",
+        <span class="ok">"state": "open"</span>,
+        "intent": "Confirm the ETH position opened",
+        "next": "read-orders"
+      },
+      <span class="dim">… close orders, close position, assert closed …</span>
+      "teardown-state": {
+        "action": "metamask.perps.teardown_state",
+        "intent": "Return Perps to globally clean home state",
+        "next": "done"
+      },
+      "done": {
+        "action": <span class="hint">"end"</span>,
+        "status": "pass"
+      }
+    }
+  }
+}</div>
+    <div class="annot-notes">
+      <div class="annot-note">
+        <b>entry + next</b>
+        <p>It is a graph, not a script. Execution starts at <code>entry</code> and follows each node's <code>next</code>. Branching exists too — a <code>switch</code> node picks an edge — which is why the trace records the path actually taken rather than assuming the file's reading order.</p>
+      </div>
+      <div class="annot-note">
+        <b>action</b>
+        <p>Always a name from the discovered manifest. <code>app.status</code>, <code>metamask.perps.place_order</code>, and <code>end</code> are all real entries you can look up with <code>mm-harness actions --action &lt;name&gt;</code>. You cannot write an action that does not exist and have it run.</p>
+      </div>
+      <div class="annot-note">
+        <b>intent</b>
+        <p>Written by a human, before the run. It is not a comment — it is carried into the trace, so the evidence reads as an argument rather than a log.</p>
+      </div>
+      <div class="annot-note">
+        <b>assert-clean-position</b>
+        <p>The pattern worth stealing: assert the <em>starting</em> state before acting. Without it, a position that was already open would make the next step look like a success it did not cause.</p>
+      </div>
+      <div class="annot-note">
+        <b>assert-open</b>
+        <p>And assert the effect afterwards, independently. <code>place_order</code> reporting success is the action's own word for it; <code>assert_positions</code> goes and looks. These are deliberately two different nodes.</p>
+      </div>
+      <div class="annot-note">
+        <b>end</b>
+        <p>The terminal node. Reaching it is what a passing run means — and it is only reachable by passing through every assertion on the path.</p>
+      </div>
+    </div>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="vocabulary">Actions come only from the discovered manifest</h2>
+  <p>
+    The available actions are fixed and discoverable, and a recipe may use nothing else. Validation
+    happens against that manifest <em>before</em> anything executes:
+  </p>
+  <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run my-recipe.json --plan</code></pre></div>
+  <div class="out"><span class="ok">✓</span> [static] validate.schema: recipe document schema + action existence/platform vs the adapter manifest</div>
+  <p>
+    A misspelled or imagined action fails validation with exit code 5, and nothing touches the app.
+    That is the cheap check — run it before the expensive one.
+  </p>
+  <div class="note blue">
+    <span class="note-title">The constraint is the point</span>
+    <p>
+      A tool free to invent action names is free to invent plausible ones, and a recipe full of
+      plausible steps that never ran is worse than no recipe. Bounding the vocabulary to what exists is
+      what makes a green run mean something — and what makes this safe to hand to an agent.
+    </p>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="intent">Intent turns a trace into a narrative</h2>
+  <p>
+    The runner copies each node's <code>intent</code> into the trace beside its result. Read them in
+    order and you have the argument the recipe makes:
+  </p>
+  <div class="out"><span class="ok">PASS</span> status      — Read runner compatibility status
+<span class="ok">PASS</span> fixture     — Verify wallet fixture availability
+<span class="ok">PASS</span> assert-clean-position — Confirm ETH position state is clean
+<span class="ok">PASS</span> place-order — Open a small ETH 3x long position
+<span class="ok">PASS</span> assert-open — Confirm the ETH position opened</div>
+    <p>
+    A reviewable claim in five lines, generated from the recipe rather than written about it
+    afterwards. It gives review a precise question: if the intents do not add up to what the pull
+    request claims, the bundle does not support it — however green.
+  </p>
+</section>
+<section class="wrap">
+  <h2 id="assertions">Assertions are first-class — and counting matters</h2>
+  <p>
+    An assertion is a node like any other: it occupies a position in the graph, carries its own intent,
+    and failing it stops the path to <code>end</code>.
+  </p>
+  <div class="table-scroll" data-copy-cells>
+    <table>
+      <thead><tr><th>Assertion</th><th>Proves</th></tr></thead>
+      <tbody>
+        <tr><td><code>assert_file</code></td><td>A project file exists, and optionally contains given text.</td></tr>
+        <tr><td><code>assert_json</code></td><td>A JSON value satisfies a selector and operator.</td></tr>
+        <tr><td><code>assert_output</code></td><td>Captured stdout or stderr from an earlier command node matches.</td></tr>
+        <tr><td><code>assert_exit_code</code></td><td>An earlier command node exited as expected.</td></tr>
+        <tr><td><code>metamask.perps.assert_positions</code></td><td>Live positions are present or absent for an explicit selection.</td></tr>
+        <tr><td><code>metamask.analytics.assert_events</code></td><td>Event names, property values, <strong>and counts</strong>.</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <div class="doctrine">
+    <p>
+      <span class="k">Counted assertions earn their keep.</span> The analytics assertion takes an
+      <code>exact</code> count, and its own description says why: an exact count catches a double emit
+      that a presence check cannot. "Did the event fire?" answers yes to a bug that fires it twice.
+    </p>
+  </div>
+  <p>
+    <code>assert_positions</code> takes <code>expect_count</code>; <code>assert_orders</code> can also
+    assert a matching order's trigger price, execution mode, and reduce-only flag. Reach for the most
+    specific assertion the surface supports — a vague one passes for the wrong reasons.
+  </p>
+</section>
+<section class="wrap">
+  <h2 id="composition">Recipes call recipes</h2>
+  <p>
+    <code>call</code> is itself an action: it invokes a named recipe by reference and runs its steps
+    inline, so shared setup is written once instead of copied into every proof. The manifest's own
+    example:
+  </p>
+  <div class="out">{
+  "action": <span class="hint">"call"</span>,
+  "ref": "mydev.open_perps_setup",
+  "intent": "Run a personal Perps setup recipe",
+  "next": "done"
+}</div>
+  <p>
+    Running inline means the called recipe's nodes appear in the trace like any others: composition is
+    an author's convenience, not a hole in the evidence. <code>--describe</code> reports both the
+    actions and the recipes pulled in:
+  </p>
+  <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run &lt;recipe&gt; --describe</code></pre></div>
+  <div class="out">  actions (3)
+    app.status
+    assert_file
+    end
+  called recipes: none</div>
+</section>
+<section class="wrap">
+  <h2 id="verdict">The verdict is derived, never declared</h2>
+  <p>
+    Status is computed from the trace, not asserted by the author or written by an agent afterwards.
+    Every node has an <code>ok</code>; the run passes only if the path reached <code>end</code> with all
+    of them true:
+  </p>
+  <div class="out">{
+  "status": <span class="ok">"pass"</span>,
+  "total": 6,
+  "passed": 6,
+  "failed": 0
+}</div>
+  <p>
+    Two outcomes only: <strong>pass</strong> or <strong>fail</strong>. No "inconclusive" hiding place at
+    this level — either the graph reached its terminal node with every assertion satisfied, or it did
+    not.
+  </p>
+  <div class="note">
+    <span class="note-title">Where "cannot be proven here" lives</span>
+    <p>
+      One level up. When a review workflow maps acceptance criteria onto proofs, a criterion the surface
+      cannot demonstrate is reported as needing a human rather than quietly passed. That third answer
+      belongs to the review layer; a recipe either proved the thing or did not.
+    </p>
+  </div>
+  <p>
+    So every number you cite comes from <code>trace.json</code>; prose around a bundle is commentary.
+    <a href="reviewers.html">The reviewer's guide</a> walks a real one.
+  </p>
+</section>
+<section class="wrap">
+  <h2 id="falsifiability">The test of a good recipe</h2>
+  <div class="doctrine">
+    <p>
+      <span class="k">A good recipe fails if the change it proves is reverted.</span> That is the whole
+      quality bar.
+    </p>
+  </div>
+  <p>
+    A sharper question than "does it pass?", because passing is easy and uninformative. A recipe that
+    navigates to a screen, screenshots it, and ends will pass forever — including after someone deletes
+    the feature. It proves the app still starts.
+  </p>
+  <p>
+    So the check is adversarial: imagine the change gone and ask which node goes red. If the answer is
+    "none", the recipe is decoration. Common ways this goes wrong:
+  </p>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>Shape</th><th>Why it survives a revert</th><th>Fix</th></tr></thead>
+      <tbody>
+        <tr>
+          <td>Screenshot with no assertion</td>
+          <td>An image is evidence for a human, but nothing in the graph inspects it.</td>
+          <td>Add an assertion on the state the screenshot illustrates.</td>
+        </tr>
+        <tr>
+          <td>Presence check where a count belongs</td>
+          <td>Still true when the bug fires the event twice, or leaves two positions open.</td>
+          <td>Use <code>exact</code> / <code>expect_count</code>.</td>
+        </tr>
+        <tr>
+          <td>No starting-state assertion</td>
+          <td>Passes off pre-existing state as the effect of the action under test.</td>
+          <td>Assert clean before acting, as <code>perps.lifecycle</code> does.</td>
+        </tr>
+        <tr>
+          <td>Asserting the action's own report</td>
+          <td>Confirms the call returned, not that the world changed.</td>
+          <td>Read the state back with a separate node.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+  <p>
+    Cheapest way to run this test rather than reason about it: revert your change locally, run the
+    recipe, watch it fail, restore. A recipe you have seen fail for the right reason is one you can
+    trust when it passes.
+  </p>
+</section>
+<section class="wrap">
+  <hr class="sep">
+  <h2 id="author">Author one yourself</h2>
+  <p>
+    You do not have to write the JSON by hand, and mostly should not. Point the recipe-authoring skill
+    at an acceptance criterion and it discovers the actions, composes the graph, validates with
+    <code>--plan</code>, and runs it — following the rules on this page because the harness enforces
+    them. <a href="tutorials/v4.html">V4 walks that flow.</a>
+  </p>
+  <p>Expect one failure-and-fix loop on the way; that is the error messages doing their job.</p>
+  <div class="grid grid-2">
+    <div class="card">
+      <h3>Before you author</h3>
+      <p>Learn the vocabulary for your checkout — you are choosing from this list, not inventing.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness actions --categories
+<span class="p">$ </span>mm-harness actions --action assert_orders</code></pre></div>
+    </div>
+    <div class="card">
+      <h3>Read one that works</h3>
+      <p>The bundled recipes are worked examples. Start from the closest one to your problem.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness run --list
+<span class="p">$ </span>mm-harness run perps.lifecycle --describe</code></pre></div>
+    </div>
+  </div>
+  <div class="btn-row">
+    <a class="btn btn-primary" href="index.html#steps">Run your first recipe →</a>
+    <a class="btn btn-ghost" href="reviewers.html">Read the evidence it produces</a>
+    <a class="btn btn-ghost" href="architecture.html">Where skills fit</a>
+  </div>
+</section>
+</main>
+<footer class="footer">
+  <div class="wrap">
+    <p>Internal getting-started guide for the MetaMask agentic coding workflow. Not official MetaMask product documentation.</p>
+    <p>Verified against mm-harness 0.26+. The annotated recipe is a bundled library recipe, abridged.</p>
+  </div>
+</footer>
+<script type="module" src="assets/progress.mjs"></script>
+</body>
+</html>