npm - @deeeed/metamask-harness - Versions diffs - 0.47.0 → 0.47.2 - Mend

@deeeed/metamask-harness 0.47.0 → 0.47.2

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

package/CHANGELOG.md +21 -0
package/adapters/mobile/bridge-runtime/lib/bridge-errors.cjs +15 -0
package/dist/commands/tutorial.js +4 -4
package/dist/mm-harness-cli.js +3 -3
package/library/actions/mobile/perps/perps.mjs +41 -12
package/library/actions/mobile/perps/set_market_favorite.mjs +0 -11
package/library/actions/mobile/platform/bridge.mjs +6 -1
package/library/actions/mobile/ui/native-navigation.mjs +9 -2
package/library/actions/mobile/ui/navigate.mjs +13 -4
package/library/manifests/mobile.action-manifest.json +1 -2
package/package.json +2 -2
package/site/assets/help-recipes.json +6 -1
package/site/architecture.html +0 -497
package/site/assets/help-recipes.mjs +0 -25
package/site/assets/metamask-fox.svg +0 -24
package/site/assets/progress.mjs +0 -325
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 -697
package/site/index.html +0 -236
package/site/perps-advanced-orders-qa.html +0 -96
package/site/perps.html +0 -265
package/site/recipes.html +0 -430
package/site/reviewers.html +0 -375
package/site/tutorials/index.html +0 -181
package/site/tutorials/v1.html +0 -216
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/recipes.html DELETED Viewed

@@ -1,430 +0,0 @@
-<!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="icon" href="assets/metamask-fox.svg" type="image/svg+xml">
-<link rel="stylesheet" href="assets/style.css?v=4">
-</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">
-      <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">The trust mechanism</span>
-  <h1>What is a recipe?</h1>
-  <p class="lede">
-    A recipe turns "I checked, it works" into something proved on a device as the change is made —
-    and something that objects later if the behaviour breaks.
-  </p>
-</section>
-<section class="wrap" id="agent-method">
-  <div class="cmd cmd-hero" data-help-recipes>
-    <pre><code>Loading version-matched recipe help…</code></pre>
-  </div>
-</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>
-  <h2 id="why">What it is for</h2>
-  <p>
-    <strong>Proof.</strong> Actions drive a real build and assertions check what should be true —
-    counted, where a count is what distinguishes working from nearly working. What lands is on-device
-    evidence, not a claim in a pull request description.
-  </p>
-  <p>
-    <strong>Self-checking, in the same context.</strong> The agent does not need a fresh session, a
-    reviewer, or a CI round-trip to know whether its change held. It replays the recipe mid-task, where
-    it is already working, and reads the verdict itself — the inner loop, closed before handoff.
-  </p>
-  <p>
-    <strong>Prevents regressions.</strong> The outer loop is the same recipe replayed against every
-    later change. Written once, it keeps refusing the bug it was written for, which is why a recipe is
-    worth authoring rather than checking by hand: the check survives the task.
-  </p>
-  <p>
-    <strong>Trust.</strong> Proven, self-checked, and still proving — so the change is trustworthy
-    while it is being built. Everything downstream, review included, inherits that, and every gate
-    stays yours to steer.
-  </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 runs the whole
-    lifecycle, clean state through teardown — 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": "assert-clean-orders"
-      },
-      <span class="dim">… assert clean orders …</span>
-      "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>
-    On Core, <code>assert_positions</code> and <code>assert_orders</code> take
-    <code>expect_count</code>; the Extension and Mobile manifests do not declare it, and a recipe that
-    passes it there fails validation with exit 5. <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>; on Core, <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="how-it-works.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 proving MetaMask changes with recipes. Not official MetaMask product documentation.</p>
-    <p>The annotated recipe is a bundled library recipe, abridged. Sample output moves between releases; trust your terminal over this page.</p>
-  </div>
-</footer>
-<script type="module" src="assets/help-recipes.mjs?v=1"></script>
-<script type="module" src="assets/progress.mjs?v=4"></script>
-</body>
-</html>